@aidc-toolkit/utility 0.9.0 → 0.9.2

package/src/sequencer.ts

@@ -0,0 +1,149 @@
+/**
+ * Sequencer. Defines an ascending or descending sequence of big integers implemented as an iterable iterator.
+ */
+export class Sequencer implements Iterable<bigint>, IterableIterator<bigint> {
+    /**
+     * Start value (inclusive).
+     */
+    private readonly _startValue: bigint;
+
+    /**
+     * End value (exclusive).
+     */
+    private readonly _endValue: bigint;
+
+    /**
+     * Count of values.
+     */
+    private readonly _count: number;
+
+    /**
+     * Delta to the next value; equal to the sign of the count.
+     */
+    private readonly _nextDelta: 1n | -1n;
+
+    /**
+     * Minimum value (inclusive).
+     */
+    private readonly _minValue: bigint;
+
+    /**
+     * Maximum value (inclusive).
+     */
+    private readonly _maxValue: bigint;
+
+    /**
+     * Next value.
+     */
+    private _nextValue: bigint;
+
+    /**
+     * Constructor.
+     *
+     * @param startValue
+     * Start value.
+     *
+     * @param count
+     * Count of values. If count is zero or positive, iteration ascends from start value, otherwise it descends from
+     * start value.
+     */
+    constructor(startValue: number | bigint, count: number) {
+        this._startValue = BigInt(startValue);
+        this._endValue = this._startValue + BigInt(count);
+        this._count = count;
+
+        const ascending = count >= 0;
+
+        if (ascending) {
+            this._nextDelta = 1n;
+            this._minValue = this._startValue;
+            this._maxValue = this._endValue - 1n;
+        } else {
+            this._nextDelta = -1n;
+            this._minValue = this._endValue + 1n;
+            this._maxValue = this._startValue;
+        }
+
+        this._nextValue = this._startValue;
+    }
+
+    /**
+     * Get the start value (inclusive).
+     */
+    get startValue(): bigint {
+        return this._startValue;
+    }
+
+    /**
+     * Get the end value (exclusive).
+     */
+    get endValue(): bigint {
+        return this._endValue;
+    }
+
+    /**
+     * Get the count of values.
+     */
+    get count(): number {
+        return this._count;
+    }
+
+    /**
+     * Get the minimum value (inclusive).
+     */
+    get minValue(): bigint {
+        return this._minValue;
+    }
+
+    /**
+     * Get the maximum value (inclusive).
+     */
+    get maxValue(): bigint {
+        return this._maxValue;
+    }
+
+    /**
+     * Iterable implementation.
+     *
+     * @returns
+     * this
+     */
+    [Symbol.iterator](): this {
+        return this;
+    }
+
+    /**
+     * Iterator implementation.
+     *
+     * @returns
+     * Iterator result. If iterator is exhausted, the value is absolute value of the count.
+     */
+    next(): IteratorResult<bigint, number> {
+        const done = this._nextValue === this._endValue;
+
+        let result: IteratorResult<bigint, number>;
+
+        if (!done) {
+            result = {
+                value: this._nextValue
+            };
+
+            this._nextValue += this._nextDelta;
+        } else {
+            result = {
+                done: true,
+                value: Math.abs(this._count)
+            };
+        }
+
+        return result;
+    }
+
+    /**
+     * Reset the iterator.
+     */
+    reset(): void {
+        // Reset simply returns to the start.
+        this._nextValue = this._startValue;
+    }
+}

package/src/string.ts

