@aidc-toolkit/utility 0.9.3 → 0.9.5

package/dist/index.d.ts

@@ -0,0 +1,909 @@
+/**
+ * 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 {@link Iterator} variable directly. Otherwise, it references an
+ * implementation of "from" that uses an internally-defined iterator proxy object.
+ *
+ * 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.
+ */
+declare const IteratorProxy: Pick<IteratorConstructor, "from">;
+
+/**
+ * Sequencer. Defines an ascending or descending sequence of big integers implemented as an iterable iterator.
+ */
+declare class Sequencer implements Iterable<bigint>, IterableIterator<bigint> {
+    /**
+     * Start value (inclusive).
+     */
+    private readonly _startValue;
+    /**
+     * End value (exclusive).
+     */
+    private readonly _endValue;
+    /**
+     * Count of values.
+     */
+    private readonly _count;
+    /**
+     * Delta to the next value; equal to the sign of the count.
+     */
+    private readonly _nextDelta;
+    /**
+     * Minimum value (inclusive).
+     */
+    private readonly _minValue;
+    /**
+     * Maximum value (inclusive).
+     */
+    private readonly _maxValue;
+    /**
+     * Next value.
+     */
+    private _nextValue;
+    /**
+     * 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 minValue(): bigint;
+    /**
+     * Get the maximum value (inclusive).
+     */
+    get maxValue(): bigint;
+    /**
+     * Iterable implementation.
+     *
+     * @returns
+     * this
+     */
+    [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;
+}
+
+/**
+ * Transformation callback, used to convert transformed value to its final value.
+ *
+ * @template T
+ * Type returned by callback.
+ *
+ * @param transformedValue
+ * Transformed value.
+ *
+ * @param index
+ * Index in sequence transformation (0 for single transformation).
+ *
+ * @returns
+ * Final value.
+ */
+type TransformationCallback<T> = (transformedValue: bigint, index: number) => T;
+/**
+ * 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: {@link IdentityTransformer} (which operates based on a domain
+ * only) and {@link 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 {@link get} method. Properties in {@link IdentityTransformer} and
+ * {@link EncryptionTransformer} are read-only once constructed, so there is no issue with their shared use.
+ */
+declare abstract class Transformer {
+    /**
+     * Transformers cache, mapping a domain to another map, which maps an optional tweak to a transformer.
+     */
+    private static readonly TRANSFORMER_MAPS_MAP;
+    /**
+     * Domain.
+     */
+    private readonly _domain;
+    /**
+     * Constructor.
+     *
+     * @param domain
+     * Domain.
+     */
+    constructor(domain: number | bigint);
+    /**
+     * Get a transformer, constructing it if necessary. The type returned is {@link IdentityTransformer} if tweak is
+     * undefined, {@link EncryptionTransformer} if tweak is defined. Note that although an {@link EncryptionTransformer}
+     * with a zero tweak operates as an {@link IdentityTransformer}, {@link EncryptionTransformer} is still the type
+     * returned if a zero tweak is explicitly specified.
+     *
+     * @param domain
+     * Domain.
+     *
+     * @param tweak
+     * Tweak.
+     *
+     * @returns
+     * {@link IdentityTransformer} if tweak is undefined, {@link EncryptionTransformer} if tweak is defined.
+     */
+    static get(domain: number | bigint, tweak?: number | bigint): Transformer;
+    /**
+     * Get the domain.
+     */
+    get domain(): bigint;
+    /**
+     * Validate that a value is within the domain.
+     *
+     * @param value
+     * Value.
+     */
+    private validate;
+    /**
+     * Do the work of transforming a value forward.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Transformed value.
+     */
+    protected abstract doForward(value: bigint): bigint;
+    /**
+     * Transform a value forward.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Transformed value.
+     */
+    forward(value: number | bigint): bigint;
+    /**
+     * Transform a value forward.
+     *
+     * @template T
+     * Type returned by transformation callback.
+     *
+     * @param value
+     * Value.
+     *
+     * @param transformationCallback
+     * Called after the value is transformed to convert it to its final value.
+     *
+     * @returns
+     * Value transformed into object.
+     */
+    forward<T>(value: number | bigint, transformationCallback: TransformationCallback<T>): T;
+    /**
+     * Transform values forward.
+     *
+     * @param values
+     * Values. If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * transformation. Otherwise, the individual values are validated at the time of transformation.
+     *
+     * @returns
+     * Transformed values.
+     */
+    forward(values: Iterable<number | bigint>): IterableIterator<bigint>;
+    /**
+     * Transform values forward.
+     *
+     * @template T
+     * Type returned by transformation callback.
+     *
+     * @param values
+     * Values. If this is an instance of {@link Sequencer}, the minimum and maximum values are validated prior to
+     * transformation. Otherwise, the individual values are validated at the time of transformation.
+     *
+     * @param transformationCallback
+     * Called after each value is transformed to convert it to its final value.
+     *
+     * @returns
+     * Values transformed into objects.
+     */
+    forward<T>(values: Iterable<number | bigint>, transformationCallback: TransformationCallback<T>): IterableIterator<T>;
+    /**
+     * Transform a value or values forward. This signature exists to allow similar overloaded methods in other classes
+     * to call this method correctly.
+     *
+     * @param valueOrValues
+     *
+     * @returns
+     */
+    forward(valueOrValues: number | bigint | Iterable<number | bigint>): bigint | IterableIterator<bigint>;
+    /**
+     * Transform a value or values forward. This signature exists to allow similar overloaded methods in other classes
+     * to call this method correctly.
+     *
+     * @template T
+     *
+     * @param valueOrValues
+     *
+     * @param transformationCallback
+     *
+     * @returns
+     */
+    forward<T>(valueOrValues: number | bigint | Iterable<number | bigint>, transformationCallback: TransformationCallback<T>): T | IterableIterator<T>;
+    /**
+     * 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. 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.
+ *
+ * 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 {
+    /**
+     * Individual bits, pre-calculated for performance.
+     */
+    private static readonly BITS;
+    /**
+     * Inverse individual bits, pre-calculated for performance.
+     */
+    private static readonly INVERSE_BITS;
+    /**
+     * Number of bytes covered by the domain.
+     */
+    private readonly _domainBytes;
+    /**
+     * Tweak.
+     */
+    private readonly _tweak;
+    /**
+     * Xor bytes array generated from the domain and tweak.
+     */
+    private readonly _xorBytes;
+    /**
+     * Bits array generated from the domain and tweak.
+     */
+    private readonly _bits;
+    /**
+     * Inverse bits array generated from the domain and tweak.
+     */
+    private readonly _inverseBits;
+    /**
+     * Number of rounds (length of arrays) generated from the domain and tweak.
+     */
+    private readonly _rounds;
+    /**
+     * Constructor.
+     *
+     * @param domain
+     * Domain.
+     *
+     * @param tweak
+     * 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.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Big-endian byte array equivalent to the value.
+     */
+    private valueToBytes;
+    /**
+     * Convert a byte array to a value.
+     *
+     * @param bytes
+     * Big-endian byte array equivalent to the value.
+     *
+     * @returns
+     * Value.
+     */
+    private static bytesToValue;
+    /**
+     * Shuffle a byte array.
+     *
+     * The input array to the forward operation (output from the reverse operation) is `bytes` and the output array from
+     * the forward operation (input to the reverse operation) is `bytes'`.
+     *
+     * The shuffle operation starts by testing the bit at `bits[round]` for each `byte` in `bytes`. The indexes for all
+     * bytes with that bit set are put into one array (`shuffleIndexes1`) and the rest are put into another
+     * (`shuffleIndexes0`). The two arrays are concatenated and used to shuffle the input array, using their values
+     * (`shuffleIndex`) and the indexes of those values (`index`) in the concatenated array.
+     *
+     * Forward shuffling moves the entry at `shuffleIndex` to the `index` position.
+     *
+     * Reverse shuffling moves the entry at `index` to the `shuffleIndex` position.
+     *
+     * As each byte is moved, the bit at `bits[round]` is preserved in its original position. This ensures that the
+     * process is reversible.
+     *
+     * @param bytes
+     * Byte array.
+     *
+     * @param round
+     * Round number.
+     *
+     * @param forward
+     * True if operating forward (encrypting), false if operating in reverse (decrypting).
+     *
+     * @returns
+     * Shuffled byte array.
+     */
+    private shuffle;
+    /**
+     * Xor a byte array.
+     *
+     * The input array to the forward operation (output from the reverse operation) is `bytes` and the output array from
+     * the forward operation (input to the reverse operation) is `bytes'`.
+     *
+     * Forward:
+     * - `bytes'[0] = bytes[0] ^ xorBytes[round]`
+     * - `bytes'[1] = bytes[1] ^ bytes'[0]`
+     * - `bytes'[2] = bytes[2] ^ bytes'[1]`
+     * - `...`
+     * - `bytes'[domainBytes - 1] = bytes[domainBytes - 1] ^ bytes'[domainBytes - 2]`
+     *
+     * Reverse:
+     * - `bytes[0] = bytes'[0] ^ xorBytes[round]`
+     * - `bytes[1] = bytes'[1] ^ bytes'[0]`
+     * - `bytes[2] = bytes'[2] ^ bytes'[1]`
+     * - `...`
+     * - `bytes[domainBytes - 1] = bytes'[domainBytes - 1] ^ bytes'[domainBytes - 2]`
+     *
+     * @param bytes
+     * Byte array.
+     *
+     * @param round
+     * Round number.
+     *
+     * @param forward
+     * True if operating forward (encrypting), false if operating in reverse (decrypting).
+     *
+     * @returns
+     * Xored byte array.
+     */
+    private xor;
+    /**
+     * @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.
+ */
+interface StringValidator<V 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?: V) => 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 {@link createErrorMessage} method create a more suitable error
+ * message for their use case.
+ */
+declare class RegExpValidator implements StringValidator {
+    /**
+     * Regular expression.
+     */
+    private readonly _regExp;
+    /**
+     * 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.
+ */
+declare class RecordValidator<T> implements StringValidator {
+    /**
+     * Type name for error message.
+     */
+    private readonly _typeName;
+    /**
+     * Record in which to look up keys.
+     */
+    private readonly _record;
+    /**
+     * 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 enum Exclusion {
+    /**
+     * No strings excluded.
+     */
+    None = 0,
+    /**
+     * Strings that start with zero ('0') excluded.
+     */
+    FirstZero = 1,
+    /**
+     * Strings that are all-numeric (e.g., "123456") excluded.
+     */
+    AllNumeric = 2
+}
+/**
+ * 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 static readonly NOT_ALL_NUMERIC_VALIDATOR;
+    /**
+     * Character set.
+     */
+    private readonly _characterSet;
+    /**
+     * Character set map, mapping each character in the character set to its index such that
+     * `_characterSetMap.get(_characterSet[index]) === index`.
+     */
+    private readonly _characterSetMap;
+    /**
+     * Exclusions supported by the character set.
+     */
+    private readonly _exclusionSupport;
+    /**
+     * 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 {@link Exclusion.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>;
+    /**
+     * Convert a component definition to a string or undefined. Checks the type of the component and makes the callback
+     * if required.
+     *
+     * @param component
+     * Component definition as a string, callback, or undefined.
+     *
+     * @returns
+     * Component as a string or undefined.
+     */
+    private static componentToString;
+    /**
+     * 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;
+}
+/**
+ * Creation callback, used to convert created string to its final value.
+ *
+ * @param s
+ * Created string.
+ *
+ * @param index
+ * Index in sequence creation (0 for single creation).
+ *
+ * @returns
+ * Final value.
+ */
+type CreationCallback = (s: string, index: number) => string;
+/**
+ * Character set creator. Maps numeric values to strings using the character set as digits.
+ */
+declare class CharacterSetCreator extends CharacterSetValidator {
+    /**
+     * Maximum string length supported.
+     */
+    static readonly MAXIMUM_STRING_LENGTH = 40;
+    /**
+     * Powers of 10 from 1 (`10**0`) to `10**MAXIMUM_STRING_LENGTH`.
+     */
+    private static readonly _powersOf10;
+    /**
+     * Create powers of a given base from 1 (`base**0`) to `base**MAXIMUM_STRING_LENGTH`.
+     *
+     * @param base
+     * Number base.
+     *
+     * @returns
+     * Array of powers of base.
+     */
+    private static createPowersOf;
+    /**
+     * Get a power of 10.
+     *
+     * @param power
+     * Power.
+     *
+     * @returns
+     * `10**power`.
+     */
+    static powerOf10(power: number): bigint;
+    /**
+     * Character set size as big integer, cached for performance purposes.
+     */
+    private readonly _characterSetSizeN;
+    /**
+     * Character set size minus 1 as big integer, cached for performance purposes.
+     */
+    private readonly _characterSetSizeMinusOneN;
+    /**
+     * Domains for every length for every supported {@link Exclusion}.
+     */
+    private readonly _exclusionDomains;
+    /**
+     * Values that would generate all zeros in the created string.
+     */
+    private readonly _allZerosValues;
+    /**
+     * 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 {@link Exclusion.None}.
+     */
+    constructor(characterSet: readonly string[], ...exclusionSupport: readonly Exclusion[]);
+    /**
+     * Get a power of character set size.
+     *
+     * @param power
+     * Power.
+     *
+     * @returns
+     * `characterSetSize**power`.
+     */
+    private powerOfSize;
+    /**
+     * Determine the shift required to skip all all-numeric strings up to the value.
+     *
+     * @param shiftForward
+     * True to shift forward (value to string), false to shift backward (string to value).
+     *
+     * @param length
+     * Length of string for which to get the all-numeric shift.
+     *
+     * @param value
+     * Value for which to get the all-numeric shift.
+     *
+     * @returns
+     * Shift required to skip all all-numeric strings.
+     */
+    private allNumericShift;
+    /**
+     * Validate that a length is less than or equal to {@link MAXIMUM_STRING_LENGTH}. If not, an error is thrown.
+     *
+     * @param length
+     * Length.
+     */
+    private validateLength;
+    /**
+     * Create a string by mapping a value to the equivalent characters in the character set across the length of the
+     * string.
+     *
+     * @param length
+     * Required string length.
+     *
+     * @param value
+     * Numeric value of the string.
+     *
+     * @param exclusion
+     * Strings to be excluded from the range of outputs. See {@link Exclusion} for possible values and their meaning.
+     *
+     * @param tweak
+     * If provided, the numerical value of the string is "tweaked" using an {@link EncryptionTransformer | encryption
+     * transformer}.
+     *
+     * @param creationCallback
+     * If provided, 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, creationCallback?: CreationCallback): string;
+    /**
+     * Create multiple strings by mapping each value to the equivalent characters in the character set across the length
+     * of the string. Equivalent to calling this method for each individual value.
+     *
+     * @param length
+     * Required string length.
+     *
+     * @param values
+     * Numeric values of the strings.
+     *
+     * @param exclusion
+     * Strings to be excluded from the range of outputs. See {@link Exclusion} for possible values and their meaning.
+     *
+     * @param tweak
+     * If provided, the numerical value of the strings are "tweaked" using an {@link EncryptionTransformer | encryption
+     * transformer}.
+     *
+     * @param creationCallback
+     * If provided, called after each string is constructed to create the final value.
+     *
+     * @returns
+     * Iterable iterator over strings created from the values.
+     */
+    create(length: number, values: Iterable<number | bigint>, exclusion?: Exclusion, tweak?: number | bigint, creationCallback?: CreationCallback): IterableIterator<string>;
+    /**
+     * Create a string or multiple strings. This signature exists to allow similar overloaded methods in other classes
+     * to call this method correctly.
+     *
+     * @param length
+     *
+     * @param valueOrValues
+     *
+     * @param exclusion
+     *
+     * @param tweak
+     *
+     * @param creationCallback
+     *
+     * @returns
+     */
+    create(length: number, valueOrValues: number | bigint | Iterable<number | bigint>, exclusion?: Exclusion, tweak?: number | bigint, creationCallback?: CreationCallback): string | IterableIterator<string>;
+    /**
+     * Determine the value for a string.
+     *
+     * @param s
+     * String.
+     *
+     * @param exclusion
+     * Strings excluded from the range of inputs. See {@link Exclusion} 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 {@link Exclusion.FirstZero}.
+ */
+declare const NUMERIC_CREATOR: CharacterSetCreator;
+/**
+ * Hexadecimal creator. Character set is 0-9, A-F. Supports {@link Exclusion.FirstZero} and {@link
+ * Exclusion.AllNumeric}.
+ */
+declare const HEXADECIMAL_CREATOR: CharacterSetCreator;
+/**
+ * Alphabetic creator. Character set is A-Z.
+ */
+declare const ALPHABETIC_CREATOR: CharacterSetCreator;
+/**
+ * Alphanumeric creator. Character set is 0-9, A-Z. Supports {@link Exclusion.FirstZero} and {@link
+ * Exclusion.AllNumeric}.
+ */
+declare const ALPHANUMERIC_CREATOR: CharacterSetCreator;
+
+export { ALPHABETIC_CREATOR, ALPHANUMERIC_CREATOR, CharacterSetCreator, type CharacterSetValidation, CharacterSetValidator, type CreationCallback, EncryptionTransformer, Exclusion, HEXADECIMAL_CREATOR, IdentityTransformer, IteratorProxy, NUMERIC_CREATOR, RecordValidator, RegExpValidator, Sequencer, type StringValidation, type StringValidator, type TransformationCallback, Transformer };