@aidc-toolkit/gs1 0.9.10-beta → 0.9.11-beta

package/src/idkey.ts

@@ -142,7 +142,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<V extends IdentificationKeyValidation = IdentificationKeyValidation> extends StringValidator<V> {
+export interface IdentificationKeyValidator<TIdentificationKeyValidation extends IdentificationKeyValidation = IdentificationKeyValidation> extends StringValidator<TIdentificationKeyValidation> {
     /**
      * Get the identification key type. Per the GS1 General Specifications, the identification key type determines
      * the remaining properties.
@@ -180,13 +180,13 @@ export interface IdentificationKeyValidator<V extends IdentificationKeyValidatio
      * @param validation
      * Identification key validation parameters.
      */
-    validate: (identificationKey: string, validation?: V) => void;
+    validate: (identificationKey: string, validation?: TIdentificationKeyValidation) => void;
 }
 
 /**
  * Abstract identification key validator. Implements common functionality for an identification key validator.
  */
-abstract class AbstractIdentificationKeyValidator<V extends IdentificationKeyValidation = IdentificationKeyValidation> implements IdentificationKeyValidator<V> {
+abstract class AbstractIdentificationKeyValidator<TIdentificationKeyValidation extends IdentificationKeyValidation = IdentificationKeyValidation> implements IdentificationKeyValidator<TIdentificationKeyValidation> {
     private static readonly CHARACTER_SET_CREATORS = [
         NUMERIC_CREATOR, AI82_CREATOR, AI39_CREATOR
     ];
@@ -319,7 +319,7 @@ abstract class AbstractIdentificationKeyValidator<V extends IdentificationKeyVal
         PrefixManager.validatePrefix(this.prefixType, true, false, partialIdentificationKey, true, this.referenceCharacterSet === ContentCharacterSet.Numeric, positionOffset);
     }
 
-    abstract validate(identificationKey: string, validation?: V): void;
+    abstract validate(identificationKey: string, validation?: TIdentificationKeyValidation): void;
 }
 
 /**
@@ -472,7 +472,16 @@ export enum GTINLevel {
  */
 export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
     /**
-     * Zero-suppressed GTIN-12 validation parameters.
+     * Validation parameters for optional indicator digit.
+     */
+    private static readonly OPTIONAL_INDICATOR_DIGIT_VALIDATION: CharacterSetValidation = {
+        minimumLength: 0,
+        maximumLength: 1,
+        component: () => i18nextGS1.t("IdentificationKey.indicatorDigit")
+    };
+
+    /**
+     * Validation parameters for zero-suppressed GTIN-12.
      */
     private static readonly ZERO_SUPPRESSED_GTIN12_VALIDATION: CharacterSetValidation = {
         minimumLength: 8,
@@ -526,6 +535,43 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
         PrefixManager.validatePrefix(this.prefixType, false, false, partialIdentificationKey, true, true, positionOffset);
     }
 
+    /**
+     * Zero suppress a GTIN-12.
+     *
+     * @param gtin12
+     * GTIN-12.
+     *
+     * @returns
+     * Zero-suppressed GTIN-12.
+     */
+    static zeroSuppress(gtin12: string): string {
+        GTIN12_VALIDATOR.validate(gtin12);
+
+        // Convert to individual digits.
+        const d = Array.from(gtin12);
+
+        let zeroSuppressedGTIN12: string | undefined;
+
+        // All rules require that digits in positions 1, 5, and 6 be zero.
+        if (d[0] === "0" && d[6] === "0" && d[7] === "0") {
+            if (d[10] >= "5" && d[8] === "0" && d[9] === "0" && d[5] !== "0") {
+                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[3]}${d[4]}${d[5]}${d[10]}${d[11]}`;
+            } else if (d[5] === "0" && d[8] === "0" && d[9] === "0" && d[4] !== "0") {
+                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[3]}${d[4]}${d[10]}4${d[11]}`;
+            } else if (d[3] <= "2" && d[4] === "0" && d[5] === "0") {
+                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[8]}${d[9]}${d[10]}${d[3]}${d[11]}`;
+            } else if (d[3] >= "3" && d[4] === "0" && d[5] === "0" && d[8] === "0") {
+                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[3]}${d[9]}${d[10]}3${d[11]}`;
+            }
+        }
+
+        if (zeroSuppressedGTIN12 === undefined) {
+            throw new RangeError(i18nextGS1.t("IdentificationKey.invalidZeroSuppressibleGTIN12"));
+        }
+
+        return zeroSuppressedGTIN12;
+    }
+
     /**
      * Zero expand a zero-suppressed GTIN-12.
      *
@@ -566,6 +612,115 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
         return gtin12;
     }
 
+    /**
+     * Convert a GTIN of any length to a GTIN-14 with an optional indicator digit.
+     *
+     * @param indicatorDigit
+     * Indicator digit. If blank, assumes "0" if the GTIN is not already a GTIN-14.
+     *
+     * @param gtin
+     * GTIN.
+     *
+     * @returns
+     * GTIN-14.
+     */
+    static convertToGTIN14(indicatorDigit: string, gtin: string): string {
+        GTINCreator.validateAny(gtin);
+
+        NUMERIC_CREATOR.validate(indicatorDigit, GTINValidator.OPTIONAL_INDICATOR_DIGIT_VALIDATION);
+
+        const gtinLength = gtin.length;
+
+        // Check digit doesn't change by prepending zeros.
+        let gtin14 = "0".repeat(GTINType.GTIN14 - gtinLength) + gtin;
+
+        // If indicator digit provided and is different, recalculate the check digit.
+        if (indicatorDigit.length !== 0 && indicatorDigit !== gtin14.charAt(0)) {
+            const partialGTIN14 = indicatorDigit + gtin14.substring(1, GTINType.GTIN14 - 1);
+
+            gtin14 = partialGTIN14 + checkDigit(partialGTIN14);
+        }
+
+        return gtin14;
+    }
+
+    /**
+     * Normalize a GTIN of any length.
+     * - A GTIN-14 that starts with six zeros or a GTIN-13 that starts with five zeros is normalized to GTIN-8.
+     * - A GTIN-14 that starts with two zeros or a GTIN-13 that starts with one zero is normalized to GTIN-12.
+     * - A GTIN-14 that starts with one zero is normalized to GTIN-13.
+     * - Otherwise, the GTIN is unchanged.
+     *
+     * @param gtin
+     * GTIN.
+     *
+     * @returns
+     * Normalized GTIN.
+     */
+    static normalize(gtin: string): string {
+        const gtinLength = gtin.length;
+
+        let normalizedGTIN: string;
+
+        switch (gtinLength) {
+            case GTINType.GTIN13 as number:
+                if (!gtin.startsWith("0")) {
+                    // GTIN is GTIN-13.
+                    normalizedGTIN = gtin;
+                } else if (!gtin.startsWith("00000")) {
+                    // GTIN is GTIN-12.
+                    normalizedGTIN = gtin.substring(1);
+                } else if (!gtin.startsWith("000000")) {
+                    // GTIN is GTIN-8.
+                    normalizedGTIN = gtin.substring(5);
+                } else {
+                    throw new RangeError(i18nextGS1.t("IdentificationKey.invalidZeroSuppressedGTIN12AsGTIN13"));
+                }
+                break;
+
+            case GTINType.GTIN12 as number:
+                // GTIN is GTIN-12.
+                normalizedGTIN = gtin;
+                break;
+
+            case GTINType.GTIN8 as number:
+                if (!gtin.startsWith("0")) {
+                    // GTIN is GTIN-8.
+                    normalizedGTIN = gtin;
+                } else {
+                    // GTIN is zero-suppressed GTIN-12.
+                    normalizedGTIN = GTINValidator.zeroExpand(gtin);
+                }
+                break;
+
+            case GTINType.GTIN14 as number:
+                if (!gtin.startsWith("0")) {
+                    // GTIN is GTIN-14.
+                    normalizedGTIN = gtin;
+                } else if (!gtin.startsWith("00")) {
+                    // GTIN is GTIN-13.
+                    normalizedGTIN = gtin.substring(1);
+                } else if (!gtin.startsWith("000000")) {
+                    // GTIN is GTIN-12.
+                    normalizedGTIN = gtin.substring(2);
+                } else if (!gtin.startsWith("0000000")) {
+                    // GTIN is GTIN-8.
+                    normalizedGTIN = gtin.substring(6);
+                } else {
+                    throw new RangeError(i18nextGS1.t("IdentificationKey.invalidZeroSuppressedGTIN12AsGTIN14"));
+                }
+                break;
+
+            default:
+                throw new RangeError(i18nextGS1.t("IdentificationKey.invalidGTINLength"));
+        }
+
+        // Validation applies to the normalized GTIN.
+        GTINCreator.validateAny(normalizedGTIN);
+
+        return normalizedGTIN;
+    }
+
     /**
      * Validate any GTIN, optionally against a level.
      *
@@ -1048,7 +1203,7 @@ export interface NumericIdentificationKeyCreator extends NumericIdentificationKe
      * @returns
      * Identification key(s).
      */
