@aidc-toolkit/utility 1.0.24-beta → 1.0.26-beta

package/src/index.ts

@@ -14,12 +14,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export * from "./locale/i18n";
-export * from "./sequence";
-export * from "./iterable-utility";
-export * from "./transformer";
-export type * from "./string";
-export * from "./reg-exp";
-export * from "./record";
-export * from "./exclusion";
-export * from "./character-set";
+export * from "./locale/i18n.js";
+export * from "./sequence.js";
+export * from "./iterable-utility.js";
+export * from "./transformer.js";
+export type * from "./string.js";
+export * from "./reg-exp.js";
+export * from "./record.js";
+export * from "./exclusion.js";
+export * from "./character-set.js";

package/src/locale/i18n.ts

@@ -1,7 +1,7 @@
 import { i18nCoreInit, type I18nEnvironment } from "@aidc-toolkit/core";
 import i18next, { type i18n, type Resource } from "i18next";
-import enLocaleResources from "./en/locale-resources";
-import frLocaleResources from "./fr/locale-resources";
+import enLocaleResources from "./en/locale-resources.js";
+import frLocaleResources from "./fr/locale-resources.js";
 
 export const utilityNS = "aidct_utility";
 
@@ -22,7 +22,7 @@ export const utilityResources: Resource = {
     }
 };
 
