@aidc-toolkit/utility 0.9.8-beta → 0.9.9-beta

package/src/transformer.ts

@@ -1,25 +1,30 @@
 import { i18nextUtility } from "./locale/i18n.js";
-import { Sequencer } from "./sequencer.js";
+import { Sequence } from "./sequence.js";
 
 /**
- * Transformer input, one of:
+ * Transformer primitive type.
+ */
+export type TransformerPrimitive = string | number | bigint | boolean;
+
+/**
+ * Transformer input type, one of:
  *
- * - T (primitive type)
- * - Iterable<T>
+ * - TInput (primitive type)
+ * - Iterable<TInput>
  *
- * @template T
- * Primitive type.
+ * @template TInput
+ * Transformer input primitive type.
  */
-export type TransformerInput<T extends string | number | bigint | boolean> = T | Iterable<T>;
+export type TransformerInput<TInput extends TransformerPrimitive> = TInput | Iterable<TInput>;
 
 /**
  * Transformer callback, used to convert transformed value to its final value.
  *
  * @template TInput
- * Type of input to callback.
+ * Transformer input primitive type.
  *
  * @template TOutput
- * Type of output to callback.
+ * Transformer output type.
  *
  * @param input
  * Input value.
@@ -30,42 +35,48 @@ export type TransformerInput<T extends string | number | bigint | boolean> = T |
  * @returns
  * Output value.
  */
-export type TransformerCallback<TInput, TOutput> = (input: TInput, index: number) => TOutput;
+export type TransformerCallback<TInput extends TransformerPrimitive, TOutput> = (input: TInput, index: number) => TOutput;
 
 /**
  * Transformer output, based on transformer input:
  *
- * - If type T is primitive, result is type TOutput.
- * - If type T is Iterable, result is type Iterable<TOutput>.
+ * - If type TTransformerInput is primitive, result is type TOutput.
+ * - If type TTransformerInput is Iterable, result is type Iterable<TOutput>.
  *
- * @template T
+ * @template TTransformerInput
  * Transformer input type.
  *
  * @template TOutput
  * Output base type.
  */
-export type TransformerOutput<T extends TransformerInput<string | number | bigint | boolean>, TOutput> =
-    T extends (T extends TransformerInput<infer TInput> ? TInput : never) ? TOutput : Iterable<TOutput>;
+export type TransformerOutput<TTransformerInput extends TransformerInput<TransformerPrimitive>, TOutput> =
+    TTransformerInput extends (TTransformerInput extends TransformerInput<infer TInput> ? TInput : never) ? TOutput : Iterable<TOutput>;
 
 /**
- * Transform an iterable by applying a transformer callback to each entry.
+ * Transform an input iterable to an output iterable that applies a transformer callback to each value in the input.
  *
- * @param iterable
- * Input iterable.
+ * @param values
+ * Input values iterable.
  *
  * @param transformerCallback
  * Callback to transform input value to output value.
  *
  * @returns
- * Output iterable.
+ * Output values iterable.
  */
