@aidc-toolkit/utility 1.0.45 → 1.0.46-beta

package/dist/index.d.ts

@@ -1,683 +1,26 @@
-import { I18nLanguageDetector } from '@aidc-toolkit/core';
-import { Resource, i18n } from 'i18next';
-
-declare const _default: {
-    Transformer: {
-        domainMustBeGreaterThanZero: string;
-        tweakMustBeGreaterThanOrEqualToZero: string;
-        valueMustBeGreaterThanOrEqualToZero: string;
-        valueMustBeLessThan: string;
-        minimumValueMustBeGreaterThanOrEqualToZero: string;
-        maximumValueMustBeLessThan: string;
-    };
-    RegExpValidator: {
-        stringDoesNotMatchPattern: string;
-    };
-    CharacterSetValidator: {
-        firstZeroFirstCharacter: string;
-        allNumericAllNumericCharacters: string;
-        stringMustNotBeAllNumeric: string;
-        lengthMustBeGreaterThanOrEqualTo: string;
-        lengthMustBeLessThanOrEqualTo: string;
-        lengthMustBeEqualTo: string;
-        lengthOfComponentMustBeGreaterThanOrEqualTo: string;
-        lengthOfComponentMustBeLessThanOrEqualTo: string;
-        lengthOfComponentMustBeEqualTo: string;
-        invalidCharacterAtPosition: string;
-        invalidCharacterAtPositionOfComponent: string;
-        exclusionNotSupported: string;
-        endSequenceValueMustBeLessThanOrEqualTo: string;
-    };
-    RecordValidator: {
-        typeNameKeyNotFound: string;
-    };
-};
-
-declare const utilityNS = "aidct_utility";
-/**
- * Locale strings type is extracted from the English locale strings object.
- */
-type UtilityLocaleResources = typeof _default;
-/**
- * Utility resource bundle.
- */
-declare const utilityResourceBundle: Resource;
-declare const i18nextUtility: i18n;
-/**
- * Initialize internationalization.
- *
- * @param languageDetector
- * Language detector.
- *
- * @param debug
- * Debug setting.
- *
- * @returns
- * Utility resource bundle.
- */
-declare function i18nUtilityInit(languageDetector: I18nLanguageDetector, debug?: boolean): Promise<Resource>;
-
-/**
- * Sequence. Defines an ascending or descending sequence of big integers implemented as an iterable.
- */
-declare class Sequence implements Iterable<bigint> {
-    #private;
-    /**
-     * 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);
-    /**
-     * Get the start value (inclusive).
-     */
-    get startValue(): bigint;
-    /**
-     * Get the end value (exclusive).
-     */
-    get endValue(): bigint;
-    /**
-     * Get the count of values.
-     */
-    get count(): number;
-    /**
-     * Get the minimum value (inclusive).
-     */
-    get minimumValue(): bigint;
-    /**
-     * Get the maximum value (inclusive).
-     */
-    get maximumValue(): bigint;
-    /**
-     * Iterable implementation.
-     *
-     * @yields
-     * Next value in sequence.
-     */
-    [Symbol.iterator](): Generator<bigint>;
-}
-
-/**
- * Indexed callback, used to map an input and optionally its index in an iterable to an output.
- *
- * @template TInput
- * Input type.
- *
- * @template TOutput
- * Output type.
- *
- * @param input
- * Input value.
- *
- * @param index
- * Index in iterable or undefined for single mapping).
- *
- * @returns
- * Output value.
- */
-type IndexedCallback<TInput, TOutput> = (input: TInput, index?: number) => TOutput;
-/**
- * Map an input iterable to an output iterable that applies a transformer callback to each value in the input.
- *
- * @template TInput
- * Input type.
- *
- * @template TOutput
- * Output type.
- *
- * @param values
- * Input values iterable.
- *
- * @param indexedCallback
- * Callback to transform input value to output value.
- *
- * @returns
- * Output values iterable.
- */
-declare function mapIterable<TInput, TOutput>(values: Iterable<TInput>, indexedCallback: IndexedCallback<TInput, TOutput>): Iterable<TOutput>;
-
-/**
- * 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 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>;
-/**
- * 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
- * range of valid output values.
- *
- * The concept is similar to {@link https://en.wikipedia.org/wiki/Format-preserving_encryption | format-preserving
- * encryption}, where input values within a specified domain (e.g., {@link
- * https://en.wikipedia.org/wiki/Payment_card_number | payment card numbers} ranging from 8-19 digits) are transformed
- * 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: {@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.
- */
-declare abstract class Transformer {
-    #private;
-    /**
-     * Constructor.
-     *
-     * @param domain
-     * Domain.
-     */
-    constructor(domain: number | bigint);
-    /**
-     * 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.
-     *
-     * @param tweak
-     * Tweak.
-     *
-     * @returns
-     * {@linkcode IdentityTransformer} if tweak is undefined, {@linkcode EncryptionTransformer} if tweak is defined.
-     */
-    static get(domain: number | bigint, tweak?: number | bigint): Transformer;
-    /**
-     * Get the domain.
-     */
-    get domain(): bigint;
-    /**
-     * Do the work of transforming a value forward.
-     *
-     * @param value
-     * Value.
-     *
-     * @returns
-     * Transformed value.
-     */
-    protected abstract doForward(value: bigint): bigint;
-    /**
-     * Transform value(s) forward.
-     *
-     * @template TTransformerInput
-     * Value(s) input type.
-     *
-     * @param valueOrValues
-     * 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
-     * Transformed value(s).
-     */
-    forward<TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput): TransformerOutput<TTransformerInput, bigint>;
-    /**
-     * Transform value(s) forward, optionally applying a transformation.
-     *
-     * @template TTransformerInput
-     * Value(s) input type.
-     *
-     * @template TOutput
-     * Transformation callback output type.
-     *
-     * @param valueOrValues
-     * 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
-     * Called after each value is transformed to convert it to its final value.
-     *
-     * @returns
-     * Transformed value(s).
-     */
-    forward<TTransformerInput extends TransformerInput<number | bigint>, TOutput>(valueOrValues: TTransformerInput, transformerCallback: IndexedCallback<bigint, TOutput>): TransformerOutput<TTransformerInput, TOutput>;
-    /**
-     * Do the work of transforming a value in reverse.
-     *
-     * @param transformedValue
-     * Transformed value.
-     *
-     * @returns
-     * Value.
-     */
-    protected abstract doReverse(transformedValue: bigint): bigint;
-    /**
-     * Transform a value in reverse.
-     *
-     * @param transformedValue
-     * Transformed value.
-     *
-     * @returns
-     * Value.
-     */
-    reverse(transformedValue: number | bigint): bigint;
-}
-/**
- * Identity transformer. Values are transformed to themselves.
- */
-declare class IdentityTransformer extends Transformer {
-    /**
-     * @inheritDoc
-     */
-    protected doForward(value: bigint): bigint;
-    /**
-     * @inheritDoc
-     */
-    protected doReverse(transformedValue: bigint): bigint;
-}
-/**
- * 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.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
- * sequence can infer production volumes (e.g., serial number 1000 implies that at least 1,000 units have been
- * manufactured) or can be used in counterfeiting (e.g., a counterfeiter can generate serial numbers 1001, 1002, ...
- * with reasonable confidence that they would be valid if queried).
- *
- * The domain and the tweak together determine the encryption key, which in turn determines the number of rounds of
- * shuffle and xor operations. The minimum number of rounds is 4, except where the domain is less than or equal to 256,
- * which results in single-byte operations. To ensure that the operations are effective for single-byte domains, the
- * number of rounds is 1 and only the xor operation is applied (shuffling a single byte is an identity operation).
- *
- * Another exception is when there is a tweak value of 0; this results in identity operations where the output value is
- * identical to the input value, as no shuffle or xor takes place.
- */
-declare class EncryptionTransformer extends Transformer {
-    #private;
-    /**
-     * Constructor.
-     *
-     * @param domain
-     * Domain.
-     *
-     * @param tweak
-     * Tweak.
-     */
-    constructor(domain: number | bigint, tweak: number | bigint);
-    /**
-     * @inheritDoc
-     */
-    protected doForward(value: bigint): bigint;
-    /**
-     * @inheritDoc
-     */
-    protected doReverse(transformedValue: bigint): bigint;
-}
-
-/**
- * String validation interface. To ensure signature compatibility in implementing classes, string validation is
- * controlled by validation interfaces specific to each validator type.
- */
-interface StringValidation {
-}
-/**
- * String validator interface.
- *
- * @template TStringValidation
- * String validation type.
- */
-interface StringValidator<TStringValidation extends StringValidation = StringValidation> {
-    /**
-     * Validate a string and throw an error if validation fails.
-     *
-     * @param s
-     * String.
-     *
-     * @param validation
-     * String validation parameters.
-     */
-    validate: (s: string, validation?: TStringValidation) => void;
-}
-
-/**
- * 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.
- *
- * Clients of this class are recommended to override the {@linkcode createErrorMessage | createErrorMessage()} method
- * to create a more suitable error message for their use case.
- */
-declare class RegExpValidator implements StringValidator {
-    #private;
-    /**
-     * Constructor.
-     *
-     * @param regExp
-     * Regular expression. See {@link RegExpValidator | class documentation} for notes.
-     */
-    constructor(regExp: RegExp);
-    /**
-     * Get the regular expression.
-     */
-    get regExp(): RegExp;
-    /**
-     * Create an error message for a string. The generic error message is sufficient for many use cases but a more
-     * domain-specific error message, possibly including the pattern itself, is often required.
-     *
-     * @param s
-     * String.
-     *
-     * @returns
-     * Error message.
-     */
-    protected createErrorMessage(s: string): string;
-    /**
-     * @inheritDoc
-     */
-    validate(s: string): void;
-}
-
-/**
- * Record validator. Validation is performed against a record with a string key type and throws an error if the key is
- * not found.
- *
- * @template T
- * Property type.
- */
-declare class RecordValidator<T> implements StringValidator {
-    #private;
-    /**
-     * Constructor.
-     *
-     * @param typeName
-     * Type name for error message.
-     *
-     * @param record
-     * Record in which to look up keys.
-     */
-    constructor(typeName: string, record: Readonly<Record<string, T>>);
-    /**
-     * Get the type name.
-     */
-    get typeName(): string;
-    /**
-     * Get the record.
-     */
-    get record(): Readonly<Record<string, T>>;
-    /**
-     * Validate a key by looking it up in the record.
-     *
-     * @param key
-     * Record key.
-     */
-    validate(key: string): void;
-}
-
-/**
- * Exclusion options for validating and creating strings based on character sets.
- */
-declare const Exclusions: {
-    /**
-     * No strings excluded.
-     */
-    readonly None: 0;
-    /**
-     * Strings that start with zero ('0') excluded.
-     */
-    readonly FirstZero: 1;
-    /**
-     * Strings that are all-numeric (e.g., "123456") excluded.
-     */
-    readonly AllNumeric: 2;
-};
-/**
- * Exclusion key.
- */
-type ExclusionKey = keyof typeof Exclusions;
-/**
- * Exclusion.
- */
-type Exclusion = typeof Exclusions[ExclusionKey];
-
-/**
- * Character set validation parameters.
- */
-interface CharacterSetValidation extends StringValidation {
-    /**
-     * Minimum length. If defined and the string is less than this length, an error is thrown.
-     */
-    minimumLength?: number | undefined;
-    /**
-     * Maximum length. If defined and the string is greater than this length, an error is thrown.
-     */
-    maximumLength?: number | undefined;
-    /**
-     * Exclusion from the string. If defined and the string is within the exclusion range, an error is thrown.
-     */
-    exclusion?: Exclusion | undefined;
-    /**
-     * Position offset within a larger string. Strings are sometimes composed of multiple substrings; this parameter
-     * ensures that the error notes the proper position in the string.
-     */
-    positionOffset?: number | undefined;
-    /**
-     * Name of component, typically but not exclusively within a larger string. This parameter ensure that the
-     * error notes the component that triggered it. Value may be a string or a callback that returns a string, the
-     * latter allowing for localization changes.
-     */
-    component?: string | (() => string) | undefined;
-}
-/**
- * Character set validator. Validates a string against a specified character set.
- */
-declare class CharacterSetValidator implements StringValidator<CharacterSetValidation> {
-    #private;
-    /**
-     * Constructor.
-     *
-     * @param characterSet
-     * Character set. Each element is a single-character string, unique within the array, that defines the character
-     * set.
-     *
-     * @param exclusionSupport
-     * Exclusions supported by the character set. All character sets implicitly support {@linkcode Exclusions.None}.
-     */
-    constructor(characterSet: readonly string[], ...exclusionSupport: readonly Exclusion[]);
-    /**
-     * Get the character set.
-     */
-    get characterSet(): readonly string[];
-    /**
-     * Get the character set size.
-     */
-    get characterSetSize(): number;
-    /**
-     * Get the exclusions supported by the character set.
-     */
-    get exclusionSupport(): readonly Exclusion[];
-    /**
-     * Get the character at an index.
-     *
-     * @param index
-     * Index into the character set.
-     *
-     * @returns
-     * Character at the index.
-     */
-    character(index: number): string;
-    /**
-     * Get the index for a character.
-     *
-     * @param c
-     * Character.
-     *
-     * @returns
-     * Index for the character or undefined if the character is not in the character set.
-     */
-    characterIndex(c: string): number | undefined;
-    /**
-     * Get the indexes for all characters in a string.
-     *
-     * @param s
-     * String.
-     *
-     * @returns
-     * Array of indexes for each character or undefined if the character is not in the character set.
-     */
-    characterIndexes(s: string): ReadonlyArray<number | undefined>;
-    /**
-     * Validate that an exclusion is supported. If not, an error is thrown.
-     *
-     * @param exclusion
-     * Exclusion.
-     */
-    protected validateExclusion(exclusion: Exclusion): void;
-    /**
-     * Validate a string. If the string violates the character set or any of the character set validation parameters, an
-     * error is thrown.
-     *
-     * @param s
-     * String.
-     *
-     * @param validation
-     * Character set validation parameters.
-     */
-    validate(s: string, validation?: CharacterSetValidation): void;
-}
-/**
- * Character set creator. Maps numeric values to strings using the character set as digits.
- */
-declare class CharacterSetCreator extends CharacterSetValidator {
-    #private;
-    /**
-     * Maximum string length supported.
-     */
-    static readonly MAXIMUM_STRING_LENGTH = 40;
-    /**
-     * Get a power of 10.
-     *
-     * @param power
-     * Power.
-     *
-     * @returns
-     * `10**power`.
-     */
-    static powerOf10(power: number): bigint;
-    /**
-     * Constructor.
-     *
-     * @param characterSet
-     * Character set. Each element is a single-character string, unique within the array, that defines the character
-     * set.
-     *
-     * @param exclusionSupport
-     * Exclusions supported by the character set. All character sets implicitly support {@linkcode Exclusions.None}.
-     */
-    constructor(characterSet: readonly string[], ...exclusionSupport: readonly Exclusion[]);
-    /**
-     * Create string(s) by mapping value(s) to the equivalent characters in the character set across the length of the
-     * string.
-     *
-     * @template TTransformerInput
-     * Transformer input type.
-     *
-     * @param length
-     * Required string length.
-     *
-     * @param valueOrValues
-     * Numeric value(s) of the string(s).
-     *
-     * @param exclusion
-     * String(s) to be excluded from the range of outputs. See {@linkcode Exclusions} 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 creatorCallback
-     * If provided, called after each string is constructed to create the final value.
-     *
-     * @returns
-     * String(s) created from the value(s).
-     */
-    create<TTransformerInput extends TransformerInput<number | bigint>>(length: number, valueOrValues: TTransformerInput, exclusion?: Exclusion, tweak?: number | bigint, creatorCallback?: IndexedCallback<string, string>): TransformerOutput<TTransformerInput, string>;
-    /**
-     * Determine the value for a string.
-     *
-     * @param s
-     * String.
-     *
-     * @param exclusion
-     * Strings excluded from the range of inputs. See {@linkcode Exclusions} for possible values and their meaning.
-     *
-     * @param tweak
-     * If provided, the numerical value of the string was "tweaked" using an {@link EncryptionTransformer | encryption
-     * transformer}.
-     *
-     * @returns
-     * Numeric value of the string.
-     */
-    valueFor(s: string, exclusion?: Exclusion, tweak?: number | bigint): bigint;
-}
-/**
- * Numeric creator. Character set is 0-9. Supports {@linkcode Exclusions.FirstZero}.
- */
-declare const NUMERIC_CREATOR: CharacterSetCreator;
-/**
- * Numeric validator. Character set is 0-9. Supports {@linkcode Exclusions.FirstZero}.
- */
-declare const NUMERIC_VALIDATOR: CharacterSetValidator;
-/**
- * Hexadecimal creator. Character set is 0-9, A-F. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
- * Exclusions.AllNumeric}.
- */
-declare const HEXADECIMAL_CREATOR: CharacterSetCreator;
-/**
- * Hexadecimal validator. Character set is 0-9, A-F. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
- * Exclusions.AllNumeric}.
- */
-declare const HEXADECIMAL_VALIDATOR: CharacterSetValidator;
-/**
- * Alphabetic creator. Character set is A-Z.
- */
-declare const ALPHABETIC_CREATOR: CharacterSetCreator;
-/**
- * Alphabetic validator. Character set is A-Z.
- */
-declare const ALPHABETIC_VALIDATOR: CharacterSetValidator;
-/**
- * Alphanumeric creator. Character set is 0-9, A-Z. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
- * Exclusions.AllNumeric}.
- */
-declare const ALPHANUMERIC_CREATOR: CharacterSetCreator;
-/**
- * Alphanumeric validator. Character set is 0-9, A-Z. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
- * Exclusions.AllNumeric}.
- */
-declare const ALPHANUMERIC_VALIDATOR: CharacterSetValidator;
-
-export { ALPHABETIC_CREATOR, ALPHABETIC_VALIDATOR, ALPHANUMERIC_CREATOR, ALPHANUMERIC_VALIDATOR, CharacterSetCreator, type CharacterSetValidation, CharacterSetValidator, EncryptionTransformer, type Exclusion, type ExclusionKey, Exclusions, HEXADECIMAL_CREATOR, HEXADECIMAL_VALIDATOR, IdentityTransformer, type IndexedCallback, NUMERIC_CREATOR, NUMERIC_VALIDATOR, RecordValidator, RegExpValidator, Sequence, type StringValidation, type StringValidator, Transformer, type TransformerInput, type TransformerOutput, type TransformerPrimitive, type UtilityLocaleResources, i18nUtilityInit, i18nextUtility, mapIterable, utilityNS, utilityResourceBundle };
+/*!
+ * Copyright © 2024-2026 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 "./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";
+//# sourceMappingURL=index.d.ts.map