@aidc-toolkit/utility 0.0.1 → 0.9.1

package/src/iteration.ts

@@ -1,343 +0,0 @@
-/**
- * Iteration source type. The underlying source is an iterable or iterator or a callback to an iterable or iterator.
- */
-export type IterationSource<T> = Iterable<T> | Iterator<T> | (() => (Iterable<T> | Iterator<T>));
-
-/**
- * Iteration proxy class for applying a callback for mapping or filtering.
- */
-class IterationProxy<T, U, V> implements IterableIterator<V> {
-    /**
-     * Proxied iterable iterator.
-     */
-    private readonly _proxiedIterableIterator: IterableIterator<T>;
-
-    /**
-     * Callback for map or filter.
-     */
-    private readonly _callback: (element: T, index: number) => U;
-
-    /**
-     * If true, callback is a predicate for a filter.
-     */
-    private readonly _isPredicate: boolean;
-
-    /**
-     * Index into proxied iterable iterator.
-     */
-    private _index: number;
-
-    /**
-     * Constructor.
-     *
-     * @param proxiedIterableIterator
-     * Proxied iterable iterator.
-     *
-     * @param callback
-     * Callback for map or filter.
-     *
-     * @param isPredicate
-     * If true, callback is a predicate for a filter.
-     */
-    constructor(proxiedIterableIterator: IterableIterator<T>, callback: (element: T, index: number) => U, isPredicate: boolean) {
-        this._proxiedIterableIterator = proxiedIterableIterator;
-        this._callback = callback;
-        this._isPredicate = isPredicate;
-
-        this._index = 0;
-    }
-
-    /**
-     * {@link Iterable} interface implementation.
-     *
-     * @returns
-     * Iterable iterator.
-     */
-    [Symbol.iterator](): IterableIterator<V> {
-        return this;
-    }
-
-    /**
-     * {@link Iterator} interface implementation.
-     *
-     * @param args
-     * Arguments.
-     *
-     * @returns
-     * Next element or number or total number of elements if none.
-     */
-    next(...args: [] | [undefined]): IteratorResult<V, number> {
-        let done = false;
-        let value: V | undefined;
-
-        let callbackDone: boolean;
-
-        do {
-            const proxiedNext = this._proxiedIterableIterator.next(...args);
-
-            if (!(proxiedNext.done ?? false)) {
-                const proxiedValue = proxiedNext.value;
-                const callbackValue = this._callback(proxiedValue, this._index++);
-
-                if (!this._isPredicate) {
-                    // Types U and V are known to be identical.
-                    value = callbackValue as unknown as V;
-
-                    callbackDone = true;
-                } else {
-                    callbackDone = callbackValue as boolean;
-
-                    if (callbackDone) {
-                        // Types T and V are known to be identical.
-                        value = proxiedValue as unknown as V;
-                    }
-                }
-            } else {
-                done = true;
-                callbackDone = true;
-            }
-        } while (!callbackDone);
-
-        return done ?
-            {
-                done: true,
-                value: this._index
-            } :
-            {
-                done: false,
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                value: value!
-            };
-    }
-}
-
-/**
- * Iteration helper. Adds array-like functionality through {@link forEach}, {@link map}, {@link filter}, and
- * {@link reduce} methods. Likely to be refactored as {@link
- * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helpers | iterator
- * helpers} are more widely deployed.
- */
-export class IterationHelper<T> implements IterableIterator<T> {
-    /**
-     * Iteration source.
-     */
-    private readonly _iterationSource: IterationSource<T>;
-
-    /**
-     * Iterable extracted from iteration source.
-     */
-    private _iterable?: Iterable<T>;
-
-    /**
-     * Iterator extracted from iteration source.
-     */
-    private _iterator?: Iterator<T>;
-
-    /**
-     * Constructor.
-     *
-     * @param iterationSource
-     * Iteration source.
-     */
-    private constructor(iterationSource: IterationSource<T>) {
-        this._iterationSource = iterationSource;
-    }
-
-    /**
-     * Get an iteration helper from an iteration source. If the iteration source is itself an iteration helper, it is
-     * returned verbatim, otherwise a new iteration helper is constructed.
-     *
-     * @param iterationSource
-     * Iteration source.
-     *
-     * @returns
-     * Iteration helper.
-     */
-    static from<T>(iterationSource: IterationSource<T>): IterationHelper<T> {
-        return iterationSource instanceof IterationHelper ? iterationSource as IterationHelper<T> : new IterationHelper(iterationSource);
-    }
-
-    /**
-     * Get the iteration source.
-     */
-    get iterationSource(): IterationSource<T> {
-        return this._iterationSource;
-    }
-
-    /**
-     * Get the iteration source as an iterable.
-     *
-     * @returns
-     * Iterable.
-     */
-    asIterable(): Iterable<T> {
-        if (this._iterable === undefined) {
-            const resolvedIterationSource = typeof this.iterationSource === "function" ? this.iterationSource() : this.iterationSource;
-
-            this._iterable = Symbol.iterator in resolvedIterationSource ?
-                resolvedIterationSource :
-                {
-                    [Symbol.iterator](): Iterator<T> {
-                        return resolvedIterationSource;
-                    }
-                };
-        }
-
-        return this._iterable;
-    }
-
-    /**
-     * Get the iteration source as an array.
-     *
-     * @returns
-     * Array.
-     */
-    asArray(): readonly T[] {
-        const iterable = this.asIterable();
-
-        // Return iterable as array.
-        return Array.isArray(iterable) ? iterable as readonly T[] : Array.from(iterable);
-    }
-
-    /**
-     * Get the iteration source as an iterator.
-     *
-     * @returns
-     * Iterator.
-     */
-    asIterator(): Iterator<T> {
-        if (this._iterator === undefined) {
-            this._iterator = this.asIterable()[Symbol.iterator]();
-        }
-
-        return this._iterator;
-    }
-
-    /**
-     * Get the iteration source as a callback.
-     *
-     * @returns
-     * Callback.
-     */
-    asCallback(): () => IterationSource<T> {
-        return typeof this._iterationSource === "function" ? this._iterationSource : () => this._iterationSource;
-    }
-
-    /**
-     * {@link Iterable} interface implementation.
-     *
-     * @returns
-     * Iterable iterator.
-     */
-    [Symbol.iterator](): IterableIterator<T> {
-        return this;
-    }
-
-    /**
-     * {@link Iterator} interface implementation.
-     *
-     * @param args
-     * Arguments.
-     *
-     * @returns
-     * Next element.
-     */
-    next(...args: [] | [undefined]): IteratorResult<T, unknown> {
-        return this.asIterator().next(...args);
-    }
-
-    /**
-     * Perform an action for each element in the iteration helper.
-     *
-     * @param callback
-     * Callback that processes the element and its index in the iteration sequence.
-     */
-    forEach(callback: (element: T, index: number) => void): void {
-        let index = 0;
-
-        for (const element of this) {
-            callback(element, index++);
-        }
-    }
-
-    /**
-     * Map the iteration helper to another iteration helper by performing an action for each element in the iteration
-     * helper along the way.
-     *
-     * @param callback
-     * Callback that processes the element and its index in the iteration sequence.
-     *
-     * @returns
-     * Iterable iterator over callback results.
-     */
-    map<U>(callback: (element: T, index: number) => U): IterableIterator<U> {
-        return new IterationProxy(this, callback, false);
-    }
-
-    /**
-     * Filter the iteration helper based on the condition specified in a predicate. Each call to `.next()` will iterate
-     * as far as necessary until it reaches an element that satisfies the predicate. Care should be taken when working
-     * with large iterators and infrequently truthy predicates.
-     *
-     * @param predicate
-     * Predicate that processes the element and its index in the iteration sequence.
-     *
-     * @returns
-     * Iterator iterable over elements that satisfy the predicate.
-     */
-    filter(predicate: (element: T, index: number) => boolean): IterableIterator<T> {
-        return new IterationProxy(this, predicate, true);
-    }
-
-    /**
-     * Reduce the iterator to a single value by applying a callback.
-     *
-     * @param callback
-     * Callback that processes the previous return value of the callback, the current value of the iterator, and the
-     * current index. The initial value is considered to be the first element in the iteration helper.
-     *
-     * @returns
-     * Reduced value.
-     */
-    reduce(callback: (previousValue: T, currentValue: T, currentIndex: number) => T): T;
-
-    /**
-     * Reduce the iterator to a single value by applying a callback.
-     *
-     * @param callback
-     * Callback that processes the previous return value of the callback, the current value of the iterator, and the
-     * current index.
-     *
-     * @param initialValue
-     * Initial value, passed as the first previous return value of the callback.
-     *
-     * @returns
-     * Reduced value.
-     */
-    reduce(callback: (previousValue: T, currentValue: T, currentIndex: number) => T, initialValue: T): T;
-
-    reduce<U>(callback: (previousValue: U, currentValue: T, currentIndex: number) => U, initialValue?: U): U {
-        let index = 0;
-        let result = initialValue;
-
-        for (const value of this) {
-            if (index === 0 && initialValue === undefined) {
-                result = value as unknown as U;
-            } else {
-                // Iteration has occurred at least once so result is of the expected type.
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                result = callback(result!, 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.
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        return result!;
-    }
-}

package/test/iteration.test.ts

@@ -1,282 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { IterationHelper, type IterationSource } from "../src/index.js";
-
-const source: readonly string[] = [
-    "1", "2", "3", "4", "5"
-];
-
-// eslint-disable-next-line jsdoc/require-jsdoc
-function iterableSource(): Iterable<string> {
-    return [...source];
-}
-
-// eslint-disable-next-line jsdoc/require-jsdoc
-function arraySource(): string[] {
-    return [...source];
-}
-
-// eslint-disable-next-line jsdoc/require-jsdoc
-function iteratorSource(): Iterator<string> {
-    return [...source][Symbol.iterator]();
-}
-
-// eslint-disable-next-line jsdoc/require-jsdoc
-function * generatorSource(): Generator<string> {
-    for (const s of source) {
-        yield s;
-    }
-}
-
-// eslint-disable-next-line jsdoc/require-jsdoc
-function callbackSource(): string[] {
-    return [...source];
-}
-
-describe("Iterable", () => {
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    function validateIterable(iterationSource: IterationSource<string>, testEquality: boolean): void {
-        const iterationHelper = IterationHelper.from(iterationSource);
-
-        expect(IterationHelper.from(iterationHelper)).toBe(iterationHelper);
-        expect(iterationHelper.iterationSource).toBe(iterationSource);
-
-        expect(iterationHelper.asIterable() === iterationSource).toBe(testEquality);
-        expect(Array.from(iterationHelper)).toStrictEqual(source);
-    }
-
-    test("Iterable", () => {
-        validateIterable(iterableSource, false);
-        validateIterable(iterableSource(), true);
-    });
-
-    test("Array", () => {
-        validateIterable(arraySource, false);
-        validateIterable(arraySource(), true);
-    });
-
-    test("Iterator", () => {
-        validateIterable(iteratorSource, false);
-        validateIterable(iteratorSource(), true);
-    });
-
-    test("Generator", () => {
-        validateIterable(generatorSource, false);
-        validateIterable(generatorSource(), true);
-    });
-
-    test("Callback", () => {
-        validateIterable(callbackSource, false);
-        validateIterable(callbackSource(), true);
-    });
-});
-
-describe("Array", () => {
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    function validateArray(iterationSource: IterationSource<string>, testEquality: boolean): void {
-        const iterationHelper = IterationHelper.from(iterationSource);
-
-        expect(IterationHelper.from(iterationHelper)).toBe(iterationHelper);
-        expect(iterationHelper.iterationSource).toBe(iterationSource);
-
-        const array = iterationHelper.asArray();
-
-        expect(array === iterationSource).toBe(testEquality);
-        expect(array).toStrictEqual(source);
-    }
-
-    test("Iterable", () => {
-        validateArray(iterableSource, false);
-        validateArray(iterableSource(), true);
-    });
-
-    test("Array", () => {
-        validateArray(arraySource, false);
-        validateArray(arraySource(), true);
-    });
-
-    test("Iterator", () => {
-        validateArray(iteratorSource, false);
-        validateArray(iteratorSource(), false);
-    });
-
-    test("Generator", () => {
-        validateArray(generatorSource, false);
-        validateArray(generatorSource(), false);
-    });
-
-    test("Callback", () => {
-        validateArray(callbackSource, false);
-        validateArray(callbackSource(), true);
-    });
-});
-
-describe("Iterator", () => {
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    function validateIterator(iterationSource: IterationSource<string>, testEquality: boolean): void {
-        const iterationHelper = IterationHelper.from(iterationSource);
-
-        expect(IterationHelper.from(iterationHelper)).toBe(iterationHelper);
-        expect(iterationHelper.iterationSource).toBe(iterationSource);
-
-        const iterator = iterationHelper.asIterator();
-
-        expect(iterator === iterationSource).toBe(testEquality);
-        expect(Array.from({
-            [Symbol.iterator](): Iterator<string> {
-                return iterator;
-            }
-        })).toStrictEqual(source);
-    }
-
-    test("Iterable", () => {
-        validateIterator(iterableSource, false);
-        validateIterator(iterableSource(), false);
-    });
-
-    test("Array", () => {
-        validateIterator(arraySource, false);
-        validateIterator(arraySource(), false);
-    });
-
-    test("Iterator", () => {
-        validateIterator(iteratorSource, false);
-        validateIterator(iteratorSource(), true);
-    });
-
-    test("Generator", () => {
-        validateIterator(generatorSource, false);
-        validateIterator(generatorSource(), true);
-    });
-
-    test("Callback", () => {
-        validateIterator(callbackSource, false);
-        validateIterator(callbackSource(), false);
-    });
-});
-
-describe("Callback", () => {
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    function validateCallback(iterationSource: IterationSource<string>, testEquality: boolean): void {
-        const iterationHelper = IterationHelper.from(iterationSource);
-
-        expect(IterationHelper.from(iterationHelper)).toBe(iterationHelper);
-        expect(iterationHelper.iterationSource).toBe(iterationSource);
-
-        expect(iterationHelper.asCallback() === iterationSource).toBe(testEquality);
-        expect(iterationHelper.asArray()).toStrictEqual(source);
-    }
-
-    test("Iterable", () => {
-        validateCallback(iterableSource, true);
-        validateCallback(iterableSource(), false);
-    });
-
-    test("Array", () => {
-        validateCallback(arraySource, true);
-        validateCallback(arraySource(), false);
-    });
-
-    test("Iterator", () => {
-        validateCallback(iteratorSource, true);
-        validateCallback(iteratorSource(), false);
-    });
-
-    test("Generator", () => {
-        validateCallback(generatorSource, true);
-        validateCallback(generatorSource(), false);
-    });
-
-    test("Callback", () => {
-        validateCallback(callbackSource, true);
-        validateCallback(callbackSource(), false);
-    });
-});
-
-describe("Helpers", () => {
-    test("For each", () => {
-        let count = 0;
-
-        IterationHelper.from(source).forEach((value, index) => {
-            expect(Number(value)).toBe(index + 1);
-            expect(index).toBe(count++);
-        });
-
-        expect(count).toBe(source.length);
-    });
-
-    test("Map", () => {
-        let count = 0;
-
-        const mappedIterationHelper = IterationHelper.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 mappedIterationHelper) {
-            expect(element).toBe(--negativeCount);
-        }
-
-        expect(count).toBe(source.length);
-    });
-
-    test("Filter", () => {
-        let count = 0;
-
-        const filteredIterable = IterationHelper.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("Reduce no initial value", () => {
-        let count = 0;
-
-        expect(IterationHelper.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(() => IterationHelper.from<string>([]).reduce(() => "")).toThrow("reduce() of empty iterator with no initial value");
-    });
-
-    test("Reduce initial value", () => {
-        let count = 0;
-
-        expect(IterationHelper.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(IterationHelper.from<string>([]).reduce(() => "", "0")).toBe("0");
-    });
-});