-// Explicit type is necessary to work around bug in type discovery with linked packages.
+// Explicit type is necessary because type can't be inferred without additional references.
 export const i18nextUtility: i18n = i18next.createInstance();
 
 /**

package/src/locale/i18next.d.ts

@@ -1,4 +1,4 @@
-import type { UtilityLocaleResources } from "./i18n";
+import type { UtilityLocaleResources } from "./i18n.js";
 
 /**
  * Internationalization module.

package/src/record.ts

@@ -1,5 +1,5 @@
-import { i18nextUtility } from "./locale/i18n";
-import type { StringValidator } from "./string";
+import { i18nextUtility } from "./locale/i18n.js";
+import type { StringValidator } from "./string.js";
 
 /**
  * Record validator. Validation is performed against a record with a string key type and throws an error if the key is

package/src/reg-exp.ts

@@ -1,14 +1,14 @@
-import { i18nextUtility } from "./locale/i18n";
-import type { StringValidator } from "./string";
+import { i18nextUtility } from "./locale/i18n.js";
+import type { StringValidator } from "./string.js";
 
 /**
  * Regular expression validator. The regular expression applies to the full string only if constructed as such. For
- * example, <code>&#x2F;\d&#x2A;&#x2F;</code> (0 or more digits) matches every string, <code>&#x2F;\d+&#x2F;</code>
- * (1 or more digits) matches strings with at least one digit, <code>&#x2F;^\d&#x2A;$&#x2F;</code> matches strings that
- * are all digits or empty, and <code>&#x2F;^\d+$&#x2F;</code> matches strings that are all digits and not empty.
+ * example, <code>&#x2F;\d&#x2A;&#x2F;</code> (0 or more digits) matches every string, <code>&#x2F;\d+&#x2F;</code> (1
+ * or more digits) matches strings with at least one digit, <code>&#x2F;^\d&#x2A;$&#x2F;</code> matches strings that are
+ * all digits or empty, and <code>&#x2F;^\d+$&#x2F;</code> matches strings that are all digits and not empty.
  *
- * Clients of this class are recommended to override the {@link createErrorMessage} method create a more suitable error
- * message for their use case.
+ * Clients of this class are recommended to override the {@linkcode createErrorMessage | createErrorMessage()} method
+ * to create a more suitable error message for their use case.
  */
 export class RegExpValidator implements StringValidator {
     /**

package/src/string.ts

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

package/src/transformer.ts

@@ -1,6 +1,6 @@
-import { type IndexedCallback, mapIterable } from "./iterable-utility";
-import { i18nextUtility } from "./locale/i18n";
-import { Sequence } from "./sequence";
+import { type IndexedCallback, mapIterable } from "./iterable-utility.js";
+import { i18nextUtility } from "./locale/i18n.js";
+import { Sequence } from "./sequence.js";
 
 /**
  * Transformer primitive type.
@@ -43,11 +43,12 @@ export type TransformerOutput<TTransformerInput extends TransformerInput<Transfo
  * into values in the same domain, typically for storage in a database where the data type and length are already fixed
  * and exfiltration of the data can have significant repercussions.
  *
- * Two subclasses are supported directly by this class: {@link IdentityTransformer} (which operates based on a domain
- * only) and {@link EncryptionTransformer} (which operates based on a domain and a tweak). If an application is expected
- * to make repeated use of a transformer with the same domain and (optional) tweak and can't manage the transformer
- * object, an in-memory cache is available via the {@link get} method. Properties in {@link IdentityTransformer} and
- * {@link EncryptionTransformer} are read-only once constructed, so there is no issue with their shared use.
+ * Two subclasses are supported directly by this class: {@linkcode IdentityTransformer} (which operates based on a
+ * domain only) and {@linkcode EncryptionTransformer} (which operates based on a domain and a tweak). If an application
+ * is expected to make repeated use of a transformer with the same domain and (optional) tweak and can't manage the
+ * transformer object, an in-memory cache is available via the {@linkcode get | get()} method. Properties in {@linkcode
+ * IdentityTransformer} and {@linkcode EncryptionTransformer} are read-only once constructed, so there is no issue with
+ * their shared use.
  */
 export abstract class Transformer {
     /**
@@ -77,10 +78,10 @@ export abstract class Transformer {
     }
 
     /**
-     * Get a transformer, constructing it if necessary. The type returned is {@link IdentityTransformer} if tweak is
-     * undefined, {@link EncryptionTransformer} if tweak is defined. Note that although an {@link EncryptionTransformer}
-     * with a zero tweak operates as an {@link IdentityTransformer}, {@link EncryptionTransformer} is still the type
-     * returned if a zero tweak is explicitly specified.
+     * Get a transformer, constructing it if necessary. The type returned is {@linkcode IdentityTransformer} if tweak is
+     * undefined, {@linkcode EncryptionTransformer} if tweak is defined. Note that although an {@linkcode
+     * EncryptionTransformer} with a zero tweak operates as an {@linkcode IdentityTransformer}, {@linkcode
+     * EncryptionTransformer} is still the type returned if a zero tweak is explicitly specified.
      *
      * @param domain
      * Domain.
@@ -89,7 +90,7 @@ export abstract class Transformer {
      * Tweak.
      *
      * @returns
-     * {@link IdentityTransformer} if tweak is undefined, {@link EncryptionTransformer} if tweak is defined.
+     * {@linkcode IdentityTransformer} if tweak is undefined, {@linkcode EncryptionTransformer} if tweak is defined.
      */
     static get(domain: number | bigint, tweak?: number | bigint): Transformer {
         const domainN = BigInt(domain);
@@ -195,7 +196,7 @@ export abstract class Transformer {
      * Value(s) input type.
      *
      * @param valueOrValues
-     * Value(s). If this is an instance of {@link Sequence}, the minimum and maximum values are validated prior to
+     * Value(s). If this is an instance of {@linkcode 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
@@ -213,7 +214,7 @@ export abstract class Transformer {
      * Transformation callback output type.
      *
      * @param valueOrValues
-     * Value(s). If this is an instance of {@link Sequence}, the minimum and maximum values are validated prior to
+     * Value(s). If this is an instance of {@linkcode 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
@@ -305,9 +306,9 @@ export class IdentityTransformer extends Transformer {
 /**
  * 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.
+ * 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.2pd | 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

package/test/character-set.test.ts

@@ -13,7 +13,7 @@ import {
     NUMERIC_CREATOR,
     NUMERIC_VALIDATOR,
     Sequence
-} from "../src";
+} from "../src/index.js";
 
 // Type is used to ensure that testCharacterSet() is not called with creator twice.
 type ValidatorNotCreator<T extends CharacterSetValidator> = T extends CharacterSetCreator ? never : T;

package/test/record.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { RecordValidator } from "../src";
+import { RecordValidator } from "../src/index.js";
 
 describe("Record validator", () => {
     const StringIndexes = {
@@ -9,7 +9,9 @@ describe("Record validator", () => {
         ValueD: "D"
     } as const;
 
-    type StringIndex = typeof StringIndexes[keyof typeof StringIndexes];
+    type StringIndexKey = keyof typeof StringIndexes;
+
+    type StringIndex = typeof StringIndexes[StringIndexKey];
 
     const stringRecord: Record<StringIndex, string> = {
         [StringIndexes.ValueA]: "This is for Value A",

package/test/reg-exp.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { RegExpValidator } from "../src";
+import { RegExpValidator } from "../src/index.js";
 
 describe("Regular expression validator", () => {
     test("Validation", () => {

package/test/sequence.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { Sequence } from "../src";
+import { Sequence } from "../src/index.js";
 
 describe("Sequence", () => {
     const sequence1 = new Sequence(10, 20);

package/test/setup.ts

@@ -1,4 +1,4 @@
 import { I18nEnvironments } from "@aidc-toolkit/core";
-import { i18nUtilityInit } from "../src";
+import { i18nUtilityInit } from "../src/index.js";
 
 await i18nUtilityInit(I18nEnvironments.CLI);

package/test/transformer.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { EncryptionTransformer, IdentityTransformer, Sequence, Transformer } from "../src";
+import { EncryptionTransformer, IdentityTransformer, Sequence, Transformer } from "../src/index.js";
 
 function testTransformer(domain: number, tweak?: number, callback?: (value: bigint, forwardValue: bigint) => void): void {
     const transformer = Transformer.get(domain, tweak);

package/tsconfig-config.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@aidc-toolkit/dev/tsconfig-template.json",
+  "files": ["./eslint.config.ts", "./tsup.config.ts", "vitest.config.ts"]
+}

package/tsconfig-src.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@aidc-toolkit/dev/tsconfig-template.json",
+  "include": ["./src/**/*"],
+  "compilerOptions": {
+    // Emit.
+    "outDir": "dist"
+  }
+}

package/tsconfig-test.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@aidc-toolkit/dev/tsconfig-template.json",
+  "include": ["./test/**/*"],
+  "references": [
+    {
+      "path": "./tsconfig-src.json"
+    }
+  ]
+}

package/tsconfig.json

@@ -1,3 +1,14 @@
 {
-  "extends": "@aidc-toolkit/dev/tsconfig.json"
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig-src.json"
+    },
+    {
+      "path": "./tsconfig-test.json"
+    },
+    {
+      "path": "./tsconfig-config.json"
+    }
+  ]
 }

package/tsup.config.ts

@@ -1,3 +1,4 @@
-import { tsupConfigAIDCToolkit } from "@aidc-toolkit/dev";
+import { tsupConfig } from "@aidc-toolkit/dev";
+import { defineConfig } from "tsup";
 
-export default tsupConfigAIDCToolkit;
+export default defineConfig(tsupConfig);