Restrained API

README.md

@@ -123,6 +123,14 @@ Each of the following functions returns a push iterable instance:
 [reverseArray]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#reverseArray
 
 
+### Iteration
+
+[`iterateIt(iterable, accept): PushIterator`][iterateIt] function iterates over the head elements of the given iterable
+and returns its tail iterator.
+
+[iterateIt]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#iterateIt
+
+
 ### Iterable Consumption
 
 Each of the following functions accepts either [Iterable] or push iterable:
@@ -136,9 +144,6 @@ Each of the following functions accepts either [Iterable] or push iterable:
   implemented by the provided function.
 - [`itsFind(iterable, search): R | undefined`][itsFind] - Searches for the value in `iterable`.
 - [`itsFirst(iterable): T | undefined`][itsFirst] - Extracts the first element of the given `iterable`, if any.
-- [`itsHead(iterable, accept): PushIterator`][itsHead] - Iterates over the head elements of the given iterable and
-  returns its tail iterator.
-- [`itsIterated(iterable, accept): boolean`][itsIterated] - Iterates over elements of the given `iterable`.
 - [`itsIterator(iterable)`][itsIterator] - Starts iteration over the given `iterable`. Always returns a push iterator.
 - [`itsMatch(iterable, test): T | undefined`][itsMatch] - Extracts the first element matching the given condition from
   `iterable`.
@@ -153,8 +158,6 @@ Each of the following functions accepts either [Iterable] or push iterable:
 [itsEvery]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsEvery
 [itsFind]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsFind
 [itsFirst]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsFirst
-[itsHead]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsHead
-[itsIterated]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsIterated
 [itsIterator]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsIterator
 [itsMatch]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsMatch
 [itsReduction]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#itsReduction
@@ -228,16 +231,11 @@ Each of the following functions accepts an indexed list of items, and returns a
 
 - [`isPushIterable(iterable)`][isPushIterable] - Checks whether the given iterable or iterator conforms to push
   iteration protocol.
-- [`iteratorOf(iterable)`][iteratorOf] - Constructs iterator over elements of the given `iterable`.
+- [`iteratorOf(iterable)`][iteratorOf] - Creates iterator over elements of the given `iterable`.
 - [`makePushIterable(iterate)`][makePushIterable] - Creates a push iterable implementation.
 - [`makePushIterator(forNext)`][makePushIterator] - Creates a push iterator implementation.
-- [`pushHead(iterable, accept): PushIterator`][pushHead] - Iterates over the head elements of the given push iterable
-  and returns its tail iterator.
-- [`pushIterated(iterable, accept): boolean`][pushIterated] - Iterates over elements of the given push iterable.
 
 [isPushIterable]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#isPushIterable
 [iteratorOf]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#iteratorOf
 [makePushIterable]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#makePushIterable
 [makePushIterator]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#makePushIterator
-[pushHead]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#pushHead
-[pushIterated]: https://proc7ts.github.io/push-iterator/modules/Module__proc7ts_push_iterator.html#pushIterated

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proc7ts/push-iterator",
-  "version": "2.6.0",
+  "version": "3.0.0-dev.0",
   "description": "Push iteration protocol",
   "keywords": [
     "iteration",

src/base/index.ts

@@ -2,5 +2,3 @@ export * from './is-push-iterable';
 export * from './iterator-of';
 export * from './make-push-iterable';
 export * from './make-push-iterator';
-export * from './push-head';
-export * from './push-iterated';

src/consumption/its-head.spec.ts → src/base/iterate-it.spec.ts

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it } from '@jest/globals';
-import { iteratorOf } from '../base';
 import { overMany } from '../construction';
