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

package/dist/index.d.ts

@@ -1,63 +1,67 @@
-declare const utilityNS = "aidct_utility";
+import { I18NEnvironment } from '@aidc-toolkit/core';
+import { Resource, i18n } from 'i18next';
+
+declare const localeStrings: {
+    readonly Transformer: {
+        readonly domainMustBeGreaterThanZero: "Domain {{domain}} must be greater than 0";
+        readonly tweakMustBeGreaterThanOrEqualToZero: "Tweak {{tweak}} must be greater than or equal to 0";
+        readonly valueMustBeGreaterThanOrEqualToZero: "Value {{value}} must be greater than or equal to 0";
+        readonly valueMustBeLessThan: "Value {{value}} must be less than {{domain}}";
+        readonly minimumValueMustBeGreaterThanOrEqualToZero: "Minimum value {{minimumValue}} must be greater than or equal to 0";
+        readonly maximumValueMustBeLessThan: "Maximum value {{maximumValue}} must be less than {{domain}}";
+    };
+    readonly RegExpValidator: {
+        readonly stringDoesNotMatchPattern: "String {{s}} does not match pattern";
+    };
+    readonly CharacterSetValidator: {
+        readonly firstZeroFirstCharacter: "Character set must support zero as first character";
+        readonly allNumericAllNumericCharacters: "Character set must support all numeric characters in sequence";
+        readonly stringMustNotBeAllNumeric: "String must not be all numeric";
+        readonly lengthMustBeGreaterThanOrEqualTo: "Length {{length}} must be greater than or equal to {{minimumLength}}";
+        readonly lengthMustBeLessThanOrEqualTo: "Length {{length}} must be less than or equal to {{maximumLength}}";
+        readonly lengthMustBeEqualTo: "Length {{length}} must be equal to {{exactLength}}";
+        readonly lengthOfComponentMustBeGreaterThanOrEqualTo: "Length {{length}} of {{component}} must be greater than or equal to {{minimumLength}}";
+        readonly lengthOfComponentMustBeLessThanOrEqualTo: "Length {{length}} of {{component}} must be less than or equal to {{maximumLength}}";
+        readonly lengthOfComponentMustBeEqualTo: "Length {{length}} of {{component}} must be equal to {{exactLength}}";
+        readonly invalidCharacterAtPosition: "Invalid character '{{c}}' at position {{position}}";
+        readonly invalidCharacterAtPositionOfComponent: "Invalid character '{{c}}' at position {{position}} of {{component}}";
+        readonly exclusionNotSupported: "Exclusion value of {{exclusion}} is not supported";
+        readonly invalidTweakWithAllNumericExclusion: "Tweak must not be used with all-numeric exclusion";
+        readonly endSequenceValueMustBeLessThanOrEqualTo: "End sequence value (start sequence value + count - 1) must be less than {{domain}}";
+    };
+    readonly RecordValidator: {
+        readonly typeNameKeyNotFound: "{{typeName}} \"{{key}}\" not found";
+    };
+};
 
+declare const utilityNS = "aidct_utility";
 /**
- * Transformer input, one of:
- *
- * - T (primitive type)
- * - Iterable<T>
- *
- * @template T
- * Primitive type.
+ * Locale strings type is extracted from the English locale strings object.
  */
-type TransformerInput<T extends string | number | bigint | boolean> = T | Iterable<T>;
+type UtilityLocaleStrings = typeof localeStrings;
 /**
- * Transformer callback, used to convert transformed value to its final value.
- *
- * @template TInput
- * Type of input to callback.
- *
- * @template TOutput
- * Type of output to callback.
- *
- * @param input
- * Input value.
- *
- * @param index
- * Index in sequence (0 for single transformation).
- *
- * @returns
- * Output value.
+ * Utility resources.
  */
-type TransformerCallback<TInput, TOutput> = (input: TInput, index: number) => TOutput;
+declare const utilityResources: Resource;
+declare const i18nextUtility: i18n;
 /**
- * Transformer output, based on transformer input:
- *
- * - If type T is primitive type, result is type U.
- * - If type T is Iterable type, result is type IterableIterator<U>.
+ * Initialize internationalization.
  *
- * @template T
- * Transformer input type.
+ * @param environment
+ * Environment in which the application is running.
  *
- * @template U
- * Output base type.
- */
-type TransformerOutput<T extends TransformerInput<string | number | bigint | boolean>, U> = T extends (T extends TransformerInput<infer V> ? V : never) ? U : IterableIterator<U>;
-
-/**
- * Iterator proxy. In environments where
- * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helpers |
- * iterator helpers} are supported, this references the {@linkcode Iterator} variable directly. Otherwise, it references
- * an implementation of "from" that uses an internally-defined iterator proxy object.
+ * @param debug
+ * Debug setting.
  *
- * Client applications should **not** rely on long-term availability of this variable as it will be removed once there
- * is widespread support for iterator helpers.
+ * @returns
+ * Void promise.
  */
