extra-iterator 0.4.0 → 0.5.0

package/dist/chain-of-responsibility.js

@@ -0,0 +1 @@
+"use strict";

package/dist/index.d.ts

@@ -12,12 +12,36 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
     static zip<A, B, C, D, E, F>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>, e: ExtraIteratorSource<E>, f: ExtraIteratorSource<F>): ExtraIterator<[A, B, C, D, E, F]>;
     static zip<A, B, C, D, E, F, G>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>, e: ExtraIteratorSource<E>, f: ExtraIteratorSource<F>, g: ExtraIteratorSource<G>): ExtraIterator<[A, B, C, D, E, F, G]>;
     static zip<A, B, C, D, E, F, G, H>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>, c: ExtraIteratorSource<C>, d: ExtraIteratorSource<D>, e: ExtraIteratorSource<E>, f: ExtraIteratorSource<F>, g: ExtraIteratorSource<G>, h: ExtraIteratorSource<H>): ExtraIterator<[A, B, C, D, E, F, G, H]>;
+    /**
+     * Creates an iterator that yields arrays containing the values that exist in the same indexes in each of the
+     * provided iterators.
+     *
+     * @example ExtraIterator.zip([1, 2, 3], ['a', 'b', 'c']).toArray() // returns [ [1, 'a'], [2, 'b'], [3, 'c'] ]
+     */
     static zip<T>(...iterables: ExtraIteratorSource<T>[]): ExtraIterator<T[]>;
+    /**
+     * Creates an iterator that yields no value.
+     *
+     * @example ExtraIterator.empty().toArray() // returns []
+     */
     static empty<T = any>(): ExtraIterator<T>;
+    /**
+     * Creates an iterator that yields incrementing numbers, starting from
+     * `start` (default 0) and ending at `end`. (exclusive)
+     *
+     * If `end` is omitted, counts to Infinity.
+     *
+     * @example ExtraIterator.count(5).toArray() // returns [0, 1, 2, 3, 4]
+     */
     static count(): ExtraIterator<number>;
     static count(end: number): ExtraIterator<number>;
     static count(start: number, end: number): ExtraIterator<number>;
     static count(start: number, end: number, interval: number): ExtraIterator<number>;
+    /**
+     * Creates an iterator that yields the provided value `count` times.
+     *
+     * @example ExtraIterator.repeat(3, 'a').toArray() // returns ['a', 'a', 'a']
+     */
     static repeat<T>(count: number, value: T): ExtraIterator<T>;
     private constructor();
     private source;
@@ -29,29 +53,263 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
     private takeLast;
     drop(count: number): ExtraIterator<T>;
     flatMap<U>(callback: (value: T, index: number) => Iterator<U, unknown, undefined> | Iterable<U, unknown, undefined>): ExtraIterator<U>;
+    /**
+     * Flattens the iterator by one level. If the iterator yields iterables, it will yield their values.
+     * If the iterator yields non-iterables, it will yield the values as is.
+     *
+     * This is equivalent to `flatMap(value => value)`.
+     *
+     * @example ExtraIterator.from([[1, 2], [3, 4]]).flatten().toArray() // returns [1, 2, 3, 4]
+     */
     flatten(): T extends Iterable<infer U> ? ExtraIterator<U> : never;
-    groupBy<K extends string | symbol>(callbackfn: (value: T, index: number) => K): Record<K, T[]>;
+    /**
+     * Creates a new iterator that yields the values of this iterator, but won't yield any duplicates.
+     *
+     * @param keyProvider An optional function that returns a key for each value. The keys are used to determine whether
+     * two values are equal or not. If two values have the same key, only the first one will be yielded. The other is
+     * ignored.
+     *
+     * @example ExtraIteartor.from('determination')
+     *     .unique()
+     *     .toArray()
+     *      // returns ['d', 'e', 't', 'r', 'm', 'i', 'n', 'a', 'o']
+     */
     unique(keyProvider?: (value: T) => unknown): ExtraIterator<T>;
