@aidc-toolkit/utility 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/utility",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Foundational utilities for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -25,15 +25,16 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "^0.9.3",
-    "eslint": "^9.14.0",
+    "@aidc-toolkit/dev": "^0.9.5",
+    "eslint": "^9.15.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^2.1.5"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "^0.9.3",
-    "i18next": "^23.16.5"
+    "@aidc-toolkit/core": "^0.9.5",
+    "@rollup/rollup-linux-x64-gnu": "^4.27.3",
+    "i18next": "^23.16.8"
   }
 }

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./iterator_proxy.js";
 export * from "./sequencer.js";
 export * from "./transformer.js";
 export type * from "./string.js";

package/src/iterator_proxy.ts

@@ -0,0 +1,517 @@
+/**
+ * Iteration source; shortcut for iterator or iterable.
+ *
+ * Client applications should **not** rely on long-term availability of this variable as it will be removed once there
+ * is widespread support for iterator helpers.
+ */
+type IterationSource<T> = Iterator<T> | Iterable<T>;
+
+/**
+ * Iterator proxy base; provides common functionality for all iterator objects.
+ */
+abstract class IteratorProxyBase<TInitial, TFinal> implements IteratorObject<TFinal, undefined> {
+    /**
+     * Convert an iteration source to an iterable.
+     *
+     * @param iterationSource
+     * Iteration source.
+     *
+     * @returns
+     * Iteration source if it is already an iterable, otherwise iteration source wrapped in an iterable.
+     */
+    protected static toIterable<T>(iterationSource: IterationSource<T>): Iterable<T> {
+        return Symbol.iterator in iterationSource ?
+            iterationSource :
+            {
+                [Symbol.iterator](): Iterator<T> {
+                    return iterationSource;
+                }
+            };
+    }
+
+    /**
+     * Initial iterable.
+     */
+    private readonly _initialIterable: Iterable<TInitial>;
+
+    /**
+     * Initial iterator.
+     */
+    private _initialIterator?: Iterator<TInitial>;
+
+    /**
+     * Constructor.
+     *
+     * @param initialIterationSource
+     * Initial iteration source.
+     */
+    constructor(initialIterationSource: IterationSource<TInitial>) {
+        this._initialIterable = IteratorProxyBase.toIterable(initialIterationSource);
+    }
+
+    /**
+     * Get the initial iterable.
+     */
+    protected get initialIterable(): Iterable<TInitial> {
+        return this._initialIterable;
+    }
+
+    /**
+     * Get the initial iterator.
+     */
+    protected get initialIterator(): Iterator<TInitial> {
+        if (this._initialIterator === undefined) {
+            this._initialIterator = this.initialIterable[Symbol.iterator]();
+        }
+
+        return this._initialIterator;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get [Symbol.toStringTag](): string {
+        return "IteratorProxy";
+    }
+
+    /**
+     * @inheritDoc
+     */
+    [Symbol.dispose](): void {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    [Symbol.iterator](): IteratorObject<TFinal, undefined> {
+        return this;
+    }
+
+    /**
+     * Get the next result from the initial iterator.
+     *
+     * @param value
+     * Tuple value to be passed to Iterator.next().
+     *
+     * @returns
+     * Next result from the initial iterator.
+     */
+    protected initialNext(...value: [] | [unknown]): IteratorResult<TInitial, undefined> {
+        return this.initialIterator.next(...value);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    abstract next(...value: [] | [unknown]): IteratorResult<TFinal, undefined>;
+
+    /**
+     * @inheritDoc
+     */
+    map<U>(callback: (value: TFinal, index: number) => U): IteratorObject<U, undefined> {
+        return new IteratorMapProxy(this, callback);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    flatMap<U>(callback: (value: TFinal, index: number) => IterationSource<U>): IteratorObject<U, undefined> {
+        return new IteratorFlatMapProxy(this, callback);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    filter(predicate: (value: TFinal, index: number) => unknown): IteratorObject<TFinal, undefined> {
+        return new IteratorFilterProxy(this, predicate, true);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    take(limit: number): IteratorObject<TFinal, undefined> {
+        return new IteratorTakeProxy(this, limit);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    drop(count: number): IteratorObject<TFinal, undefined> {
+        return new IteratorDropProxy(this, count);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    reduce<U>(callback: (previousValue: U, currentValue: TFinal, currentIndex: number) => U, initialValue?: U): U {
+        let index = 0;
+        let result = initialValue;
+
+        for (const value of this) {
+            // Need to check arguments length as U could include undefined.
+            if (index === 0 && arguments.length === 1) {
+                // Initial value is not supplied only when U is identical to TFinal.
+                result = value as unknown as U;
+            } else {
+                // Iteration has occurred at least once so result is of the expected type.
+                result = callback(result as U, value, index);
+            }
+
+            index++;
+        }
+
+        if (index === 0 && arguments.length === 1) {
+            throw new Error("reduce() of empty iterator with no initial value");
+        }
+
+        // Iteration has occurred at least once so result is of the expected type.
+        return result as U;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    toArray(): TFinal[] {
+        return Array.from(this);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    forEach(callback: (value: TFinal, index: number) => void): void {
+        let index = 0;
+
+        for (const element of this) {
+            callback(element, index++);
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    some(predicate: (value: TFinal, index: number) => unknown): boolean {
+        // Filter until predicate returns truthy; return true if found.
+        return new IteratorFilterProxy(this, predicate, true).next().done !== true;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    every(predicate: (value: TFinal, index: number) => unknown): boolean {
+        // Filter until predicate returns falsy; return false if found.
+        return new IteratorFilterProxy(this, predicate, false).next().done === true;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    find(predicate: (value: TFinal, index: number) => unknown): TFinal | undefined {
+        // Filter until predicate returns truthy; return value.
+        return new IteratorFilterProxy(this, predicate, true).next().value;
+    }
+}
+
+/**
+ * Core iterator proxy object.
+ */
+class IteratorProxyObject<T> extends IteratorProxyBase<T, T> {
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        // Initial result is the final result.
+        return this.initialNext(...value);
+    }
+}
+
+/**
+ * Iterator map proxy base.
+ */
+abstract class IteratorMapProxyBase<TInitial, TIntermediate, TFinal> extends IteratorProxyBase<TInitial, TFinal> {
+    /**
+     * Callback.
+     */
+    private readonly _callback: (element: TInitial, index: number) => TIntermediate;
+
+    /**
+     * Index into initial iteration source.
+     */
+    private _index: number;
+
+    /**
+     * Constructor.
+     *
+     * @param initialIterationSource
+     * Initial iteration source.
+     *
+     * @param callback
+     * Callback.
+     */
+    constructor(initialIterationSource: IterationSource<TInitial>, callback: (element: TInitial, index: number) => TIntermediate) {
+        super(initialIterationSource);
+
+        this._callback = callback;
+        this._index = 0;
+    }
+
+    /**
+     * Get the next result from the intermediate iterator.
+     *
+     * @param value
+     * Tuple value to be passed to Iterator.next().
+     *
+     * @returns
+     * Next result from the intermediate iterator.
+     */
+    protected intermediateNext(...value: [] | [unknown]): IteratorResult<TIntermediate, undefined> {
+        const initialResult = this.initialNext(...value);
+
+        return initialResult.done !== true ?
+            {
+                value: this._callback(initialResult.value, this._index++)
+            } :
+            {
+                done: true,
+                value: undefined
+            };
+    }
+}
+
+/**
+ * Iterator map proxy.
+ */
+class IteratorMapProxy<TInitial, TFinal> extends IteratorMapProxyBase<TInitial, TFinal, TFinal> {
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<TFinal, undefined> {
+        // Intermediate result is the final result.
+        return this.intermediateNext(...value);
+    }
+}
+
+/**
+ * Iterator flat map proxy.
+ */
+class IteratorFlatMapProxy<TInitial, TFinal> extends IteratorMapProxyBase<TInitial, IterationSource<TFinal>, TFinal> {
+    private _intermediateIterator: Iterator<TFinal, undefined> | undefined;
+
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<TFinal, undefined> {
+        let finalResult: IteratorResult<TFinal, undefined> | undefined = undefined;
+
+        do {
+            if (this._intermediateIterator === undefined) {
+                const intermediateResult = this.intermediateNext(...value);
+
+                if (intermediateResult.done === true) {
+                    finalResult = intermediateResult;
+                } else {
+                    this._intermediateIterator = IteratorProxyBase.toIterable(intermediateResult.value)[Symbol.iterator]();
+                }
+            } else {
+                const pendingFinalResult = this._intermediateIterator.next();
+
+                if (pendingFinalResult.done === true) {
+                    this._intermediateIterator = undefined;
+                } else {
+                    finalResult = pendingFinalResult;
+                }
+            }
+        } while (finalResult === undefined);
+
+        return finalResult;
+    }
+}
+
+/**
+ * Iterator filter proxy.
+ */
+class IteratorFilterProxy<T> extends IteratorProxyBase<T, T> {
+    /**
+     * Predicate.
+     */
+    private readonly _predicate: (value: T, index: number) => unknown;
+
+    /**
+     * Expected truthy result of the predicate.
+     */
+    private readonly _expectedTruthy: boolean;
+
+    /**
+     * Index into iteration source.
+     */
+    private _index: number;
+
+    /**
+     * Constructor.
+     *
+     * @param iterationSource
+     * Iteration source.
+     *
+     * @param predicate
+     * Predicate.
+     *
+     * @param expectedTruthy
+     * Expected truthy result of the predicate.
+     */
+    constructor(iterationSource: IterationSource<T>, predicate: (element: T, index: number) => unknown, expectedTruthy: boolean) {
+        super(iterationSource);
+
+        this._predicate = predicate;
+        this._expectedTruthy = expectedTruthy;
+
+        this._index = 0;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        let result: IteratorResult<T, undefined> | undefined;
+
+        const expectedTruthy = this._expectedTruthy;
+
+        do {
+            result = this.initialNext(...value);
+        } while (result.done !== true && Boolean(this._predicate(result.value, this._index++)) !== expectedTruthy);
+
+        return result;
+    }
+}
+
+/**
+ * Iterator count proxy base.
+ */
+abstract class IteratorCountProxyBase<T> extends IteratorProxyObject<T> {
+    /**
+     * Count.
+     */
+    private _count: number;
+
+    /**
+     * Constructor.
+     *
+     * @param initialIterationSource
+     * Initial iteration source.
+     *
+     * @param count
+     * Count.
+     */
+    constructor(initialIterationSource: IterationSource<T>, count: number) {
+        super(initialIterationSource);
+
+        if (!Number.isInteger(count) || count < 0) {
+            throw new RangeError("Count must be a positive integer");
+        }
+
+        this._count = count;
+    }
+
+    /**
+     * Determine if iterator is exhausted (by count or by iterator itself).
+     */
+    protected get exhausted(): boolean {
+        return this._count <= 0;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    override next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        const result = super.next(...value);
+
+        if (result.done !== true) {
+            this._count--;
+        } else {
+            // Iterator exhausted before count.
+            this._count = 0;
+        }
+
+        return result;
+    }
+}
+
+/**
+ * Iterator take proxy.
+ */
+class IteratorTakeProxy<T> extends IteratorCountProxyBase<T> {
+    /**
+     * @inheritDoc
+     */
+    override next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        return !this.exhausted ?
+            super.next(...value) :
+            {
+                done: true,
+                value: undefined
+            };
+    }
+}
+
+/**
+ * Iterator drop proxy.
+ */
+class IteratorDropProxy<T> extends IteratorCountProxyBase<T> {
+    /**
+     * @inheritDoc
+     */
+    override next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        while (!this.exhausted) {
+            super.next(...value);
+        }
+
+        return super.next(...value);
+    }
+}
+
+/**
+ * Get Iterator variable if supported or a proxy for it if not.
+ *
+ * @returns
+ * Iterator variable if supported or a proxy for it if not.
+ */
+function iteratorProxy(): Pick<typeof Iterator, "from"> {
+    let supported: boolean;
+
+    try {
+        // Not supported if in testing.
+        supported = process.env["NODE_ENV"] !== "test";
+    } catch (_e) {
+        // Assume supported.
+        supported = true;
+    }
+
+    if (supported) {
+        try {
+            // This will throw a ReferenceError if Iterator variable is not supported.
+            Iterator.from([]);
+        } catch (_e) {
+            supported = false;
+        }
+    }
+
+    return supported ?
+        Iterator :
+        {
+            /**
+             * @inheritDoc
+             */
+            from<T>(value: Iterator<T> | Iterable<T>): IteratorObject<T, undefined> {
+                return value instanceof IteratorProxyBase ? value : new IteratorProxyObject(value);
+            }
+        };
+}
+
+/**
+ * Iterator proxy. In environments where
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helpers |
+ * iterator helpers} are supported, this references the {@link Iterator} variable directly. Otherwise, it references an
+ * implementation of "from" that uses an internally-defined iterator proxy object.
+ *
+ * Client applications should **not** rely on long-term availability of this variable as it will be removed once there
+ * is widespread support for iterator helpers.
+ */
+export const IteratorProxy = iteratorProxy();

package/src/transformer.ts

@@ -1,3 +1,4 @@
+import { IteratorProxy } from "./iterator_proxy.js";
 import i18next, { utilityNS } from "./locale/i18n.js";
 import { Sequencer } from "./sequencer.js";
 
@@ -266,18 +267,18 @@ export abstract class Transformer {
             }
 
             result = transformationCallback === undefined ?
-                Iterator.from(valueOrValues).map(value => this.doForward(value)) :
-                Iterator.from(valueOrValues).map((value, index) => transformationCallback(this.doForward(value), index));
+                IteratorProxy.from(valueOrValues).map(value => this.doForward(value)) :
+                IteratorProxy.from(valueOrValues).map((value, index) => transformationCallback(this.doForward(value), index));
         } else {
             result = transformationCallback === undefined ?
-                Iterator.from(valueOrValues).map((value) => {
+                IteratorProxy.from(valueOrValues).map((value) => {
                     const valueN = BigInt(value);
 
                     this.validate(valueN);
 
                     return this.doForward(valueN);
                 }) :
-                Iterator.from(valueOrValues).map((value, index) => {
+                IteratorProxy.from(valueOrValues).map((value, index) => {
                     const valueN = BigInt(value);
 
                     this.validate(valueN);

package/test/character_set.test.ts

@@ -6,11 +6,12 @@ import {
     CharacterSetCreator,
     Exclusion,
     HEXADECIMAL_CREATOR,
+    IteratorProxy,
     NUMERIC_CREATOR,
     Sequencer
 } from "../src/index.js";
 
-await i18nInit(I18NEnvironment.CLI, true);
+await i18nInit(I18NEnvironment.CLI);
 
 function testCharacterSetCreator(name: string, characterSetCreator: CharacterSetCreator, characterSetSize: number, length: number, excludeFirstZero: boolean, excludeAllNumeric: boolean): void {
     describe(name, () => {
@@ -64,7 +65,7 @@ function testCharacterSetCreator(name: string, characterSetCreator: CharacterSet
                     break;
             }
 
-            const sequence = Iterator.from(characterSetCreator.create(length, new Sequencer(0n, domain), exclusion));
+            const sequence = IteratorProxy.from(characterSetCreator.create(length, new Sequencer(0n, domain), exclusion));
 
             let previousS = "";
 
@@ -85,7 +86,7 @@ function testCharacterSetCreator(name: string, characterSetCreator: CharacterSet
 
             expect(() => characterSetCreator.create(length, domain, exclusion)).toThrow(`Value ${domain} must be less than ${domain}`);
 
-            const sparseSequence = Iterator.from(characterSetCreator.create(length, new Sequencer(domain - 1, -domain), exclusion, 123456n));
+            const sparseSequence = IteratorProxy.from(characterSetCreator.create(length, new Sequencer(domain - 1, -domain), exclusion, 123456n));
 
             let sequential = true;
             previousS = "~";
@@ -193,7 +194,7 @@ testCharacterSetCreator("Hexadecimal", HEXADECIMAL_CREATOR, 16, 4, true, true);
 testCharacterSetCreator("Alphabetic", ALPHABETIC_CREATOR, 26, 3, false, false);
 testCharacterSetCreator("Alphanumeric", ALPHANUMERIC_CREATOR, 36, 3, true, true);
 testCharacterSetCreator("Middle numeric", new CharacterSetCreator([
-    "(", ")", "*", "+",
+    "(", ")",
     "0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
-    ":", ";", "<", ">"
-], Exclusion.AllNumeric), 18, 4, false, true);
+    "<", ">"
+], Exclusion.AllNumeric), 14, 4, false, true);