@aidc-toolkit/utility 0.9.4 → 0.9.5

package/package.json

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

package/src/iterator_proxy.ts

@@ -1,59 +1,34 @@
-/**
- * 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.
+ * 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.
  */
-function iterationSourceToIterable<T>(iterationSource: IterationSource<T>): Iterable<T> {
-    return Symbol.iterator in iterationSource ?
-        iterationSource :
-        {
-            [Symbol.iterator](): Iterator<T> {
-                return iterationSource;
-            }
-        };
-}
+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.
      */
@@ -71,7 +46,7 @@ abstract class IteratorProxyBase<TInitial, TFinal> implements IteratorObject<TFi
      * Initial iteration source.
      */
     constructor(initialIterationSource: IterationSource<TInitial>) {
-        this._initialIterable = iterationSourceToIterable(initialIterationSource);
+        this._initialIterable = IteratorProxyBase.toIterable(initialIterationSource);
     }
 
     /**
@@ -133,8 +108,8 @@ abstract class IteratorProxyBase<TInitial, TFinal> implements IteratorObject<TFi
     /**
      * @inheritDoc
      */
-    map<U>(callbackfn: (value: TFinal, index: number) => U): IteratorObject<U, undefined> {
-        return new IteratorMapProxy(this, callbackfn);
+    map<U>(callback: (value: TFinal, index: number) => U): IteratorObject<U, undefined> {
+        return new IteratorMapProxy(this, callback);
     }
 
     /**
@@ -148,7 +123,7 @@ abstract class IteratorProxyBase<TInitial, TFinal> implements IteratorObject<TFi
      * @inheritDoc
      */
     filter(predicate: (value: TFinal, index: number) => unknown): IteratorObject<TFinal, undefined> {
-        return new IteratorFilterProxy(this, predicate);
+        return new IteratorFilterProxy(this, predicate, true);
     }
 
     /**
@@ -168,23 +143,24 @@ abstract class IteratorProxyBase<TInitial, TFinal> implements IteratorObject<TFi
     /**
      * @inheritDoc
      */
-    reduce<U>(callbackfn: (previousValue: U, currentValue: TFinal, currentIndex: number) => U, initialValue?: U): U {
+    reduce<U>(callback: (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.
+            // 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 = callbackfn(result as U, value, index);
+                result = callback(result as U, value, index);
             }
 
             index++;
         }
 
-        if (index === 0 && initialValue === undefined) {
+        if (index === 0 && arguments.length === 1) {
             throw new Error("reduce() of empty iterator with no initial value");
         }
 
@@ -202,69 +178,36 @@ abstract class IteratorProxyBase<TInitial, TFinal> implements IteratorObject<TFi
     /**
      * @inheritDoc
      */
-    forEach(callbackfn: (value: TFinal, index: number) => void): void {
+    forEach(callback: (value: TFinal, index: number) => void): void {
         let index = 0;
 
         for (const element of this) {
-            callbackfn(element, index++);
+            callback(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;
+        // 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 {
-        // Iterate until predicate returns falsy; return done status.
-        return this.untilChanged(predicate, true).done === true;
+        // 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 {
-        // Iterate until predicate returns truthy; return value.
-        return this.untilChanged(predicate, false).value;
+        // Filter until predicate returns truthy; return value.
+        return new IteratorFilterProxy(this, predicate, true).next().value;
     }
 }
 
@@ -276,14 +219,15 @@ 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 callback proxy base.
+ * Iterator map proxy base.
  */
-abstract class IteratorCallbackProxyBase<TInitial, TIntermediate, TFinal> extends IteratorProxyBase<TInitial, TFinal> {
+abstract class IteratorMapProxyBase<TInitial, TIntermediate, TFinal> extends IteratorProxyBase<TInitial, TFinal> {
     /**
      * Callback.
      */
@@ -313,48 +257,44 @@ abstract class IteratorCallbackProxyBase<TInitial, TIntermediate, TFinal> extend
     /**
      * Get the next result from the intermediate iterator.
      *
-     * @param initialResult
-     * Next result from the initial iterator.
+     * @param value
+     * Tuple value to be passed to Iterator.next().
      *
      * @returns
      * Next result from the intermediate iterator.
      */
-    protected intermediateNext(initialResult: IteratorResult<TInitial, undefined>): IteratorResult<TIntermediate, undefined> {
-        let intermediateResult: IteratorResult<TIntermediate, undefined>;
+    protected intermediateNext(...value: [] | [unknown]): IteratorResult<TIntermediate, undefined> {
+        const initialResult = this.initialNext(...value);
 
-        if (initialResult.done !== true) {
-            intermediateResult = {
-                done: false,
+        return initialResult.done !== true ?
+            {
                 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> {
+class IteratorMapProxy<TInitial, TFinal> extends IteratorMapProxyBase<TInitial, TFinal, TFinal> {
     /**
      * @inheritDoc
      */
     next(...value: [] | [unknown]): IteratorResult<TFinal, undefined> {
-        return this.intermediateNext(this.initialNext(...value));
+        // Intermediate result is the final result.
+        return this.intermediateNext(...value);
     }
 }
 
 /**
  * Iterator flat map proxy.
  */
-class IteratorFlatMapProxy<TInitial, TFinal> extends IteratorCallbackProxyBase<TInitial, IterationSource<TFinal>, TFinal> {
-    private _pendingFinalIterator: Iterator<TFinal, undefined> | undefined;
+class IteratorFlatMapProxy<TInitial, TFinal> extends IteratorMapProxyBase<TInitial, IterationSource<TFinal>, TFinal> {
+    private _intermediateIterator: Iterator<TFinal, undefined> | undefined;
 
     /**
      * @inheritDoc
@@ -363,26 +303,21 @@ class IteratorFlatMapProxy<TInitial, TFinal> extends IteratorCallbackProxyBase<T
         let finalResult: IteratorResult<TFinal, undefined> | undefined = undefined;
 
         do {
-            if (this._pendingFinalIterator === undefined) {
-                const intermediateResult = this.intermediateNext(this.initialNext(...value));
+            if (this._intermediateIterator === undefined) {
+                const intermediateResult = this.intermediateNext(...value);
 
                 if (intermediateResult.done === true) {
                     finalResult = intermediateResult;
                 } else {
-                    this._pendingFinalIterator = iterationSourceToIterable(intermediateResult.value)[Symbol.iterator]();
+                    this._intermediateIterator = IteratorProxyBase.toIterable(intermediateResult.value)[Symbol.iterator]();
                 }
-            }
-
-            if (this._pendingFinalIterator !== undefined) {
-                const pendingFinalResult = this._pendingFinalIterator.next();
+            } else {
+                const pendingFinalResult = this._intermediateIterator.next();
 
                 if (pendingFinalResult.done === true) {
-                    this._pendingFinalIterator = undefined;
+                    this._intermediateIterator = undefined;
                 } else {
-                    finalResult = {
-                        done: false,
-                        value: pendingFinalResult.value
-                    };
+                    finalResult = pendingFinalResult;
                 }
             }
         } while (finalResult === undefined);
@@ -394,35 +329,56 @@ class IteratorFlatMapProxy<TInitial, TFinal> extends IteratorCallbackProxyBase<T
 /**
  * Iterator filter proxy.
  */
-class IteratorFilterProxy<T> extends IteratorCallbackProxyBase<T, unknown, T> {
+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 finalResult: IteratorResult<T, undefined> | undefined = undefined;
+        let result: IteratorResult<T, undefined> | undefined;
 
-        do {
-            const initialResult = this.initialNext(...value);
+        const expectedTruthy = this._expectedTruthy;
 
-            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);
+        do {
+            result = this.initialNext(...value);
+        } while (result.done !== true && Boolean(this._predicate(result.value, this._index++)) !== expectedTruthy);
 
-        return finalResult;
+        return result;
     }
 }
 
@@ -448,18 +404,33 @@ abstract class IteratorCountProxyBase<T> extends IteratorProxyObject<T> {
         super(initialIterationSource);
 
         if (!Number.isInteger(count) || count < 0) {
-            throw new RangeError("Limit must be a positive integer");
+            throw new RangeError("Count must be a positive integer");
         }
 
         this._count = count;
     }
 
     /**
-     * Determine if count is exhausted.
+     * Determine if iterator is exhausted (by count or by iterator itself).
      */
-    protected get countExhausted(): boolean {
-        // Decrementing the count may go below zero so use less-than-or-equal comparison.
-        return this._count-- <= 0;
+    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;
     }
 }
 
@@ -471,12 +442,12 @@ class IteratorTakeProxy<T> extends IteratorCountProxyBase<T> {
      * @inheritDoc
      */
     override next(...value: [] | [unknown]): IteratorResult<T, undefined> {
-        return this.countExhausted ?
+        return !this.exhausted ?
+            super.next(...value) :
             {
                 done: true,
                 value: undefined
-            } :
-            super.next(...value);
+            };
     }
 }
 
@@ -488,42 +459,59 @@ 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);
+        while (!this.exhausted) {
+            super.next(...value);
+        }
 
-        return result;
+        return super.next(...value);
     }
 }
 
 /**
- * Iterator type.
+ * Get Iterator variable if supported or a proxy for it if not.
+ *
+ * @returns
+ * Iterator variable if supported or a proxy for it if not.
  */
-type IteratorType = typeof Iterator;
+function iteratorProxy(): Pick<typeof Iterator, "from"> {
+    let supported: boolean;
 
-/**
- * Iterator proxy is interested only in the "from" method.
- */
-type IteratorProxyType = Pick<IteratorType, "from">;
+    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 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.
+ * 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: IteratorProxyType = isIteratorSupported() ?
-    Iterator :
-    {
-        /**
-         * @inheritDoc
-         */
-        from<T>(value: IterationSource<T>): IteratorObject<T, undefined> {
-            return value instanceof IteratorProxyBase ? value : new IteratorProxyObject(value);
-        }
-    };
+export const IteratorProxy = iteratorProxy();

package/test/character_set.test.ts

@@ -11,7 +11,7 @@ import {
     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, () => {
@@ -194,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);

package/test/iterator_proxy.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { type IterationSource, IteratorProxy } from "../src/index.js";
+import { IteratorProxy } from "../src/index.js";
 
 const source: readonly string[] = [
     "1", "2", "3", "4", "5"
@@ -28,7 +28,7 @@ function callbackSource(): string[] {
 }
 
 describe("Basic", () => {
-    function validateIterable(iterationSource: IterationSource<string>): void {
+    function validateIterable(iterationSource: Iterator<string> | Iterable<string>): void {
         const iteratorProxy = IteratorProxy.from(iterationSource);
 
         expect(IteratorProxy.from(iteratorProxy)).toBe(iteratorProxy);
@@ -143,6 +143,22 @@ describe("Helpers", () => {
         }
 
         expect(count).toBe(3);
+
+        count = 0;
+
+        for (const element of IteratorProxy.from(source).take(source.length + 1)) {
+            expect(element).toBe(String(++count));
+        }
+
+        expect(count).toBe(source.length);
+
+        count = 0;
+
+        for (const element of IteratorProxy.from(source).take(0)) {
+            expect(element).toBe(String(++count));
+        }
+
+        expect(count).toBe(0);
     });
 
     test("Drop", () => {
@@ -153,6 +169,22 @@ describe("Helpers", () => {
         }
 
         expect(count).toBe(source.length - 3);
+
+        count = 0;
+
+        for (const element of IteratorProxy.from(source).drop(0)) {
+            expect(element).toBe(String(++count));
+        }
+
+        expect(count).toBe(source.length);
+
+        count = 0;
+
+        for (const element of IteratorProxy.from(source).drop(source.length)) {
+            expect(element).toBe(String(++count));
+        }
+
+        expect(count).toBe(0);
     });
 
     test("To array", () => {

package/test/record.test.ts

@@ -2,7 +2,7 @@ import { I18NEnvironment, i18nInit } from "@aidc-toolkit/core";
 import { describe, expect, test } from "vitest";
 import { RecordValidator } from "../src/index.js";
 
-await i18nInit(I18NEnvironment.CLI, true);
+await i18nInit(I18NEnvironment.CLI);
 
 describe("Record validator", () => {
     enum StringEnum {

package/test/reg_exp.test.ts

@@ -2,7 +2,7 @@ import { I18NEnvironment, i18nInit } from "@aidc-toolkit/core";
 import { describe, expect, test } from "vitest";
 import { RegExpValidator } from "../src/index.js";
 
-await i18nInit(I18NEnvironment.CLI, true);
+await i18nInit(I18NEnvironment.CLI);
 
 describe("Regular expression validator", () => {
     test("Validation", () => {