+    /**
+     * Creates a new iterator that yields the values of this iterator, but won't yield any null or undefined values.
+     *
+     * @example ExtraIterator.from([0, 1, null, 3, undefined, 5])
+     *    .compact()
+     *    .toArray()
+     *    // returns [0, 1, 3, 5]
+     */
     compact(): ExtraIterator<Exclude<T, null | undefined>>;
-    withEach(callbackfn: (value: T, index: number) => void): ExtraIterator<T>;
-    first(): T | undefined;
-    last(): T | undefined;
-    at(index: number): T | undefined;
-    concat(items: Iterable<T>): ExtraIterator<T>;
+    /**
+     * Appends a new value to the end of the iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .append(4)
+     *     .toArray()
+     *     // returns [1, 2, 3, 4]
+     */
     append(item: T): ExtraIterator<T>;
-    prependMany(items: Iterable<T>): ExtraIterator<T>;
+    /**
+     * Prepends a new value to the beginning of the iterator. The new value will be yielded first, then the rest of this
+     * iterator will be yielded.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .prepend(0)
+     *     .toArray()
+     *     // returns [0, 1, 2, 3]
+     */
     prepend(item: T): ExtraIterator<T>;
+    /**
+     * Concatenates multiple values to the end of this iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .concat([4, 5, 6])
+     *     .toArray()
+     *     // returns [1, 2, 3, 4, 5, 6]
+     */
+    concat(items: Iterable<T>): ExtraIterator<T>;
+    /**
+     * Concatenates multiple values to the start of this iterator.
+     *
+     * The order of the values is preserved. This means the first element yielded by the returning iterator will be the
+     * first element of the `items` param; and the first element of this iterator will be yielded after the last element
+     * of the `items` param.
+     *
+     * @example
+     *
+     * ExtraIterator.from([4, 5, 6])
+     *     .prependMany([1, 2, 3])
+     *     .toArray()
+     *     // returns [1, 2, 3, 4, 5, 6]
+     */
+    prependMany(items: Iterable<T>): ExtraIterator<T>;
+    /**
+     * Creates a new iterator that invokes the provided callback function over each element of this iterator and yields
+     * the elements for which the callback returns `true`, only for as long as the callback returns `true`.
+     *
+     * This is similar to {@link filter}, except iteration stops once the callback returns `false` for the first time.
+     *
+     * @example
+     *
+     * ExtraIterator.from(['Alice', 'Antony', 'Charlie', 'Ashley'])
+     *     .takeWhile(name => name[0] === 'A')
+     *     .toArray()
+     *     // returns ['Alice', 'Antony']
+     *
+     * // ℹ Note that, in the example above, `filter()` would have returned `['Alice', 'Antony', 'Ashley']` instead.
+     */
     takeWhile(predicate: (value: T, index: number) => boolean): ExtraIterator<T>;
+    /**
+     * Creates a new iterator that invokes the provided callback function over each element of this iterator and skips
+     * the elements for which the callback returns `true`, but only for as long as the callback returns `true`.
+     *
+     * Once the callback function returns `false`, it will no longer be called. The iterator yields the element that
+     * caused the callback to return `false`, and well as the subsequent elements.
+     *
+     * @example
+     *
+     * ExtraIterator.from(['Alice', 'Antony', 'Charlie', 'Ashley'])
+     *    .dropWhile(name => name[0] === 'A')
+     *    .toArray()
+     *    // returns ['Charlie', 'Ashley']
+     */
     dropWhile(predicate: (value: T, index: number) => boolean): ExtraIterator<T>;
+    /**
+     * Groups the elements in this iterator into arrays of fixed size.
+     * The last array might be smaller than the others if the number of elements in this iterator is not divisible by
+     * the provided `size` param.
+     *
+     * @example ExtraIterator.from([1, 2, 3, 4, 5, 6, 7])
+     *     .chunk(3)
+     *     .toArray()
+     *     // returns [[1, 2, 3], [4, 5, 6], [7]]
+     */
     chunk(size: number): ExtraIterator<T[]>;