-    create: <T extends TransformerInput<number | bigint>>(valueOrValues: T, sparse?: boolean) => TransformerOutput<T, string>;
+    create: <TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput, sparse?: boolean) => TransformerOutput<TTransformerInput, string>;
 
     /**
      * Create all identification keys for the prefix from `0` to `capacity - 1`.
@@ -1134,7 +1289,7 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
     /**
      * @inheritDoc
      */
-    create<T extends TransformerInput<number | bigint>>(valueOrValues: T, sparse = false): TransformerOutput<T, string> {
+    create<TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput, sparse = false): TransformerOutput<TTransformerInput, string> {
         return NUMERIC_CREATOR.create(this.referenceLength, valueOrValues, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
     }
 
@@ -1224,15 +1379,6 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
         component: () => i18nextGS1.t("IdentificationKey.indicatorDigit")
     };
 
-    /**
-     * Validation parameters for optional indicator digit.
-     */
-    private static readonly OPTIONAL_INDICATOR_DIGIT_VALIDATION: CharacterSetValidation = {
-        minimumLength: 0,
-        maximumLength: 1,
-        component: () => i18nextGS1.t("IdentificationKey.indicatorDigit")
-    };
-
     /**
      * Constructor. Called internally by {@link PrefixManager.gtinCreator}; should not be called by other code.
      *
@@ -1271,7 +1417,7 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      * @returns
      * GTIN-14(s).
      */
