@aidc-toolkit/utility 0.0.1 → 0.9.1

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Platform**
+ - OS: [e.g. Windows, iOS]
+ - Browser [e.g. chrome, safari]
+ - Browser Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/workflows/npm-publish.yml

@@ -16,6 +16,12 @@ jobs:
         with:
           node-version: 22
       - run: npm ci
+      # This is necessary to work around platform-specific optional dependencies bug (https://github.com/npm/cli/issues/4828).
+      # - run: npm i @rollup/rollup-linux-x64-gnu
+      # "vitest run" fails with:
+      # Error: failed to resolve "extends":"@aidc-toolkit/dev/tsconfig.json" in /home/runner/work/utility/utility/tsconfig.json
+      # Caused by: Error: Cannot find module '@aidc-toolkit/dev/tsconfig.json/tsconfig.json'
+      # - run: npm test
 
   publish-npm:
     needs: build

package/.idea/runConfigurations/build_dev.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="build-dev" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="build-dev" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/eslint.config.js

@@ -6,6 +6,9 @@ import esLintConfigLove from "eslint-config-love";
 import { esLintConfigAIDCToolkit } from "@aidc-toolkit/dev";
 
 export default tseslint.config(
+    {
+        ignores: ["eslint.config.js", "dist"]
+    },
     js.configs.recommended,
     ...tseslint.configs.strictTypeChecked,
     stylistic.configs["recommended-flat"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/utility",
-  "version": "0.0.1",
+  "version": "0.9.1",
   "description": "Foundational utilities for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -20,23 +20,24 @@
   },
   "scripts": {
     "eslint": "eslint .",
-    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "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",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "^0.0.1",
-    "@eslint/js": "^9.10.0",
-    "@stylistic/eslint-plugin": "^2.7.2",
-    "eslint-config-love": "^64.0.0",
-    "eslint-plugin-jsdoc": "^50.2.2",
+    "@aidc-toolkit/dev": "^0.9.1",
+    "@eslint/js": "^9.11.1",
+    "@stylistic/eslint-plugin": "^2.8.0",
+    "eslint-config-love": "^71.0.0",
+    "eslint-plugin-jsdoc": "^50.3.0",
     "ts-node": "^10.9.2",
-    "tsup": "^8.2.4",
-    "typescript": "^5.5.4",
-    "typescript-eslint": "^8.4.0",
-    "vitest": "^2.0.5"
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.7.0",
+    "vitest": "^2.1.1"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "^0.0.1",
-    "i18next": "^23.14.0"
+    "@aidc-toolkit/core": "^0.9.1",
+    "i18next": "^23.15.1"
   }
 }

package/src/character_set.ts

@@ -1,8 +1,7 @@
-import { IterationHelper, type IterationSource } from "./iteration.js";
 import i18next, { utilityNS } from "./locale/i18n.js";
 import { RegExpValidator } from "./reg_exp.js";
 import type { StringValidation, StringValidator } from "./string.js";
-import { type TransformationCallback, Transformer } from "./transformer.js";
+import { Transformer } from "./transformer.js";
 
 /**
  * Exclusion options for validating and creating strings based on character sets.
@@ -60,8 +59,17 @@ export interface CharacterSetValidation extends StringValidation {
 /**
  * Character set validator. Validates a string against a specified character set.
  */