+    /**
+     * Creates a new iterator that iterates on this iterator and the proviuded other iterator, yielding arrays of pairs
+     * of elements from this iterator and the other.
+     *
+     * The elements in this iterator are the first elements of the pairs, and the elements in the other iterator are the
+     * second elements of the pairs.
+     *
+     * @example ExtraIterator.from([1, 2, 3])
+     *     .zip(['a', 'b', 'c'])
+     *     .toArray()
+     *     // returns [[1, 'a'], [2, 'b'], [3, 'c']]
+     */
     zip<U>(other: Iterable<U>): ExtraIterator<[T, U]>;
+    /**
+     * Creates a new iterator that yields the values of this iterator interposed by the provided separator. i.e. The
+     * separator is inserted between each pair of subsequent elements of this iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3, 4])
+     *     .interpose('a')
+     *     .toArray()
+     *     // returns [1, 'a', 2, 'a', 3, 'a', 4]
+     */
     interpose<U>(separator: U): ExtraIterator<T | U>;
+    /**
+     * Creates a new iterator that yields the values of this iterator interposed by separator values produced by calling
+     * the callback function provided as argument.
+     *
+     * @example
+     *
+     * ExtraIterator.from([2, 3, 5, 8])
+     *     .interposeWith((lhs, rhs) => (lhs + rhs) / 2)
+     *     .toArray()
+     *     // returns [2, 2.5, 3, 4, 5, 6.5, 8]
+     */
+    interposeWith<U>(separatorProvider: (lhs: T, rhs: T, index: number) => U): ExtraIterator<T | U>;
+    /**
+     * Creates a new iterator that yields the values of this iterator and the values of the provided iterator
+     * interleaved (alternating). The elements of this iterator always come before the elements of the other iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .interleave(['a', 'b', 'c'])
+     *     .toArray()
+     *     // returns [1, 'a', 2, 'b', 3, 'c']
+     */
     interleave<U>(other: ExtraIteratorSource<U>): ExtraIterator<T | U>;
+    /**
+     * Replaces some elements of this iterator with new values.
+     *
+     * @param startIndex The index of the first element to be replaced.
+     * @param deleteCount The number of elements to be replaced.
+     * @param newItems The new elements to be inserted.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3, 4])
+     *     .splice(1, 2, 5, 6)
+     *     .toArray()
+     *     // returns [1, 5, 6, 4]
+     */
     splice(startIndex: number, deleteCount: number, ...newItems: T[]): ExtraIterator<T>;
+    /**
+     * Returns an iterator the provided element if this iterator is empty; otherwise, it returns this iterator.
+     */
     defaultIfEmpty(provider: () => T): ExtraIterator<T>;
+    /**
+     * Returns the first element of the iterator, or `undefined` if the iterator is empty.
+     */
+    first(): T | undefined;
+    /**
+     * Consumes the iteratror and returns the last value yielded.
+     *
+     * Returns `undefined` if the iterator is empty.
+     */
+    last(): T | undefined;
+    /**
+     * Consumes the iterator and returns the value at the provided index.
+     */
+    at(index: number): T | undefined;
+    /**
+     * Groups the elements in this iterator into separate arrays and returns an object containing all the groups.
+     *
+     * The returned object is composed of keys generated by calling the provided callback function on each element of
+     * this iterator, and the value for each key is an array containing all the elements that were assigned to that key.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3, 4, 5])
+     *  .groupBy(value => value % 2 === 0 ? 'even' : 'odd')
+     *  .toArray()
+     *  // returns { even: [2, 4], odd: [1, 3, 5] }
+     */
+    groupBy<K extends string | symbol>(callbackfn: (value: T, index: number) => K): Record<K, T[]>;
+    toChainOfResponsibilityFunction<ResultType = void | Promise<void>, ParamsType extends any[] = []>(invokeHandler: (handler: T, next: (...args: ParamsType) => ResultType, ...args: ParamsType) => ResultType): (...args: ParamsType) => ResultType;
+    /**
+     * Consumes the iterator and returns a value determined by calling the provided function using the iterator as
+     * argument.
+     *
+     * @example
+     *
+     * ExtraIterator.from(Object.entries({ a: 1, b: 2 }))
+     *     .map(([key, value]) => ['_' + key, value * 2])
+     *     .collect(Object.fromEntries)
+     *     // returns { _a: 2, _b: 4 }
+     */
     collect<U>(collectfn: ((iter: Iterable<T>) => U)): U;
     toSortedBy(...keys: (keyof T)[]): T[];
