extra-iterator 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -13,8 +13,8 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
     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.
+     * Creates a new iterator that iterates over all the provided iterators simultaneously. The returned iterator yields
+     * arrays containing the values yielded by each of the provided iterators.
      *
      * @example ExtraIterator.zip([1, 2, 3], ['a', 'b', 'c']).toArray() // returns [ [1, 'a'], [2, 'b'], [3, 'c'] ]
      */
@@ -26,23 +26,35 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      */
     static empty<T = any>(): ExtraIterator<T>;
     /**
-     * Creates an iterator that yields incrementing numbers, starting from
-     * `start` (default 0) and ending at `end`. (exclusive)
+     * Creates an iterator that yields incrementing numbers.
      *
-     * If `end` is omitted, counts to Infinity.
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
      *
-     * @example ExtraIterator.count(5).toArray() // returns [0, 1, 2, 3, 4]
+     * @example ExtraIterator.count().take(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>;
+    static count({ start, interval }?: {
+        start?: number | undefined;
+        interval?: number | undefined;
+    }): ExtraIterator<number>;
     /**
-     * Creates an iterator that yields the provided value `count` times.
+     * Creates an iterator that repeatedly yields the provided value.
+     *
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
      *
      * @example ExtraIterator.repeat(3, 'a').toArray() // returns ['a', 'a', 'a']
      */
-    static repeat<T>(count: number, value: T): ExtraIterator<T>;
+    static repeat<T>(value: T): ExtraIterator<T>;
+    /**
+     * Generates random cryptographically strong random numbers.
+     *
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
+     *
+     * @param param0
+     * @returns
+     */
+    static random({ bufferSize }?: {
+        bufferSize?: number | undefined;
+    }): ExtraIterator<number>;
     private constructor();
     private source;
     next(value?: any): IteratorResult<T, any>;
@@ -243,6 +255,14 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      * Returns an iterator the provided element if this iterator is empty; otherwise, it returns this iterator.
      */
     defaultIfEmpty(provider: () => T): ExtraIterator<T>;
+    /**
+     * Creates a new iterator that yields the values of this iterator and then reiterates over the same values and
+     * yields each of them again, a number of times determined by the {@param times} parameter. If omitted, loops
+     * infinitely.
+     *
+     * @example ExtraIterator.from([1, 2, 3]).loop(3).toArray() // returns [1, 2, 3, 1, 2, 3, 1, 2, 3]
+     */
+    loop(times?: number): ExtraIterator<T>;
     /**
      * Returns the first element of the iterator, or `undefined` if the iterator is empty.
      */
@@ -263,6 +283,9 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      * 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.
      *
+     * This method is similar to {@link toMap}, but the returned object is a plain, null-prototype, object, instead of a
+     * `Map`.
+     *
      * @example
      *
      * ExtraIterator.from([1, 2, 3, 4, 5])
@@ -271,6 +294,20 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      *  // returns { even: [2, 4], odd: [1, 3, 5] }
      */
     groupBy<K extends string | symbol>(callbackfn: (value: T, index: number) => K): Record<K, T[]>;
