@aidc-toolkit/utility 1.0.24-beta → 1.0.26-beta

package/dist/transformer.js

@@ -0,0 +1,457 @@
+import { mapIterable } from "./iterable-utility.js";
+import { i18nextUtility } from "./locale/i18n.js";
+import { Sequence } from "./sequence.js";
+/**
+ * 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.
+ */
+export class Transformer {
+    /**
+     * Transformers cache, mapping a domain to another map, which maps an optional tweak to a transformer.
+     */
+    static TRANSFORMER_MAPS_MAP = new Map();
+    /**
+     * Domain.
+     */
+    _domain;
+    /**
+     * Constructor.
+     *
+     * @param domain
+     * Domain.
+     */
+    constructor(domain) {
+        this._domain = BigInt(domain);
+        if (this._domain <= 0n) {
+            throw new RangeError(i18nextUtility.t("Transformer.domainMustBeGreaterThanZero", {
+                domain
+            }));
+        }
+    }
+    /**
+     * 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, tweak) {
+        const domainN = BigInt(domain);
+        let transformersMap = Transformer.TRANSFORMER_MAPS_MAP.get(domainN);
+        if (transformersMap === undefined) {
+            transformersMap = new Map();
+            Transformer.TRANSFORMER_MAPS_MAP.set(domainN, transformersMap);
+        }
+        const tweakN = tweak === undefined ? undefined : BigInt(tweak);
+        let transformer = transformersMap.get(tweakN);
+        if (transformer === undefined) {
+            transformer = tweakN === undefined ? new IdentityTransformer(domainN) : new EncryptionTransformer(domainN, tweakN);
+            transformersMap.set(tweakN, transformer);
+        }
+        return transformer;
+    }
+    /**
+     * Get the domain.
+     */
+    get domain() {
+        return this._domain;
+    }
+    /**
+     * Validate that a value is within the domain.
+     *
+     * @param value
+     * Value.
+     */
+    validate(value) {
+        if (value < 0n) {
+            throw new RangeError(i18nextUtility.t("Transformer.valueMustBeGreaterThanOrEqualToZero", {
+                value
+            }));
+        }
+        if (value >= this.domain) {
+            throw new RangeError(i18nextUtility.t("Transformer.valueMustBeLessThan", {
+                value,
+                domain: this.domain
+            }));
+        }
+    }
+    /**
+     * Validate that a value is within the domain and do the work of transforming it forward.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Transformed value.
+     */
+    validateDoForward(value) {
+        const valueN = BigInt(value);
+        this.validate(valueN);
+        return this.doForward(valueN);
+    }
+    /**
+     * 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.
+     */
+    validateDoForwardCallback(transformerCallback, value, index) {
+        return transformerCallback(this.validateDoForward(value), index);
+    }
+    ;
+    // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
+    forward(valueOrValues, transformerCallback) {
+        // TODO Refactor type when https://github.com/microsoft/TypeScript/pull/56941 released.
+        let result;
+        if (typeof valueOrValues !== "object") {
+            result = transformerCallback === undefined ? this.validateDoForward(valueOrValues) : this.validateDoForwardCallback(transformerCallback, valueOrValues);
+        }
+        else if (valueOrValues instanceof Sequence) {
+            if (valueOrValues.minimumValue < 0n) {
+                throw new RangeError(i18nextUtility.t("Transformer.minimumValueMustBeGreaterThanOrEqualToZero", {
+                    minimumValue: valueOrValues.minimumValue
+                }));
+            }
+            if (valueOrValues.maximumValue >= this.domain) {
+                throw new RangeError(i18nextUtility.t("Transformer.maximumValueMustBeLessThan", {
+                    maximumValue: valueOrValues.maximumValue,
+                    domain: this.domain
+                }));
+            }
+            result = transformerCallback === undefined ? mapIterable(valueOrValues, value => this.doForward(value)) : mapIterable(valueOrValues, (value, index) => transformerCallback(this.doForward(value), index));
+        }
+        else {
+            result = transformerCallback === undefined ? mapIterable(valueOrValues, value => this.validateDoForward(value)) : mapIterable(valueOrValues, (value, index) => this.validateDoForwardCallback(transformerCallback, value, index));
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type determination is handled above.
+        return result;
+    }
+    /**
+     * Transform a value in reverse.
+     *
+     * @param transformedValue
+     * Transformed value.
+     *
+     * @returns
+     * Value.
+     */
+    reverse(transformedValue) {
+        const transformedValueN = BigInt(transformedValue);
+        this.validate(transformedValueN);
+        return this.doReverse(transformedValueN);
+    }
+}
+/**
+ * Identity transformer. Values are transformed to themselves.
+ */
+export class IdentityTransformer extends Transformer {
+    /**
+     * @inheritDoc
+     */
+    doForward(value) {
+        return value;
+    }
+    /**
+     * @inheritDoc
+     */
+    doReverse(transformedValue) {
+        return transformedValue;
+    }
+}
+/**
+ * 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.
+ */
+export class EncryptionTransformer extends Transformer {
+    /**
+     * Individual bits, pre-calculated for performance.
+     */
+    static BITS = new Uint8Array([
+        0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80
+    ]);
+    /**
+     * Inverse individual bits, pre-calculated for performance.
+     */
+    static INVERSE_BITS = new Uint8Array([
+        0xFE, 0xFD, 0xFB, 0xF7, 0xEF, 0xDF, 0xBF, 0x7F
+    ]);
+    /**
+     * Number of bytes covered by the domain.
+     */
+    _domainBytes;
+    /**
+     * Xor bytes array generated from the domain and tweak.
+     */
+    _xorBytes;
+    /**
+     * Bits array generated from the domain and tweak.
+     */
+    _bits;
+    /**
+     * Inverse bits array generated from the domain and tweak.
+     */
+    _inverseBits;
+    /**
+     * Number of rounds (length of arrays) generated from the domain and tweak.
+     */
+    _rounds;
+    /**
+     * Constructor.
+     *
+     * @param domain
+     * Domain.
+     *
+     * @param tweak
+     * Tweak.
+     */
+    constructor(domain, tweak) {
+        super(domain);
+        if (tweak < 0n) {
+            throw new RangeError(i18nextUtility.t("Transformer.tweakMustBeGreaterThanOrEqualToZero", {
+                tweak
+            }));
+        }
+        let domainBytes = 0;
+        // The number of bytes in the domain determines the size of the shuffle and xor operations.
+        for (let reducedDomainMinusOne = this.domain - 1n; reducedDomainMinusOne !== 0n; reducedDomainMinusOne >>= 8n) {
+            domainBytes++;
+        }
+        this._domainBytes = domainBytes;
+        const xorBytes = new Array();
+        const bits = new Array();
+        const inverseBits = new Array();
+        // Key is the product of domain, tweak, and an 8-digit prime to force at least four rounds.
+        for (let reducedKey = this.domain * BigInt(tweak) * 603868999n; reducedKey !== 0n; reducedKey >>= 8n) {
+            // Extract the least significant byte.
+            xorBytes.unshift(Number(BigInt.asUintN(8, reducedKey)));
+            // Bit number is the reduced key mod 8.
+            const bitNumber = Number(BigInt.asUintN(3, reducedKey));
+            // Bits are applied in reverse order so that they don't correlate directly with the key bytes at the same index.
+            bits.push(EncryptionTransformer.BITS[bitNumber]);
+            inverseBits.push(EncryptionTransformer.INVERSE_BITS[bitNumber]);
+        }
+        // Domains occupying a single byte will not shuffle and will map all values to themselves for very small domains.
+        if (domainBytes === 1) {
+            // Determine the lowest possible mask that will cover all values in the domain.
+            const domainMask = EncryptionTransformer.BITS.filter(bit => bit < domain).reduce((accumulator, bit) => accumulator | bit, 0);
+            // Reduce all xor bytes to a single byte and strip higher bits.
+            this._xorBytes = new Uint8Array([xorBytes.reduce((accumulator, xorByte) => accumulator ^ xorByte, 0) & domainMask]);
+            // Bits and inverse bits are irrelevant as there will be no shuffling; choose first bit arbitrarily.
+            this._bits = new Uint8Array([EncryptionTransformer.BITS[0]]);
+            this._inverseBits = new Uint8Array([EncryptionTransformer.INVERSE_BITS[0]]);
+            // Everything will be done in one round.
+            this._rounds = 1;
+        }
+        else {
+            this._xorBytes = new Uint8Array(xorBytes);
+            this._bits = new Uint8Array(bits);
+            this._inverseBits = new Uint8Array(inverseBits);
+            this._rounds = xorBytes.length;
+        }
+    }
+    /**
+     * 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.
+     */
+    valueToBytes(value) {
+        const bytes = new Uint8Array(this._domainBytes);
+        // Build byte array in reverse order to get as big-endian.
+        for (let index = this._domainBytes - 1, reducedValue = value; index >= 0 && reducedValue !== 0n; index--, reducedValue >>= 8n) {
+            bytes[index] = Number(BigInt.asUintN(8, reducedValue));
+        }
+        return bytes;
+    }
+    /**
+     * Convert a byte array to a value.
+     *
+     * @param bytes
+     * Big-endian byte array equivalent to the value.
+     *
+     * @returns
+     * Value.
+     */
+    static bytesToValue(bytes) {
+        return bytes.reduce((accumulator, byte) => accumulator << 8n | BigInt(byte), 0n);
+    }
+    /**
+     * 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.
+     */
+    shuffle(bytes, round, forward) {
+        const bytesLength = bytes.length;
+        const determinants = new Uint8Array(bytesLength);
+        const shuffleIndexes1 = new Array();
+        const shuffleIndexes0 = new Array();
+        const bit = this._bits[round];
+        bytes.forEach((byte, index) => {
+            const determinant = byte & bit;
+            determinants[index] = determinant;
+            // Place byte in array chosen by bit state.
+            (determinant !== 0 ? shuffleIndexes1 : shuffleIndexes0).push(index);
+        });
+        const inverseBit = this._inverseBits[round];
+        const shuffleBytes = new Uint8Array(bytesLength);
+        // Concatenate shuffle indexes arrays and complete shuffle.
+        [...shuffleIndexes1, ...shuffleIndexes0].forEach((shuffleIndex, index) => {
+            if (forward) {
+                shuffleBytes[index] = (bytes[shuffleIndex] & inverseBit) | determinants[index];
+            }
+            else {
+                shuffleBytes[shuffleIndex] = (bytes[index] & inverseBit) | determinants[shuffleIndex];
+            }
+        });
+        return shuffleBytes;
+    }
+    /**
+     * 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.
+     */
+    xor(bytes, round, forward) {
+        let cumulativeXorByte = this._xorBytes[round];
+        return bytes.map((byte) => {
+            const xorByte = byte ^ cumulativeXorByte;
+            cumulativeXorByte = forward ? xorByte : byte;
+            return xorByte;
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    doForward(value) {
+        let bytes = this.valueToBytes(value);
+        let transformedValue;
+        // Loop repeats until transformed value is within domain.
+        do {
+            // Forward operation is shuffle then xor for the number of rounds.
+            for (let round = 0; round < this._rounds; round++) {
+                bytes = this.xor(this.shuffle(bytes, round, true), round, true);
+            }
+            transformedValue = EncryptionTransformer.bytesToValue(bytes);
+        } while (transformedValue >= this.domain);
+        return transformedValue;
+    }
+    /**
+     * @inheritDoc
+     */
+    doReverse(transformedValue) {
+        let bytes = this.valueToBytes(transformedValue);
+        let value;
+        // Loop repeats until value is within domain.
+        do {
+            // Reverse operation is xor then shuffle for the number of rounds in reverse.
+            for (let round = this._rounds - 1; round >= 0; round--) {
+                bytes = this.shuffle(this.xor(bytes, round, false), round, false);
+            }
+            value = EncryptionTransformer.bytesToValue(bytes);
+        } while (value >= this.domain);
+        return value;
+    }
+}
+//# sourceMappingURL=transformer.js.map

package/dist/transformer.js.map

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

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@aidc-toolkit/utility",
-  "version": "1.0.24-beta",
+  "version": "1.0.26-beta",
   "description": "Foundational utilities for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
   "homepage": "https://aidc-toolkit.com/",
-  "repository": "aidc-toolkit/utility",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidc-toolkit/utility.git"
+  },
   "bugs": {
     "url": "https://github.com/aidc-toolkit/utility/issues"
   },
@@ -17,16 +20,17 @@
   },
   "scripts": {
     "lint": "eslint",
-    "build:dev": "tsup --define.mode=dev",
-    "build:release": "tsup",
+    "tsc:core": "tsc --project tsconfig-src.json",
+    "build:dev": "rimraf dist && npm run tsc:core -- --declarationMap --sourceMap",
+    "build:release": "npm run tsc:core -- --noEmit && tsup",
     "build:doc": "npm run build:dev",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "beta",
-    "vitest": "^4.0.14"
+    "@aidc-toolkit/dev": "1.0.26-beta",
+    "vitest": "^4.0.15"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "beta"
+    "@aidc-toolkit/core": "1.0.26-beta"
   }
 }

package/src/character-set.ts

@@ -1,9 +1,9 @@
-import { type Exclusion, Exclusions } from "./exclusion";
-import type { IndexedCallback } from "./iterable-utility";
-import { i18nextUtility } from "./locale/i18n";
-import { RegExpValidator } from "./reg-exp";
-import type { StringValidation, StringValidator } from "./string";
-import { Transformer, type TransformerInput, type TransformerOutput } from "./transformer";
+import { type Exclusion, Exclusions } from "./exclusion.js";
+import type { IndexedCallback } from "./iterable-utility.js";
+import { i18nextUtility } from "./locale/i18n.js";
+import { RegExpValidator } from "./reg-exp.js";
+import type { StringValidation, StringValidator } from "./string.js";
+import { Transformer, type TransformerInput, type TransformerOutput } from "./transformer.js";
 
 /**
  * Character set validation parameters.
@@ -81,7 +81,7 @@ export class CharacterSetValidator implements StringValidator<CharacterSetValida
      * set.
      *
      * @param exclusionSupport
-     * Exclusions supported by the character set. All character sets implicitly support {@link Exclusions.None}.
+     * Exclusions supported by the character set. All character sets implicitly support {@linkcode Exclusions.None}.
      */
     constructor(characterSet: readonly string[], ...exclusionSupport: readonly Exclusion[]) {
         this._characterSet = characterSet;
@@ -324,7 +324,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
     private readonly _characterSetSizeMinusOneN: bigint;
 
     /**
-     * Domains for every length for every supported {@link Exclusions}.
+     * Domains for every length for every supported {@linkcode Exclusions}.
      */
     private readonly _exclusionDomains: ReadonlyArray<readonly bigint[]>;
 
@@ -341,7 +341,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
      * set.
      *
      * @param exclusionSupport
-     * Exclusions supported by the character set. All character sets implicitly support {@link Exclusions.None}.
+     * Exclusions supported by the character set. All character sets implicitly support {@linkcode Exclusions.None}.
      */
     constructor(characterSet: readonly string[], ...exclusionSupport: readonly Exclusion[]) {
         super(characterSet, ...exclusionSupport);
@@ -488,7 +488,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
     }
 
     /**
-     * Validate that a length is less than or equal to {@link MAXIMUM_STRING_LENGTH}. If not, an error is thrown.
+     * Validate that a length is less than or equal to {@linkcode MAXIMUM_STRING_LENGTH}. If not, an error is thrown.
      *
      * @param length
      * Length.
@@ -523,7 +523,8 @@ export class CharacterSetCreator extends CharacterSetValidator {
      * Numeric value(s) of the string(s).
      *
      * @param exclusion
-     * String(s) to be excluded from the range of outputs. See {@link Exclusions} for possible values and their meaning.
+     * 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 |
@@ -553,7 +554,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
 
                 if (exclusion === Exclusions.AllNumeric && convertValue >= allZerosValue) {
                     // Value to convert is shifted by the number of all-numeric strings that occur at or prior to it.
-                    convertValue = convertValue + this.allNumericShift(true, length, convertValue - allZerosValue);
+                    convertValue += this.allNumericShift(true, length, convertValue - allZerosValue);
                 }
 
                 // Build string from right to left excluding the first character.
@@ -581,7 +582,7 @@ export class CharacterSetCreator extends CharacterSetValidator {
      * String.
      *
      * @param exclusion
-     * Strings excluded from the range of inputs. See {@link Exclusions} for possible values and their meaning.
+     * 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
@@ -640,19 +641,19 @@ export class CharacterSetCreator extends CharacterSetValidator {
 }
 
 /**
- * Numeric creator. Character set is 0-9. Supports {@link Exclusions.FirstZero}.
+ * Numeric creator. Character set is 0-9. Supports {@linkcode Exclusions.FirstZero}.
  */
 export const NUMERIC_CREATOR = new CharacterSetCreator([
     "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"
 ], Exclusions.FirstZero);
 
 /**
- * Numeric validator. Character set is 0-9. Supports {@link Exclusions.FirstZero}.
+ * Numeric validator. Character set is 0-9. Supports {@linkcode Exclusions.FirstZero}.
  */
 export const NUMERIC_VALIDATOR = NUMERIC_CREATOR as CharacterSetValidator;
 
 /**
- * Hexadecimal creator. Character set is 0-9, A-F. Supports {@link Exclusions.FirstZero} and {@link
+ * Hexadecimal creator. Character set is 0-9, A-F. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
  * Exclusions.AllNumeric}.
  */
 export const HEXADECIMAL_CREATOR = new CharacterSetCreator([
@@ -661,7 +662,7 @@ export const HEXADECIMAL_CREATOR = new CharacterSetCreator([
 ], Exclusions.FirstZero, Exclusions.AllNumeric);
 
 /**
- * Hexadecimal validator. Character set is 0-9, A-F. Supports {@link Exclusions.FirstZero} and {@link
+ * Hexadecimal validator. Character set is 0-9, A-F. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
  * Exclusions.AllNumeric}.
  */
 export const HEXADECIMAL_VALIDATOR = HEXADECIMAL_CREATOR as CharacterSetValidator;
@@ -680,7 +681,7 @@ export const ALPHABETIC_CREATOR = new CharacterSetCreator([
 export const ALPHABETIC_VALIDATOR = ALPHABETIC_CREATOR as CharacterSetValidator;
 
 /**
- * Alphanumeric creator. Character set is 0-9, A-Z. Supports {@link Exclusions.FirstZero} and {@link
+ * Alphanumeric creator. Character set is 0-9, A-Z. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
  * Exclusions.AllNumeric}.
  */
 export const ALPHANUMERIC_CREATOR = new CharacterSetCreator([
@@ -690,7 +691,7 @@ export const ALPHANUMERIC_CREATOR = new CharacterSetCreator([
 ], Exclusions.FirstZero, Exclusions.AllNumeric);
 
 /**
- * Alphanumeric validator. Character set is 0-9, A-Z. Supports {@link Exclusions.FirstZero} and {@link
+ * Alphanumeric validator. Character set is 0-9, A-Z. Supports {@linkcode Exclusions.FirstZero} and {@linkcode
  * Exclusions.AllNumeric}.
  */
 export const ALPHANUMERIC_VALIDATOR = ALPHANUMERIC_CREATOR as CharacterSetValidator;

package/src/exclusion.ts

@@ -18,7 +18,12 @@ export const Exclusions = {
     AllNumeric: 2
 } as const;
 
+/**
+ * Exclusion key.
+ */
+export type ExclusionKey = keyof typeof Exclusions;
+
 /**
  * Exclusion.
  */
-export type Exclusion = typeof Exclusions[keyof typeof Exclusions];
+export type Exclusion = typeof Exclusions[ExclusionKey];