extra-iterator 0.11.1 → 0.13.0

package/dist/index.d.ts

@@ -3,6 +3,33 @@ interface ArrayIsh<T> {
     length: number;
 }
 export type ExtraIteratorSource<T> = Iterator<T, any, any> | Iterable<T, any, any> | ArrayIsh<T>;
+/**
+ * An extended iterator class that provides additional chainable utility methods for working with iterables.
+ *
+ * @template T The type of values yielded by this iterator.
+ *
+ * @example
+ * // Creating an iterator from an array
+ * const iter = ExtraIterator.from([1, 2, 3, 4, 5]);
+ *
+ * @example
+ * // Creating a sequence of ancestors of a given element
+ * ExtraIterator.from(function*() {
+ *
+ * }()).toArray();
+ * ExtraIterator.from([1, 2, 3, 4, 5])
+ *   .filter(n => n % 2 === 0)
+ *   .map(n => n * 2)
+ *   .toArray()
+ *   // returns [4, 8]
+ *
+ * @example
+ * // Using static factory methods
+ * ExtraIterator.range(1, 5)
+ *   .map(n => n * n)
+ *   .toArray()
+ *   // returns [1, 4, 9, 16]
+ */
 export declare class ExtraIterator<T> extends Iterator<T, any, any> {
     static from<T>(source: ExtraIteratorSource<T>): ExtraIterator<T>;
     static zip<A, B>(a: ExtraIteratorSource<A>, b: ExtraIteratorSource<B>): ExtraIterator<[A, B]>;
@@ -25,6 +52,12 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      * @example ExtraIterator.empty().toArray() // returns []
      */
     static empty<T = any>(): ExtraIterator<T>;
+    /**
+     * Creates an iterator that yields a single value.
+     *
+     * @example ExtraIterator.single(42).toArray() // returns [42]
+     */
+    static single<T>(value: T): ExtraIterator<T>;
     /**
      * Creates an iterator that yields incrementing numbers.
      *
@@ -70,14 +103,30 @@ export declare class ExtraIterator<T> extends Iterator<T, any, any> {
      */
     static repeat<T>(value: T): ExtraIterator<T>;
     /**
-     * Generates an infinite sequence of cryptographically strong random bytes using `crypto.getRandomValues`. Each
-     * yielded value is a number in between 0 and 255 (inclusive).
+     * Generates an infinite sequence of random numbers between 0 and 1 (exclusive) using `Math.random` or another
+     * specified random number generator.
      *
      * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
      */
-    static random({ bufferSize }?: {
-        bufferSize?: number | undefined;
-    }): ExtraIterator<number>;
+    static random(rng?: () => number): ExtraIterator<number>;
+    /**
+     * Generates an infinite sequence of cryptographically strong random bytes using `crypto.getRandomValues`, in
+     * chunks of `chunkSize` bytes.
+     *
+     * By default, this method reuses the same `ArrayBuffer` instance for each chunk, refilling it with new random
+     * values at each iteration, so you should not keep references to the yielded buffers. Set `reuseBuffer` to `false`
+     * if you want this method to yield copies of the buffer instead.
+     *
+     * If you want a flat sequence of individual byte values instead of chunks, you can chain the iterator returned by
+     * this method with the {@link flatten} method. The resulting iterator will contain interger values from 0 to 255
+     * (inclusive).
+     *
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
+     */
+    static randomBytes({ chunkSize, reuseBuffer }?: {
+        chunkSize?: number | undefined;
+        reuseBuffer?: boolean | undefined;
+    }): ExtraIterator<ArrayBuffer>;
     private constructor();
     private source;
     next(value?: any): IteratorResult<T, any>;

package/dist/index.js

@@ -1,8 +1,34 @@
+/**
+ * An extended iterator class that provides additional chainable utility methods for working with iterables.
+ *
+ * @template T The type of values yielded by this iterator.
+ *
+ * @example
+ * // Creating an iterator from an array
+ * const iter = ExtraIterator.from([1, 2, 3, 4, 5]);
+ *
+ * @example
+ * // Creating a sequence of ancestors of a given element
+ * ExtraIterator.from(function*() {
+ *
+ * }()).toArray();
+ * ExtraIterator.from([1, 2, 3, 4, 5])
+ *   .filter(n => n % 2 === 0)
+ *   .map(n => n * 2)
+ *   .toArray()
+ *   // returns [4, 8]
+ *
+ * @example
+ * // Using static factory methods
+ * ExtraIterator.range(1, 5)
+ *   .map(n => n * n)
+ *   .toArray()
+ *   // returns [1, 4, 9, 16]
+ */
 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) {
             return new ExtraIterator(function* () {
@@ -29,6 +55,14 @@ export class ExtraIterator extends Iterator {
     static empty() {
         return new ExtraIterator([]);
     }
+    /**
+     * Creates an iterator that yields a single value.
+     *
+     * @example ExtraIterator.single(42).toArray() // returns [42]
+     */
+    static single(value) {
+        return new ExtraIterator([value]);
+    }
     /**
      * Creates an iterator that yields incrementing numbers.
      *
@@ -98,16 +132,37 @@ export class ExtraIterator extends Iterator {
         }());
     }
     /**
-     * Generates an infinite sequence of cryptographically strong random bytes using `crypto.getRandomValues`. Each
-     * yielded value is a number in between 0 and 255 (inclusive).
+     * Generates an infinite sequence of random numbers between 0 and 1 (exclusive) using `Math.random` or another
+     * specified random number generator.
      *
      * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
      */
-    static random({ bufferSize = 1024 } = {}) {
-        const buffer = new Uint8Array(bufferSize);
+    static random(rng = Math.random) {
+        return ExtraIterator.from(function* () {
+            while (true) {
+                yield rng();
+            }
+        }());
+    }
+    /**
+     * Generates an infinite sequence of cryptographically strong random bytes using `crypto.getRandomValues`, in
+     * chunks of `chunkSize` bytes.
+     *
+     * By default, this method reuses the same `ArrayBuffer` instance for each chunk, refilling it with new random
+     * values at each iteration, so you should not keep references to the yielded buffers. Set `reuseBuffer` to `false`
+     * if you want this method to yield copies of the buffer instead.
+     *
+     * If you want a flat sequence of individual byte values instead of chunks, you can chain the iterator returned by
+     * this method with the {@link flatten} method. The resulting iterator will contain interger values from 0 to 255
+     * (inclusive).
+     *
+     * > ⚠ This iterator is infinite. Use {@link take} method if you want a specific number of values.
+     */
+    static randomBytes({ chunkSize = 1024, reuseBuffer = true } = {}) {
+        const bytes = new Uint8Array(chunkSize);
         return new ExtraIterator(function* () {
-            globalThis.crypto.getRandomValues(buffer);
-            yield* new Uint8Array(buffer);
+            globalThis.crypto.getRandomValues(bytes);
+            yield reuseBuffer ? bytes.buffer : new Uint8Array(bytes).buffer;
         }())
             .loop();
     }
@@ -140,17 +195,19 @@ export class ExtraIterator extends Iterator {
     take(limit) {
         return limit >= 0
             ? ExtraIterator.from(super.take(limit))
-            : ExtraIterator.from(this.takeLast(-limit));
+            : this.takeLast(-limit);
     }
     takeLast(count) {
-        const result = [];
-        for (let item; item = this.next(), !item.done;) {
-            result.push(item.value);
-            if (result.length > count) {
-                result.shift();
-            }
+        const ringbuffer = new Array(count);
+        let index = 0;
+        for (let item; item = this.next(), !item.done; index = (index + 1) % count) {
+            ringbuffer[index] = item.value;
         }
-        return result;
+        return ExtraIterator.from(function* () {
+            for (let i = index; i < count + index; i++) {
+                yield ringbuffer[i % count];
+            }
+        }());
     }
     drop(count) {
         return count >= 0
@@ -174,7 +231,11 @@ export class ExtraIterator extends Iterator {
      * @example ExtraIterator.from([[1, 2], [3, 4]]).flatten().toArray() // returns [1, 2, 3, 4]
      */
     flatten() {
-        return this.flatMap(value => Array.isArray(value) ? new ExtraIterator(value).flatten() : [value]);
+        return this.flatMap(value => typeof value === 'object'
+            && value !== null
+            && Symbol.iterator in value
+            ? new ExtraIterator(value).flatten()
+            : [value]);
     }
     /**
      * Creates a new iterator that yields the values of this iterator, but won't yield any duplicates.

package/dist/index.test.js

@@ -37,10 +37,15 @@ describe(ExtraIterator.name, () => {
         const iterator = ExtraIterator.repeat('x').take(3);
         expect(iterator.toArray()).toEqual(['x', 'x', 'x']);
     });
-    it('should yield random values', () => {
+    it('should yield random numbers', () => {
         const values = ExtraIterator.random().take(10000).toArray();
         expect(values.length).toBe(10000);
-        expect(values.every(value => typeof value === 'number' && value >= 0 && value < 256)).toBe(true);
+        expect(values.every(value => typeof value === 'number' && value >= 0 && value < 1)).toBe(true);
+    });
+    it('should yield random bytes', () => {
+        const values = ExtraIterator.randomBytes({ chunkSize: 1024 }).take(1).map(chunk => new Uint8Array(chunk)).flatten().toArray();
+        expect(values.length).toBe(1024);
+        expect(values.every(value => typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 255)).toBe(true);
     });
     it('should filter values based on a predicate', () => {
         const iterator = ExtraIterator.from([1, 2, 3, 4]).filter(x => x % 2 === 0);
@@ -70,6 +75,10 @@ describe(ExtraIterator.name, () => {
         const iterator = ExtraIterator.from([1, 2, 3]);
         expect(iterator.first()).toBe(1);
     });
+    it('should have a single value', () => {
+        const iterator = ExtraIterator.single(42);
+        expect(iterator.first()).toBe(42);
+    });
     describe(ExtraIterator.prototype.last.name, () => {
         it('should return the last value if the iterator is not empty', () => {
             const iterator = ExtraIterator.from([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.11.1",
+  "version": "0.13.0",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -13,9 +13,11 @@
     "dist"
   ],
   "scripts": {
-    "test": "run-s test:types test:unit",
+    "test": "run-p test:*",
     "test:types": "tsc --noEmit",
     "test:unit": "node --import=tsx --test **/*.test.ts",
+    "coverage": "run-s build coverage:test",
+    "coverage:test": "node --import=tsx --test --experimental-test-coverage",
     "build": "tsc",
     "prebuild": "rimraf dist",
     "prepack": "run-s test build"