@aidc-toolkit/utility 0.9.2 → 0.9.4

package/.idea/runConfigurations/Test_iterator_proxy.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Test iterator proxy" type="JavaScriptTestRunnerVitest">
+    <node-interpreter value="project" />
+    <vitest-package value="$PROJECT_DIR$/node_modules/vitest" />
+    <working-dir value="$PROJECT_DIR$" />
+    <vitest-options value="--run" />
+    <envs />
+    <scope-kind value="TEST_FILE" />
+    <test-file value="$PROJECT_DIR$/test/iterator_proxy.test.ts" />
+    <method v="2" />
+  </configuration>
+</component>

package/eslint.config.js

@@ -1,13 +1,3 @@
-import tseslint from "typescript-eslint";
-import stylistic from "@stylistic/eslint-plugin";
-import jsdoc from "eslint-plugin-jsdoc";
-import esLintConfigLove from "eslint-config-love";
 import { esLintConfigAIDCToolkit } from "@aidc-toolkit/dev";
 
-export default tseslint.config(
-    ...tseslint.configs.strictTypeChecked,
-    stylistic.configs["recommended-flat"],
-    jsdoc.configs["flat/recommended-typescript"],
-    esLintConfigLove,
-    ...esLintConfigAIDCToolkit
-);
+export default esLintConfigAIDCToolkit;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/utility",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Foundational utilities for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -21,22 +21,19 @@
   "scripts": {
     "eslint": "eslint .",
     "build": "tsup src/index.ts --clean --format cjs,esm --dts",
-    "build-dev": "npm run build && tsc src/index.ts --outDir dist --target esnext --moduleResolution nodenext --module nodenext --emitDeclarationOnly --declaration --declarationMap",
+    "build-doc": "npm run build && tsc src/index.ts --outDir dist --target esnext --moduleResolution nodenext --module nodenext --emitDeclarationOnly --declaration --declarationMap",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "^0.9.2",
-    "@stylistic/eslint-plugin": "^2.10.1",
-    "eslint-config-love": "^98.0.2",
-    "eslint-plugin-jsdoc": "^50.5.0",
+    "@aidc-toolkit/dev": "^0.9.4",
+    "eslint": "^9.15.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
-    "typescript-eslint": "^8.14.0",
-    "vitest": "^2.1.4"
+    "vitest": "^2.1.5"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "^0.9.2",
+    "@aidc-toolkit/core": "^0.9.4",
     "i18next": "^23.16.5"
   }
 }

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,529 @@
+/**
+ * Determine if Iterator variable is supported.
+ *
+ * @returns
+ * True if Iterator variable is supported.
+ */
+function isIteratorSupported(): boolean {
+    let supported: boolean;
+
+    try {
+        // Not supported if in testing.
+        supported = process.env["NODE_ENV"] !== "test";
+    } catch (_e) {
+        // Assume supported.
+        supported = true;
+    }
+
+    if (supported) {
+        try {
+            Iterator.from([]);
+        } catch (_e) {
+            supported = false;
+        }
+    }
+
+    return supported;
+}
+
+/**
+ * Iteration source; shortcut for iterator or iterable.
+ */
+export type IterationSource<T> = Iterator<T> | Iterable<T>;
+
+/**
+ * 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 interable.
+ */
+function iterationSourceToIterable<T>(iterationSource: IterationSource<T>): Iterable<T> {
+    return Symbol.iterator in iterationSource ?
+        iterationSource :
+        {
+            [Symbol.iterator](): Iterator<T> {
+                return iterationSource;
+            }
+        };
+}
+
+/**
+ * Iterator proxy base; provides common functionality for all iterator objects.
+ */
+abstract class IteratorProxyBase<TInitial, TFinal> implements IteratorObject<TFinal, undefined> {
+    /**
+     * 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 = iterationSourceToIterable(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>(callbackfn: (value: TFinal, index: number) => U): IteratorObject<U, undefined> {
+        return new IteratorMapProxy(this, callbackfn);
+    }
+
+    /**
+     * @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);
+    }
+
+    /**
+     * @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>(callbackfn: (previousValue: U, currentValue: TFinal, currentIndex: number) => U, initialValue?: U): U {
+        let index = 0;
+        let result = initialValue;
+
+        for (const value of this) {
+            if (index === 0 && initialValue === undefined) {
+                // Initial value is undefined only when TFinal and U are identical.
+                result = value as unknown as U;
+            } else {
+                // Iteration has occurred at least once so result is of the expected type.
+                result = callbackfn(result as U, value, index);
+            }
+
+            index++;
+        }
+
+        if (index === 0 && initialValue === undefined) {
+            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(callbackfn: (value: TFinal, index: number) => void): void {
+        let index = 0;
+
+        for (const element of this) {
+            callbackfn(element, index++);
+        }
+    }
+
+    /**
+     * Iterate until the truthy result of the predicate changes or until the iterator is exhausted.
+     *
+     * @param predicate
+     * Predicate.
+     *
+     * @param initialTruthy
+     * Initial truthy result of the predicate.
+     *
+     * @returns
+     * Iterator result.
+     */
+    private untilChanged(predicate: (value: TFinal, index: number) => unknown, initialTruthy: boolean): IteratorResult<TFinal, undefined> {
+        let result: IteratorResult<TFinal, undefined> | undefined;
+
+        const iterator = this[Symbol.iterator]();
+        let index = 0;
+
+        do {
+            result = iterator.next();
+
+            if (result.done !== true) {
+                const truthy = Boolean(predicate(result.value, index++));
+
+                if (truthy === initialTruthy) {
+                    result = undefined;
+                }
+            }
+        } while (result === undefined);
+
+        return result;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    some(predicate: (value: TFinal, index: number) => unknown): boolean {
+        // Iterate until predicate returns truthy; return done status.
+        return this.untilChanged(predicate, false).done !== true;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    every(predicate: (value: TFinal, index: number) => unknown): boolean {
+        // Iterate until predicate returns falsy; return done status.
+        return this.untilChanged(predicate, true).done === true;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    find(predicate: (value: TFinal, index: number) => unknown): TFinal | undefined {
+        // Iterate until predicate returns truthy; return value.
+        return this.untilChanged(predicate, false).value;
+    }
+}
+
+/**
+ * Core iterator proxy object.
+ */
+class IteratorProxyObject<T> extends IteratorProxyBase<T, T> {
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        return this.initialNext(...value);
+    }
+}
+
+/**
+ * Iterator callback proxy base.
+ */
+abstract class IteratorCallbackProxyBase<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 initialResult
+     * Next result from the initial iterator.
+     *
+     * @returns
+     * Next result from the intermediate iterator.
+     */
+    protected intermediateNext(initialResult: IteratorResult<TInitial, undefined>): IteratorResult<TIntermediate, undefined> {
+        let intermediateResult: IteratorResult<TIntermediate, undefined>;
+
+        if (initialResult.done !== true) {
+            intermediateResult = {
+                done: false,
+                value: this._callback(initialResult.value, this._index++)
+            };
+        } else {
+            intermediateResult = {
+                done: true,
+                value: undefined
+            };
+        }
+
+        return intermediateResult;
+    }
+}
+
+/**
+ * Iterator map proxy.
+ */
+class IteratorMapProxy<TInitial, TFinal> extends IteratorCallbackProxyBase<TInitial, TFinal, TFinal> {
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<TFinal, undefined> {
+        return this.intermediateNext(this.initialNext(...value));
+    }
+}
+
+/**
+ * Iterator flat map proxy.
+ */
+class IteratorFlatMapProxy<TInitial, TFinal> extends IteratorCallbackProxyBase<TInitial, IterationSource<TFinal>, TFinal> {
+    private _pendingFinalIterator: Iterator<TFinal, undefined> | undefined;
+
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<TFinal, undefined> {
+        let finalResult: IteratorResult<TFinal, undefined> | undefined = undefined;
+
+        do {
+            if (this._pendingFinalIterator === undefined) {
+                const intermediateResult = this.intermediateNext(this.initialNext(...value));
+
+                if (intermediateResult.done === true) {
+                    finalResult = intermediateResult;
+                } else {
+                    this._pendingFinalIterator = iterationSourceToIterable(intermediateResult.value)[Symbol.iterator]();
+                }
+            }
+
+            if (this._pendingFinalIterator !== undefined) {
+                const pendingFinalResult = this._pendingFinalIterator.next();
+
+                if (pendingFinalResult.done === true) {
+                    this._pendingFinalIterator = undefined;
+                } else {
+                    finalResult = {
+                        done: false,
+                        value: pendingFinalResult.value
+                    };
+                }
+            }
+        } while (finalResult === undefined);
+
+        return finalResult;
+    }
+}
+
+/**
+ * Iterator filter proxy.
+ */
+class IteratorFilterProxy<T> extends IteratorCallbackProxyBase<T, unknown, T> {
+    /**
+     * @inheritDoc
+     */
+    next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        let finalResult: IteratorResult<T, undefined> | undefined = undefined;
+
+        do {
+            const initialResult = this.initialNext(...value);
+
+            if (initialResult.done === true) {
+                finalResult = {
+                    done: true,
+                    value: undefined
+                };
+            } else {
+                const intermediateResult = this.intermediateNext(initialResult);
+                const booleanValue = Boolean(intermediateResult.value);
+
+                if (booleanValue) {
+                    finalResult = {
+                        done: false,
+                        value: initialResult.value
+                    };
+                }
+            }
+        } while (finalResult === undefined);
+
+        return finalResult;
+    }
+}
+
+/**
+ * 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("Limit must be a positive integer");
+        }
+
+        this._count = count;
+    }
+
+    /**
+     * Determine if count is exhausted.
+     */
+    protected get countExhausted(): boolean {
+        // Decrementing the count may go below zero so use less-than-or-equal comparison.
+        return this._count-- <= 0;
+    }
+}
+
+/**
+ * Iterator take proxy.
+ */
+class IteratorTakeProxy<T> extends IteratorCountProxyBase<T> {
+    /**
+     * @inheritDoc
+     */
+    override next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        return this.countExhausted ?
+            {
+                done: true,
+                value: undefined
+            } :
+            super.next(...value);
+    }
+}
+
+/**
+ * Iterator drop proxy.
+ */
+class IteratorDropProxy<T> extends IteratorCountProxyBase<T> {
+    /**
+     * @inheritDoc
+     */
+    override next(...value: [] | [unknown]): IteratorResult<T, undefined> {
+        let result: IteratorResult<T, undefined> | undefined = undefined;
+
+        do {
+            result = super.next(...value);
+
+            if (result.done !== true && !this.countExhausted) {
+                // Discard result.
+                result = undefined;
+            }
+        } while (result === undefined);
+
+        return result;
+    }
+}
+
+/**
+ * Iterator type.
+ */
+type IteratorType = typeof Iterator;
+
+/**
+ * Iterator proxy is interested only in the "from" method.
+ */
+type IteratorProxyType = Pick<IteratorType, "from">;
+
+/**
+ * Iterator proxy. In environments where the Iterator variable is supported, this is the Iterator variable. Otherwise,
+ * it's an implementation of "from" that uses an internally-defined iterator proxy object.
+ */
+export const IteratorProxy: IteratorProxyType = isIteratorSupported() ?
+    Iterator :
+    {
+        /**
+         * @inheritDoc
+         */
+        from<T>(value: IterationSource<T>): IteratorObject<T, undefined> {
+            return value instanceof IteratorProxyBase ? value : new IteratorProxyObject(value);
+        }
+    };