-export function transformIterable<TInput, TOutput>(iterable: Iterable<TInput>, transformerCallback: TransformerCallback<TInput, TOutput>): Iterable<TOutput> {
+export function transformIterable<TInput extends TransformerPrimitive, TOutput>(values: Iterable<TInput>, transformerCallback: TransformerCallback<TInput, TOutput>): Iterable<TOutput> {
     return {
+        /**
+         * Iterable implementation.
+         *
+         * @yields
+         * Next output value.
+         */
         * [Symbol.iterator](): Generator<TOutput> {
             let index = 0;
 
-            for (const input of iterable) {
-                yield transformerCallback(input, index++);
+            for (const value of values) {
+                yield transformerCallback(value, index++);
             }
         }
     };
@@ -191,32 +202,68 @@ export abstract class Transformer {
      */
     protected abstract doForward(value: bigint): bigint;
 
+    /**
+     * Validate that a value is within the domain and do the work of transforming it forward.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Transformed value.
+     */
+    private validateDoForward(value: number | bigint): bigint {
+        const valueN = BigInt(value);
+
+        this.validate(valueN);
+
+        return this.doForward(valueN);
+    }
+
+    /**
+     * Validate that a value is within the domain, do the work of transforming it forward, and apply a callback.
+     *
+     * @param transformerCallback
+     * Called after each value is transformed to convert it to its final value.
+     *
+     * @param value
+     * Value.
+     *
+     * @param index
+     * Index in sequence (0 for single transformation).
+     *
+     * @returns
+     * Transformed value.
+     */
+    private validateDoForwardCallback<TOutput>(transformerCallback: TransformerCallback<bigint, TOutput>, value: number | bigint, index: number): TOutput {
+        return transformerCallback(this.validateDoForward(value), index);
+    };
+
     /**
      * Transform value(s) forward.
      *
-     * @template T
+     * @template TTransformerInput
      * Value(s) input type.
      *
      * @param valueOrValues
-     * Value(s). If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * Value(s). If this is an instance of {@link Sequence}, the minimum and maximum values are validated prior to
      * transformation. Otherwise, the individual value(s) is/are validated at the time of transformation.
      *
      * @returns
      * Transformed value(s).
      */
-    forward<T extends TransformerInput<number | bigint>>(valueOrValues: T): TransformerOutput<T, bigint>;
+    forward<TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput): TransformerOutput<TTransformerInput, bigint>;
 
     /**
      * Transform value(s) forward, optionally applying a transformation.
      *
-     * @template T
+     * @template TTransformerInput
      * Value(s) input type.
      *
-     * @template U
+     * @template TOutput
      * Transformation callback output type.
      *
      * @param valueOrValues
-     * Value(s). If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * Value(s). If this is an instance of {@link Sequence}, the minimum and maximum values are validated prior to
      * transformation. Otherwise, the individual value(s) is/are validated at the time of transformation.
      *
      * @param transformerCallback
@@ -225,62 +272,36 @@ export abstract class Transformer {
      * @returns
      * Transformed value(s).
      */
-    forward<T extends TransformerInput<number | bigint>, U>(valueOrValues: T, transformerCallback: TransformerCallback<bigint, U>): TransformerOutput<T, U>;
+    forward<TTransformerInput extends TransformerInput<number | bigint>, TOutput>(valueOrValues: TTransformerInput, transformerCallback: TransformerCallback<bigint, TOutput>): TransformerOutput<TTransformerInput, TOutput>;
 
     // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
-    forward<T extends TransformerInput<number | bigint>, U>(valueOrValues: T, transformerCallback?: TransformerCallback<bigint, U>): TransformerOutput<T, U> {
+    forward<TTransformerInput extends TransformerInput<number | bigint>, TOutput>(valueOrValues: TTransformerInput, transformerCallback?: TransformerCallback<bigint, TOutput>): TransformerOutput<TTransformerInput, TOutput> {
         // TODO Refactor type when https://github.com/microsoft/TypeScript/pull/56941 released.
-        let result: bigint | U | Iterable<bigint> | Iterable<U>;
+        let result: bigint | TOutput | Iterable<bigint> | Iterable<TOutput>;
 
         if (typeof valueOrValues !== "object") {
-            const valueN = BigInt(valueOrValues);
-
-            this.validate(valueN);
-
-            const transformedValue = this.doForward(valueN);
-
-            result = transformerCallback === undefined ? transformedValue : transformerCallback(transformedValue, 0);
-        } else if (valueOrValues instanceof Sequencer) {
-            if (valueOrValues.minValue < 0n) {
-                throw new RangeError(i18nextUtility.t("Transformer.minValueMustBeGreaterThanOrEqualToZero", {
-                    minValue: valueOrValues.minValue
+            result = transformerCallback === undefined ? this.validateDoForward(valueOrValues) : this.validateDoForwardCallback(transformerCallback, valueOrValues, 0);
+        } else if (valueOrValues instanceof Sequence) {
+            if (valueOrValues.minimumValue < 0n) {
+                throw new RangeError(i18nextUtility.t("Transformer.minimumValueMustBeGreaterThanOrEqualToZero", {
+                    minimumValue: valueOrValues.minimumValue
                 }));
             }
 
-            if (valueOrValues.maxValue >= this.domain) {
-                throw new RangeError(i18nextUtility.t("Transformer.maxValueMustBeLessThan", {
-                    maxValue: valueOrValues.maxValue,
+            if (valueOrValues.maximumValue >= this.domain) {
+                throw new RangeError(i18nextUtility.t("Transformer.maximumValueMustBeLessThan", {
+                    maximumValue: valueOrValues.maximumValue,
                     domain: this.domain
                 }));
             }
 
-            if (transformerCallback === undefined) {
-                result = transformIterable(valueOrValues, value => this.doForward(value));
-            } else {
-                result = transformIterable(valueOrValues, (value, index) => transformerCallback(this.doForward(value), index));
-            }
+            result = transformerCallback === undefined ? transformIterable(valueOrValues, value => this.doForward(value)) : transformIterable(valueOrValues, (value, index) => transformerCallback(this.doForward(value), index));
         } else {
-            if (transformerCallback === undefined) {
-                result = transformIterable(valueOrValues, (value) => {
-                    const valueN = BigInt(value);
-
-                    this.validate(valueN);
-
-                    return this.doForward(valueN);
-                });
-            } else {
-                result = transformIterable(valueOrValues, (value, index) => {
-                    const valueN = BigInt(value);
-
-                    this.validate(valueN);
-
-                    return transformerCallback(this.doForward(valueN), index);
-                });
-            }
+            result = transformerCallback === undefined ? transformIterable(valueOrValues, value => this.validateDoForward(value)) : transformIterable(valueOrValues, (value, index) => this.validateDoForwardCallback(transformerCallback, value, index));
         }
 
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type determination is handled above.
-        return result as TransformerOutput<T, U>;
+        return result as TransformerOutput<TTransformerInput, TOutput>;
     }
 
     /**
@@ -332,10 +353,11 @@ export class IdentityTransformer extends Transformer {
 }
 
 /**
- * Encryption transformer. Values are transformed using repeated shuffle and xor operations. The underlying operations
- * are similar to those found in many cryptography algorithms, particularly AES. While sufficient for obfuscation of
- * numeric sequences (e.g., serial number generation, below), if true format-preserving encryption is required, a more
- * robust algorithm such as {@link https://doi.org/10.6028/NIST.SP.800-38Gr1-draft | FF1} is recommended.
+ * Encryption transformer. Values are transformed using repeated shuffle and xor operations, similar to those found in
+ * many cryptography algorithms, particularly AES. While sufficient for obfuscation of numeric sequences (e.g., serial
+ * number generation, below), if true format-preserving encryption is required, a more robust algorithm such as
+ * {@link https://doi.org/10.6028/NIST.SP.800-38Gr1-draft | FF1} is recommended. Furthermore, no work has been done to
+ * mitigate {@link https://timing.attacks.cr.yp.to/index.html | timing attacks} for key detection.
  *
  * The purpose of the encryption transformer is to generate pseudo-random values in a deterministic manner to obscure
  * the sequence of values generated over time. A typical example is for serial number generation, where knowledge of the
@@ -371,11 +393,6 @@ export class EncryptionTransformer extends Transformer {
      */
     private readonly _domainBytes: number;
 
-    /**
-     * Tweak.
-     */
-    private readonly _tweak: bigint;
-
     /**
      * Xor bytes array generated from the domain and tweak.
      */
@@ -417,26 +434,23 @@ 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 = this.domain - 1n; reducedDomainMinusOne !== 0n; reducedDomainMinusOne = reducedDomainMinusOne >> 8n) {
+        for (let reducedDomainMinusOne = this.domain - 1n; reducedDomainMinusOne !== 0n; reducedDomainMinusOne >>= 8n) {
             domainBytes++;
         }
 
         this._domainBytes = domainBytes;
-        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 = this.domain * this.tweak * 603868999n; reducedKey !== 0n; reducedKey = reducedKey >> 8n) {
-            // Extract least-significant byte.
-            const keyByte = Number(reducedKey & 0xFFn);
-
-            xorBytes.unshift(keyByte);
+        for (let reducedKey = this.domain * BigInt(tweak) * 603868999n; reducedKey !== 0n; reducedKey >>= 8n) {
+            // Extract the least significant byte.
+            xorBytes.unshift(Number(BigInt.asUintN(8, reducedKey)));
 
-            // Bit number is the key byte mod 8.
-            const bitNumber = keyByte & 0x07;
+            // Bit number is the reduced key mod 8.
+            const bitNumber = Number(BigInt.asUintN(3, reducedKey));
 
             // Bits are applied in reverse order so that they don't correlate directly with the key bytes at the same index.
             bits.push(EncryptionTransformer.BITS[bitNumber]);
@@ -465,13 +479,6 @@ export class EncryptionTransformer extends Transformer {
         }
     }
 
-    /**
-     * Get the tweak.
-     */
-    get tweak(): bigint {
-        return this._tweak;
-    }
-
     /**
      * Convert a value to a byte array big enough to handle the entire domain.
      *
@@ -484,13 +491,9 @@ export class EncryptionTransformer extends Transformer {
     private valueToBytes(value: bigint): Uint8Array {
         const bytes = new Uint8Array(this._domainBytes);
 
-        let reducedValue = value;
-
         // Build byte array in reverse order to get as big-endian.
-        for (let index = this._domainBytes - 1; index >= 0; index--) {
-            bytes[index] = Number(reducedValue & 0xFFn);
-
-            reducedValue = reducedValue >> 8n;
+        for (let index = this._domainBytes - 1, reducedValue = value; index >= 0 && reducedValue !== 0n; index--, reducedValue >>= 8n) {
+            bytes[index] = Number(BigInt.asUintN(8, reducedValue));
         }
 
         return bytes;

package/test/character-set.test.ts

@@ -8,7 +8,7 @@ import {
     HEXADECIMAL_CREATOR,
     i18nUtilityInit,
     NUMERIC_CREATOR,
-    Sequencer
+    Sequence
 } from "../src/index.js";
 
 await i18nUtilityInit(I18NEnvironment.CLI);
@@ -65,7 +65,7 @@ function testCharacterSetCreator(name: string, characterSetCreator: CharacterSet
                     break;
             }
 
-            const sequence = Iterator.from(characterSetCreator.create(length, new Sequencer(0n, domain), exclusion));
+            const sequence = Iterator.from(characterSetCreator.create(length, new Sequence(0n, domain), exclusion));
 
             let previousS = "";
 
@@ -86,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 = Iterator.from(characterSetCreator.create(length, new Sequence(domain - 1, -domain), exclusion, 123456n));
 
             let sequential = true;
             previousS = "~";
@@ -96,7 +96,7 @@ function testCharacterSetCreator(name: string, characterSetCreator: CharacterSet
             sequenceCount = 0;
 
             sparseSequence.forEach((s, index) => {
-                sequential = sequential && s < previousS;
+                sequential &&= s < previousS;
                 previousS = s;
 
                 expect(s.length).toBe(length);

package/test/{sequencer.test.ts → sequence.test.ts}

@@ -1,25 +1,25 @@
 import { I18NEnvironment } from "@aidc-toolkit/core";
 import { describe, expect, test } from "vitest";
-import { i18nUtilityInit, Sequencer } from "../src/index.js";
+import { i18nUtilityInit, Sequence } from "../src/index.js";
 
 await i18nUtilityInit(I18NEnvironment.CLI);
 
 describe("Sequence", () => {
-    const sequencer1 = new Sequencer(10, 20);
-    const sequencer2 = new Sequencer(29, -20);
+    const sequence1 = new Sequence(10, 20);
+    const sequence2 = new Sequence(29, -20);
 
     test("Structure", () => {
-        expect(sequencer1.startValue).toBe(10n);
-        expect(sequencer1.endValue).toBe(30n);
-        expect(sequencer1.count).toBe(20);
-        expect(sequencer1.minValue).toBe(10n);
-        expect(sequencer1.maxValue).toBe(29n);
-
-        expect(sequencer2.startValue).toBe(29n);
-        expect(sequencer2.endValue).toBe(9n);
-        expect(sequencer2.count).toBe(-20);
-        expect(sequencer2.minValue).toBe(10n);
-        expect(sequencer2.maxValue).toBe(29n);
+        expect(sequence1.startValue).toBe(10n);
+        expect(sequence1.endValue).toBe(30n);
+        expect(sequence1.count).toBe(20);
+        expect(sequence1.minimumValue).toBe(10n);
+        expect(sequence1.maximumValue).toBe(29n);
+
+        expect(sequence2.startValue).toBe(29n);
+        expect(sequence2.endValue).toBe(9n);
+        expect(sequence2.count).toBe(-20);
+        expect(sequence2.minimumValue).toBe(10n);
+        expect(sequence2.maximumValue).toBe(29n);
     });
 
     function iterate(): void {
@@ -29,7 +29,7 @@ describe("Sequence", () => {
         expectedValue = 10n;
         count = 0;
 
-        for (const value of Iterator.from(sequencer1)) {
+        for (const value of Iterator.from(sequence1)) {
             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 Iterator.from(sequence2)) {
             expect(value).toBe(expectedValue);
 
             expectedValue--;

package/test/transformer.test.ts

@@ -1,6 +1,6 @@
 import { I18NEnvironment } from "@aidc-toolkit/core";
 import { describe, expect, test } from "vitest";
-import { EncryptionTransformer, i18nUtilityInit, IdentityTransformer, Sequencer, Transformer } from "../src/index.js";
+import { EncryptionTransformer, i18nUtilityInit, IdentityTransformer, Sequence, Transformer } from "../src/index.js";
 
 await i18nUtilityInit(I18NEnvironment.CLI);
 
@@ -11,7 +11,7 @@ function testTransformer(domain: number, tweak?: number, callback?: (value: bigi
 
     const transformedValuesSet = new Set<bigint>();
 
-    Iterator.from(transformer.forward(new Sequencer(0n, domain))).forEach((transformedValue, index) => {
+    Iterator.from(transformer.forward(new Sequence(0n, domain))).forEach((transformedValue, index) => {
         const indexN = BigInt(index);
 
         if (sequential && transformedValue !== indexN) {
@@ -43,11 +43,11 @@ function testTransformer(domain: number, tweak?: number, callback?: (value: bigi
     expect(Array.from(transformer.forward(randomValues))).toStrictEqual(transformedRandomValues);
 
     expect(() => transformer.forward(domain)).toThrow(`Value ${domain} must be less than ${domain}`);
-    expect(() => transformer.forward(new Sequencer(domain, 0))).not.toThrow(RangeError);
-    expect(() => transformer.forward(new Sequencer(domain - 1, 1))).not.toThrow(RangeError);
-    expect(() => transformer.forward(new Sequencer(domain, 1))).toThrow(`Maximum value ${domain} must be less than ${domain}`);
-    expect(() => transformer.forward(new Sequencer(0, -1))).not.toThrow(RangeError);
-    expect(() => transformer.forward(new Sequencer(-1, -1))).toThrow("Minimum value -1 must be greater than or equal to 0");
+    expect(() => transformer.forward(new Sequence(domain, 0))).not.toThrow(RangeError);
+    expect(() => transformer.forward(new Sequence(domain - 1, 1))).not.toThrow(RangeError);
+    expect(() => transformer.forward(new Sequence(domain, 1))).toThrow(`Maximum value ${domain} must be less than ${domain}`);
+    expect(() => transformer.forward(new Sequence(0, -1))).not.toThrow(RangeError);
+    expect(() => transformer.forward(new Sequence(-1, -1))).toThrow("Minimum value -1 must be greater than or equal to 0");
 }
 
 describe("Identity", () => {
@@ -83,7 +83,6 @@ describe("Encryption", () => {
         expect(Transformer.get(1000n, 1234n)).toBe(transformer);
 
         expect(transformer.domain).toBe(BigInt(1000n));
-        expect((transformer as EncryptionTransformer).tweak).toBe(BigInt(1234n));
 
         const transformer0 = Transformer.get(1000, 0);
 
@@ -129,7 +128,7 @@ describe("Encryption", () => {
     });
 
     test("Tweak variation", () => {
-        expect(Array.from(Transformer.get(1000, 1235).forward(new Sequencer(0n, 1000)))).not.toStrictEqual(Array.from(Transformer.get(1000, 1234).forward(new Sequencer(0n, 1000))));
+        expect(Array.from(Transformer.get(1000, 1235).forward(new Sequence(0n, 1000)))).not.toStrictEqual(Array.from(Transformer.get(1000, 1234).forward(new Sequence(0n, 1000))));
     });
 
     test("Consistency", () => {
@@ -140,30 +139,30 @@ describe("Encryption", () => {
     });
 });
 
-describe("Non-sequencer", () => {
-    function testIterables(sequencer: Sequencer): void {
-        const nonSequencer = Array.from(sequencer);
+describe("Non-sequence", () => {
+    function testIterables(sequence: Sequence): void {
+        const nonSequence = Array.from(sequence);
 
         const transformer = Transformer.get(1000n, 1234n);
 
-        const sequencerForward = transformer.forward(sequencer);
-        const nonSequencerForward = transformer.forward(nonSequencer);
+        const sequenceForward = transformer.forward(sequence);
+        const nonSequenceForward = transformer.forward(nonSequence);
 
-        const nonSequencerIterator = nonSequencerForward[Symbol.iterator]();
+        const nonSequenceIterator = nonSequenceForward[Symbol.iterator]();
 
-        for (const sequencerValue of sequencerForward) {
-            const nonSequencerNext = nonSequencerIterator.next();
+        for (const sequenceValue of sequenceForward) {
+            const nonSequenceNext = nonSequenceIterator.next();
 
-            expect(nonSequencerNext.done).not.toBe(true);
-            expect(nonSequencerNext.value).toBe(sequencerValue);
+            expect(nonSequenceNext.done).not.toBe(true);
+            expect(nonSequenceNext.value).toBe(sequenceValue);
         }
     }
 
     test("Ascending", () => {
-        testIterables(new Sequencer(0, 10));
+        testIterables(new Sequence(0, 10));
     });
 
     test("Descending", () => {
-        testIterables(new Sequencer(9, -10));
+        testIterables(new Sequence(9, -10));
     });
 });