@aidc-toolkit/gs1 0.9.0 → 0.9.2

package/src/idkey.ts

@@ -2,7 +2,8 @@ import {
     CharacterSetCreator,
     type CharacterSetValidation,
     type CharacterSetValidator,
-    Exclusion, IterationHelper, type IterationSource, NUMERIC_CREATOR,
+    Exclusion,
+    NUMERIC_CREATOR,
     RegExpValidator,
     type StringValidation,
     type StringValidator
@@ -130,7 +131,7 @@ export enum CharacterSet {
 export interface IdentificationKeyValidation extends StringValidation {
     /**
      * Position offset within a larger string. Strings are sometimes composed of multiple substrings; this parameter
-     * ensures that the exception notes the proper position in the string.
+     * ensures that the error notes the proper position in the string.
      */
     positionOffset?: number | undefined;
 }
@@ -139,7 +140,7 @@ export interface IdentificationKeyValidation extends StringValidation {
  * Identification key validator. Validates an identification key against its definition in section 3 of the {@link
  * https://www.gs1.org/genspecs | GS1 General Specifications}.
  */
-export interface IdentificationKeyValidator extends StringValidator {
+export interface IdentificationKeyValidator<V extends IdentificationKeyValidation = IdentificationKeyValidation> extends StringValidator<V> {
     /**
      * Get the identification key type. Per the GS1 General Specifications, the identification key type determines
      * the remaining properties.
@@ -169,7 +170,7 @@ export interface IdentificationKeyValidator extends StringValidator {
     get referenceValidator(): CharacterSetValidator;
 
     /**
-     * Validate an identification key and throw an exception if validation fails.
+     * Validate an identification key and throw an error if validation fails.
      *
      * @param identificationKey
      * Identification key.
@@ -177,13 +178,17 @@ export interface IdentificationKeyValidator extends StringValidator {
      * @param validation
      * Identification key validation parameters.
      */
-    validate: (identificationKey: string, validation?: IdentificationKeyValidation) => void;
+    validate: (identificationKey: string, validation?: V) => void;
 }
 
 /**
  * Abstract identification key validator. Implements common functionality for an identification key validator.
  */
-abstract class AbstractIdentificationKeyValidator implements IdentificationKeyValidator {
+abstract class AbstractIdentificationKeyValidator<V extends IdentificationKeyValidation = IdentificationKeyValidation> implements IdentificationKeyValidator<V> {
+    private static readonly CHARACTER_SET_CREATORS = [
+        NUMERIC_CREATOR, AI82_CREATOR, AI39_CREATOR
+    ];
+
     /**
      * Identification key type.
      */
@@ -205,7 +210,7 @@ abstract class AbstractIdentificationKeyValidator implements IdentificationKeyVa
     private readonly _referenceCharacterSet: CharacterSet;
 
     /**
-     * Character set validator.
+     * Reference validator.
      */
     private readonly _referenceValidator: CharacterSetValidator;
 
@@ -219,23 +224,7 @@ abstract class AbstractIdentificationKeyValidator implements IdentificationKeyVa
      * Character set validator.
      */
     protected static validatorFor(characterSet: CharacterSet): CharacterSetValidator {
-        let characterSetValidator: CharacterSetValidator;
-
-        switch (characterSet) {
-            case CharacterSet.Numeric:
-                characterSetValidator = NUMERIC_CREATOR;
-                break;
-
-            case CharacterSet.AI82:
-                characterSetValidator = AI82_CREATOR;
-                break;
-
-            case CharacterSet.AI39:
-                characterSetValidator = AI39_CREATOR;
-                break;
-        }
-
-        return characterSetValidator;
+        return AbstractIdentificationKeyValidator.CHARACTER_SET_CREATORS[characterSet];
     }
 
     /**
@@ -261,28 +250,43 @@ abstract class AbstractIdentificationKeyValidator implements IdentificationKeyVa
         this._referenceValidator = AbstractIdentificationKeyValidator.validatorFor(referenceCharacterSet);
     }
 
+    /**
+     * @inheritDoc
+     */
     get identificationKeyType(): IdentificationKeyType {
         return this._identificationKeyType;
     }
 
+    /**
+     * @inheritDoc
+     */
     get prefixType(): PrefixType {
         return this._prefixType;
     }
 
+    /**
+     * @inheritDoc
+     */
     get length(): number {
         return this._length;
     }
 
+    /**
+     * @inheritDoc
+     */
     get referenceCharacterSet(): CharacterSet {
         return this._referenceCharacterSet;
     }
 
+    /**
+     * @inheritDoc
+     */
     get referenceValidator(): CharacterSetValidator {
         return this._referenceValidator;
     }
 
     /**
-     * Pad an identification key on the left with zeroes for validation purposes. This is done to align an
+     * Pad an identification key on the left with zero-value character for validation purposes. This is done to align an
      * identification key with a position offset for any error message that may be thrown by the reference validator.
      *
      * @param identificationKey
@@ -294,9 +298,9 @@ abstract class AbstractIdentificationKeyValidator implements IdentificationKeyVa
      * @returns
      * Padded identification key.
      */
-    protected static padIdentificationKey(identificationKey: string, validation: IdentificationKeyValidation | undefined): string {
+    protected padIdentificationKey(identificationKey: string, validation: IdentificationKeyValidation | undefined): string {
         // Identification key is returned as is if position offset is undefined.
-        return validation?.positionOffset === undefined ? identificationKey : "0".repeat(validation.positionOffset).concat(identificationKey);
+        return validation?.positionOffset === undefined ? identificationKey : this.referenceValidator.character(0).repeat(validation.positionOffset).concat(identificationKey);
     }
 
     /**
@@ -313,7 +317,7 @@ abstract class AbstractIdentificationKeyValidator implements IdentificationKeyVa
         PrefixManager.validatePrefix(this.prefixType, true, false, partialIdentificationKey, true, this.referenceCharacterSet === CharacterSet.Numeric, positionOffset);
     }
 
-    abstract validate(identificationKey: string, validation?: IdentificationKeyValidation): void;
+    abstract validate(identificationKey: string, validation?: V): void;
 }
 
 /**
@@ -383,10 +387,16 @@ abstract class AbstractNumericIdentificationKeyValidator extends AbstractIdentif
         this._prefixPosition = Number(this.leaderType === LeaderType.ExtensionDigit);
     }
 
+    /**
+     * @inheritDoc
+     */
     get leaderType(): LeaderType {
         return this._leaderType;
     }
 
+    /**
+     * @inheritDoc
+     */
     validate(identificationKey: string, validation?: IdentificationKeyValidation): void {
         // Validate the prefix, with care taken for its position within the identification key.
         if (this._prefixPosition === 0) {
@@ -405,7 +415,7 @@ abstract class AbstractNumericIdentificationKeyValidator extends AbstractIdentif
         }
 
         // Validating the check digit will also validate the characters.
-        if (!hasValidCheckDigit(AbstractIdentificationKeyValidator.padIdentificationKey(identificationKey, validation))) {
+        if (!hasValidCheckDigit(this.padIdentificationKey(identificationKey, validation))) {
             throw new RangeError(i18next.t("IdentificationKey.invalidCheckDigit", {
                 ns: gs1NS
             }));
@@ -501,11 +511,17 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
         super(IdentificationKeyType.GTIN, prefixType, gtinType, LeaderType.IndicatorDigit);
     }
 
+    /**
+     * @inheritDoc
+     */
     get gtinType(): GTINType {
         // Length maps to GTIN type enumeration.
-        return this.length as GTINType;
+        return this.length satisfies GTINType;
     }
 
+    /**
+     * @inheritDoc
+     */
     protected override validatePrefix(partialIdentificationKey: string, positionOffset?: number): void {
         // Delegate to prefix manager requiring exact match for prefix type.
         PrefixManager.validatePrefix(this.prefixType, false, false, partialIdentificationKey, true, true, positionOffset);
@@ -519,8 +535,6 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
      *
      * @returns
      * GTIN-12.
-     *
-     * @throws RangeError
      */
     static zeroExpand(zeroSuppressedGTIN12: string): string {
         NUMERIC_CREATOR.validate(zeroSuppressedGTIN12, GTINValidator.ZERO_SUPPRESSED_GTIN12_VALIDATION);
@@ -563,8 +577,6 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
      *
      * @param gtinLevel
      * Level at which GTIN is to be validated.
-     *
-     * @throws RangeError
      */
     static validateAny(gtin: string, gtinLevel: GTINLevel = GTINLevel.Any): void {
         // Assume length-validated GTIN is the GTIN (true for all except zero-suppressed GTIN-12).
@@ -638,11 +650,9 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
      *
      * @param gtin14
      * GTIN-14.
-     *
-     * @throws RangeError
      */
     static validateGTIN14(gtin14: string): void {
-        if (gtin14.length !== GTINType.GTIN14 as number) {
+        if (gtin14.length as GTINType !== GTINType.GTIN14) {
             throw new RangeError(i18next.t("IdentificationKey.invalidGTIN14Length", {
                 ns: gs1NS
             }));
@@ -689,7 +699,7 @@ export class SerializableNumericIdentificationKeyValidator extends NonGTINNumeri
     private readonly _serialComponentCharacterSet: CharacterSet;
 
     /**
-     * Serial component character set validation parameters.
+     * Serial component validation parameters.
      */
     private readonly _serialComponentValidation: CharacterSetValidation;
 
@@ -758,6 +768,9 @@ export class SerializableNumericIdentificationKeyValidator extends NonGTINNumeri
         return this._serialComponentValidator;
     }
 
+    /**
+     * @inheritDoc
+     */
     override validate(identificationKey: string, validation?: IdentificationKeyValidation): void {
         super.validate(identificationKey.substring(0, this.length), validation);
 
@@ -771,17 +784,24 @@ export class SerializableNumericIdentificationKeyValidator extends NonGTINNumeri
  * Non-numeric identification key validation parameters.
  */
 export interface NonNumericIdentificationKeyValidation extends IdentificationKeyValidation {
+    /**
+     * Exclusion support for reference. Prevents non-numeric identification key from being mistaken for numeric
+     * identification key.
+     */
     exclusion?: Exclusion.None | Exclusion.AllNumeric | undefined;
 }
 
 /**
  * Non-numeric identification key validator.
  */
-export class NonNumericIdentificationKeyValidator extends AbstractIdentificationKeyValidator {
+export class NonNumericIdentificationKeyValidator extends AbstractIdentificationKeyValidator<NonNumericIdentificationKeyValidation> {
     /**
      * Validator to ensure that an identification key (minus check character pair) is not all numeric.
      */
     private static readonly NOT_ALL_NUMERIC_VALIDATOR = new class extends RegExpValidator {
+        /**
+         * @inheritDoc
+         */
         protected override createErrorMessage(_s: string): string {
             return i18next.t("IdentificationKey.referenceCantBeAllNumeric", {
                 ns: gs1NS
@@ -822,6 +842,15 @@ export class NonNumericIdentificationKeyValidator extends AbstractIdentification
         return this._requiresCheckCharacterPair;
     }
 
+    /**
+     * Validate a non-numeric identification key and throw an error if validation fails.
+     *
+     * @param identificationKey
+     * Identification key.
+     *
+     * @param validation
+     * Validation parameters.
+     */
     validate(identificationKey: string, validation?: NonNumericIdentificationKeyValidation): void {
         const partialIdentificationKey = this.requiresCheckCharacterPair ? identificationKey.substring(0, identificationKey.length - 2) : identificationKey;
 
@@ -833,7 +862,7 @@ export class NonNumericIdentificationKeyValidator extends AbstractIdentification
                 positionOffset: validation?.positionOffset
             });
         // Validating the check character pair will also validate the characters.
-        } else if (!hasValidCheckCharacterPair(AbstractIdentificationKeyValidator.padIdentificationKey(identificationKey, validation))) {
+        } else if (!hasValidCheckCharacterPair(this.padIdentificationKey(identificationKey, validation))) {
             throw new RangeError(i18next.t("IdentificationKey.invalidCheckCharacterPair", {
                 ns: gs1NS
             }));
@@ -961,12 +990,12 @@ abstract class AbstractIdentificationKeyCreator implements IdentificationKeyCrea
     /**
      * Prefix manager.
      */
-    private _prefixManager?: PrefixManager;
+    private _prefixManager!: PrefixManager;
 
     /**
      * Reference length.
      */
-    private _referenceLength?: number;
+    private _referenceLength!: number;
 
     /**
      * Initialize the prefix manager. This method is in lieu of a constructor due to the mixin architecture.
@@ -979,16 +1008,8 @@ abstract class AbstractIdentificationKeyCreator implements IdentificationKeyCrea
      *
      * @param checkAllowance
      * Number of characters to allow for check digit or check character pair.
-     *
-     * @throws Error
      */
     protected init(prefixManager: PrefixManager, prefix: string, checkAllowance: number): void {
-        // Verify that prefix manager has not already been assigned.
-        if (this._prefixManager !== undefined) {
-            // Should never get here.
-            throw new Error("Not supported");
-        }
-
         this._prefixManager = prefixManager;
 
         // Reference length allows for prefix and optionally check digit or check character pair.
@@ -1005,22 +1026,32 @@ abstract class AbstractIdentificationKeyCreator implements IdentificationKeyCrea
 
     abstract get referenceValidator(): CharacterSetValidator;
 
+    /**
+     * @inheritDoc
+     */
     get referenceCreator(): CharacterSetCreator {
         return this.referenceValidator as CharacterSetCreator;
     }
 
+    /**
+     * @inheritDoc
+     */
     get prefixManager(): PrefixManager {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        return this._prefixManager!;
+        return this._prefixManager;
     }
 
+    /**
+     * @inheritDoc
+     */
     get prefix(): string {
         return this.prefixManager.gs1CompanyPrefix;
     }
 
+    /**
+     * @inheritDoc
+     */
     get referenceLength(): number {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        return this._referenceLength!;
+        return this._referenceLength;
     }
 
     abstract validate(identificationKey: string, validation?: IdentificationKeyValidation): void;
@@ -1035,58 +1066,37 @@ export interface NumericIdentificationKeyCreator extends NumericIdentificationKe
      */
     get capacity(): number;
 
-    /**
-     * Create an identification key with a reference based on a numeric value. The value is converted to a reference of
-     * the appropriate length using {@linkcode NUMERIC_CREATOR}.
-     *
-     * @param value
-     * Numeric value.
-     *
-     * @param sparse
-     * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Identification key.
-     */
-    create: (value: number, sparse?: boolean) => string;
-
-    /**
-     * Create a sequence of identification keys with references based on a sequence of numeric values. The values are
-     * converted to references of the appropriate length using {@linkcode NUMERIC_CREATOR}. References are created with
-     * values from `startValue` to `startValue + count - 1`.
-     *
-     * The implementation uses {@link CharacterSetCreator.createSequence}, so the values are created only as needed.
-     *
-     * @param startValue
-     * Start numeric value.
-     *
-     * @param count
-     * Count of identification keys to create.
-     *
-     * @param sparse
-     * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Iterable iterator over created identification keys.
-     */
-    createSequence: (startValue: number, count: number, sparse?: boolean) => IterableIterator<string>;
-
-    /**
-     * Create multiple identification keys with references based on numeric values. The values are converted to
-     * references of the appropriate length using {@linkcode NUMERIC_CREATOR}.
-     *
-     * The implementation uses {@link CharacterSetCreator.createMultiple}, so the values are created only as needed.
-     *
-     * @param valuesSource
-     * Source of values.
-     *
-     * @param sparse
-     * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Iterable iterator over created identification keys.
-     */
-    createMultiple: (valuesSource: IterationSource<number>, sparse?: boolean) => IterableIterator<string>;
+    create: {
+        /**
+         * Create an identification key with a reference based on a numeric value. The value is converted to a reference of
+         * the appropriate length using {@linkcode NUMERIC_CREATOR}.
+         *
+         * @param value
+         * Numeric value.
+         *
+         * @param sparse
+         * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
+         *
+         * @returns
+         * Identification key.
+         */
+        (value: number | bigint, sparse?: boolean): string;
+
+        /**
+         * Create identification keys with references based on numeric values. The values are converted to references of
+         * the appropriate length using {@linkcode NUMERIC_CREATOR}.
+         *
+         * @param values
+         * Numeric values.
+         *
+         * @param sparse
+         * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
+         *
+         * @returns
+         * Identification keys.
+         */
+        (values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
+    };
 
     /**
      * Create all identification keys for the prefix from `0` to `capacity - 1`.
@@ -1107,7 +1117,7 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
     /**
      * Capacity.
      */
-    private _capacity?: number;
+    private _capacity!: number;
 
     /**
      * Tweak for sparse creation.
@@ -1122,8 +1132,6 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
      *
      * @param prefix
      * Prefix within prefix manager to use to calculate reference length.
-     *
-     * @throws Error
      */
     protected override init(prefixManager: PrefixManager, prefix: string): void {
         super.init(prefixManager, prefix, 1);
@@ -1134,9 +1142,11 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
 
     abstract get leaderType(): LeaderType;
 
+    /**
+     * @inheritDoc
+     */
     get capacity(): number {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        return this._capacity!;
+        return this._capacity;
     }
 
     /**
@@ -1168,16 +1178,19 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
         return partialIdentificationKey + checkDigit(partialIdentificationKey);
     }
 
-    create(value: number, sparse = false): string {
-        return NUMERIC_CREATOR.create(this.referenceLength, value, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
-    }
+    /**
+     * @inheritDoc
+     */
+    create(value: number | bigint, sparse?: boolean): string;
 
-    createSequence(startValue: number, count: number, sparse = false): IterableIterator<string> {
-        return NUMERIC_CREATOR.createSequence(this.referenceLength, startValue, count, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
-    }
+    /**
+     * @inheritDoc
+     */
+    create(values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
 
-    createMultiple(valuesSource: IterationSource<number>, sparse = false): IterableIterator<string> {
-        return NUMERIC_CREATOR.createMultiple(this.referenceLength, valuesSource, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
+    // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
+    create(valueOrValues: number | bigint | Iterable<number | bigint>, sparse = false): string | IterableIterator<string> {
+        return NUMERIC_CREATOR.create(this.referenceLength, valueOrValues, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
     }
 
     /**
@@ -1232,6 +1245,9 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     createAll(): IterableIterator<string> {
         const hasExtensionDigit = this.leaderType === LeaderType.ExtensionDigit;
         const prefix = this.prefix;
@@ -1285,26 +1301,11 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
         this.init(prefixManager, prefixManager.prefix);
     }
 
-    override get prefix(): string {
-        return this.prefixManager.prefix;
-    }
-
     /**
-     * Build a GTIN-14 from an indicator digit, the prefix, and a reference.
-     *
-     * @param indicatorDigit
-     * Indicator digit.
-     *
-     * @param reference
-     * Reference.
-     *
-     * @returns
-     * GTIN-14.
+     * @inheritDoc
      */
-    private buildGTIN14(indicatorDigit: string, reference: string): string {
-        const partialIdentificationKey = indicatorDigit + this.prefixManager.gs1CompanyPrefix + reference;
-
-        return partialIdentificationKey + checkDigit(partialIdentificationKey);
+    override get prefix(): string {
+        return this.prefixManager.prefix;
     }
 
     /**
@@ -1315,7 +1316,7 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      * Indicator digit.
      *
      * @param value
-     * Numeric value.
+     * Numeric value of the reference.
      *
      * @param sparse
      * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
@@ -1323,51 +1324,19 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      * @returns
      * GTIN-14.
      */
-    createGTIN14(indicatorDigit: string, value: number, sparse = false): string {
-        NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.REQUIRED_INDICATOR_DIGIT_VALIDATION);
-
-        return NUMERIC_CREATOR.create(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, value, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildGTIN14(indicatorDigit, reference));
-    }
-
-    /**
-     * Create a sequence of GTIN-14s with an indicator digit and references based on a sequence of numeric values.
-     * The values are converted to references of the appropriate length using {@linkcode NUMERIC_CREATOR}. References
-     * are created with values from `startValue` to `startValue + count - 1`.
-     *
-     * The implementation uses {@link CharacterSetCreator.createSequence}, so the values are created only as needed.
-     *
-     * @param indicatorDigit
-     * Indicator digit.
-     *
-     * @param startValue
-     * Start numeric value.
-     *
-     * @param count
-     * Count of identification keys to create.
-     *
-     * @param sparse
-     * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Iterable iterator over created GTIN-14s.
-     */
-    createGTIN14Sequence(indicatorDigit: string, startValue: number, count: number, sparse = false): IterableIterator<string> {
-        NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.REQUIRED_INDICATOR_DIGIT_VALIDATION);
-
-        return NUMERIC_CREATOR.createSequence(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, startValue, count, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildGTIN14(indicatorDigit, reference));
-    }
+    createGTIN14(indicatorDigit: string, value: number | bigint, sparse?: boolean): string;
 
     /**
      * Create multiple GTIN-14s with an indicator digit and references based on numeric values. The values are converted
      * to references of the appropriate length using {@linkcode NUMERIC_CREATOR}.
      *
-     * The implementation uses {@link CharacterSetCreator.createMultiple}, so the values are created only as needed.
+     * The implementation uses {@link CharacterSetCreator.create}, so the values are created only as needed.
      *
      * @param indicatorDigit
      * Indicator digit.
      *
-     * @param valuesSource
-     * Source of values.
+     * @param values
+     * Values.
      *
      * @param sparse
      * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
@@ -1375,10 +1344,17 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      * @returns
      * Iterable iterator over created GTIN-14s.
      */
-    createGTIN14Multiple(indicatorDigit: string, valuesSource: IterationSource<number>, sparse = false): IterableIterator<string> {
+    createGTIN14(indicatorDigit: string, values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
+    createGTIN14(indicatorDigit: string, valueOrValues: number | bigint | Iterable<number | bigint>, sparse = false): string | IterableIterator<string> {
         NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.REQUIRED_INDICATOR_DIGIT_VALIDATION);
 
-        return NUMERIC_CREATOR.createMultiple(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, valuesSource, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildGTIN14(indicatorDigit, reference));
+        return NUMERIC_CREATOR.create(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, valueOrValues, Exclusion.None, sparse ? this.tweak : undefined, (reference) => {
+            const partialIdentificationKey = indicatorDigit + this.prefixManager.gs1CompanyPrefix + reference;
+
+            return partialIdentificationKey + checkDigit(partialIdentificationKey);
+        });
     }
 
     /**
@@ -1389,8 +1365,6 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      *
      * @returns
      * Zero-suppressed GTIN-12.
-     *
-     * @throws RangeError
      */
     static zeroSuppress(gtin12: string): string {
         GTIN12_VALIDATOR.validate(gtin12);
@@ -1466,8 +1440,6 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      *
      * @returns
      * Normalized GTIN.
-     *
-     * @throws RangeError
      */
     static normalize(gtin: string): string {
         const gtinLength = gtin.length;
@@ -1498,7 +1470,7 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
                 break;
 
             case GTINType.GTIN8 as number:
-                if (gtin.charAt(0) !== "0") {
+                if (!gtin.startsWith("0")) {
                     // GTIN is GTIN-8.
                     normalizedGTIN = gtin;
                 } else {
@@ -1615,11 +1587,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key.
      */
-    private concatenateValidated(baseIdentificationKey: string, serialComponent: string): string {
-        this.serialComponentCreator.validate(serialComponent, this.serialComponentValidation);
-
-        return baseIdentificationKey + serialComponent;
-    }
+    private concatenateValidated(baseIdentificationKey: string, serialComponent: string): string;
 
     /**
      * Concatenate a validated base identification key with multiple serial components.
@@ -1627,14 +1595,27 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @param baseIdentificationKey
      * Base identification key.
      *
-     * @param serialComponentsSource
-     * Source of serial components.
+     * @param serialComponents
+     * Serial components.
      *
      * @returns
      * Serialized identification keys.
      */
-    private concatenateValidatedMultiple(baseIdentificationKey: string, serialComponentsSource: IterationSource<string>): IterableIterator<string> {
-        return IterationHelper.from(serialComponentsSource).map(serialComponent => this.concatenateValidated(baseIdentificationKey, serialComponent));
+    private concatenateValidated(baseIdentificationKey: string, serialComponents: Iterable<string>): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
+    private concatenateValidated(baseIdentificationKey: string, serialComponent: string | Iterable<string>): string | IterableIterator<string> {
+        let result: string | IterableIterator<string>;
+
+        if (typeof serialComponent === "string") {
+            this.serialComponentCreator.validate(serialComponent, this.serialComponentValidation);
+
+            result = baseIdentificationKey + serialComponent;
+        } else {
+            result = Iterator.from(serialComponent).map(serialComponent => this.concatenateValidated(baseIdentificationKey, serialComponent));
+        }
+
+        return result;
     }
 
     /**
@@ -1642,7 +1623,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * value is converted to a reference of the appropriate length using {@linkcode NUMERIC_CREATOR}.
      *
      * @param value
-     * Numeric value.
+     * Numeric value of the references.
      *
      * @param serialComponent
      * Serial component.
@@ -1653,9 +1634,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key.
      */
-    createSerialized(value: number, serialComponent: string, sparse = false): string {
-        return this.concatenateValidated(this.create(value, sparse), serialComponent);
-    }
+    createSerialized(value: number, serialComponent: string, sparse?: boolean): string;
 
     /**
      * Create multiple serialized identification keys with a reference based on a numeric value and multiple serial
@@ -1664,8 +1643,8 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @param value
      * Numeric value.
      *
-     * @param serialComponentsSource
-     * Source of serial components.
+     * @param serialComponents
+     * Serial components.
      *
      * @param sparse
      * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
@@ -1673,8 +1652,11 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification keys.
      */
-    createMultipleSerialized(value: number, serialComponentsSource: IterationSource<string>, sparse = false): IterableIterator<string> {
-        return this.concatenateValidatedMultiple(this.create(value, sparse), serialComponentsSource);
+    createSerialized(value: number, serialComponents: Iterable<string>, sparse?: boolean): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
+    createSerialized(value: number, serialComponent: string | Iterable<string>, sparse = false): string | IterableIterator<string> {
+        return this.concatenateValidated(this.create(value, sparse), serialComponent);
     }
 
     /**
@@ -1689,11 +1671,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key.
      */
-    concatenate(baseIdentificationKey: string, serialComponent: string): string {
-        this.validate(baseIdentificationKey);
-
-        return this.concatenateValidated(baseIdentificationKey, serialComponent);
-    }
+    concatenate(baseIdentificationKey: string, serialComponent: string): string;
 
     /**
      * Concatenate a base identification key with multiple serial components.
@@ -1701,16 +1679,19 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @param baseIdentificationKey
      * Base identification key.
      *
-     * @param serialComponentsSource
-     * Source of serial components.
+     * @param serialComponents
+     * Serial components.
      *
      * @returns
      * Serialized identification keys.
      */
-    concatenateMultiple(baseIdentificationKey: string, serialComponentsSource: IterationSource<string>): IterableIterator<string> {
+    concatenate(baseIdentificationKey: string, serialComponents: Iterable<string>): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
+    concatenate(baseIdentificationKey: string, serialComponent: string | Iterable<string>): string | IterableIterator<string> {
         this.validate(baseIdentificationKey);
 
-        return this.concatenateValidatedMultiple(baseIdentificationKey, serialComponentsSource);
+        return this.concatenateValidated(baseIdentificationKey, serialComponent);
     }
 }
 
@@ -1719,7 +1700,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
  */
 export class NonNumericIdentificationKeyCreator extends Mixin(NonNumericIdentificationKeyValidator, AbstractIdentificationKeyCreator) {
     /**
-     * Reference character set validation parameters.
+     * Reference validation parameters.
      */
     private readonly _referenceValidation: CharacterSetValidation;
 
@@ -1766,28 +1747,57 @@ export class NonNumericIdentificationKeyCreator extends Mixin(NonNumericIdentifi
      * @returns
      * Identification key.
      */
-    create(reference: string): string {
-        this.referenceValidator.validate(reference, this._referenceValidation);
-
-        const partialIdentificationKey = this.prefix + reference;
-
-        return this.requiresCheckCharacterPair ? partialIdentificationKey + checkCharacterPair(partialIdentificationKey) : partialIdentificationKey;
-    }
+    create(reference: string): string;
 
     /**
      * Create multiple identification keys with references.
      *
-     * @param referencesSource
-     * Source of references.
+     * @param references
+     * References.
      *
      * @returns
      * Identification keys.
      */
-    createMultiple(referencesSource: IterationSource<string>): IterableIterator<string> {
-        return IterationHelper.from(referencesSource).map(reference => this.create(reference));
+    create(references: Iterable<string>): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc -- Implementation of overloaded signatures.
+    create(referenceOrReferences: string | Iterable<string>): string | IterableIterator<string> {
+        let result: string | IterableIterator<string>;
+
+        if (typeof referenceOrReferences === "string") {
+            this.referenceValidator.validate(referenceOrReferences, this._referenceValidation);
+
+            const partialIdentificationKey = this.prefix + referenceOrReferences;
+
+            result = this.requiresCheckCharacterPair ? partialIdentificationKey + checkCharacterPair(partialIdentificationKey) : partialIdentificationKey;
+        } else {
+            result = Iterator.from(referenceOrReferences).map(reference => this.create(reference));
+        }
+
+        return result;
     }
 }
 
+/**
+ * Prefix validation parameters.
+ */
+interface PrefixValidation extends CharacterSetValidation {
+    /**
+     * Minimum length.
+     */
+    minimumLength: number;
+
+    /**
+     * Maximum length.
+     */
+    maximumLength: number;
+
+    /**
+     * Callback to localized prefix type name.
+     */
+    component: () => string;
+}
+
 /**
  * Prefix manager. This is the core class for identification key creation.
  *
@@ -1848,7 +1858,7 @@ export class PrefixManager {
     /**
      * Validation parameters for GS1 Company Prefix.
      */
-    private static readonly GS1_COMPANY_PREFIX_VALIDATION: CharacterSetValidation = {
+    private static readonly GS1_COMPANY_PREFIX_VALIDATION: PrefixValidation = {
         minimumLength: PrefixManager.GS1_COMPANY_PREFIX_MINIMUM_LENGTH,
         maximumLength: PrefixManager.GS1_COMPANY_PREFIX_MAXIMUM_LENGTH,
         component: () => i18next.t("Prefix.gs1CompanyPrefix", {
@@ -1859,7 +1869,7 @@ export class PrefixManager {
     /**
      * Validation parameters for U.P.C. Company Prefix expressed as GS1 Company Prefix.
      */
-    private static readonly UPC_COMPANY_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION: CharacterSetValidation = {
+    private static readonly UPC_COMPANY_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION: PrefixValidation = {
         minimumLength: PrefixManager.UPC_COMPANY_PREFIX_MINIMUM_LENGTH + 1,
         maximumLength: PrefixManager.UPC_COMPANY_PREFIX_MAXIMUM_LENGTH + 1,
         component: () => i18next.t("Prefix.gs1CompanyPrefix", {
@@ -1870,7 +1880,7 @@ export class PrefixManager {
     /**
      * Validation parameters for GS1-8 Prefix expressed as GS1 Company Prefix.
      */
-    private static readonly GS1_8_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION: CharacterSetValidation = {
+    private static readonly GS1_8_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION: PrefixValidation = {
         minimumLength: PrefixManager.GS1_8_PREFIX_MINIMUM_LENGTH + 5,
         maximumLength: PrefixManager.GS1_8_PREFIX_MAXIMUM_LENGTH + 5,
         component: () => i18next.t("Prefix.gs1CompanyPrefix", {
@@ -1881,7 +1891,7 @@ export class PrefixManager {
     /**
      * Validation parameters for U.P.C. Company Prefix.
      */
-    private static readonly UPC_COMPANY_PREFIX_VALIDATION: CharacterSetValidation = {
+    private static readonly UPC_COMPANY_PREFIX_VALIDATION: PrefixValidation = {
         minimumLength: PrefixManager.UPC_COMPANY_PREFIX_MINIMUM_LENGTH,
         maximumLength: PrefixManager.UPC_COMPANY_PREFIX_MAXIMUM_LENGTH,
         component: () => i18next.t("Prefix.upcCompanyPrefix", {
@@ -1892,7 +1902,7 @@ export class PrefixManager {
     /**
      * Validation parameters for GS1-8 Prefix.
      */
-    private static readonly GS1_8_PREFIX_VALIDATION: CharacterSetValidation = {
+    private static readonly GS1_8_PREFIX_VALIDATION: PrefixValidation = {
         minimumLength: PrefixManager.GS1_8_PREFIX_MINIMUM_LENGTH,
         maximumLength: PrefixManager.GS1_8_PREFIX_MAXIMUM_LENGTH,
         component: () => i18next.t("Prefix.gs18Prefix", {
@@ -1904,7 +1914,7 @@ export class PrefixManager {
      * Creator tweak factors. Different numeric identification key types have different tweak factors so that sparse
      * creation generates different sequences for each.
      */
-    private static readonly CREATOR_TWEAK_FACTORS_MAP = new Map<IdentificationKeyType, bigint>([
+    private static readonly CREATOR_TWEAK_FACTORS_MAP: ReadonlyMap<IdentificationKeyType, bigint> = new Map([
         [IdentificationKeyType.GTIN, 1987n],
         [IdentificationKeyType.GLN, 4241n],
         [IdentificationKeyType.SSCC, 8087n],
@@ -2046,9 +2056,9 @@ export class PrefixManager {
         if (this._tweakFactor !== tweakFactor) {
             this._tweakFactor = tweakFactor;
 
-            this._identificationKeyCreatorsMap.forEach((creator) => {
+            for (const creator of this._identificationKeyCreatorsMap.values()) {
                 this.setCreatorTweak(creator);
-            });
+            }
         }
     }
 
@@ -2124,11 +2134,9 @@ export class PrefixManager {
      *
      * @param positionOffset
      * Position offset within a larger string.
-     *
-     * @throws RangeError
      */
     static validatePrefix(prefixType: PrefixType, allowUPCCompanyPrefix: boolean, allowGS18Prefix: boolean, prefix: string, isFromIdentificationKey = false, isNumericIdentificationKey = false, positionOffset?: number): void {
-        let baseValidation: CharacterSetValidation;
+        let baseValidation: PrefixValidation;
 
         // Validate the prefix type and determine the prefix validation parameters.
         switch (prefixType) {
@@ -2179,7 +2187,7 @@ export class PrefixManager {
                 break;
         }
 
-        const mergedValidation: CharacterSetValidation = {
+        const mergedValidation: PrefixValidation = {
             ...baseValidation,
             positionOffset
         };
@@ -2189,8 +2197,7 @@ export class PrefixManager {
             NUMERIC_CREATOR.validate(prefix, mergedValidation);
         } else if (!isNumericIdentificationKey) {
             // Validate only the minimum length, allowing at least one character for the (possibly non-numeric) reference.
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            NUMERIC_CREATOR.validate(prefix.substring(0, Math.min(mergedValidation.minimumLength!, prefix.length - 1)), mergedValidation);
+            NUMERIC_CREATOR.validate(prefix.substring(0, Math.min(mergedValidation.minimumLength, prefix.length - 1)), mergedValidation);
         }
     }
 
@@ -2205,8 +2212,6 @@ export class PrefixManager {
      *
      * @returns
      * Identification key creator.
-     *
-     * @throws RangeError
      */
     private getIdentificationKeyCreator<T extends IdentificationKeyCreator>(identificationKeyType: IdentificationKeyType, constructorCallback: () => T): T {
         let creator = this._identificationKeyCreatorsMap.get(identificationKeyType) as (T | undefined);
@@ -2222,6 +2227,8 @@ export class PrefixManager {
             creator = constructorCallback();
 
             this.setCreatorTweak(creator);
+
+            this._identificationKeyCreatorsMap.set(identificationKeyType, creator);
         }
 
         return creator;