+    /**
+     * Consumes the iterator and returns the number of elements it contained.
+     */
     count(): number;
+    /**
+     * Consumes the iterator and returns a boolean indicating whether all elements in the iterator were unique.
+     *
+     * If it returns false, then the iterator had at least one duplicated element.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3]).uniqueness() // returns true
+     * ExtraIterator.from([1, 2, 3, 1]).uniqueness() // returns false
+     */
     uniqueness(mapper?: (value: T) => unknown): boolean;
+    /**
+     * Lazily executes a function over each element of this iterator as the values are iterated.
+     *
+     * This method does not change the output values of the iterator.
+     *
+     * This method is equivalent to {@link map} when the callback function returns the iterated value.
+     *
+     * This is similar to {@link forEach}, except the callback function is not executed immediately (instead, it is
+     * executed when the iterator is iterated), and this method returns the iterator itself.
+     */
+    withEach(callbackfn: (value: T, index: number) => void): ExtraIterator<T>;
 }
 export {};

package/dist/index.js

@@ -1,4 +1,7 @@
 export class ExtraIterator extends Iterator {
+    // =================================================================================================================
+    // STATIC FUNCTIONS
+    // =================================================================================================================
     // TODO Consider using a lib like `make-iterator` to transform things into iterators
     static from(source) {
         if (!(Symbol.iterator in source) && 'length' in source) {
@@ -18,6 +21,11 @@ export class ExtraIterator extends Iterator {
             }
         }().toArray());
     }
+    /**
+     * Creates an iterator that yields no value.
+     *
+     * @example ExtraIterator.empty().toArray() // returns []
+     */
     static empty() {
         return new ExtraIterator([]);
     }
@@ -31,6 +39,11 @@ export class ExtraIterator extends Iterator {
             }
         }());
     }