package/src/locale/fr/locale_strings.ts

@@ -0,0 +1,32 @@
+export const localeStrings = {
+    Transformer: {
+        domainMustBeGreaterThanZero: "Le domaine {{domain}} doit être supérieur à 0",
+        tweakMustBeGreaterThanOrEqualToZero: "Le réglage {{tweak}} doit être supérieur ou égal à 0",
+        valueMustBeGreaterThanOrEqualToZero: "La valeur {{value}} doit être supérieure ou égale à 0",
+        valueMustBeLessThan: "La valeur {{value}} doit être inférieure à {{domain}}",
+        minValueMustBeGreaterThanOrEqualToZero: "La valeur minimale {{minValue}} doit être supérieure ou égale à 0",
+        maxValueMustBeLessThan: "La valeur maximale {{maxValue}} doit être inférieure à {{domain}}"
+    },
+    RegExpValidator: {
+        stringDoesNotMatchPattern: "La chaîne {{s}} ne correspond pas au modèle"
+    },
+    CharacterSetValidator: {
+        firstZeroFirstCharacter: "Le jeu de caractères doit prendre en charge zéro comme premier caractère",
+        allNumericAllNumericCharacters: "Le jeu de caractères doit prendre en charge tous les caractères numériques en séquence",
+        stringMustNotBeAllNumeric: "La chaîne ne doit pas être entièrement numérique",
+        lengthMustBeGreaterThanOrEqualTo: "La longueur {{length}} doit être supérieure ou égale à {{minimumLength}}",
+        lengthMustBeLessThanOrEqualTo: "La longueur {{length}} doit être inférieure ou égale à {{maximumLength}}",
+        lengthMustBeEqualTo: "La longueur {{length}} doit être égale à {{exactLength}}",
+        lengthOfComponentMustBeGreaterThanOrEqualTo: "La longueur {{length}} de {{component}} doit être supérieure ou égale à {{minimumLength}}",
+        lengthOfComponentMustBeLessThanOrEqualTo: "La longueur {{length}} de {{component}} doit être inférieure ou égale à {{maximumLength}}",
+        lengthOfComponentMustBeEqualTo: "La longueur {{length}} de {{component}} doit être égale à {{exactLength}}",
+        invalidCharacterAtPosition: "Caractère non valide '{{c}}' à la position {{position}}",
+        invalidCharacterAtPositionOfComponent: "Caractère non valide '{{c}}' à la position {{position}} de {{component}}",
+        exclusionNotSupported: "La valeur d'exclusion de {{exclusion}} n'est pas prise en charge",
+        invalidTweakWithAllNumericExclusion: "Le réglage ne doit pas être utilisé avec une exclusion entièrement numérique",
+        endSequenceValueMustBeLessThanOrEqualTo: "La valeur de la séquence de fin (valeur de la séquence de début + nombre - 1) doit être inférieure à {{domaine}}"
+    },
+    RecordValidator: {
+        typeNameKeyNotFound: "{{typeName}} \"{{key}}\" introuvable"
+    }
+} as const;

