extra-iterator 0.4.1 → 0.6.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>;
@@ -200,6 +212,18 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      *     // 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.
@@ -231,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.
      */

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
     // =================================================================================================================
@@ -330,6 +353,28 @@ 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.
@@ -401,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
     // -----------------------------------------------------------------------------------------------------------------

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]);
@@ -57,6 +66,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]]);
@@ -137,4 +150,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.4.1",
+  "version": "0.6.0",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",