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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/utility",
-  "version": "0.9.7-beta",
+  "version": "0.9.9-beta",
   "description": "Foundational utilities for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -20,20 +20,21 @@
   },
   "scripts": {
     "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",
+    "build-dist": "tsup src/index.ts --clean --format cjs,esm --dts",
+    "build-doc": "npm run build-dist && tsc src/index.ts --outDir dist --target esnext --moduleResolution nodenext --module nodenext --emitDeclarationOnly --declaration --declarationMap",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "^0.9.7-beta",
-    "eslint": "^9.16.0",
+    "@aidc-toolkit/dev": "^0.9.9-beta",
+    "eslint": "^9.17.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "^0.9.7-beta",
-    "@rollup/rollup-linux-x64-gnu": "^4.28.1"
+    "@aidc-toolkit/core": "^0.9.9-beta",
+    "@rollup/rollup-linux-x64-gnu": "^4.29.1",
+    "i18next": "^24.2.0"
   }
 }

package/src/{character_set.ts → character-set.ts}

@@ -1,8 +1,7 @@
-import i18next, { utilityNS } from "./locale/i18n.js";
-import { RegExpValidator } from "./reg_exp.js";
+import { i18nextUtility } 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";
+import { Transformer, type TransformerCallback, type TransformerInput, type TransformerOutput } from "./transformer.js";
 
 /**
  * Exclusion options for validating and creating strings based on character sets.
@@ -72,9 +71,7 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
          * Error message.
          */
         protected override createErrorMessage(_s: string): string {
-            return i18next.t("CharacterSetValidator.stringMustNotBeAllNumeric", {
-                ns: utilityNS
-            });
+            return i18nextUtility.t("CharacterSetValidator.stringMustNotBeAllNumeric");
         }
     }(/\D/);
 