+    /**
+     * Creates an iterator that yields the provided value `count` times.
+     *
+     * @example ExtraIterator.repeat(3, 'a').toArray() // returns ['a', 'a', 'a']
+     */
     static repeat(count, value) {
         return new ExtraIterator(function* () {
             for (let index = 0; index < count; index++) {
@@ -38,6 +51,9 @@ export class ExtraIterator extends Iterator {
             }
         }());
     }
+    // =================================================================================================================
+    // PRIVATES
+    // =================================================================================================================
     constructor(source) {
         super();
         this.source = Iterator.from(source);
@@ -49,6 +65,9 @@ export class ExtraIterator extends Iterator {
         }
     }
     source;
+    // =================================================================================================================
+    // OVERRIDES
+    // =================================================================================================================
     next(value) {
         return this.source.next(value);
     }
@@ -81,20 +100,34 @@ export class ExtraIterator extends Iterator {
     flatMap(callback) {
         return ExtraIterator.from(super.flatMap(callback));
     }
+    // =================================================================================================================
+    // TRANSFORMING FUNCTIONS
+    // -----------------------------------------------------------------------------------------------------------------
+    // These functions transform the iterator somehow and returns a new iterator.
+    // =================================================================================================================
+    /**
+     * Flattens the iterator by one level. If the iterator yields iterables, it will yield their values.
+     * If the iterator yields non-iterables, it will yield the values as is.
+     *
+     * This is equivalent to `flatMap(value => value)`.
+     *
+     * @example ExtraIterator.from([[1, 2], [3, 4]]).flatten().toArray() // returns [1, 2, 3, 4]
+     */
     flatten() {
         return this.flatMap(value => value);
     }
-    groupBy(callbackfn) {
-        const result = Object.create(null);
-        for (let index = 0, next; next = this.next(), !next.done; index++) {
-            const key = callbackfn(next.value, index);
-            if (!result[key]) {
-                result[key] = [];
-            }
-            result[key].push(next.value);
-        }
-        return result;
-    }
+    /**
+     * Creates a new iterator that yields the values of this iterator, but won't yield any duplicates.
+     *
+     * @param keyProvider An optional function that returns a key for each value. The keys are used to determine whether
+     * two values are equal or not. If two values have the same key, only the first one will be yielded. The other is
+     * ignored.
+     *
+     * @example ExtraIteartor.from('determination')
+     *     .unique()
+     *     .toArray()
+     *      // returns ['d', 'e', 't', 'r', 'm', 'i', 'n', 'a', 'o']
+     */
     unique(keyProvider = value => value) {
         return ExtraIterator.from(function* () {
             const seen = new Set();
@@ -107,60 +140,102 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Creates a new iterator that yields the values of this iterator, but won't yield any null or undefined values.
+     *
+     * @example ExtraIterator.from([0, 1, null, 3, undefined, 5])
+     *    .compact()
+     *    .toArray()
+     *    // returns [0, 1, 3, 5]
+     */
     compact() {
         const predicate = (value => value !== null && value !== undefined);
         return ExtraIterator.from(this.filter(predicate));
     }
-    withEach(callbackfn) {
+    /**
+     * Appends a new value to the end of the iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .append(4)
+     *     .toArray()
+     *     // returns [1, 2, 3, 4]
+     */
+    append(item) {
         return ExtraIterator.from(function* () {
-            for (let index = 0, next; next = this.next(), !next.done; index++) {
-                callbackfn(next.value, index);
-                yield next.value;
-            }
+            yield* this;
+            yield item;
         }.call(this));
     }
-    first() {
-        const next = this.next();
-        return next.done ? undefined : next.value;
-    }
-    last() {
-        let previousItem = this.next();
-        if (previousItem.done) {
-            return undefined;
-        }
-        for (let currentItem; currentItem = this.next(), !currentItem.done; previousItem = currentItem)
-            ;
-        return previousItem.value;
-    }
-    at(index) {
-        return index === -1 ? this.last()
-            : index < 0 ? this.take(index).at(0)
-                : this.drop(index).first();
-    }
-    concat(items) {
+    /**
+     * Prepends a new value to the beginning of the iterator. The new value will be yielded first, then the rest of this
+     * iterator will be yielded.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .prepend(0)
+     *     .toArray()
+     *     // returns [0, 1, 2, 3]
+     */
+    prepend(item) {
         return ExtraIterator.from(function* () {
+            yield item;
             yield* this;
-            yield* items;
         }.call(this));
     }
-    append(item) {
+    /**
+     * Concatenates multiple values to the end of this iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .concat([4, 5, 6])
+     *     .toArray()
+     *     // returns [1, 2, 3, 4, 5, 6]
+     */
+    concat(items) {
         return ExtraIterator.from(function* () {
             yield* this;
-            yield item;
+            yield* items;
         }.call(this));
     }
+    /**
+     * Concatenates multiple values to the start of this iterator.
+     *
+     * The order of the values is preserved. This means the first element yielded by the returning iterator will be the
+     * first element of the `items` param; and the first element of this iterator will be yielded after the last element
+     * of the `items` param.
+     *
+     * @example
+     *
+     * ExtraIterator.from([4, 5, 6])
+     *     .prependMany([1, 2, 3])
+     *     .toArray()
+     *     // returns [1, 2, 3, 4, 5, 6]
+     */
     prependMany(items) {
         return ExtraIterator.from(function* () {
             yield* items;
             yield* this;
         }.call(this));
     }
-    prepend(item) {
-        return ExtraIterator.from(function* () {
-            yield item;
-            yield* this;
-        }.call(this));
-    }
+    /**
+     * Creates a new iterator that invokes the provided callback function over each element of this iterator and yields
+     * the elements for which the callback returns `true`, only for as long as the callback returns `true`.
+     *
+     * This is similar to {@link filter}, except iteration stops once the callback returns `false` for the first time.
+     *
+     * @example
+     *
+     * ExtraIterator.from(['Alice', 'Antony', 'Charlie', 'Ashley'])
+     *     .takeWhile(name => name[0] === 'A')
+     *     .toArray()
+     *     // returns ['Alice', 'Antony']
+     *
+     * // ℹ Note that, in the example above, `filter()` would have returned `['Alice', 'Antony', 'Ashley']` instead.
+     */
     takeWhile(predicate) {
         return ExtraIterator.from(function* () {
             for (let index = 0, next; next = this.next(), !next.done; index++) {
@@ -171,6 +246,20 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Creates a new iterator that invokes the provided callback function over each element of this iterator and skips
+     * the elements for which the callback returns `true`, but only for as long as the callback returns `true`.
+     *
+     * Once the callback function returns `false`, it will no longer be called. The iterator yields the element that
+     * caused the callback to return `false`, and well as the subsequent elements.
+     *
+     * @example
+     *
+     * ExtraIterator.from(['Alice', 'Antony', 'Charlie', 'Ashley'])
+     *    .dropWhile(name => name[0] === 'A')
+     *    .toArray()
+     *    // returns ['Charlie', 'Ashley']
+     */
     dropWhile(predicate) {
         return ExtraIterator.from(function* () {
             for (let index = 0, next; next = this.next(), !next.done; index++) {
@@ -182,6 +271,16 @@ export class ExtraIterator extends Iterator {
             yield* this;
         }.call(this));
     }
+    /**
+     * Groups the elements in this iterator into arrays of fixed size.
+     * The last array might be smaller than the others if the number of elements in this iterator is not divisible by
+     * the provided `size` param.
+     *
+     * @example ExtraIterator.from([1, 2, 3, 4, 5, 6, 7])
+     *     .chunk(3)
+     *     .toArray()
+     *     // returns [[1, 2, 3], [4, 5, 6], [7]]
+     */
     chunk(size) {
         return ExtraIterator.from(function* () {
             for (let next; next = this.next(), !next.done;) {
@@ -189,6 +288,18 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Creates a new iterator that iterates on this iterator and the proviuded other iterator, yielding arrays of pairs
+     * of elements from this iterator and the other.
+     *
+     * The elements in this iterator are the first elements of the pairs, and the elements in the other iterator are the
+     * second elements of the pairs.
+     *
+     * @example ExtraIterator.from([1, 2, 3])
+     *     .zip(['a', 'b', 'c'])
+     *     .toArray()
+     *     // returns [[1, 'a'], [2, 'b'], [3, 'c']]
+     */
     zip(other) {
         return ExtraIterator.from(function* () {
             const otherIterator = Iterator.from(other);
@@ -197,6 +308,17 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Creates a new iterator that yields the values of this iterator interposed by the provided separator. i.e. The
+     * separator is inserted between each pair of subsequent elements of this iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3, 4])
+     *     .interpose('a')
+     *     .toArray()
+     *     // returns [1, 'a', 2, 'a', 3, 'a', 4]
+     */
     interpose(separator) {
         return ExtraIterator.from(function* () {
             for (let next = this.next(); !next.done;) {
@@ -208,6 +330,39 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Creates a new iterator that yields the values of this iterator interposed by separator values produced by calling
+     * the callback function provided as argument.
+     *
+     * @example
+     *
+     * ExtraIterator.from([2, 3, 5, 8])
+     *     .interposeWith((lhs, rhs) => (lhs + rhs) / 2)
+     *     .toArray()
+     *     // returns [2, 2.5, 3, 4, 5, 6.5, 8]
+     */
+    interposeWith(separatorProvider) {
+        return ExtraIterator.from(function* () {
+            for (let previous = this.next(), next, index = 0; !previous.done; previous = next, index++) {
+                yield previous.value;
+                next = this.next();
+                if (!next.done) {
+                    yield separatorProvider(previous.value, next.value, index);
+                }
+            }
+        }.call(this));
+    }
+    /**
+     * Creates a new iterator that yields the values of this iterator and the values of the provided iterator
+     * interleaved (alternating). The elements of this iterator always come before the elements of the other iterator.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3])
+     *     .interleave(['a', 'b', 'c'])
+     *     .toArray()
+     *     // returns [1, 'a', 2, 'b', 3, 'c']
+     */
     interleave(other) {
         return ExtraIterator.from(function* () {
             const otherIterator = ExtraIterator.from(other);
@@ -223,6 +378,20 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Replaces some elements of this iterator with new values.
+     *
+     * @param startIndex The index of the first element to be replaced.
+     * @param deleteCount The number of elements to be replaced.
+     * @param newItems The new elements to be inserted.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3, 4])
+     *     .splice(1, 2, 5, 6)
+     *     .toArray()
+     *     // returns [1, 5, 6, 4]
+     */
     splice(startIndex, deleteCount, ...newItems) {
         if (startIndex < 0) {
             return ExtraIterator.from(this.toArray()
@@ -239,6 +408,9 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Returns an iterator the provided element if this iterator is empty; otherwise, it returns this iterator.
+     */
     defaultIfEmpty(provider) {
         return ExtraIterator.from(function* () {
             const result = this.next();
@@ -251,6 +423,90 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    // =================================================================================================================
+    // AGGREGATING FUNCTIONS
+    // -----------------------------------------------------------------------------------------------------------------
+    // These functions consume the iterator and return a new value.
+    // =================================================================================================================
+    /**
+     * Returns the first element of the iterator, or `undefined` if the iterator is empty.
+     */
+    first() {
+        const next = this.next();
+        return next.done ? undefined : next.value;
+    }
+    /**
+     * Consumes the iteratror and returns the last value yielded.
+     *
+     * Returns `undefined` if the iterator is empty.
+     */
+    last() {
+        let previousItem = this.next();
+        if (previousItem.done) {
+            return undefined;
+        }
+        for (let currentItem; currentItem = this.next(), !currentItem.done; previousItem = currentItem)
+            ;
+        return previousItem.value;
+    }
+    /**
+     * Consumes the iterator and returns the value at the provided index.
+     */
+    at(index) {
+        return index === -1 ? this.last()
+            : index < 0 ? this.take(index).at(0)
+                : this.drop(index).first();
+    }
+    /**
+     * Groups the elements in this iterator into separate arrays and returns an object containing all the groups.
+     *
+     * The returned object is composed of keys generated by calling the provided callback function on each element of
+     * this iterator, and the value for each key is an array containing all the elements that were assigned to that key.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3, 4, 5])
+     *  .groupBy(value => value % 2 === 0 ? 'even' : 'odd')
+     *  .toArray()
+     *  // returns { even: [2, 4], odd: [1, 3, 5] }
+     */
+    groupBy(callbackfn) {
+        const result = Object.create(null);
+        for (let index = 0, next; next = this.next(), !next.done; index++) {
+            const key = callbackfn(next.value, index);
+            if (!result[key]) {
+                result[key] = [];
+            }
+            result[key].push(next.value);
+        }
+        return result;
+    }
+    toChainOfResponsibilityFunction(invokeHandler) {
+        const handlers = this.toArray();
+        return (...initialArgs) => {
+            const iterator = Iterator.from(handlers);
+            function nextFn(...args) {
+                const next = iterator.next();
+                if (next.done) {
+                    throw new Error('Chain of responsibility exhausted. No more handlers available.');
+                }
+                return invokeHandler(next.value, nextFn, ...args);
+            }
+            ;
+            return nextFn(...initialArgs);
+        };
+    }
+    /**
+     * Consumes the iterator and returns a value determined by calling the provided function using the iterator as
+     * argument.
+     *
+     * @example
+     *
+     * ExtraIterator.from(Object.entries({ a: 1, b: 2 }))
+     *     .map(([key, value]) => ['_' + key, value * 2])
+     *     .collect(Object.fromEntries)
+     *     // returns { _a: 2, _b: 4 }
+     */
     collect(collectfn) {
         return collectfn(this);
     }
@@ -266,6 +522,9 @@ export class ExtraIterator extends Iterator {
             return 0;
         });
     }
+    /**
+     * Consumes the iterator and returns the number of elements it contained.
+     */
     count() {
         let count = 0;
         for (let next; next = this.next(), !next.done;) {
@@ -273,6 +532,16 @@ export class ExtraIterator extends Iterator {
         }
         return count;
     }
+    /**
+     * Consumes the iterator and returns a boolean indicating whether all elements in the iterator were unique.
+     *
+     * If it returns false, then the iterator had at least one duplicated element.
+     *
+     * @example
+     *
+     * ExtraIterator.from([1, 2, 3]).uniqueness() // returns true
+     * ExtraIterator.from([1, 2, 3, 1]).uniqueness() // returns false
+     */
     uniqueness(mapper) {
         const seen = new Set();
         for (let next; next = this.next(), !next.done;) {
@@ -284,4 +553,25 @@ export class ExtraIterator extends Iterator {
         }
         return true;
     }
+    // =================================================================================================================
+    // MISC FUNCTIONS
+    // =================================================================================================================
+    /**
+     * Lazily executes a function over each element of this iterator as the values are iterated.
+     *
+     * This method does not change the output values of the iterator.
+     *
+     * This method is equivalent to {@link map} when the callback function returns the iterated value.
+     *
+     * This is similar to {@link forEach}, except the callback function is not executed immediately (instead, it is
+     * executed when the iterator is iterated), and this method returns the iterator itself.
+     */
+    withEach(callbackfn) {
+        return ExtraIterator.from(function* () {
+            for (let index = 0, next; next = this.next(), !next.done; index++) {
+                callbackfn(next.value, index);
+                yield next.value;
+            }
+        }.call(this));
+    }
 }

package/dist/index.test.js

@@ -57,6 +57,10 @@ describe('ExtraIterator', () => {
         const iterator = ExtraIterator.from([1, 2, 3]).interpose(0);
         expect(iterator.toArray()).toEqual([1, 0, 2, 0, 3]);
     });
+    it('should interpose with a function', () => {
+        const iterator = ExtraIterator.from([1, 2, 3, 5, 8, 13]).interposeWith((a, b) => (a + b) / 2);
+        expect(iterator.toArray()).toEqual([1, 1.5, 2, 2.5, 3, 4, 5, 6.5, 8, 10.5, 13]);
+    });
     it('should chunk values into groups of a given size', () => {
         const iterator = ExtraIterator.from([1, 2, 3, 4]).chunk(2);
         expect(iterator.toArray()).toEqual([[1, 2], [3, 4]]);
@@ -118,4 +122,23 @@ describe('ExtraIterator', () => {
         const sum = iterator.collect(iter => Array.from(iter).reduce((a, b) => a + b, 0));
         expect(sum).toBe(6);
     });
+    it('should create a chain of responsibility function', () => {
+        const humanizeDuration = ExtraIterator.from([
+            (next, miliseconds) => miliseconds < 1000 ? `${miliseconds} miliseconds` : next(miliseconds / 1000),
+            (next, seconds) => seconds < 60 ? `${seconds} seconds` : next(seconds / 60),
+            (next, minutes) => minutes < 60 ? `${minutes} minutes` : next(minutes / 60),
+            (next, hours) => hours < 24 ? `${hours} hours` : next(hours / 24),
+            (_next, days) => `${days} days`,
+        ]).toChainOfResponsibilityFunction((handler, next, value) => handler(next, value));
+        expect(humanizeDuration(500)).toBe('500 miliseconds');
+        expect(humanizeDuration(2000)).toBe('2 seconds');
+        expect(humanizeDuration(120000)).toBe('2 minutes');
+        expect(humanizeDuration(7200000)).toBe('2 hours');
+        expect(humanizeDuration(172800000)).toBe('2 days');
+    });
+    it('should throw an error if no handlers are available', () => {
+        const handlers = ExtraIterator.empty();
+        const chain = handlers.toChainOfResponsibilityFunction(next => next());
+        expect(() => chain()).toThrow();
+    });
 });

package/package.json

@@ -3,7 +3,7 @@
   "description": "An extension of the Iterator class with additional utility helper functions.",
   "author": "Leonardo Raele <leonardoraele@gmail.com>",
   "license": "MIT",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",