@@ -8,9 +8,9 @@ export interface StringValidation {
 /**
  * String validator interface.
  */
-export interface StringValidator {
+export interface StringValidator<V extends StringValidation = StringValidation> {
     /**
-     * Validate a string and throw an exception if validation fails.
+     * Validate a string and throw an error if validation fails.
      *
      * @param s
      * String.
@@ -18,5 +18,5 @@ export interface StringValidator {
      * @param validation
      * String validation parameters.
      */
-    validate: (s: string, validation?: StringValidation) => void;
+    validate: (s: string, validation?: V) => void;
 }

package/src/transformer.ts

@@ -1,5 +1,5 @@
-import { IterationHelper, type IterationSource } from "./iteration.js";
 import i18next, { utilityNS } from "./locale/i18n.js";
+import { Sequencer } from "./sequencer.js";
 
 /**
  * Transformation callback, used to convert transformed value to its final value.
@@ -52,15 +52,15 @@ export abstract class Transformer {
      * @param domain
      * Domain.
      */
-    constructor(domain: bigint) {
-        if (domain <= 0n) {
+    constructor(domain: number | bigint) {
+        this._domain = BigInt(domain);
+
+        if (this._domain <= 0n) {
             throw new RangeError(i18next.t("Transformer.domainMustBeGreaterThanZero", {
                 ns: utilityNS,
                 domain
             }));
         }
-
-        this._domain = BigInt(domain);
     }
 
     /**
@@ -108,30 +108,23 @@ export abstract class Transformer {
     }
 
     /**
-     * Validate that a start value and count are within the domain.
+     * Validate that a value is within the domain.
      *
-     * @param startValue
-     * Start value of range to validate.
-     *
-     * @param count
-     * Number of entries in the range to validate or 1 if undefined.
-     *
-     * @throws RangeError
+     * @param value
+     * Value.
      */
-    private validate(startValue: bigint, count?: number): void {
-        if (startValue < 0n) {
-            throw new RangeError(i18next.t(count === undefined ? "Transformer.valueMustBeGreaterThanOrEqualToZero" : "Transformer.startValueMustBeGreaterThanOrEqualToZero", {
+    private validate(value: bigint): void {
+        if (value < 0n) {
+            throw new RangeError(i18next.t("Transformer.valueMustBeGreaterThanOrEqualToZero", {
                 ns: utilityNS,
-                startValue
+                value
             }));
         }
 
-        const endValue = count === undefined ? startValue : startValue + BigInt(count - 1);
-
-        if (endValue >= this.domain) {
-            throw new RangeError(i18next.t(count === undefined ? "Transformer.valueMustBeLessThan" : "Transformer.endValueMustBeLessThan", {
+        if (value >= this.domain) {
+            throw new RangeError(i18next.t("Transformer.valueMustBeLessThan", {
                 ns: utilityNS,
-                endValue,
+                value,
                 domain: this.domain
             }));
         }
@@ -157,13 +150,13 @@ export abstract class Transformer {
      * @returns
      * Transformed value.
      */
-    forward(value: bigint): bigint;
+    forward(value: number | bigint): bigint;
 
     /**
      * Transform a value forward.
      *
      * @template T
-     * Type returned by transformation callback or bigint if none.
+     * Type returned by transformation callback.
      *
      * @param value
      * Value.
@@ -174,118 +167,126 @@ export abstract class Transformer {
      * @returns
      * Value transformed into object.
      */
-    forward<T>(value: bigint, transformationCallback: TransformationCallback<T>): T;
-
-    forward<T>(value: bigint, transformationCallback?: TransformationCallback<T>): bigint | T {
-        this.validate(value);
+    forward<T>(value: number | bigint, transformationCallback: TransformationCallback<T>): T;
 
-        const transformedValue = this.doForward(value);
-
-        return transformationCallback === undefined ? transformedValue : transformationCallback(transformedValue, 0);
-    }
+    /**
+     * Transform values forward.
+     *
+     * @param values
+     * Values. If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * transformation. Otherwise, the individual values are validated at the time of transformation.
+     *
+     * @returns
+     * Transformed values.
+     */
+    forward(values: Iterable<number | bigint>): IterableIterator<bigint>;
 
     /**
-     * Do the work for the forward sequence method. Parameters are as defined in the public methods.
+     * Transform values forward.
      *
      * @template T
-     * See public methods.
+     * Type returned by transformation callback.
      *
-     * @param startValue
-     * See public methods.
-     *
-     * @param count
-     * See public methods.
+     * @param values
+     * Values. If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * transformation. Otherwise, the individual values are validated at the time of transformation.
      *
      * @param transformationCallback
-     * See public methods.
+     * Called after each value is transformed to convert it to its final value.
      *
-     * @yields
-     * Transformed value optionally defined by transformation callback.
+     * @returns
+     * Values transformed into objects.
      */
-    private * doForwardSequence<T>(startValue: bigint, count: number, transformationCallback?: TransformationCallback<T>): Generator<bigint | T> {
-        for (let index = 0, value = startValue; index < count; index++, value++) {
-            const transformedValue = this.doForward(value);
-
-            yield transformationCallback !== undefined ? transformationCallback(transformedValue, index) : transformedValue;
-        }
-    }
+    forward<T>(values: Iterable<number | bigint>, transformationCallback: TransformationCallback<T>): IterableIterator<T>;
 
     /**
-     * Transform a sequence of values forward.
+     * Transform a value or values forward. This signature exists to allow similar overloaded methods in other classes
+     * to call this method correctly.
      *
-     * @param startValue
-     * Numerical value of the first object. Objects are created from `startValue` to `startValue + count - 1`.
+     * @param valueOrValues
      *
-     * @param count
-     * Number of objects to create.
-     *
-     * @yields
-     * Transformed value.
+     * @returns
      */
-    forwardSequence(startValue: bigint, count: number): IterableIterator<bigint>;
+    forward(valueOrValues: number | bigint | Iterable<number | bigint>): bigint | IterableIterator<bigint>;
 
     /**
-     * Transform a sequence of values forward.
+     * Transform a value or values forward. This signature exists to allow similar overloaded methods in other classes
+     * to call this method correctly.
      *
      * @template T
-     * Type returned by transformation callback or bigint if none.
-     *
-     * @param startValue
-     * Numerical value of the first object. Objects are created from `startValue` to `startValue + count - 1`.
      *
-     * @param count
-     * Number of objects to create.
+     * @param valueOrValues
      *
      * @param transformationCallback
-     * Transformation callback called after the value is transformed to convert it to its final value.
      *
      * @returns
-     * Iterable iterator over transformed values as defined by transformation callback.
      */
-    forwardSequence<T>(startValue: bigint, count: number, transformationCallback: TransformationCallback<T>): IterableIterator<T>;
-
-    forwardSequence<T>(startValue: bigint, count: number, transformationCallback?: TransformationCallback<T>): IterableIterator<bigint | T> {
-        this.validate(startValue, count);
-
-        return this.doForwardSequence(startValue, count, transformationCallback);
-    }
+    forward<T>(valueOrValues: number | bigint | Iterable<number | bigint>, transformationCallback: TransformationCallback<T>): T | IterableIterator<T>;
 
     /**
-     * Transform multiple values forward.
-     *
-     * @param valuesSource
-     * Source of values.
-     *
-     * @returns
-     * Iterable iterator over transformed values.
-     */
-    forwardMultiple(valuesSource: IterationSource<bigint>): IterableIterator<bigint>;
-
-    /**
-     * Transform multiple values forward.
+     * Transform a value or values forward.
      *
      * @template T
-     * Type returned by transformation callback or bigint if none.
+     * Type returned by transformation callback.
      *
-     * @param valuesSource
-     * Source of values.
+     * @param valueOrValues
+     * Value(s).
      *
      * @param transformationCallback
-     * Transformation callback called after the value is transformed to convert it to its final value.
+     * Called after value(s) is/are transformed to convert it/them to its/their final value(s).
      *
      * @returns
-     * Iterable iterator over transformed values as defined by transformation callback.
+     * Value(s) transformed into object(s).
      */
-    forwardMultiple<T>(valuesSource: IterationSource<bigint>, transformationCallback: TransformationCallback<T>): IterableIterator<T>;
+    forward<T>(valueOrValues: number | bigint | Iterable<number | bigint>, transformationCallback?: TransformationCallback<T>): bigint | T | IterableIterator<bigint> | IterableIterator<T> {
+        let result: bigint | T | IterableIterator<bigint> | IterableIterator<T>;
 
-    forwardMultiple<T>(valuesSource: IterationSource<bigint>, transformationCallback?: TransformationCallback<T>): IterableIterator<bigint | T> {
-        return IterationHelper.from(valuesSource).map((value, index) => {
-            this.validate(value);
+        if (typeof valueOrValues !== "object") {
+            const valueN = BigInt(valueOrValues);
 
-            const transformedValue = this.doForward(value);
+            this.validate(valueN);
 
-            return transformationCallback !== undefined ? transformationCallback(transformedValue, index) : transformedValue;
-        });
+            const transformedValue = this.doForward(valueN);
+
+            result = transformationCallback === undefined ? transformedValue : transformationCallback(transformedValue, 0);
+        } else if (valueOrValues instanceof Sequencer) {
+            if (valueOrValues.minValue < 0n) {
+                throw new RangeError(i18next.t("Transformer.minValueMustBeGreaterThanOrEqualToZero", {
+                    ns: utilityNS,
+                    minValue: valueOrValues.minValue
+                }));
+            }
+
+            if (valueOrValues.maxValue >= this.domain) {
+                throw new RangeError(i18next.t("Transformer.maxValueMustBeLessThan", {
+                    ns: utilityNS,
+                    maxValue: valueOrValues.maxValue,
+                    domain: this.domain
+                }));
+            }
+
+            result = transformationCallback === undefined ?
+                Iterator.from(valueOrValues).map(value => this.doForward(value)) :
+                Iterator.from(valueOrValues).map((value, index) => transformationCallback(this.doForward(value), index));
+        } else {
+            result = transformationCallback === undefined ?
+                Iterator.from(valueOrValues).map((value) => {
+                    const valueN = BigInt(value);
+
+                    this.validate(valueN);
+
+                    return this.doForward(valueN);
+                }) :
+                Iterator.from(valueOrValues).map((value, index) => {
+                    const valueN = BigInt(value);
+
+                    this.validate(valueN);
+
+                    return transformationCallback(this.doForward(valueN), index);
+                });
+        }
+
+        return result;
     }
 
     /**
@@ -308,10 +309,12 @@ export abstract class Transformer {
      * @returns
      * Value.
      */
-    reverse(transformedValue: bigint): bigint {
-        this.validate(transformedValue);
+    reverse(transformedValue: number | bigint): bigint {
+        const transformedValueN = BigInt(transformedValue);
+
+        this.validate(transformedValueN);
 
-        return this.doReverse(transformedValue);
+        return this.doReverse(transformedValueN);
     }
 }
 
@@ -319,10 +322,16 @@ export abstract class Transformer {
  * Identity transformer. Values are transformed to themselves.
  */
 export class IdentityTransformer extends Transformer {
+    /**
+     * @inheritDoc
+     */
     protected doForward(value: bigint): bigint {
         return value;
     }
 
+    /**
+     * @inheritDoc
+     */
     protected doReverse(transformedValue: bigint): bigint {
         return transformedValue;
     }
@@ -402,7 +411,7 @@ export class EncryptionTransformer extends Transformer {
      * @param tweak
      * Tweak.
      */
-    constructor(domain: bigint, tweak: bigint) {
+    constructor(domain: number | bigint, tweak: number | bigint) {
         super(domain);
 
         if (tweak < 0n) {
@@ -415,19 +424,19 @@ export class EncryptionTransformer extends Transformer {
         let domainBytes = 0;
 
         // The number of bytes in the domain determines the size of the shuffle and xor operations.
-        for (let reducedDomainMinusOne = domain - 1n; reducedDomainMinusOne !== 0n; reducedDomainMinusOne = reducedDomainMinusOne >> 8n) {
+        for (let reducedDomainMinusOne = this.domain - 1n; reducedDomainMinusOne !== 0n; reducedDomainMinusOne = reducedDomainMinusOne >> 8n) {
             domainBytes++;
         }
 
         this._domainBytes = domainBytes;
-        this._tweak = tweak;
+        this._tweak = BigInt(tweak);
 
         const xorBytes = new Array<number>();
         const bits = new Array<number>();
         const inverseBits = new Array<number>();
 
         // Key is the product of domain, tweak, and an 8-digit prime to force at least four rounds.
-        for (let reducedKey = domain * tweak * 603868999n; reducedKey !== 0n; reducedKey = reducedKey >> 8n) {
+        for (let reducedKey = this.domain * this.tweak * 603868999n; reducedKey !== 0n; reducedKey = reducedKey >> 8n) {
             // Extract least-significant byte.
             const keyByte = Number(reducedKey & 0xFFn);
 
@@ -504,9 +513,7 @@ export class EncryptionTransformer extends Transformer {
      * Value.
      */
     private static bytesToValue(bytes: Uint8Array): bigint {
-        return bytes.reduce((accumulator, byte) => {
-            return accumulator << 8n | BigInt(byte);
-        }, 0n);
+        return bytes.reduce((accumulator, byte) => accumulator << 8n | BigInt(byte), 0n);
     }
 
     /**
@@ -618,6 +625,9 @@ export class EncryptionTransformer extends Transformer {
         });
     }
 
+    /**
+     * @inheritDoc
+     */
     protected doForward(value: bigint): bigint {
         let bytes = this.valueToBytes(value);
         let transformedValue: bigint;
@@ -635,6 +645,9 @@ export class EncryptionTransformer extends Transformer {
         return transformedValue;
     }
 
+    /**
+     * @inheritDoc
+     */
     protected doReverse(transformedValue: bigint): bigint {
         let bytes = this.valueToBytes(transformedValue);
         let value: bigint;