package/src/locale/i18n.ts

@@ -1,8 +1,12 @@
-import { i18nAddResourceBundle, i18next } from "@aidc-toolkit/core";
+import { i18nAddResourceBundle, i18nAssertValidResources, i18next } from "@aidc-toolkit/core";
 import { localeStrings as enLocaleStrings } from "./en/locale_strings.js";
+import { localeStrings as frLocaleStrings } from "./fr/locale_strings.js";
 
 export const utilityNS = "aidct_utility";
 
+i18nAssertValidResources(enLocaleStrings, "fr", frLocaleStrings);
+
 i18nAddResourceBundle("en", utilityNS, enLocaleStrings);
+i18nAddResourceBundle("fr", utilityNS, frLocaleStrings);
 
 export default i18next;

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,6 +6,7 @@ import {
     CharacterSetCreator,
     Exclusion,
     HEXADECIMAL_CREATOR,
+    IteratorProxy,
     NUMERIC_CREATOR,
     Sequencer
 } from "../src/index.js";
@@ -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 = "~";

package/test/iterator_proxy.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, test } from "vitest";
+import { type IterationSource, IteratorProxy } from "../src/index.js";
+
+const source: readonly string[] = [
+    "1", "2", "3", "4", "5"
+];
+
+function iterableSource(): Iterable<string> {
+    return [...source];
+}
+
+function arraySource(): string[] {
+    return [...source];
+}
+
+function iteratorSource(): Iterator<string> {
+    return [...source][Symbol.iterator]();
+}
+
+function * generatorSource(): Generator<string> {
+    for (const s of source) {
+        yield s;
+    }
+}
+
+function callbackSource(): string[] {
+    return [...source];
+}
+
+describe("Basic", () => {
+    function validateIterable(iterationSource: IterationSource<string>): void {
+        const iteratorProxy = IteratorProxy.from(iterationSource);
+
+        expect(IteratorProxy.from(iteratorProxy)).toBe(iteratorProxy);
+
+        // @ts-expect-error -- Property exists.
+        expect(iteratorProxy["_initialIterable"]).toBe(iterationSource);
+
+        expect(Array.from(iteratorProxy)).toStrictEqual(source);
+    }
+
+    test("Iterator proxy", () => {
+        expect(IteratorProxy).not.toBe(Iterator);
+    });
+
+    test("Iterable", () => {
+        validateIterable(iterableSource());
+    });
+
+    test("Array", () => {
+        validateIterable(arraySource());
+    });
+
+    test("Iterator", () => {
+        validateIterable(iteratorSource());
+    });
+
+    test("Generator", () => {
+        validateIterable(generatorSource());
+    });
+
+    test("Callback", () => {
+        validateIterable(callbackSource());
+    });
+});
+
+describe("Helpers", () => {
+    test("Map", () => {
+        let count = 0;
+
+        const mapIteratorProxy = IteratorProxy.from(source).map((element, index) => {
+            expect(Number(element)).toBe(index + 1);
+            expect(index).toBe(count++);
+
+            return -count;
+        });
+
+        expect(count).toBe(0);
+
+        let negativeCount = 0;
+
+        for (const element of mapIteratorProxy) {
+            expect(element).toBe(--negativeCount);
+        }
+
+        expect(count).toBe(source.length);
+    });
+
+    test("Flat map", () => {
+        let count = 0;
+
+        const flatMapIteratorProxy = IteratorProxy.from(source).flatMap((element, index) => {
+            expect(Number(element)).toBe(index + 1);
+            expect(index).toBe(count++);
+
+            return [count, -count];
+        });
+
+        expect(count).toBe(0);
+
+        let index = 0;
+
+        for (const element of flatMapIteratorProxy) {
+            const absoluteElement = Math.floor(index / 2) + 1;
+
+            expect(element).toBe(index % 2 === 0 ? absoluteElement : -absoluteElement);
+            index++;
+        }
+
+        expect(count).toBe(source.length);
+    });
+
+    test("Filter", () => {
+        let count = 0;
+
+        const filteredIterable = IteratorProxy.from(source).filter((element, index) => {
+            expect(Number(element)).toBe(index + 1);
+            expect(index).toBe(count++);
+
+            return Number(element) % 2 === 0;
+        });
+
+        expect(count).toBe(0);
+
+        let evenCount = 0;
+
+        for (const element of filteredIterable) {
+            const n = Number(element);
+
+            expect(n % 2).toBe(0);
+            expect(Math.floor((n - 1) / 2)).toBe(evenCount++);
+        }
+
+        expect(count).toBe(source.length);
+        expect(evenCount).toBe(Math.floor(source.length / 2));
+    });
+
+    test("Take", () => {
+        let count = 0;
+
+        for (const element of IteratorProxy.from(source).take(3)) {
+            expect(element).toBe(String(++count));
+        }
+
+        expect(count).toBe(3);
+    });
+
+    test("Drop", () => {
+        let count = 0;
+
+        for (const element of IteratorProxy.from(source).drop(3)) {
+            expect(element).toBe(String(++count + 3));
+        }
+
+        expect(count).toBe(source.length - 3);
+    });
+
+    test("To array", () => {
+        const sourceToArray = IteratorProxy.from(source).toArray();
+
+        expect(sourceToArray).not.toBe(source);
+        expect(sourceToArray).toStrictEqual(source);
+    });
+
+    test("For each", () => {
+        let count = 0;
+
+        IteratorProxy.from(source).forEach((value, index) => {
+            expect(Number(value)).toBe(index + 1);
+            expect(index).toBe(count++);
+        });
+
+        expect(count).toBe(source.length);
+    });
+
+    test("Reduce no initial value", () => {
+        let count = 0;
+
+        expect(IteratorProxy.from(source).reduce((previousValue, currentValue, currentIndex) => {
+            expect(Number(currentValue)).toBe(currentIndex + 1);
+            expect(currentIndex - 1).toBe(count++);
+
+            return previousValue + currentValue;
+        })).toBe("".concat(...source));
+
+        expect(count).toBe(source.length - 1);
+
+        expect(() => IteratorProxy.from<string>([]).reduce(() => "")).toThrow("reduce() of empty iterator with no initial value");
+    });
+
+    test("Reduce initial value", () => {
+        let count = 0;
+
+        expect(IteratorProxy.from(source).reduce((previousValue, currentValue, currentIndex) => {
+            expect(Number(currentValue)).toBe(currentIndex + 1);
+            expect(currentIndex).toBe(count++);
+
+            return previousValue + currentValue;
+        }, "0")).toBe("0".concat(...source));
+
+        expect(count).toBe(source.length);
+
+        expect(IteratorProxy.from<string>([]).reduce(() => "", "0")).toBe("0");
+    });
+
+    test("Some", () => {
+        expect(IteratorProxy.from(source).some(value => value === "3")).toBe(true);
+        expect(IteratorProxy.from(source).some(value => value === "6")).toBe(false);
+    });
+
+    test("Every", () => {
+        expect(IteratorProxy.from(source).every(value => Number(value) > 0)).toBe(true);
+        expect(IteratorProxy.from(source).every(value => Number(value) < Number(source[source.length - 1]))).toBe(false);
+    });
+
+    test("Find", () => {
+        expect(IteratorProxy.from(source).find(value => Number(value) % 3 === 0)).toBe("3");
+        expect(IteratorProxy.from(source).find(value => Number(value) % 7 === 0)).toBeUndefined();
+    });
+});