-declare const IteratorProxy: Pick<IteratorConstructor, "from">;
+declare function i18nUtilityInit(environment: I18NEnvironment, debug?: boolean): Promise<void>;
 
 /**
- * Sequencer. Defines an ascending or descending sequence of big integers implemented as an iterable iterator.
+ * Sequence. Defines an ascending or descending sequence of big integers implemented as an iterable.
  */
-declare class Sequencer implements Iterable<bigint>, IterableIterator<bigint> {
+declare class Sequence implements Iterable<bigint> {
     /**
      * Start value (inclusive).
      */
@@ -77,15 +81,11 @@ declare class Sequencer implements Iterable<bigint>, IterableIterator<bigint> {
     /**
      * Minimum value (inclusive).
      */
-    private readonly _minValue;
+    private readonly _minimumValue;
     /**
      * Maximum value (inclusive).
      */
-    private readonly _maxValue;
-    /**
-     * Next value.
-     */
-    private _nextValue;
+    private readonly _maximumValue;
     /**
      * Constructor.
      *
@@ -112,31 +112,79 @@ declare class Sequencer implements Iterable<bigint>, IterableIterator<bigint> {
     /**
      * Get the minimum value (inclusive).
      */
-    get minValue(): bigint;
+    get minimumValue(): bigint;
     /**
      * Get the maximum value (inclusive).
      */
-    get maxValue(): bigint;
+    get maximumValue(): bigint;
     /**
      * Iterable implementation.
      *
-     * @returns
-     * this
+     * @yields
+     * Next value in sequence.
      */
-    [Symbol.iterator](): this;
-    /**
-     * Iterator implementation.
-     *
-     * @returns
-     * Iterator result. If iterator is exhausted, the value is absolute value of the count.
-     */
-    next(): IteratorResult<bigint, number>;
-    /**
-     * Reset the iterator.
-     */
-    reset(): void;
+    [Symbol.iterator](): Generator<bigint>;
 }
 
+/**
+ * Transformer primitive type.
+ */
+type TransformerPrimitive = string | number | bigint | boolean;
+/**
+ * Transformer input type, one of:
+ *
+ * - TInput (primitive type)
+ * - Iterable<TInput>
+ *
+ * @template TInput
+ * Transformer input primitive type.
+ */
+type TransformerInput<TInput extends TransformerPrimitive> = TInput | Iterable<TInput>;
+/**
+ * Transformer callback, used to convert transformed value to its final value.
+ *
+ * @template TInput
+ * Transformer input primitive type.
+ *
+ * @template TOutput
+ * Transformer output type.
+ *
+ * @param input
+ * Input value.
+ *
+ * @param index
+ * Index in sequence (0 for single transformation).
+ *
+ * @returns
+ * Output value.
+ */
+type TransformerCallback<TInput extends TransformerPrimitive, TOutput> = (input: TInput, index: number) => TOutput;
+/**
+ * Transformer output, based on transformer input:
+ *
+ * - If type TTransformerInput is primitive, result is type TOutput.
+ * - If type TTransformerInput is Iterable, result is type Iterable<TOutput>.
+ *
+ * @template TTransformerInput
+ * Transformer input type.
+ *
+ * @template TOutput
+ * Output base type.
+ */
+type TransformerOutput<TTransformerInput extends TransformerInput<TransformerPrimitive>, TOutput> = TTransformerInput extends (TTransformerInput extends TransformerInput<infer TInput> ? TInput : never) ? TOutput : Iterable<TOutput>;
+/**
+ * Transform an input iterable to an output iterable that applies a transformer callback to each value in the input.
+ *
+ * @param values
+ * Input values iterable.
+ *
+ * @param transformerCallback
+ * Callback to transform input value to output value.
+ *
+ * @returns
+ * Output values iterable.
+ */
+declare function transformIterable<TInput extends TransformerPrimitive, TOutput>(values: Iterable<TInput>, transformerCallback: TransformerCallback<TInput, TOutput>): Iterable<TOutput>;
 /**
  * Transformer that transforms values in a numeric domain to values in a range equal to the domain or to another range
  * defined by a callback function. In other words, the domain determines valid input values and, without a callback, the
@@ -207,31 +255,57 @@ declare abstract class Transformer {
      * Transformed value.
      */
     protected abstract doForward(value: bigint): bigint;
+    /**
+     * Validate that a value is within the domain and do the work of transforming it forward.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Transformed value.
+     */
+    private validateDoForward;
+    /**
+     * 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.
+     */
+    private validateDoForwardCallback;
     /**
      * Transform value(s) forward.
      *
-     * @template T
+     * @template TTransformerInput
      * Value(s) input type.
      *
      * @param valueOrValues
-     * Value(s). If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * Value(s). If this is an instance of {@link 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
      * Transformed value(s).
      */
-    forward<T extends TransformerInput<number | bigint>>(valueOrValues: T): TransformerOutput<T, bigint>;
+    forward<TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput): TransformerOutput<TTransformerInput, bigint>;
     /**
      * Transform value(s) forward, optionally applying a transformation.
      *
-     * @template T
+     * @template TTransformerInput
      * Value(s) input type.
      *
-     * @template U
+     * @template TOutput
      * Transformation callback output type.
      *
      * @param valueOrValues
-     * Value(s). If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * Value(s). If this is an instance of {@link 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
@@ -240,7 +314,7 @@ declare abstract class Transformer {
      * @returns
      * Transformed value(s).
      */
-    forward<T extends TransformerInput<number | bigint>, U>(valueOrValues: T, transformerCallback: TransformerCallback<bigint, U>): TransformerOutput<T, U>;
+    forward<TTransformerInput extends TransformerInput<number | bigint>, TOutput>(valueOrValues: TTransformerInput, transformerCallback: TransformerCallback<bigint, TOutput>): TransformerOutput<TTransformerInput, TOutput>;
     /**
      * Do the work of transforming a value in reverse.
      *
@@ -276,10 +350,11 @@ declare class IdentityTransformer extends Transformer {
     protected doReverse(transformedValue: bigint): bigint;
 }
 /**
- * Encryption transformer. Values are transformed using repeated shuffle and xor operations. The underlying operations
- * are 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.
+ * 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.
  *
  * 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
@@ -308,10 +383,6 @@ declare class EncryptionTransformer extends Transformer {
      * Number of bytes covered by the domain.
      */
     private readonly _domainBytes;
-    /**
-     * Tweak.
-     */
-    private readonly _tweak;
     /**
      * Xor bytes array generated from the domain and tweak.
      */
@@ -338,10 +409,6 @@ declare class EncryptionTransformer extends Transformer {
      * Tweak.
      */
     constructor(domain: number | bigint, tweak: number | bigint);
-    /**
-     * Get the tweak.
-     */
-    get tweak(): bigint;
     /**
      * Convert a value to a byte array big enough to handle the entire domain.
      *
@@ -839,4 +906,4 @@ declare const ALPHABETIC_CREATOR: CharacterSetCreator;
  */
 declare const ALPHANUMERIC_CREATOR: CharacterSetCreator;
 
-export { ALPHABETIC_CREATOR, ALPHANUMERIC_CREATOR, CharacterSetCreator, type CharacterSetValidation, CharacterSetValidator, EncryptionTransformer, Exclusion, HEXADECIMAL_CREATOR, IdentityTransformer, IteratorProxy, NUMERIC_CREATOR, RecordValidator, RegExpValidator, Sequencer, type StringValidation, type StringValidator, Transformer, type TransformerCallback, type TransformerInput, type TransformerOutput, utilityNS };
+export { ALPHABETIC_CREATOR, ALPHANUMERIC_CREATOR, CharacterSetCreator, type CharacterSetValidation, CharacterSetValidator, EncryptionTransformer, Exclusion, HEXADECIMAL_CREATOR, IdentityTransformer, NUMERIC_CREATOR, RecordValidator, RegExpValidator, Sequence, type StringValidation, type StringValidator, Transformer, type TransformerCallback, type TransformerInput, type TransformerOutput, type TransformerPrimitive, type UtilityLocaleStrings, i18nUtilityInit, i18nextUtility, transformIterable, utilityNS, utilityResources };