+    /**
+     * Groups elements into separate arrays and returns a Map containing each group.
+     *
+     * The returned Map 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 to which the callback function
+     * returned that key.
+     *
+     * This method is similart to {@link groupBy}, but the returned object is a Map instead of a plain object.
+     */
+    toMap<K extends string | symbol>(callbackfn: (value: T, index: number) => K): Map<K, T[]>;
+    /**
+     * Creates a set containing all the values yielded by this iterator.
+     */
+    toSet(): Set<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
@@ -284,9 +321,10 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      *     // 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.
+     *
+     * @example ExtraIterator.from([1, 2, 3, 4]).count() // returns 4
      */
     count(): number;
     /**

package/dist/index.js

@@ -29,28 +29,51 @@ export class ExtraIterator extends Iterator {
     static empty() {
         return new ExtraIterator([]);
     }
-    static count(...args) {
-        const [start, end, interval] = args.length === 0 ? [0, Infinity, 1]
-            : args.length === 1 ? [0, args[0], 1]
-                : [args[0], args[1], args[2] ?? 1];
+    /**
+     * Creates an iterator that yields incrementing numbers.
+     *
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
+     *
+     * @example ExtraIterator.count().take(5).toArray() // returns [0, 1, 2, 3, 4]
+     */
+    static count({ start = 0, interval = 1 } = {}) {
         return new ExtraIterator(function* () {
-            for (let counter = start; counter < end; counter += interval) {
-                yield counter;
+            while (true) {
+                yield start;
+                start += interval;
             }
         }());
     }
     /**
-     * Creates an iterator that yields the provided value `count` times.
+     * Creates an iterator that repeatedly yields the provided value.
+     *
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
      *
      * @example ExtraIterator.repeat(3, 'a').toArray() // returns ['a', 'a', 'a']
      */
-    static repeat(count, value) {
+    static repeat(value) {
         return new ExtraIterator(function* () {
-            for (let index = 0; index < count; index++) {
+            while (true) {
                 yield value;
             }
         }());
     }
+    /**
+     * Generates random cryptographically strong random numbers.
+     *
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
+     *
+     * @param param0
+     * @returns
+     */
+    static random({ bufferSize = 1024 } = {}) {
+        const buffer = new Uint8Array(bufferSize);
+        return new ExtraIterator(function* () {
+            globalThis.crypto.getRandomValues(buffer);
+            yield* new Float64Array(buffer);
+        }())
+            .loop();
+    }
     // =================================================================================================================
     // PRIVATES
     // =================================================================================================================
@@ -423,6 +446,24 @@ export class ExtraIterator extends Iterator {
             }
         }.call(this));
     }
+    /**
+     * Creates a new iterator that yields the values of this iterator and then reiterates over the same values and
+     * yields each of them again, a number of times determined by the {@param times} parameter. If omitted, loops
+     * infinitely.
+     *
+     * @example ExtraIterator.from([1, 2, 3]).loop(3).toArray() // returns [1, 2, 3, 1, 2, 3, 1, 2, 3]
+     */
+    loop(times = Infinity) {
+        return ExtraIterator.from(function* () {
+            const values = this.toArray();
+            if (values.length === 0) {
+                return;
+            }
+            for (let i = 0; i < times; i++) {
+                yield* values;
+            }
+        }.call(this));
+    }
     // =================================================================================================================
     // AGGREGATING FUNCTIONS
     // -----------------------------------------------------------------------------------------------------------------
@@ -463,6 +504,9 @@ export class ExtraIterator extends Iterator {
      * 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.
      *
+     * This method is similar to {@link toMap}, but the returned object is a plain, null-prototype, object, instead of a
+     * `Map`.
+     *
      * @example
      *
      * ExtraIterator.from([1, 2, 3, 4, 5])
@@ -481,6 +525,37 @@ export class ExtraIterator extends Iterator {
         }
         return result;
     }