-    createGTIN14<T extends TransformerInput<number | bigint>>(indicatorDigit: string, valueOrValues: T, sparse = false): TransformerOutput<T, string> {
+    createGTIN14<TTransformerInput extends TransformerInput<number | bigint>>(indicatorDigit: string, valueOrValues: TTransformerInput, sparse = false): TransformerOutput<TTransformerInput, string> {
         NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.REQUIRED_INDICATOR_DIGIT_VALIDATION);
 
         return NUMERIC_CREATOR.create(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, valueOrValues, Exclusion.None, sparse ? this.tweak : undefined, (reference) => {
@@ -1280,152 +1426,6 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
             return partialIdentificationKey + checkDigit(partialIdentificationKey);
         });
     }
-
-    /**
-     * Zero suppress a GTIN-12.
-     *
-     * @param gtin12
-     * GTIN-12.
-     *
-     * @returns
-     * Zero-suppressed GTIN-12.
-     */
-    static zeroSuppress(gtin12: string): string {
-        GTIN12_VALIDATOR.validate(gtin12);
-
-        // Convert to individual digits.
-        const d = Array.from(gtin12);
-
-        let zeroSuppressedGTIN12: string | undefined;
-
-        // All rules require that digits in positions 1, 5, and 6 be zero.
-        if (d[0] === "0" && d[6] === "0" && d[7] === "0") {
-            if (d[10] >= "5" && d[8] === "0" && d[9] === "0" && d[5] !== "0") {
-                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[3]}${d[4]}${d[5]}${d[10]}${d[11]}`;
-            } else if (d[5] === "0" && d[8] === "0" && d[9] === "0" && d[4] !== "0") {
-                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[3]}${d[4]}${d[10]}4${d[11]}`;
-            } else if (d[3] <= "2" && d[4] === "0" && d[5] === "0") {
-                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[8]}${d[9]}${d[10]}${d[3]}${d[11]}`;
-            } else if (d[3] >= "3" && d[4] === "0" && d[5] === "0" && d[8] === "0") {
-                zeroSuppressedGTIN12 = `0${d[1]}${d[2]}${d[3]}${d[9]}${d[10]}3${d[11]}`;
-            }
-        }
-
-        if (zeroSuppressedGTIN12 === undefined) {
-            throw new RangeError(i18nextGS1.t("IdentificationKey.invalidZeroSuppressibleGTIN12"));
-        }
-
-        return zeroSuppressedGTIN12;
-    }
-
-    /**
-     * Convert a GTIN of any length to a GTIN-14 with an optional indicator digit.
-     *
-     * @param indicatorDigit
-     * Indicator digit. If blank, assumes "0" if the GTIN is not already a GTIN-14.
-     *
-     * @param gtin
-     * GTIN.
-     *
-     * @returns
-     * GTIN-14.
-     */
-    static convertToGTIN14(indicatorDigit: string, gtin: string): string {
-        GTINCreator.validateAny(gtin);
-
-        NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.OPTIONAL_INDICATOR_DIGIT_VALIDATION);
-
-        const gtinLength = gtin.length;
-
-        // Check digit doesn't change by prepending zeros.
-        let gtin14 = "0".repeat(GTINType.GTIN14 - gtinLength) + gtin;
-
-        // If indicator digit provided and is different, recalculate the check digit.
-        if (indicatorDigit.length !== 0 && indicatorDigit !== gtin14.charAt(0)) {
-            const partialGTIN14 = indicatorDigit + gtin14.substring(1, GTINType.GTIN14 - 1);
-
-            gtin14 = partialGTIN14 + checkDigit(partialGTIN14);
-        }
-
-        return gtin14;
-    }
-
-    /**
-     * Normalize a GTIN of any length.
-     * - A GTIN-14 that starts with six zeros or a GTIN-13 that starts with five zeros is normalized to GTIN-8.
-     * - A GTIN-14 that starts with two zeros or a GTIN-13 that starts with one zero is normalized to GTIN-12.
-     * - A GTIN-14 that starts with one zero is normalized to GTIN-13.
-     * - Otherwise, the GTIN is unchanged.
-     *
-     * @param gtin
-     * GTIN.
-     *
-     * @returns
-     * Normalized GTIN.
-     */
-    static normalize(gtin: string): string {
-        const gtinLength = gtin.length;
-
-        let normalizedGTIN: string;
-
-        switch (gtinLength) {
-            case GTINType.GTIN13 as number:
-                if (!gtin.startsWith("0")) {
-                    // GTIN is GTIN-13.
-                    normalizedGTIN = gtin;
-                } else if (!gtin.startsWith("00000")) {
-                    // GTIN is GTIN-12.
-                    normalizedGTIN = gtin.substring(1);
-                } else if (!gtin.startsWith("000000")) {
-                    // GTIN is GTIN-8.
-                    normalizedGTIN = gtin.substring(5);
-                } else {
-                    throw new RangeError(i18nextGS1.t("IdentificationKey.invalidZeroSuppressedGTIN12AsGTIN13"));
-                }
-                break;
-
-            case GTINType.GTIN12 as number:
-                // GTIN is GTIN-12.
-                normalizedGTIN = gtin;
-                break;
-
-            case GTINType.GTIN8 as number:
-                if (!gtin.startsWith("0")) {
-                    // GTIN is GTIN-8.
-                    normalizedGTIN = gtin;
-                } else {
-                    // GTIN is zero-suppressed GTIN-12.
-                    normalizedGTIN = GTINCreator.zeroExpand(gtin);
-                }
-                break;
-
-            case GTINType.GTIN14 as number:
-                if (!gtin.startsWith("0")) {
-                    // GTIN is GTIN-14.
-                    normalizedGTIN = gtin;
-                } else if (!gtin.startsWith("00")) {
-                    // GTIN is GTIN-13.
-                    normalizedGTIN = gtin.substring(1);
-                } else if (!gtin.startsWith("000000")) {
-                    // GTIN is GTIN-12.
-                    normalizedGTIN = gtin.substring(2);
-                } else if (!gtin.startsWith("0000000")) {
-                    // GTIN is GTIN-8.
-                    normalizedGTIN = gtin.substring(6);
-                } else {
-                    throw new RangeError(i18nextGS1.t("IdentificationKey.invalidZeroSuppressedGTIN12AsGTIN14"));
-                }
-                break;
-
-            default:
-                throw new RangeError(i18nextGS1.t("IdentificationKey.invalidGTINLength"));
-        }
-
-        // Validation applies to the normalized GTIN.
-        GTINCreator.validateAny(normalizedGTIN);
-
-        return normalizedGTIN;
-    }
 }
 
 /**
@@ -1496,7 +1496,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key(s).
      */
-    private concatenateValidated<T extends TransformerInput<string>>(baseIdentificationKey: string, serialComponentOrComponents: T): TransformerOutput<T, string> {
+    private concatenateValidated<TTransformerInput extends TransformerInput<string>>(baseIdentificationKey: string, serialComponentOrComponents: TTransformerInput): TransformerOutput<TTransformerInput, string> {
         // TODO Refactor type when https://github.com/microsoft/TypeScript/pull/56941 released.
         let result: string | Iterable<string>;
 
@@ -1525,7 +1525,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
         }
 
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type determination is handled above.
-        return result as TransformerOutput<T, string>;
+        return result as TransformerOutput<TTransformerInput, string>;
     }
 
     /**
@@ -1544,7 +1544,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification keys.
      */
-    createSerialized<T extends TransformerInput<string>>(value: number, serialComponentOrComponents: T, sparse?: boolean): TransformerOutput<T, string> {
+    createSerialized<TTransformerInput extends TransformerInput<string>>(value: number, serialComponentOrComponents: TTransformerInput, sparse?: boolean): TransformerOutput<TTransformerInput, string> {
         return this.concatenateValidated(this.create(value, sparse), serialComponentOrComponents);
     }
 
@@ -1560,7 +1560,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key(s).
      */
-    concatenate<T extends TransformerInput<string>>(baseIdentificationKey: string, serialComponentOrComponents: T): TransformerOutput<T, string> {
+    concatenate<TTransformerInput extends TransformerInput<string>>(baseIdentificationKey: string, serialComponentOrComponents: TTransformerInput): TransformerOutput<TTransformerInput, string> {
         this.validate(baseIdentificationKey);
 
         return this.concatenateValidated(baseIdentificationKey, serialComponentOrComponents);
@@ -1624,7 +1624,7 @@ export class NonNumericIdentificationKeyCreator extends Mixin(NonNumericIdentifi
      * @returns
      * Identification key(s).
      */
-    create<T extends TransformerInput<string>>(referenceOrReferences: T): TransformerOutput<T, string> {
+    create<TTransformerInput extends TransformerInput<string>>(referenceOrReferences: TTransformerInput): TransformerOutput<TTransformerInput, string> {
         // TODO Refactor type when https://github.com/microsoft/TypeScript/pull/56941 released.
         let result: string | Iterable<string>;
 
@@ -1657,7 +1657,7 @@ export class NonNumericIdentificationKeyCreator extends Mixin(NonNumericIdentifi
         }
 
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type determination is handled above.
-        return result as TransformerOutput<T, string>;
+        return result as TransformerOutput<TTransformerInput, string>;
     }
 }
 
@@ -2076,9 +2076,9 @@ export class PrefixManager {
      * @returns
      * Identification key creator.
      */
-    private getIdentificationKeyCreator<T extends IdentificationKeyCreator>(identificationKeyType: IdentificationKeyType, constructorCallback: () => T): T {
+    private getIdentificationKeyCreator<TIdentificationKeyCreator extends IdentificationKeyCreator>(identificationKeyType: IdentificationKeyType, constructorCallback: () => TIdentificationKeyCreator): TIdentificationKeyCreator {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type is paired with constructor callback.
-        let creator = this._identificationKeyCreatorsMap.get(identificationKeyType) as (T | undefined);
+        let creator = this._identificationKeyCreatorsMap.get(identificationKeyType) as (TIdentificationKeyCreator | undefined);
 
         if (creator === undefined) {
             if (this.prefixType === PrefixType.GS18Prefix && identificationKeyType !== IdentificationKeyType.GTIN) {