@@ -200,8 +197,7 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
      */
     protected validateExclusion(exclusion: Exclusion): void {
         if (exclusion !== Exclusion.None && !this._exclusionSupport.includes(exclusion)) {
-            throw new RangeError(i18next.t("CharacterSetValidator.exclusionNotSupported", {
-                ns: utilityNS,
+            throw new RangeError(i18nextUtility.t("CharacterSetValidator.exclusionNotSupported", {
                 exclusion
             }));
         }
@@ -227,15 +223,13 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
             let errorMessage: string;
 
             if (maximumLength !== undefined && maximumLength === minimumLength) {
-                errorMessage = i18next.t(validation?.component === undefined ? "CharacterSetValidator.lengthMustBeEqualTo" : "CharacterSetValidator.lengthOfComponentMustBeEqualTo", {
-                    ns: utilityNS,
+                errorMessage = i18nextUtility.t(validation?.component === undefined ? "CharacterSetValidator.lengthMustBeEqualTo" : "CharacterSetValidator.lengthOfComponentMustBeEqualTo", {
                     component: CharacterSetValidator.componentToString(validation?.component),
                     length,
                     exactLength: minimumLength
                 });
             } else {
-                errorMessage = i18next.t(validation?.component === undefined ? "CharacterSetValidator.lengthMustBeGreaterThanOrEqualTo" : "CharacterSetValidator.lengthOfComponentMustBeGreaterThanOrEqualTo", {
-                    ns: utilityNS,
+                errorMessage = i18nextUtility.t(validation?.component === undefined ? "CharacterSetValidator.lengthMustBeGreaterThanOrEqualTo" : "CharacterSetValidator.lengthOfComponentMustBeGreaterThanOrEqualTo", {
                     component: CharacterSetValidator.componentToString(validation?.component),
                     length,
                     minimumLength
@@ -246,8 +240,7 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
         }
 
         if (maximumLength !== undefined && length > maximumLength) {
-            throw new RangeError(i18next.t(validation?.component === undefined ? "CharacterSetValidator.lengthMustBeLessThanOrEqualTo" : "CharacterSetValidator.lengthOfComponentMustBeLessThanOrEqualTo", {
-                ns: utilityNS,
+            throw new RangeError(i18nextUtility.t(validation?.component === undefined ? "CharacterSetValidator.lengthMustBeLessThanOrEqualTo" : "CharacterSetValidator.lengthOfComponentMustBeLessThanOrEqualTo", {
                 component: CharacterSetValidator.componentToString(validation?.component),
                 length,
                 maximumLength
@@ -258,8 +251,7 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
         const index = this.characterIndexes(s).findIndex(characterIndex => characterIndex === undefined);
 
         if (index !== -1) {
-            throw new RangeError(i18next.t(validation?.component === undefined ? "CharacterSetValidator.invalidCharacterAtPosition" : "CharacterSetValidator.invalidCharacterAtPositionOfComponent", {
-                ns: utilityNS,
+            throw new RangeError(i18nextUtility.t(validation?.component === undefined ? "CharacterSetValidator.invalidCharacterAtPosition" : "CharacterSetValidator.invalidCharacterAtPositionOfComponent", {
                 component: CharacterSetValidator.componentToString(validation?.component),
                 c: s.charAt(index),
                 position: index + (validation?.positionOffset ?? 0) + 1
@@ -275,8 +267,7 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
 
                 case Exclusion.FirstZero:
                     if (s.startsWith("0")) {
-                        throw new RangeError(i18next.t(validation.component === undefined ? "CharacterSetValidator.invalidCharacterAtPosition" : "CharacterSetValidator.invalidCharacterAtPositionOfComponent", {
-                            ns: utilityNS,
+                        throw new RangeError(i18nextUtility.t(validation.component === undefined ? "CharacterSetValidator.invalidCharacterAtPosition" : "CharacterSetValidator.invalidCharacterAtPositionOfComponent", {
                             component: CharacterSetValidator.componentToString(validation.component),
                             c: "0",
                             position: (validation.positionOffset ?? 0) + 1
@@ -384,9 +375,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
 
         if (exclusionSupport.includes(Exclusion.FirstZero)) {
             if (characterSet[0] !== "0") {
-                throw new RangeError(i18next.t("CharacterSetValidator.firstZeroFirstCharacter", {
-                    ns: utilityNS
-                }));
+                throw new RangeError(i18nextUtility.t("CharacterSetValidator.firstZeroFirstCharacter"));
             }
 
             const exclusionFirstZeroDomains = new Array<bigint>(CharacterSetCreator.MAXIMUM_STRING_LENGTH + 1);
@@ -417,9 +406,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
                 // 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
-                        }));
+                        throw new RangeError(i18nextUtility.t("CharacterSetValidator.allNumericAllNumericCharacters"));
                     }
 
                     expectedNumberIndex = numberIndex + 1;
@@ -491,9 +478,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
         if (length === 0) {
             if (!shiftForward && value < 10n) {
                 // If calculation gets this far, string is all-numeric.
-                throw new RangeError(i18next.t("CharacterSetValidator.stringMustNotBeAllNumeric", {
-                    ns: utilityNS
-                }));
+                throw new RangeError(i18nextUtility.t("CharacterSetValidator.stringMustNotBeAllNumeric"));
             }
 
             // Now dealing with individual characters; shift by 10 to skip numeric characters.
@@ -528,16 +513,14 @@ export class CharacterSetCreator extends CharacterSetValidator {
      */
     private validateLength(length: number): void {
         if (length < 0) {
-            throw new RangeError(i18next.t("CharacterSetValidator.lengthMustBeGreaterThanOrEqualTo", {
-                ns: utilityNS,
+            throw new RangeError(i18nextUtility.t("CharacterSetValidator.lengthMustBeGreaterThanOrEqualTo", {
                 length,
                 minimumLength: 0
             }));
         }
 
         if (length > CharacterSetCreator.MAXIMUM_STRING_LENGTH) {
-            throw new RangeError(i18next.t("CharacterSetValidator.lengthMustBeLessThanOrEqualTo", {
-                ns: utilityNS,
+            throw new RangeError(i18nextUtility.t("CharacterSetValidator.lengthMustBeLessThanOrEqualTo", {
                 length,
                 maximumLength: CharacterSetCreator.MAXIMUM_STRING_LENGTH
             }));
@@ -602,7 +585,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
                 s = this.character(exclusion === Exclusion.FirstZero ? Number(convertValue % this._characterSetSizeMinusOneN) + 1 : Number(convertValue % this._characterSetSizeN)) + s;
             }
 
-            return creatorCallback !== undefined ? creatorCallback(s, index) : s;
+            return creatorCallback === undefined ? s : creatorCallback(s, index);
         });
     }
 
@@ -633,8 +616,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
         // Convert string to its value character by character.
         let value = this.characterIndexes(s).reduce((accumulator, characterIndex, index) => {
             if (characterIndex === undefined) {
-                throw new RangeError(i18next.t("CharacterSetValidator.invalidCharacterAtPosition", {
-                    ns: utilityNS,
+                throw new RangeError(i18nextUtility.t("CharacterSetValidator.invalidCharacterAtPosition", {
                     c: s.charAt(index),
                     position: index + 1
                 }));
@@ -644,8 +626,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
 
             if (index === 0 && exclusion === Exclusion.FirstZero) {
                 if (characterIndex === 0) {
-                    throw new RangeError(i18next.t("CharacterSetValidator.invalidCharacterAtPosition", {
-                        ns: utilityNS,
+                    throw new RangeError(i18nextUtility.t("CharacterSetValidator.invalidCharacterAtPosition", {
                         c: "0",
                         position: 1
                     }));

package/src/index.ts

@@ -1,9 +1,23 @@
-export { utilityNS } from "./locale/i18n.js";
-export type * from "./types.js";
-export * from "./iterator_proxy.js";
-export * from "./sequencer.js";
+/*!
+ * Copyright © 2024-2025 Dolphin Data Development Ltd. and AIDC Toolkit
+ * contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from "./locale/i18n.js";
+export * from "./sequence.js";
 export * from "./transformer.js";
 export type * from "./string.js";
-export * from "./reg_exp.js";
+export * from "./reg-exp.js";
 export * from "./record.js";
-export * from "./character_set.js";
+export * from "./character-set.js";

package/src/locale/en/{locale_strings.ts → locale-strings.ts}

@@ -4,8 +4,8 @@ export const localeStrings = {
         tweakMustBeGreaterThanOrEqualToZero: "Tweak {{tweak}} must be greater than or equal to 0",
         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}}"
+        minimumValueMustBeGreaterThanOrEqualToZero: "Minimum value {{minimumValue}} must be greater than or equal to 0",
+        maximumValueMustBeLessThan: "Maximum value {{maximumValue}} must be less than {{domain}}"
     },
     RegExpValidator: {
         stringDoesNotMatchPattern: "String {{s}} does not match pattern"

package/src/locale/fr/{locale_strings.ts → locale-strings.ts}

@@ -4,8 +4,8 @@ export const localeStrings = {
         tweakMustBeGreaterThanOrEqualToZero: "Le réglage {{tweak}} doit être supérieur ou égal à 0",
         valueMustBeGreaterThanOrEqualToZero: "La valeur {{value}} doit être supérieure ou égale à 0",
         valueMustBeLessThan: "La valeur {{value}} doit être inférieure à {{domain}}",
-        minValueMustBeGreaterThanOrEqualToZero: "La valeur minimale {{minValue}} doit être supérieure ou égale à 0",
-        maxValueMustBeLessThan: "La valeur maximale {{maxValue}} doit être inférieure à {{domain}}"
+        minimumValueMustBeGreaterThanOrEqualToZero: "La valeur minimale {{minimumValue}} doit être supérieure ou égale à 0",
+        maximumValueMustBeLessThan: "La valeur maximale {{maximumValue}} doit être inférieure à {{domain}}"
     },
     RegExpValidator: {
         stringDoesNotMatchPattern: "La chaîne {{s}} ne correspond pas au modèle"

package/src/locale/i18n.ts

@@ -1,12 +1,44 @@
-import { i18nAddResourceBundle, i18nAssertValidResources, i18next } from "@aidc-toolkit/core";
-import { localeStrings as enLocaleStrings } from "./en/locale_strings.js";
-import { localeStrings as frLocaleStrings } from "./fr/locale_strings.js";
+import { i18nAssertValidResources, i18nCoreInit, type I18NEnvironment } from "@aidc-toolkit/core";
+import i18next, { type i18n, type Resource } from "i18next";
+import { localeStrings as enLocaleStrings } from "./en/locale-strings.js";
+import { localeStrings as frLocaleStrings } from "./fr/locale-strings.js";
 
 export const utilityNS = "aidct_utility";
 
+/**
+ * Locale strings type is extracted from the English locale strings object.
+ */
+export type UtilityLocaleStrings = typeof enLocaleStrings;
+
 i18nAssertValidResources(enLocaleStrings, "fr", frLocaleStrings);
 
-i18nAddResourceBundle("en", utilityNS, enLocaleStrings);
-i18nAddResourceBundle("fr", utilityNS, frLocaleStrings);
+/**
+ * Utility resources.
+ */
+export const utilityResources: Resource = {
+    en: {
+        aidct_utility: enLocaleStrings
+    },
+    fr: {
+        aidct_utility: frLocaleStrings
+    }
+};
+
+// Explicit type is necessary to work around bug in type discovery with linked packages.
+export const i18nextUtility: i18n = i18next.createInstance();
 
-export default i18next;
+/**
+ * Initialize internationalization.
+ *
+ * @param environment
+ * Environment in which the application is running.
+ *
+ * @param debug
+ * Debug setting.
+ *
+ * @returns
+ * Void promise.
+ */
+export async function i18nUtilityInit(environment: I18NEnvironment, debug = false): Promise<void> {
+    await i18nCoreInit(i18nextUtility, environment, debug, utilityNS, utilityResources);
+}

package/src/locale/i18next.d.ts

@@ -1,4 +1,4 @@
-import type { localeStrings } from "./en/locale_strings.js";
+import type { UtilityLocaleStrings } from "./i18n.js";
 
 /**
  * Internationalization module.
@@ -8,9 +8,9 @@ declare module "i18next" {
      * Custom type options for this package.
      */
     interface CustomTypeOptions {
+        defaultNS: "aidct_utility";
         resources: {
-            // Extract the type from the English locale strings object.
-            aidct_utility: typeof localeStrings;
+            aidct_utility: UtilityLocaleStrings;
         };
     }
 }

package/src/record.ts

@@ -1,4 +1,4 @@
-import i18next, { utilityNS } from "./locale/i18n.js";
+import { i18nextUtility } from "./locale/i18n.js";
 import type { StringValidator } from "./string.js";
 
 /**
@@ -51,9 +51,8 @@ export class RecordValidator<T> implements StringValidator {
      * Record key.
      */
     validate(key: string): void {
-        if (this.record[key] === undefined) {
-            throw new RangeError(i18next.t("RecordValidator.typeNameKeyNotFound", {
-                ns: utilityNS,
+        if (!(key in this.record)) {
+            throw new RangeError(i18nextUtility.t("RecordValidator.typeNameKeyNotFound", {
                 typeName: this.typeName,
                 key
             }));

package/src/{reg_exp.ts → reg-exp.ts}

@@ -1,4 +1,4 @@
-import i18next, { utilityNS } from "./locale/i18n.js";
+import { i18nextUtility } from "./locale/i18n.js";
 import type { StringValidator } from "./string.js";
 
 /**
@@ -44,8 +44,7 @@ export class RegExpValidator implements StringValidator {
      * Error message.
      */
     protected createErrorMessage(s: string): string {
-        return i18next.t("RegExpValidator.stringDoesNotMatchPattern", {
-            ns: utilityNS,
+        return i18nextUtility.t("RegExpValidator.stringDoesNotMatchPattern", {
             s
         });
     }

package/src/sequence.ts

@@ -0,0 +1,107 @@
+/**
+ * Sequence. Defines an ascending or descending sequence of big integers implemented as an iterable.
+ */
+export class Sequence implements Iterable<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 _minimumValue: bigint;
+
+    /**
+     * Maximum value (inclusive).
+     */
+    private readonly _maximumValue: 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;
+
+        if (count >= 0) {
+            this._nextDelta = 1n;
+            this._minimumValue = this._startValue;
+            this._maximumValue = this._endValue - 1n;
+        } else {
+            this._nextDelta = -1n;
+            this._minimumValue = this._endValue + 1n;
+            this._maximumValue = 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 minimumValue(): bigint {
+        return this._minimumValue;
+    }
+
+    /**
+     * Get the maximum value (inclusive).
+     */
+    get maximumValue(): bigint {
+        return this._maximumValue;
+    }
+
+    /**
+     * Iterable implementation.
+     *
+     * @yields
+     * Next value in sequence.
+     */
+    * [Symbol.iterator](): Generator<bigint> {
+        for (let value = this._startValue; value !== this._endValue; value += this._nextDelta) {
+            yield value;
+        }
+    }
+}