+    /**
+     * Groups elements into separate arrays and returns a Map containing each group.
+     *
+     * The returned Map 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 to which the callback function
+     * returned that key.
+     *
+     * This method is similart to {@link groupBy}, but the returned object is a Map instead of a plain object.
+     */
+    toMap(callbackfn) {
+        const result = new Map();
+        for (let index = 0, next; next = this.next(), !next.done; index++) {
+            const key = callbackfn(next.value, index);
+            const array = result.get(key);
+            if (!array) {
+                result.set(key, [next.value]);
+            }
+            else {
+                array.push(next.value);
+            }
+        }
+        return result;
+    }
+    /**
+     * Creates a set containing all the values yielded by this iterator.
+     */
+    toSet() {
+        const result = new Set();
+        this.forEach(value => result.add(value));
+        return result;
+    }
     toChainOfResponsibilityFunction(invokeHandler) {
         const handlers = this.toArray();
         return (...initialArgs) => {
@@ -510,20 +585,10 @@ export class ExtraIterator extends Iterator {
     collect(collectfn) {
         return collectfn(this);
     }
-    toSortedBy(...keys) {
-        return this.toArray()
-            .sort((a, b) => {
-            for (const key of keys) {
-                if (a[key] < b[key])
-                    return -1;
-                if (a[key] > b[key])
-                    return 1;
-            }
-            return 0;
-        });
-    }
     /**
      * Consumes the iterator and returns the number of elements it contained.
+     *
+     * @example ExtraIterator.from([1, 2, 3, 4]).count() // returns 4
      */
     count() {
         let count = 0;

package/dist/index.test.js

@@ -14,13 +14,22 @@ describe('ExtraIterator', () => {
         expect(zipped.toArray()).toEqual([[1, 'a'], [2, 'b'], [3, 'c']]);
     });
     it('should count from 0 to a given number', () => {
-        const iterator = ExtraIterator.count(5);
+        const iterator = ExtraIterator.count().take(5);
         expect(iterator.toArray()).toEqual([0, 1, 2, 3, 4]);
     });
+    it('should count in 2s, starting from 5', () => {
+        const iterator = ExtraIterator.count({ start: 5, interval: 2 }).take(5);
+        expect(iterator.toArray()).toEqual([5, 7, 9, 11, 13]);
+    });
     it('should repeat a value a given number of times', () => {
-        const iterator = ExtraIterator.repeat(3, 'x');
+        const iterator = ExtraIterator.repeat('x').take(3);
         expect(iterator.toArray()).toEqual(['x', 'x', 'x']);
     });
+    it('should yield random values', () => {
+        const values = ExtraIterator.random().take(5).toArray();
+        expect(values.length).toBe(5);
+        expect(values.every(value => typeof value === 'number')).toBe(true);
+    });
     it('should filter values based on a predicate', () => {
         const iterator = ExtraIterator.from([1, 2, 3, 4]).filter(x => x % 2 === 0);
         expect(iterator.toArray()).toEqual([2, 4]);
@@ -117,6 +126,25 @@ describe('ExtraIterator', () => {
             b: ['banana'],
         });
     });
+    it('should convert to a Map', () => {
+        const iterator = ExtraIterator.from([{ key: 'a', value: 1 }, { key: 'b', value: 2 }, { key: 'a', value: 3 }]);
+        const map = iterator.toMap(item => item.key);
+        expect(map).toBeInstanceOf(Map);
+        expect(map).toEqual(new Map([
+            ['a', [{ key: 'a', value: 1 }, { key: 'a', value: 3 }]],
+            ['b', [{ key: 'b', value: 2 }]],
+        ]));
+    });
+    it('should convert to a Set', () => {
+        const iterator = ExtraIterator.from([3, 1, 3, 2, 2, 1, 3]);
+        const set = iterator.toSet();
+        expect(set).toBeInstanceOf(Set);
+        expect(set.size).toBe(3);
+        expect(set.has(1)).toBe(true);
+        expect(set.has(2)).toBe(true);
+        expect(set.has(3)).toBe(true);
+        expect(set).toEqual(new Set([3, 1, 2]));
+    });
     it('should collect values using a custom collector', () => {
         const iterator = ExtraIterator.from([1, 2, 3]);
         const sum = iterator.collect(iter => Array.from(iter).reduce((a, b) => a + b, 0));
@@ -141,4 +169,8 @@ describe('ExtraIterator', () => {
         const chain = handlers.toChainOfResponsibilityFunction(next => next());
         expect(() => chain()).toThrow();
     });
+    it('should repeat values', () => {
+        const iterator = ExtraIterator.from([1, 2, 3]).loop(3);
+        expect(iterator.toArray()).toEqual([1, 2, 3, 1, 2, 3, 1, 2, 3]);
+    });
 });

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.5.0",
+  "version": "0.7.0",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",

package/dist/chain-of-responsibility.js

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