@aidc-toolkit/utility 0.9.4 → 0.9.6-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/utility",
-  "version": "0.9.4",
+  "version": "0.9.6-beta",
   "description": "Foundational utilities for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -19,21 +19,21 @@
     "url": "https://www.linkedin.com/in/kdean"
   },
   "scripts": {
-    "eslint": "eslint .",
+    "lint": "eslint .",
     "build": "tsup src/index.ts --clean --format cjs,esm --dts",
     "build-doc": "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.9.4",
-    "eslint": "^9.15.0",
+    "@aidc-toolkit/dev": "^0.9.6-beta",
+    "eslint": "^9.16.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.5"
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.7"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "^0.9.4",
-    "i18next": "^23.16.5"
+    "@aidc-toolkit/core": "^0.9.6-beta",
+    "@rollup/rollup-linux-x64-gnu": "^4.28.0"
   }
 }

package/src/character_set.ts

@@ -2,6 +2,7 @@ import i18next, { utilityNS } from "./locale/i18n.js";
 import { RegExpValidator } from "./reg_exp.js";
 import type { StringValidation, StringValidator } from "./string.js";
 import { Transformer } from "./transformer.js";
+import type { TransformerCallback, TransformerInput, TransformerOutput } from "./types.js";
 
 /**
  * Exclusion options for validating and creating strings based on character sets.
@@ -291,20 +292,6 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
     }
 }
 
-/**
- * Creation callback, used to convert created string to its final value.
- *
- * @param s
- * Created string.
- *
- * @param index
- * Index in sequence creation (0 for single creation).
- *
- * @returns
- * Final value.
- */
-export type CreationCallback = (s: string, index: number) => string;
-
 /**
  * Character set creator. Maps numeric values to strings using the character set as digits.
  */
@@ -418,23 +405,33 @@ export class CharacterSetCreator extends CharacterSetValidator {
         if (exclusionSupport.includes(Exclusion.AllNumeric)) {
             const exclusionAllNumericDomains = new Array<bigint>(CharacterSetCreator.MAXIMUM_STRING_LENGTH + 1);
 
-            const numberIndexes = this.characterIndexes("0123456789");
-
-            let expectedNumberIndex = numberIndexes[0];
+            /**
+             * Validate that number indexes are defined and sequential.
+             *
+             * @param numberIndexes
+             * Number indexes.
+             */
+            function validateNumberIndexes(numberIndexes: ReadonlyArray<number | undefined>): asserts numberIndexes is number[] {
+                let expectedNumberIndex = numberIndexes[0];
+
+                // Make sure that all numeric characters are present and in sequence.
+                for (const numberIndex of numberIndexes) {
+                    if (numberIndex === undefined || numberIndex !== expectedNumberIndex) {
+                        throw new RangeError(i18next.t("CharacterSetValidator.allNumericAllNumericCharacters", {
+                            ns: utilityNS
+                        }));
+                    }
 
-            // Make sure that all numeric characters are present and in sequence.
-            for (const numberIndex of numberIndexes) {
-                if (numberIndex === undefined || numberIndex !== expectedNumberIndex) {
-                    throw new RangeError(i18next.t("CharacterSetValidator.allNumericAllNumericCharacters", {
-                        ns: utilityNS
-                    }));
+                    expectedNumberIndex = numberIndex + 1;
                 }
-
-                expectedNumberIndex = numberIndex + 1;
             }
 
+            const numberIndexes = this.characterIndexes("0123456789");
+
+            validateNumberIndexes(numberIndexes);
+
             // Zero index is the all-zero value for a single-character string.
-            const zeroIndex = BigInt((numberIndexes as number[])[0]);
+            const zeroIndex = BigInt(numberIndexes[0]);
 
             const allZerosValues = new Array<bigint>(CharacterSetCreator.MAXIMUM_STRING_LENGTH + 1);
             let allZerosValue = 0n;
@@ -548,79 +545,33 @@ 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
+     * Create string(s) by mapping value(s) 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, 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
-     * Required string length.
-     *
-     * @param values
-     * Numeric values of the strings.
-     *
-     * @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 strings are "tweaked" using an {@link EncryptionTransformer | encryption
-     * transformer}.
-     *
-     * @param creationCallback
-     * If provided, called after each string is constructed to create the final value.
-     *
-     * @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
+     * Numeric value(s) of the string(s).
      *
      * @param exclusion
+     * String(s) 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(s) is/are "tweaked" using an {@link EncryptionTransformer |
+     * encryption transformer}.
      *
-     * @param creationCallback
+     * @param creatorCallback
+     * If provided, called after each string is constructed to create the final value.
      *
      * @returns
+     * String(s) created from the value(s).
      */
-    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 -- Implementation of overloaded signatures.
-    create(length: number, valueOrValues: number | bigint | Iterable<number | bigint>, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint, creationCallback?: CreationCallback): string | IterableIterator<string> {
+    create<T extends TransformerInput<number | bigint>>(length: number, valueOrValues: T, exclusion: Exclusion = Exclusion.None, tweak?: number | bigint, creatorCallback?: TransformerCallback<string, string>): TransformerOutput<T, string> {
         this.validateLength(length);
         this.validateExclusion(exclusion);
 
-        // Zero value obviates need for non-null assertion.
+        // Zero value in ternary else obviates need for non-null assertion.
         const allZerosValue = exclusion === Exclusion.AllNumeric ? this._allZerosValues[length] : 0n;
 
         const transformer = Transformer.get(this._exclusionDomains[exclusion][length], tweak);
@@ -651,7 +602,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
                 s = this.character(exclusion === Exclusion.FirstZero ? Number(convertValue % this._characterSetSizeMinusOneN) + 1 : Number(convertValue % this._characterSetSizeN)) + s;
             }
 
-            return creationCallback !== undefined ? creationCallback(s, index) : s;
+            return creatorCallback !== undefined ? creatorCallback(s, index) : s;
         });
     }
 

package/src/index.ts

@@ -1,3 +1,4 @@
+export type * from "./types.js";
 export * from "./iterator_proxy.js";
 export * from "./sequencer.js";
 export * from "./transformer.js";