-export class CharacterSetValidator implements StringValidator {
+export class CharacterSetValidator implements StringValidator<CharacterSetValidation> {
     private static readonly NOT_ALL_NUMERIC_VALIDATOR = new class extends RegExpValidator {
+        /**
+         * Create an error message for an all-numeric string.
+         *
+         * @param _s
+         * String.
+         *
+         * @returns
+         * Error message.
+         */
         protected override createErrorMessage(_s: string): string {
             return i18next.t("CharacterSetValidator.stringMustNotBeAllNumeric", {
                 ns: utilityNS
@@ -174,7 +182,7 @@ export class CharacterSetValidator implements StringValidator {
      * Component as a string or undefined.
      */
     private static componentToString(component: string | (() => string) | undefined): string | undefined {
-        return component === undefined || typeof component === "string" ? component : component();
+        return typeof component === "function" ? component() : component;
     }
 
     /**
@@ -182,8 +190,6 @@ export class CharacterSetValidator implements StringValidator {
      *
      * @param exclusion
      * Exclusion.
-     *
-     * @throws RangeError
      */
     protected validateExclusion(exclusion: Exclusion): void {
         if (exclusion !== Exclusion.None && !this._exclusionSupport.includes(exclusion)) {
@@ -203,8 +209,6 @@ export class CharacterSetValidator implements StringValidator {
      *
      * @param validation
      * Character set validation parameters.
-     *
-     * @throws RangeError
      */
     validate(s: string, validation?: CharacterSetValidation): void {
         const length = s.length;
@@ -452,8 +456,6 @@ export class CharacterSetCreator extends CharacterSetValidator {
      *
      * @returns
      * Shift required to skip all all-numeric strings.
-     *
-     * @throws RangeError
      */
     private allNumericShift(shiftForward: boolean, length: number, value: bigint): bigint {
         let shift: bigint;
@@ -495,10 +497,16 @@ export class CharacterSetCreator extends CharacterSetValidator {
      *
      * @param length
      * Length.
-     *
-     * @throws RangeError
      */
     private validateLength(length: number): void {
+        if (length < 0) {
+            throw new RangeError(i18next.t("CharacterSetValidator.lengthMustBeGreaterThanOrEqualTo", {
+                ns: utilityNS,
+                length,
+                minimumLength: 0
+            }));
+        }
+
         if (length > CharacterSetCreator.MAXIMUM_STRING_LENGTH) {
             throw new RangeError(i18next.t("CharacterSetValidator.lengthMustBeLessThanOrEqualTo", {
                 ns: utilityNS,
@@ -509,31 +517,75 @@ export class CharacterSetCreator extends CharacterSetValidator {
     }
 
     /**
-     * Do the work for the creation methods. Undocumented parameters are as defined in the public methods.
+     * Create a string by mapping a value to the equivalent characters in the character set across the length of the
+     * string.
+     *
+     * @param length
+     * Required string length.
      *
-     * @template T
-     * Type defined by creation callback to do the work of creation (string or string[]).
+     * @param value
+     * Numeric value of the string.
+     *
+     * @param exclusion
+     * Strings to be excluded from the range of outputs. See {@link Exclusion} for possible values and their meaning.
+     *
+     * @param tweak
+     * If provided, the numerical value of the string is "tweaked" using an {@link EncryptionTransformer | encryption
+     * transformer}.
+     *
+     * @param creationCallback
+     * If provided, called after the string is constructed to create the final value.
+     *
+     * @returns
+     * String created from the value.
+     */
+    create(length: number, value: number | bigint, exclusion?: Exclusion, tweak?: number | bigint, creationCallback?: CreationCallback): string;
+
+    /**
+     * Create multiple strings by mapping each value to the equivalent characters in the character set across the length
+     * of the string. Equivalent to calling this method for each individual value.
      *
      * @param length
-     * See public methods.
+     * Required string length.
+     *
+     * @param values
+     * Numeric values of the strings.
      *
      * @param exclusion
-     * See public methods.
+     * Strings to be excluded from the range of outputs. See {@link Exclusion} for possible values and their meaning.
      *
      * @param tweak
-     * See public methods.
+     * If provided, the numerical value of the strings are "tweaked" using an {@link EncryptionTransformer | encryption
+     * transformer}.
      *
      * @param creationCallback
-     * See public methods.
+     * If provided, called after each string is constructed to create the final value.
      *
-     * @param createCallback
-     * Callback to do the work of creation, whether for a single value or a sequence. Called with the appropriate
-     * transformer and a transformation callback method to map individual transformed values to strings.
+     * @returns
+     * Iterable iterator over strings created from the values.
+     */
+    create(length: number, values: Iterable<number | bigint>, exclusion?: Exclusion, tweak?: number | bigint, creationCallback?: CreationCallback): IterableIterator<string>;
+
+    /**
+     * Create a string or multiple strings. This signature exists to allow similar overloaded methods in other classes
+     * to call this method correctly.
+     *
+     * @param length
+     *
+     * @param valueOrValues
+     *
+     * @param exclusion
+     *
+     * @param tweak
+     *
+     * @param creationCallback
      *
      * @returns
-     * Created string or iterable iterator over created strings.
      */
-    private doCreate<T>(length: number, exclusion: Exclusion, tweak: number | bigint | undefined, creationCallback: CreationCallback | undefined, createCallback: (transformer: Transformer, transformationCallback: TransformationCallback<string>) => T): T {
+    create(length: number, valueOrValues: number | bigint | Iterable<number | bigint>, exclusion?: Exclusion, tweak?: number | bigint, creationCallback?: CreationCallback): string | IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    create(length: number, valueOrValues: number | bigint | Iterable<number | bigint>, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint, creationCallback?: CreationCallback): string | IterableIterator<string> {
         this.validateLength(length);
         this.validateExclusion(exclusion);
 
@@ -543,7 +595,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         const transformer = Transformer.get(this._exclusionDomains[exclusion]![length], tweak);
 
-        return createCallback(transformer, (transformedValue, index) => {
+        return transformer.forward(valueOrValues, (transformedValue, index) => {
             let s = "";
 
             // Empty string is valid.
@@ -575,93 +627,6 @@ export class CharacterSetCreator extends CharacterSetValidator {
         });
     }
 
-    /**
-     * Create a string by mapping a value to the equivalent characters in the character set across the length of the
-     * string.
-     *
-     * @param length
-     * Required string length.
-     *
-     * @param value
-     * Numeric value of the string.
-     *
-     * @param exclusion
-     * Strings to be excluded from the range of outputs. See {@link Exclusion} for possible values and their meaning.
-     *
-     * @param tweak
-     * If provided, the numerical value of the string is "tweaked" using an {@link EncryptionTransformer | encryption
-     * transformer}.
-     *
-     * @param creationCallback
-     * If provided, called after the string is constructed to create the final value.
-     *
-     * @returns
-     * String created from the value.
-     */
-    create(length: number, value: number | bigint, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint, creationCallback?: CreationCallback): string {
-        return this.doCreate(length, exclusion, tweak, creationCallback, (transformer, transformationCallback) => transformer.forward(BigInt(value), transformationCallback));
-    }
-
-    /**
-     * Create a sequence of strings by mapping each value to the equivalent characters in the character set across the
-     * length of the string. Equivalent to calling {@link create} for `value = startValue + n` where `n` ranges from `0`
-     * to `count - 1`.
-     *
-     * The implementation uses {@link Transformer.forwardSequence}, so the values are created only as needed.
-     *
-     * @param length
-     * See {@link create}.
-     *
-     * @param startValue
-     * Numeric value of the first string. Strings are created from `startValue` to `startValue + count - 1`.
-     *
-     * @param count
-     * The number of strings to create.
-     *
-     * @param exclusion
-     * See {@link create}.
-     *
-     * @param tweak
-     * See {@link create}.
-     *
-     * @param creationCallback
-     * See {@link create}.
-     *
-     * @returns
-     * Iterable iterator over created strings.
-     */
-    createSequence(length: number, startValue: number | bigint, count: number, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint, creationCallback?: CreationCallback): IterableIterator<string> {
-        return this.doCreate(length, exclusion, tweak, creationCallback, (transformer, transformationCallback) => transformer.forwardSequence(BigInt(startValue), count, transformationCallback));
-    }
-
-    /**
-     * Create multiple strings by mapping each value to the equivalent characters in the character set across the length
-     * of the string. Equivalent to calling {@link create} for each value in the values source.
-     *
-     * The implementation uses {@link Transformer.forwardMultiple}, so the values are created only as needed.
-     *
-     * @param length
-     * See {@link create}.
-     *
-     * @param valuesSource
-     * Source of values.
-     *
-     * @param exclusion
-     * See {@link create}.
-     *
-     * @param tweak
-     * See {@link create}.
-     *
-     * @param creationCallback
-     * See {@link create}.
-     *
-     * @returns
-     * Iterable iterator over created strings.
-     */
-    createMultiple(length: number, valuesSource: IterationSource<number | bigint>, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint, creationCallback?: CreationCallback): IterableIterator<string> {
-        return this.doCreate(length, exclusion, tweak, creationCallback, (transformer, transformationCallback) => transformer.forwardMultiple(IterationHelper.from(valuesSource).map(value => BigInt(value)), transformationCallback));
-    }
-
     /**
      * Determine the value for a string.
      *
@@ -678,7 +643,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
      * @returns
      * Numeric value of the string.
      */
-    value(s: string, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint): bigint {
+    valueFor(s: string, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint): bigint {
         const length = s.length;
 
         this.validateLength(length);

package/src/index.ts

@@ -1,6 +1,6 @@
-export * from "./iteration.js";
+export * from "./sequencer.js";
 export * from "./transformer.js";
-export * from "./string.js";
+export type * from "./string.js";
 export * from "./reg_exp.js";
 export * from "./record.js";
 export * from "./character_set.js";

package/src/locale/en/locale_strings.ts

@@ -2,10 +2,10 @@ export const localeStrings = {
     Transformer: {
         domainMustBeGreaterThanZero: "Domain {{domain}} must be greater than 0",
         tweakMustBeGreaterThanOrEqualToZero: "Tweak {{tweak}} must be greater than or equal to 0",
-        valueMustBeGreaterThanOrEqualToZero: "Value {{startValue}} must be greater than or equal to 0",
-        startValueMustBeGreaterThanOrEqualToZero: "Start value {{startValue}} must be greater than or equal to 0",
-        valueMustBeLessThan: "Value {{endValue}} must be less than {{domain}}",
-        endValueMustBeLessThan: "End value (start value + count - 1) {{endValue}} must be less than {{domain}}"
+        valueMustBeGreaterThanOrEqualToZero: "Value {{value}} must be greater than or equal to 0",
+        valueMustBeLessThan: "Value {{value}} must be less than {{domain}}",
+        minValueMustBeGreaterThanOrEqualToZero: "Minimum value {{minValue}} must be greater than or equal to 0",
+        maxValueMustBeLessThan: "Maximum value {{maxValue}} must be less than {{domain}}"
     },
     RegExpValidator: {
         stringDoesNotMatchPattern: "String {{s}} does not match pattern"

package/src/locale/i18next.d.ts

@@ -1,6 +1,12 @@
 import type { localeStrings } from "./en/locale_strings.js";
 
+/**
+ * Internationalization module.
+ */
 declare module "i18next" {
+    /**
+     * Custom type options for this package.
+     */
     interface CustomTypeOptions {
         resources: {
             // Extract the type from the English locale strings object.

package/src/record.ts

@@ -49,8 +49,6 @@ export class RecordValidator<T> implements StringValidator {
      *
      * @param key
      * Record key.
-     *
-     * @throws RangeError
      */
     validate(key: string): void {
         if (this.record[key] === undefined) {

package/src/reg_exp.ts

@@ -50,6 +50,9 @@ export class RegExpValidator implements StringValidator {
         });
     }
 
+    /**
+     * @inheritDoc
+     */
     validate(s: string): void {
         if (!this._regExp.test(s)) {
             throw new RangeError(this.createErrorMessage(s));

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,7 +8,7 @@ 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.
      *
@@ -18,5 +18,5 @@ export interface StringValidator {
      * @param validation
      * String validation parameters.
      */
-    validate: (s: string, validation?: StringValidation) => void;
+    validate: (s: string, validation?: V) => void;
 }