@aidc-toolkit/utility 1.0.45 → 1.0.46-beta

package/dist/character-set.d.ts

@@ -0,0 +1,242 @@
+import { type Exclusion } from "./exclusion.js";
+import type { IndexedCallback } from "./iterable-utility.js";
+import type { StringValidation, StringValidator } from "./string.js";
+/**
+ * Character set validation parameters.
+ */
+export 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.
+ */
+export 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 | undefined): 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.
+ */
+export 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 a string by mapping a value to the equivalent characters in the character set across the required string
+     * length.
+     *
+     * @param length
+     * Required string length.
+     *
+     * @param value
+     * Numeric value of the string.
+     *
+     * @param exclusion
+     * Strings to be excluded from the output range. See {@linkcode Exclusions} for possible values and their meanings.
+     *
+     * @param tweak
+     * If provided, the numeric value of the string is "tweaked" using an {@link EncryptionTransformer | encryption
+     * transformer}.
+     *
+     * @param creatorCallback
+     * Called after the string is constructed to create the final value.
+     *
+     * @returns
+     * String created from the value.
+     */
+    create(length: number, value: number | bigint, exclusion?: Exclusion, tweak?: number | bigint, creatorCallback?: IndexedCallback<string, string>): string;
+    /**
+     * Create strings by mapping values to the equivalent characters in the character set across the required string
+     * length.
+     *
+     * @param length
+     * Required string length.
+     *
+     * @param values
+     * Numeric values of the string.
+     *
+     * @param exclusion
+     * Strings to be excluded from the output range. See {@linkcode Exclusions} for possible values and their meanings.
+     *
+     * @param tweak
+     * If provided, the numeric value of each string is "tweaked" using an {@link EncryptionTransformer | encryption
+     * transformer}.
+     *
+     * @param creatorCallback
+     * Called after each string is constructed to create the final value.
+     *
+     * @returns
+     * Strings created from the values.
+     */
+    create(length: number, values: Iterable<number | bigint>, exclusion?: Exclusion, tweak?: number | bigint, creatorCallback?: IndexedCallback<string, string>): Iterable<string>;
+    create<TInput extends number | bigint | Iterable<number | bigint>>(length: number, valueOrValues: TInput extends Iterable<number | bigint> ? TInput : number | bigint, exclusion?: Exclusion, tweak?: number | bigint, creatorCallback?: IndexedCallback<string, string>): TInput extends Iterable<number | bigint> ? Iterable<string> : string;
+    /**
+     * Determine the value for a string.
+     *
+     * @param s
+     * String.
+     *
+     * @param exclusion
+     * Strings excluded from the input domain. See {@linkcode Exclusions} for possible values and their meanings.
+     *
+     * @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}.
+ */
+export declare const NUMERIC_CREATOR: CharacterSetCreator;
+/**
+ * Numeric validator. Character set is 0-9. Supports {@linkcode Exclusions.FirstZero}.
+ */
+export declare const NUMERIC_VALIDATOR: CharacterSetValidator;
+/**
+ * Hexadecimal creator. Character set is 0-9, A-F. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
+ * Exclusions.AllNumeric}.
+ */
+export declare const HEXADECIMAL_CREATOR: CharacterSetCreator;
+/**
+ * Hexadecimal validator. Character set is 0-9, A-F. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
+ * Exclusions.AllNumeric}.
+ */
+export declare const HEXADECIMAL_VALIDATOR: CharacterSetValidator;
+/**
+ * Alphabetic creator. Character set is A-Z.
+ */
+export declare const ALPHABETIC_CREATOR: CharacterSetCreator;
+/**
+ * Alphabetic validator. Character set is A-Z.
+ */
+export declare const ALPHABETIC_VALIDATOR: CharacterSetValidator;
+/**
+ * Alphanumeric creator. Character set is 0-9, A-Z. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
+ * Exclusions.AllNumeric}.
+ */
+export declare const ALPHANUMERIC_CREATOR: CharacterSetCreator;
+/**
+ * Alphanumeric validator. Character set is 0-9, A-Z. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
+ * Exclusions.AllNumeric}.
+ */
+export declare const ALPHANUMERIC_VALIDATOR: CharacterSetValidator;
+//# sourceMappingURL=character-set.d.ts.map

package/dist/character-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-set.d.ts","sourceRoot":"","sources":["../src/character-set.ts"],"names":[],"mappings":"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"}