-import { itsHead } from './its-head';
+import { iteratorOf } from './index';
+import { iterateIt } from './iterate-it';
 
 describe('itsHead', () => {
 
@@ -34,14 +34,14 @@ describe('itsHead', () => {
 
     it('iterates over all elements', () => {
 
-      const tail = itsHead(iterable, el => { result.push(el); });
+      const tail = iterateIt(iterable, el => { result.push(el); });
 
       expect(result).toEqual([1, 22, 333]);
       expect(tail.isOver()).toBe(true);
     });
     it('iterates over head only', () => {
 
-      const tail = itsHead(
+      const tail = iterateIt(
           iterable,
           el => {
             result.push(el);
@@ -54,7 +54,7 @@ describe('itsHead', () => {
     });
     it('iterates over head and returns tail', () => {
 
-      const tail = itsHead(
+      const tail = iterateIt(
           iterable,
           el => {
             result.push(el);
@@ -73,7 +73,7 @@ describe('itsHead', () => {
   describe('over empty array', () => {
     it('does not iterate', () => {
 
-      const tail = itsHead([], el => { result.push(el); });
+      const tail = iterateIt([], el => { result.push(el); });
 
       expect(result).toHaveLength(0);
       expect(tail.isOver()).toBe(true);

src/consumption/its-head.ts → src/base/iterate-it.ts

@@ -1,17 +1,16 @@
-import { isPushIterable, iteratorOf, pushHead } from '../base';
-import { iterateOverArray } from '../base/iterate-over-array.impl';
-import { PushIterator$empty } from '../base/push-iterator.empty.impl';
-import { rawIteratorPusher, toPushIterator } from '../base/raw-iterator.impl';
+import { PushIterator__symbol } from '../push-iterable';
 import type { PushIterator } from '../push-iterator';
+import { isPushIterable } from './index';
+import { iterateOverArray } from './iterate-over-array.impl';
+import { PushIterator$empty } from './push-iterator.empty.impl';
+import { rawIteratorPusher, toPushIterator } from './push-iterator.raw.impl';
 
 /**
  * Iterates over elements of the given iterable.
  *
  * Calls `accept` method for each iterated element until there are elements to iterate, or `accept` returned either
  * `true` or `false`.
  *
- * In contrast to {@link pushHead} function, this one accepts any iterable instance.
- *
  * @typeParam T - Iterated elements type.
  * @param iterable - An iterable to iterate elements of.
  * @param accept - A function to push iterated elements to. Accepts iterated element as its only parameter. May return
@@ -20,29 +19,30 @@ import type { PushIterator } from '../push-iterator';
  * @returns A push iterator instance representing the tail of the given iterable. This iterator can be used to continue
  * iteration with, unless `accept` returned `false`. In the latter case the further iteration won't be possible.
  */
-export function itsHead<T>(iterable: Iterable<T>, accept: PushIterator.Acceptor<T>): PushIterator<T> {
+export function iterateIt<T>(iterable: Iterable<T>, accept: PushIterator.Acceptor<T>): PushIterator<T> {
   if (isPushIterable(iterable)) {
-    return pushHead(iterable, accept);
+    return iterable[PushIterator__symbol](accept);
   }
   if (Array.isArray(iterable)) {
-    return arrayHead(iterable, accept);
+    return iterateIt$array(iterable, accept);
   }
-  return rawIterableHead(iterable, accept);
+
+  return iterateIt$raw(iterable, accept);
 }
 
-function arrayHead<T>(array: ArrayLike<T>, accept: PushIterator.Acceptor<T>): PushIterator<T> {
+function iterateIt$array<T>(array: ArrayLike<T>, accept: PushIterator.Acceptor<T>): PushIterator<T> {
   return array.length ? iterateOverArray(array)(accept) : PushIterator$empty;
 }
 
-function rawIterableHead<T>(
+function iterateIt$raw<T>(
     iterable: Iterable<T>,
     accept: PushIterator.Acceptor<T>,
 ): PushIterator<T> {
 
-  const it = iteratorOf(iterable);
+  const it = iterable[Symbol.iterator]();
 
   if (isPushIterable(it)) {
-    return pushHead(it, accept);
+    return it[PushIterator__symbol](accept);
   }
 
   const forEach = rawIteratorPusher(it);

src/base/push-iterator.impl.ts

@@ -1,5 +1,5 @@
+import { PushIterator__symbol } from '../push-iterable';
 import type { PushIterator } from '../push-iterator';
-import { pushIterated } from './push-iterated';
 
 export function PushIterator$iterator<T>(this: T): T {
   return this;
@@ -9,18 +9,15 @@ export function PushIterator$next<T>(this: PushIterator<T>): IteratorResult<T> {
   for (; ;) {
 
     let result: IteratorYieldResult<T> | undefined;
-    const over = !pushIterated(
-        this,
-        value => {
-          result = { value };
-          return true;
-        },
-    );
+    const tail = this[PushIterator__symbol](value => {
+      result = { value };
+      return true;
+    });
 
     if (result) {
       return result;
     }
-    if (over) {
+    if (tail.isOver()) {
       return { done: true } as IteratorReturnResult<T>;
     }
   }

src/construction/over-array.spec.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it } from '@jest/globals';
-import { iteratorOf, pushIterated } from '../base';
+import { iteratorOf } from '../base';
+import { iterateIt } from '../base/iterate-it';
 import { itsElements, itsIterator } from '../consumption';
 import { overArray } from './over-array';
 
@@ -17,21 +18,21 @@ describe('overArray', () => {
     expect([...overArray(array)]).toEqual(array);
   });
   it('pushes array elements', () => {
-    expect(pushIterated(overArray(array), element => {
+    expect(iterateIt(overArray(array), element => {
       result.push(element);
-    })).toBe(false);
+    }).isOver()).toBe(true);
     expect(result).toEqual(array);
   });
   it('resumes iteration', () => {
 
     const it = itsIterator(overArray(array));
 
-    expect(pushIterated(it, () => true)).toBe(true);
+    expect(iterateIt(it, () => true).isOver()).toBe(false);
     expect(it.isOver()).toBe(false);
 
-    expect(pushIterated(it, element => {
+    expect(iterateIt(it, element => {
       result.push(element);
-    })).toBe(false);
+    }).isOver()).toBe(true);
     expect(it.isOver()).toBe(true);
     expect(result).toEqual(array.slice(1));
   });

src/construction/over-elements-of.ts

@@ -1,5 +1,5 @@
 import { makePushIterable, makePushIterator } from '../base';
-import { itsHead } from '../consumption';
+import { iterateIt } from '../base/iterate-it';
 import type { PushIterable } from '../push-iterable';
 import type { PushIterator } from '../push-iterator';
 import { overIterable } from './over-iterable';
@@ -15,13 +15,13 @@ import { overNone } from './over-none';
  */
 export function overElementsOf<T>(...sources: readonly Iterable<T>[]): PushIterable<T> {
   return sources.length > 1
-      ? makePushIterable(iterateOverSubElements(sources))
+      ? makePushIterable(overElementsOf$(sources))
       : (sources.length
           ? overIterable(sources[0])
           : overNone());
 }
 
-function iterateOverSubElements<T>(sources: readonly Iterable<T>[]): PushIterable.Iterate<T> {
+function overElementsOf$<T>(sources: readonly Iterable<T>[]): PushIterable.Iterate<T> {
   return accept => {
 
     let i = 0;
@@ -32,7 +32,7 @@ function iterateOverSubElements<T>(sources: readonly Iterable<T>[]): PushIterabl
 
         // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
         let status: boolean | void;
-        const srcTail = itsHead(src, element => status = accept(element));
+        const srcTail = iterateIt(src, element => status = accept(element));
 
         if (srcTail.isOver()) {
           if (++i >= sources.length) {

src/construction/over-indexed.spec.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it } from '@jest/globals';
-import { iteratorOf, pushIterated } from '../base';
+import { iteratorOf } from '../base';
+import { iterateIt } from '../base/iterate-it';
 import { itsElements, itsIterator } from '../consumption';
 import type { IndexedItemList } from './over-indexed';
 import { overIndexed } from './over-indexed';
@@ -27,21 +28,21 @@ describe('overIndexed', () => {
     expect([...overIndexed(list)]).toEqual(array);
   });
   it('pushes list items', () => {
-    expect(pushIterated(overIndexed(list), element => {
+    expect(iterateIt(overIndexed(list), element => {
       result.push(element);
-    })).toBe(false);
+    }).isOver()).toBe(true);
     expect(result).toEqual(array);
   });
   it('resumes iteration', () => {
 
     const it = itsIterator(overIndexed(list));
 
-    expect(pushIterated(it, () => true)).toBe(true);
+    expect(iterateIt(it, () => true).isOver()).toBe(false);
     expect(it.isOver()).toBe(false);
 
-    expect(pushIterated(it, element => {
+    expect(iterateIt(it, element => {
       result.push(element);
-    })).toBe(false);
+    }).isOver()).toBe(true);
     expect(it.isOver()).toBe(true);
     expect(result).toEqual(array.slice(1));
   });

src/construction/over-iterable.spec.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from '@jest/globals';
-import { iteratorOf, pushIterated } from '../base';
+import { iteratorOf } from '../base';
+import { iterateIt } from '../base/iterate-it';
 import { PushIterator__symbol } from '../push-iterable';
 import { overIterable } from './over-iterable';
 import { overMany } from './over-many';
@@ -30,7 +31,7 @@ describe('overIterable', () => {
     const it = overIterable(new Set([1, 2, 3]));
     const result: number[] = [];
 
-    pushIterated(it, el => { result.push(el); });
+    iterateIt(it, el => { result.push(el); });
 
     expect(result).toEqual([1, 2, 3]);
   });
@@ -61,7 +62,7 @@ describe('overIterable', () => {
 
         const it = iteratorOf(overIterable(new Set()));
 
-        expect(pushIterated(it, () => true)).toBe(false);
+        expect(iterateIt(it, () => true).isOver()).toBe(true);
         expect(it.isOver()).toBe(true);
       });
     });

src/construction/over-iterable.ts

@@ -1,4 +1,3 @@
-import { iteratorOf } from '../base';
 import type { PushIterable } from '../push-iterable';
 import { overArray } from './over-array';
 import { overIterator } from './over-iterator';
@@ -14,5 +13,5 @@ import { overIterator } from './over-iterator';
 export function overIterable<T>(iterable: Iterable<T>): PushIterable<T> {
   return Array.isArray(iterable)
       ? overArray<T>(iterable)
-      : overIterator(() => iteratorOf(iterable));
+      : overIterator(() => iterable[Symbol.iterator]());
 }

src/construction/over-iterator.ts

@@ -1,5 +1,5 @@
 import { isPushIterable, makePushIterable } from '../base';
-import { rawIteratorPusher, toPushIterator } from '../base/raw-iterator.impl';
+import { rawIteratorPusher, toPushIterator } from '../base/push-iterator.raw.impl';
 import type { PushIterable } from '../push-iterable';
 import { PushIterator__symbol } from '../push-iterable';
 import { overNone } from './over-none';