package/test/sequencer.test.ts

@@ -1,6 +1,6 @@
 import { I18NEnvironment, i18nInit } from "@aidc-toolkit/core";
 import { describe, expect, test } from "vitest";
-import { Sequencer } from "../src/index.js";
+import { IteratorProxy, Sequencer } from "../src/index.js";
 
 await i18nInit(I18NEnvironment.CLI, true);
 
@@ -29,7 +29,7 @@ describe("Sequence", () => {
         expectedValue = 10n;
         count = 0;
 
-        for (const value of Iterator.from(sequencer1)) {
+        for (const value of IteratorProxy.from(sequencer1)) {
             expect(value).toBe(expectedValue);
 
             expectedValue++;
@@ -41,7 +41,7 @@ describe("Sequence", () => {
         expectedValue = 29n;
         count = 0;
 
-        for (const value of Iterator.from(sequencer2)) {
+        for (const value of IteratorProxy.from(sequencer2)) {
             expect(value).toBe(expectedValue);
 
             expectedValue--;
@@ -60,7 +60,7 @@ describe("Sequence", () => {
 
         sequencer1.reset();
 
-        for (const value of Iterator.from(sequencer1)) {
+        for (const value of IteratorProxy.from(sequencer1)) {
             expect(value).toBe(expectedValue);
 
             expectedValue++;

package/test/transformer.test.ts

@@ -1,6 +1,6 @@
 import { I18NEnvironment, i18nInit } from "@aidc-toolkit/core";
 import { describe, expect, test } from "vitest";
-import { Sequencer, EncryptionTransformer, IdentityTransformer, Transformer } from "../src/index.js";
+import { EncryptionTransformer, IdentityTransformer, Sequencer, Transformer } from "../src/index.js";
 
 await i18nInit(I18NEnvironment.CLI, true);