@aidc-toolkit/utility 1.0.23-beta → 1.0.25-beta

package/dist/sequence.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sequence.js","sourceRoot":"","sources":["../src/sequence.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,QAAQ;IACjB;;OAEG;IACc,WAAW,CAAS;IAErC;;OAEG;IACc,SAAS,CAAS;IAEnC;;OAEG;IACc,MAAM,CAAS;IAEhC;;OAEG;IACc,UAAU,CAAW;IAEtC;;OAEG;IACc,aAAa,CAAS;IAEvC;;OAEG;IACc,aAAa,CAAS;IAEvC;;;;;;;;;OASG;IACH,YAAY,UAA2B,EAAE,KAAa;QAClD,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QAEpB,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACb,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC;YACtC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;QAC7C,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;YACzC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC;QAC1C,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAI,QAAQ;QACR,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,IAAI,YAAY;QACZ,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,YAAY;QACZ,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,CAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,IAAI,CAAC,SAAS,EAAE,KAAK,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpF,MAAM,KAAK,CAAC;QAChB,CAAC;IACL,CAAC;CACJ"}

package/dist/string.d.ts

@@ -1,25 +0,0 @@
-/**
- * String validation interface. To ensure signature compatibility in implementing classes, string validation is
- * controlled by validation interfaces specific to each validator type.
- */
-export interface StringValidation {
-}
-/**
- * String validator interface.
- *
- * @template V
- * String validation type.
- */
-export 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;
-}
-//# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../src/string.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,gBAAgB;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IAC1E;;;;;;;;OAQG;IACH,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;CACjD"}

package/dist/string.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=string.js.map

package/dist/string.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"string.js","sourceRoot":"","sources":["../src/string.ts"],"names":[],"mappings":""}

package/dist/transformer.d.ts

@@ -1,346 +0,0 @@
-import { type IndexedCallback } from "./iterable-utility.js";
-/**
- * Transformer primitive type.
- */
-export type TransformerPrimitive = string | number | bigint | boolean;
-/**
- * Transformer input type, one of:
- *
- * - TInput (primitive type)
- * - Iterable\<TInput\>
- *
- * @template TInput
- * Transformer input primitive type.
- */
-export 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.
- */
-export 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: {@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.
- */
-export 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;
-    /**
-     * 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 TTransformerInput
-     * Value(s) input type.
-     *
-     * @param valueOrValues
-     * 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<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 {@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
-     * 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.
- */
-export 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-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
- * 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.
- */
-export 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;
-    /**
-     * 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);
-    /**
-     * 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;
-}
-//# sourceMappingURL=transformer.d.ts.map

package/dist/transformer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../src/transformer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAe,MAAM,uBAAuB,CAAC;AAI1E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,CAAC,MAAM,SAAS,oBAAoB,IAAI,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAE9F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,CAAC,iBAAiB,SAAS,gBAAgB,CAAC,oBAAoB,CAAC,EAAE,OAAO,IAAI,iBAAiB,SAAS,CAAC,iBAAiB,SAAS,gBAAgB,CAAC,MAAM,MAAM,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;AAE/O;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,WAAW;IAC7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAA2D;IAEvG;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,GAAG,MAAM;IAUnC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAsBzE;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAehB;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAEnD;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iBAAiB,SAAS,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,aAAa,EAAE,iBAAiB,GAAG,iBAAiB,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEpJ;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,iBAAiB,SAAS,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAAC,iBAAiB,EAAE,OAAO,CAAC;IAgCrN;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM;IAE9D;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;CAOrD;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAChD;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI1C;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM;CAGxD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,qBAAsB,SAAQ,WAAW;IAClD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAEzB;IAEH;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAEjC;IAEH;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IAEvC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAE1C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;;;;;OAQG;gBACS,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAyD3D;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAWpB;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAI3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,CAAC,OAAO;IAmCf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,OAAO,CAAC,GAAG;IAYX;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAiB1C;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM;CAgBxD"}