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

package/LICENSE

@@ -172,30 +172,3 @@
       defend, and hold each Contributor harmless for any liability
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright © 2024 Dolphin Data Development Ltd.
-
-   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
-
-       http://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.

package/README.md

@@ -1,3 +1,17 @@
+# Utility Package
+
+**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.
+
+## Overview
+
 ⚠️ **This software is in beta**, with production release is scheduled for 2024Q4. To follow the status of that and other
 projects, go to the AIDC Toolkit [projects](https://github.com/orgs/aidc-toolkit/projects) page.
 

package/dist/index.cjs

@@ -28,8 +28,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   ALPHABETIC_CREATOR: () => ALPHABETIC_CREATOR,
   ALPHANUMERIC_CREATOR: () => ALPHANUMERIC_CREATOR,
   CharacterSetCreator: () => CharacterSetCreator,
@@ -41,7 +41,7 @@ __export(src_exports, {
   NUMERIC_CREATOR: () => NUMERIC_CREATOR,
   RecordValidator: () => RecordValidator,
   RegExpValidator: () => RegExpValidator,
-  Sequencer: () => Sequencer,
+  Sequence: () => Sequence,
   Transformer: () => Transformer,
   i18nUtilityInit: () => i18nUtilityInit,
   i18nextUtility: () => i18nextUtility,
@@ -49,7 +49,7 @@ __export(src_exports, {
   utilityNS: () => utilityNS,
   utilityResources: () => utilityResources
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/locale/i18n.ts
 var import_core = require("@aidc-toolkit/core");
@@ -62,8 +62,8 @@ var 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"
@@ -96,8 +96,8 @@ var localeStrings2 = {
     tweakMustBeGreaterThanOrEqualToZero: "Le r\xE9glage {{tweak}} doit \xEAtre sup\xE9rieur ou \xE9gal \xE0 0",
     valueMustBeGreaterThanOrEqualToZero: "La valeur {{value}} doit \xEAtre sup\xE9rieure ou \xE9gale \xE0 0",
     valueMustBeLessThan: "La valeur {{value}} doit \xEAtre inf\xE9rieure \xE0 {{domain}}",
-    minValueMustBeGreaterThanOrEqualToZero: "La valeur minimale {{minValue}} doit \xEAtre sup\xE9rieure ou \xE9gale \xE0 0",
-    maxValueMustBeLessThan: "La valeur maximale {{maxValue}} doit \xEAtre inf\xE9rieure \xE0 {{domain}}"
+    minimumValueMustBeGreaterThanOrEqualToZero: "La valeur minimale {{minimumValue}} doit \xEAtre sup\xE9rieure ou \xE9gale \xE0 0",
+    maximumValueMustBeLessThan: "La valeur maximale {{maximumValue}} doit \xEAtre inf\xE9rieure \xE0 {{domain}}"
   },
   RegExpValidator: {
     stringDoesNotMatchPattern: "La cha\xEEne {{s}} ne correspond pas au mod\xE8le"
@@ -139,8 +139,8 @@ async function i18nUtilityInit(environment, debug = false) {
   await (0, import_core.i18nCoreInit)(i18nextUtility, environment, debug, utilityNS, utilityResources);
 }
 
-// src/sequencer.ts
-var Sequencer = class {
+// src/sequence.ts
+var Sequence = class {
   /**
    * Start value (inclusive).
    */
@@ -160,11 +160,11 @@ var Sequencer = class {
   /**
    * Minimum value (inclusive).
    */
-  _minValue;
+  _minimumValue;
   /**
    * Maximum value (inclusive).
    */
-  _maxValue;
+  _maximumValue;
   /**
    * Constructor.
    *
@@ -181,12 +181,12 @@ var Sequencer = class {
     this._count = count;
     if (count >= 0) {
       this._nextDelta = 1n;
-      this._minValue = this._startValue;
-      this._maxValue = this._endValue - 1n;
+      this._minimumValue = this._startValue;
+      this._maximumValue = this._endValue - 1n;
     } else {
       this._nextDelta = -1n;
-      this._minValue = this._endValue + 1n;
-      this._maxValue = this._startValue;
+      this._minimumValue = this._endValue + 1n;
+      this._maximumValue = this._startValue;
     }
   }
   /**
@@ -210,14 +210,14 @@ var Sequencer = class {
   /**
    * Get the minimum value (inclusive).
    */
-  get minValue() {
-    return this._minValue;
+  get minimumValue() {
+    return this._minimumValue;
   }
   /**
    * Get the maximum value (inclusive).
    */
-  get maxValue() {
-    return this._maxValue;
+  get maximumValue() {
+    return this._maximumValue;
   }
   /**
    * Iterable implementation.
@@ -233,12 +233,18 @@ var Sequencer = class {
 };
 
 // src/transformer.ts
-function transformIterable(iterable, transformerCallback) {
+function transformIterable(values, transformerCallback) {
   return {
+    /**
+     * Iterable implementation.
+     *
+     * @yields
+     * Next output value.
+     */
     *[Symbol.iterator]() {
       let index = 0;
-      for (const input of iterable) {
-        yield transformerCallback(input, index++);
+      for (const value of values) {
+        yield transformerCallback(value, index++);
       }
     }
   };
@@ -321,45 +327,58 @@ var Transformer = class _Transformer {
       }));
     }
   }
+  /**
+   * Validate that a value is within the domain and do the work of transforming it forward.
+   *
+   * @param value
+   * Value.
+   *
+   * @returns
+   * Transformed value.
+   */
+  validateDoForward(value) {
+    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.
+   */
+  validateDoForwardCallback(transformerCallback, value, index) {
+    return transformerCallback(this.validateDoForward(value), index);
+  }
   // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
   forward(valueOrValues, transformerCallback) {
     let result;
     if (typeof valueOrValues !== "object") {
-      const valueN = BigInt(valueOrValues);
-      this.validate(valueN);
-      const transformedValue = this.doForward(valueN);
-      result = transformerCallback === void 0 ? 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 === void 0 ? 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 === void 0) {
-        result = transformIterable(valueOrValues, (value) => this.doForward(value));
-      } else {
-        result = transformIterable(valueOrValues, (value, index) => transformerCallback(this.doForward(value), index));
-      }
+      result = transformerCallback === void 0 ? transformIterable(valueOrValues, (value) => this.doForward(value)) : transformIterable(valueOrValues, (value, index) => transformerCallback(this.doForward(value), index));
     } else {
-      if (transformerCallback === void 0) {
-        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 === void 0 ? transformIterable(valueOrValues, (value) => this.validateDoForward(value)) : transformIterable(valueOrValues, (value, index) => this.validateDoForwardCallback(transformerCallback, value, index));
     }
     return result;
   }
@@ -423,10 +442,6 @@ var EncryptionTransformer = class _EncryptionTransformer extends Transformer {
    * Number of bytes covered by the domain.
    */
   _domainBytes;
-  /**
-   * Tweak.
-   */
-  _tweak;
   /**
    * Xor bytes array generated from the domain and tweak.
    */
@@ -460,18 +475,16 @@ var EncryptionTransformer = class _EncryptionTransformer extends Transformer {
       }));
     }
     let domainBytes = 0;
-    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();
     const bits = new Array();
     const inverseBits = new Array();
-    for (let reducedKey = this.domain * this.tweak * 603868999n; reducedKey !== 0n; reducedKey = reducedKey >> 8n) {
-      const keyByte = Number(reducedKey & 0xFFn);
-      xorBytes.unshift(keyByte);
-      const bitNumber = keyByte & 7;
+    for (let reducedKey = this.domain * BigInt(tweak) * 603868999n; reducedKey !== 0n; reducedKey >>= 8n) {
+      xorBytes.unshift(Number(BigInt.asUintN(8, reducedKey)));
+      const bitNumber = Number(BigInt.asUintN(3, reducedKey));
       bits.push(_EncryptionTransformer.BITS[bitNumber]);
       inverseBits.push(_EncryptionTransformer.INVERSE_BITS[bitNumber]);
     }
@@ -488,12 +501,6 @@ var EncryptionTransformer = class _EncryptionTransformer extends Transformer {
       this._rounds = xorBytes.length;
     }
   }
-  /**
-   * Get the tweak.
-   */
-  get tweak() {
-    return this._tweak;
-  }
   /**
    * Convert a value to a byte array big enough to handle the entire domain.
    *
@@ -505,10 +512,8 @@ var EncryptionTransformer = class _EncryptionTransformer extends Transformer {
    */
   valueToBytes(value) {
     const bytes = new Uint8Array(this._domainBytes);
-    let reducedValue = value;
-    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;
   }
@@ -1164,7 +1169,7 @@ var CharacterSetCreator = class _CharacterSetCreator extends CharacterSetValidat
         }
         s = this.character(exclusion === 1 /* FirstZero */ ? Number(convertValue % this._characterSetSizeMinusOneN) + 1 : Number(convertValue % this._characterSetSizeN)) + s;
       }
-      return creatorCallback !== void 0 ? creatorCallback(s, index) : s;
+      return creatorCallback === void 0 ? s : creatorCallback(s, index);
     });
   }
   /**
@@ -1327,7 +1332,7 @@ var ALPHANUMERIC_CREATOR = new CharacterSetCreator([
   NUMERIC_CREATOR,
   RecordValidator,
   RegExpValidator,
-  Sequencer,
+  Sequence,
   Transformer,
   i18nUtilityInit,
   i18nextUtility,
@@ -1335,3 +1340,19 @@ var ALPHANUMERIC_CREATOR = new CharacterSetCreator([
   utilityNS,
   utilityResources
 });
+/*!
+ * 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.
+ */