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

package/src/prefix-manager.ts

@@ -1,57 +1,39 @@
-import { GTINCreator } from "./gtin-creator";
-import { type GTINType, GTINTypes } from "./gtin-validator";
-import type { IdentifierCreator } from "./identifier-creator";
-import { type IdentifierType, IdentifierTypes } from "./identifier-type";
-import { i18nextGS1 } from "./locale/i18n";
-import { NonGTINNumericIdentifierCreator } from "./non-gtin-numeric-identifier-creator";
-import {
-    GLN_VALIDATOR,
-    GSIN_VALIDATOR,
-    GSRN_VALIDATOR,
-    type NonGTINNumericIdentifierValidator,
-    SSCC_VALIDATOR
-} from "./non-gtin-numeric-identifier-validator";
-import { NonNumericIdentifierCreator } from "./non-numeric-identifier-creator";
-import {
-    CPID_VALIDATOR,
-    GIAI_VALIDATOR,
-    GINC_VALIDATOR,
-    GMN_VALIDATOR,
-    type NonNumericIdentifierValidator
-} from "./non-numeric-identifier-validator";
-import type { AbstractNumericIdentifierCreator } from "./numeric-identifier-creator";
-import type { NumericIdentifierType } from "./numeric-identifier-validator";
-import type { PrefixProvider } from "./prefix-provider";
-import { type PrefixType, PrefixTypes } from "./prefix-type";
-import { PrefixValidator } from "./prefix-validator";
-import { SerializableNumericIdentifierCreator } from "./serializable-numeric-identifier-creator";
-import {
-    GCN_VALIDATOR,
-    GDTI_VALIDATOR,
-    GRAI_VALIDATOR,
-    type SerializableNumericIdentifierValidator
-} from "./serializable-numeric-identifier-validator";
+import { type IdentifierCreatorsRecord, isNumericIdentifierCreator } from "./creators.js";
+import { GTINCreator } from "./gtin-creator.js";
+import { GTIN_BASE_TYPES } from "./gtin-type.js";
+import type { IdentifierCreator } from "./identifier-creator.js";
+import { type IdentifierType, IdentifierTypes } from "./identifier-type.js";
+import { i18nextGS1 } from "./locale/i18n.js";
+import { NonGTINNumericIdentifierCreator } from "./non-gtin-numeric-identifier-creator.js";
+import type { NonGTINNumericIdentifierType } from "./non-gtin-numeric-identifier-type.js";
+import { NonNumericIdentifierCreator } from "./non-numeric-identifier-creator.js";
+import type { NonNumericIdentifierType } from "./non-numeric-identifier-type.js";
+import type { NumericIdentifierType } from "./numeric-identifier-type.js";
+import type { PrefixProvider } from "./prefix-provider.js";
+import { type PrefixType, PrefixTypes } from "./prefix-type.js";
+import { PrefixValidator } from "./prefix-validator.js";
+import { SerializableNumericIdentifierCreator } from "./serializable-numeric-identifier-creator.js";
+import type { SerializableNumericIdentifierType } from "./serializable-numeric-identifier-type.js";
 
 /**
  * Prefix manager. This is the core class for identifier creation.
  *
- * A prefix manager may be created for any {@link PrefixType | prefix type}. As most applications work with a limited
- * number of prefixes for creating identifiers, prefix managers are cached in memory and may be reused.
+ * A prefix manager may be constructed for any {@link PrefixType | prefix type}. Construction may be done directly or
+ * via the static {@linkcode PrefixManager.get | get()} method, which allows for caching and reuse. As most applications
+ * work with a limited number of prefixes for creating identifiers, caching and reuse may be a more efficient option.
  *
- * Prefix managers are keyed by GS1 Company Prefix, so the prefix type that is requested may not match the prefix type
- * of the returned prefix manager. For example, the prefix manager for GS1 Company Prefix 0614141 is identical to the
- * one for U.P.C. Company Prefix 614141, with the prefix type equal to {@link PrefixTypes.UPCCompanyPrefix} and the
- * prefix equal to "614141".
+ * The prefix type and prefix are normalized before the prefix manager is constructed, so they may not match the input
+ * values. For example, the GS1 Company Prefix 0614141 is equivalent to U.P.C. Company Prefix 614141; both result in a
+ * prefix manager with prefix type equal to {@linkcode PrefixTypes.UPCCompanyPrefix} and prefix equal to "614141".
  *
- * To support the creation of sparse identifiers, a prefix manager maintains a {@link tweakFactor | tweak
- * factor} which is used, along with a type-specific multiplier, as the tweak when creating numeric identifiers.
- * The default tweak factor is the numeric value of the GS1 Company Prefix representation of the prefix preceded by '1'
- * to ensure uniqueness (i.e., so that prefixes 0 N1 N2 N3... and N1 N2 N3... produce different tweak factors). This is
- * usually sufficient for obfuscation, but as the sparse creation algorithm is reversible and as the GS1 Company Prefix
- * is discoverable via {@link https://www.gs1.org/services/verified-by-gs1 | Verified by GS1}, a user-defined tweak
- * factor should be used if a higher degree of obfuscation is required. When using a tweak factor other than the
- * default, care should be taken to restore it when resuming the application. A tweak factor of 0 creates a straight
- * sequence.
+ * To support the creation of sparse identifiers, a prefix manager maintains a {@link tweakFactor | tweak factor} which
+ * is used, along with a type-specific multiplier, as the tweak when creating numeric identifiers. The default tweak
+ * factor is the numeric value of the GS1 Company Prefix representation of the prefix preceded by '1' to ensure
+ * uniqueness (i.e., so that prefixes 0 N1 N2 N3... and N1 N2 N3... produce different tweak factors). This is usually
+ * sufficient for obfuscation, but as the sparse creation algorithm is reversible and as the GS1 Company Prefix is
+ * discoverable via {@link https://www.gs1.org/services/verified-by-gs1 | Verified by GS1}, a user-defined tweak factor
+ * should be used if a higher degree of obfuscation is required. When using a tweak factor other than the default, care
+ * should be taken to restore it when resuming the application. A tweak factor of 0 creates a straight sequence.
  */
 export class PrefixManager implements PrefixProvider {
     /**
@@ -90,12 +72,12 @@ export class PrefixManager implements PrefixProvider {
     private readonly _gs1CompanyPrefix: string;
 
     /**
-     * U.P.C. Company Prefix if prefix type is {@link PrefixTypes.UPCCompanyPrefix}.
+     * U.P.C. Company Prefix if prefix type is {@linkcode PrefixTypes.UPCCompanyPrefix}.
      */
     private readonly _upcCompanyPrefix: string | undefined;
 
     /**
-     * GS1-8 Prefix if prefix type is {@link PrefixTypes.GS18Prefix}.
+     * GS1-8 Prefix if prefix type is {@linkcode PrefixTypes.GS18Prefix}.
      */
     private readonly _gs18Prefix: string | undefined;
 
@@ -112,30 +94,25 @@ export class PrefixManager implements PrefixProvider {
     /**
      * Cached identifier creators.
      */
-    private readonly _identifierCreators: Partial<Record<IdentifierType, IdentifierCreator>> = {};
+    private readonly _identifierCreators: Partial<IdentifierCreatorsRecord> = {};
 
     /**
      * Constructor.
      *
-     * @param gs1CompanyPrefix
-     * GS1 Company Prefix.
-     */
-    private constructor(gs1CompanyPrefix: string) {
-        this._gs1CompanyPrefix = gs1CompanyPrefix;
-
-        // Determine the prefix type and populate the remaining fields.
-        if (!gs1CompanyPrefix.startsWith("0")) {
-            this._prefixType = PrefixTypes.GS1CompanyPrefix;
-            this._prefix = this._gs1CompanyPrefix;
-        } else if (!gs1CompanyPrefix.startsWith("00000")) {
-            this._prefixType = PrefixTypes.UPCCompanyPrefix;
-            this._upcCompanyPrefix = gs1CompanyPrefix.substring(1);
-            this._prefix = this._upcCompanyPrefix;
-        } else {
-            this._prefixType = PrefixTypes.GS18Prefix;
-            this._gs18Prefix = gs1CompanyPrefix.substring(5);
-            this._prefix = this._gs18Prefix;
-        }
+     * @param prefixType
+     * Prefix type.
+     *
+     * @param prefix
+     * Prefix.
+     */
+    constructor(prefixType: PrefixType, prefix: string) {
+        const normalizedPrefixProvider = PrefixValidator.normalize(prefixType, prefix);
+
+        this._prefixType = normalizedPrefixProvider.prefixType;
+        this._prefix = normalizedPrefixProvider.prefix;
+        this._gs1CompanyPrefix = normalizedPrefixProvider.gs1CompanyPrefix;
+        this._upcCompanyPrefix = normalizedPrefixProvider.upcCompanyPrefix;
+        this._gs18Prefix = normalizedPrefixProvider.gs18Prefix;
 
         // Default tweak factor is the numeric value of the GS1 Company Prefix preceded by '1'.
         this._defaultTweakFactor = BigInt(`1${this.gs1CompanyPrefix}`);
@@ -165,14 +142,14 @@ export class PrefixManager implements PrefixProvider {
     }
 
     /**
-     * Get the U.P.C. Company Prefix if prefix type is {@link PrefixTypes.UPCCompanyPrefix} or undefined if not.
+     * Get the U.P.C. Company Prefix if prefix type is {@linkcode PrefixTypes.UPCCompanyPrefix} or undefined if not.
      */
     get upcCompanyPrefix(): string | undefined {
         return this._upcCompanyPrefix;
     }
 
     /**
-     * Get the GS1-8 Prefix if prefix type is {@link PrefixTypes.GS18Prefix} or undefined if not.
+     * Get the GS1-8 Prefix if prefix type is {@linkcode PrefixTypes.GS18Prefix} or undefined if not.
      */
     get gs18Prefix(): string | undefined {
         return this._gs18Prefix;
@@ -181,16 +158,13 @@ export class PrefixManager implements PrefixProvider {
     /**
      * Set the tweak for an identifier creator if it's a numeric identifier creator.
      *
-     * @param creator
+     * @param identifierCreator
      * Identifier creator.
      */
-    private setCreatorTweak(creator: IdentifierCreator): void {
-        if (creator.identifierType in PrefixManager.CREATOR_TWEAK_FACTORS) {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type is known by testing for presence in record.
-            const creatorTweakFactor = PrefixManager.CREATOR_TWEAK_FACTORS[creator.identifierType as NumericIdentifierType];
-
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion,no-param-reassign -- Type is known by testing identifier type. Method purpose is to set the tweak.
-            (creator as AbstractNumericIdentifierCreator).tweak = this.tweakFactor * creatorTweakFactor;
+    private setCreatorTweak(identifierCreator: IdentifierCreator): void {
+        if (isNumericIdentifierCreator(identifierCreator)) {
+            // eslint-disable-next-line no-param-reassign -- Method purpose is to set the tweak.
+            identifierCreator.tweak = this.tweakFactor * PrefixManager.CREATOR_TWEAK_FACTORS[identifierCreator.identifierType];
         }
     }
 
@@ -239,33 +213,14 @@ export class PrefixManager implements PrefixProvider {
      * Prefix manager with normalized prefix type and prefix.
      */
     static get(prefixType: PrefixType, prefix: string): PrefixManager {
-        PrefixValidator.validate(prefixType, true, true, prefix);
-
-        let gs1CompanyPrefix: string;
+        // Normalization will occur in constructor as well, but it's necessary here for the map.
+        const normalizedPrefixProvider = PrefixValidator.normalize(prefixType, prefix);
 
-        switch (prefixType) {
-            case PrefixTypes.GS1CompanyPrefix:
-                gs1CompanyPrefix = prefix;
-                break;
-
-            case PrefixTypes.UPCCompanyPrefix:
-                gs1CompanyPrefix = "0" + prefix;
-                break;
-
-            case PrefixTypes.GS18Prefix:
-                gs1CompanyPrefix = "00000" + prefix;
-                break;
-
-            // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- Method may be called by unsafe means.
-            default:
-                throw new RangeError(i18nextGS1.t("Prefix.invalidPrefixType"));
-        }
-
-        let prefixManager = PrefixManager.PREFIX_MANAGERS_MAP.get(gs1CompanyPrefix);
+        let prefixManager = PrefixManager.PREFIX_MANAGERS_MAP.get(normalizedPrefixProvider.gs1CompanyPrefix);
 
         if (prefixManager === undefined) {
-            prefixManager = new PrefixManager(gs1CompanyPrefix);
-            PrefixManager.PREFIX_MANAGERS_MAP.set(gs1CompanyPrefix, prefixManager);
+            prefixManager = new PrefixManager(normalizedPrefixProvider.prefixType, normalizedPrefixProvider.prefix);
+            PrefixManager.PREFIX_MANAGERS_MAP.set(normalizedPrefixProvider.gs1CompanyPrefix, prefixManager);
         }
 
         return prefixManager;
@@ -274,18 +229,23 @@ export class PrefixManager implements PrefixProvider {
     /**
      * Get an identifier creator.
      *
+     * @template TIdentifierType
+     * Identifier type type.
+     *
      * @param identifierType
-     * Identifier type.
+     * Identifier type used to construct identifier creator.
      *
-     * @param constructorCallback
+     * @param constructorParameter
+     * Second constructor parameter passed to constructor callback alongside this.
+     *
+     * @param ConstructorCallback
      * Constructor callback.
      *
      * @returns
      * Identifier creator.
      */
-    private getIdentifierCreator<TIdentifierCreator extends IdentifierCreator>(identifierType: IdentifierType, constructorCallback: () => TIdentifierCreator): TIdentifierCreator {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type is paired with constructor callback.
-        let creator = this._identifierCreators[identifierType] as TIdentifierCreator | undefined;
+    private getIdentifierCreator<TIdentifierType extends IdentifierType, TConstructorParameter>(identifierType: TIdentifierType, constructorParameter: TConstructorParameter, ConstructorCallback: new (prefixProvider: PrefixProvider, constructorParameter: TConstructorParameter) => IdentifierCreatorsRecord[TIdentifierType]): IdentifierCreatorsRecord[TIdentifierType] {
+        let creator: IdentifierCreatorsRecord[TIdentifierType] | undefined = this._identifierCreators[identifierType];
 
         if (creator === undefined) {
             if (this.prefixType === PrefixTypes.GS18Prefix && identifierType !== IdentifierTypes.GTIN) {
@@ -294,7 +254,7 @@ export class PrefixManager implements PrefixProvider {
                 }));
             }
 
-            creator = constructorCallback();
+            creator = new ConstructorCallback(this, constructorParameter);
 
             this.setCreatorTweak(creator);
 
@@ -307,141 +267,123 @@ export class PrefixManager implements PrefixProvider {
     /**
      * Get non-GTIN numeric identifier creator.
      *
-     * @param validator
-     * Validator on which identifier creator is based.
+     * @param identifierType
+     * Identifier type used to construct identifier creator.
      *
      * @returns
      * Identifier creator.
      */
-    private getNonGTINNumericIdentifierCreator(validator: NonGTINNumericIdentifierValidator): NonGTINNumericIdentifierCreator {
-        return this.getIdentifierCreator(validator.identifierType, () => new NonGTINNumericIdentifierCreator(this, validator.identifierType, validator.length, validator.leaderType));
+    private getNonGTINNumericIdentifierCreator(identifierType: Exclude<NonGTINNumericIdentifierType, SerializableNumericIdentifierType>): NonGTINNumericIdentifierCreator {
+        return this.getIdentifierCreator(identifierType, identifierType, NonGTINNumericIdentifierCreator);
     }
 
     /**
      * Get serialized numeric identifier creator.
      *
-     * @param validator
-     * Validator on which identifier creator is based.
+     * @param identifierType
+     * Identifier type used to construct identifier creator.
      *
      * @returns
      * Identifier creator.
      */
-    private getSerializableNumericIdentifierCreator(validator: SerializableNumericIdentifierValidator): SerializableNumericIdentifierCreator {
-        return this.getIdentifierCreator(validator.identifierType, () => new SerializableNumericIdentifierCreator(this, validator.identifierType, validator.length, validator.serialComponentLength, validator.serialComponentCharacterSet));
+    private getSerializableNumericIdentifierCreator(identifierType: SerializableNumericIdentifierType): SerializableNumericIdentifierCreator {
+        return this.getIdentifierCreator(identifierType, identifierType, SerializableNumericIdentifierCreator);
     }
 
     /**
      * Get non-numeric identifier creator.
      *
-     * @param validator
-     * Validator on which identifier creator is based.
+     * @param identifierType
+     * Identifier type used to construct identifier creator.
      *
      * @returns
      * Identifier creator.
      */
-    private getNonNumericIdentifierCreator(validator: NonNumericIdentifierValidator): NonNumericIdentifierCreator {
-        return this.getIdentifierCreator(validator.identifierType, () => new NonNumericIdentifierCreator(this, validator.identifierType, validator.length, validator.referenceCharacterSet, validator.requiresCheckCharacterPair));
+    private getNonNumericIdentifierCreator(identifierType: NonNumericIdentifierType): NonNumericIdentifierCreator {
+        return this.getIdentifierCreator(identifierType, identifierType, NonNumericIdentifierCreator);
     }
 
     /**
      * Get GTIN creator.
      */
     get gtinCreator(): GTINCreator {
-        return this.getIdentifierCreator(IdentifierTypes.GTIN, () => {
-            let gtinType: GTINType;
-
-            switch (this.prefixType) {
-                case PrefixTypes.GS1CompanyPrefix:
-                    gtinType = GTINTypes.GTIN13;
-                    break;
-
-                case PrefixTypes.UPCCompanyPrefix:
-                    gtinType = GTINTypes.GTIN12;
-                    break;
-
-                case PrefixTypes.GS18Prefix:
-                    gtinType = GTINTypes.GTIN8;
-                    break;
-            }
-
-            return new GTINCreator(this, gtinType);
-        });
+        return this.getIdentifierCreator(IdentifierTypes.GTIN, GTIN_BASE_TYPES[this.prefixType], GTINCreator);
     }
 
     /**
      * Get GLN creator.
      */
     get glnCreator(): NonGTINNumericIdentifierCreator {
-        return this.getNonGTINNumericIdentifierCreator(GLN_VALIDATOR);
+        return this.getNonGTINNumericIdentifierCreator(IdentifierTypes.GLN);
     }
 
     /**
      * Get SSCC creator.
      */
     get ssccCreator(): NonGTINNumericIdentifierCreator {
-        return this.getNonGTINNumericIdentifierCreator(SSCC_VALIDATOR);
+        return this.getNonGTINNumericIdentifierCreator(IdentifierTypes.SSCC);
     }
 
     /**
      * Get GRAI creator.
      */
     get graiCreator(): SerializableNumericIdentifierCreator {
-        return this.getSerializableNumericIdentifierCreator(GRAI_VALIDATOR);
+        return this.getSerializableNumericIdentifierCreator(IdentifierTypes.GRAI);
     }
 
     /**
      * Get GIAI creator.
      */
     get giaiCreator(): NonNumericIdentifierCreator {
-        return this.getNonNumericIdentifierCreator(GIAI_VALIDATOR);
+        return this.getNonNumericIdentifierCreator(IdentifierTypes.GIAI);
     }
 
     /**
      * Get GSRN creator.
      */
     get gsrnCreator(): NonGTINNumericIdentifierCreator {
-        return this.getNonGTINNumericIdentifierCreator(GSRN_VALIDATOR);
+        return this.getNonGTINNumericIdentifierCreator(IdentifierTypes.GSRN);
     }
 
     /**
      * Get GDTI creator.
      */
     get gdtiCreator(): SerializableNumericIdentifierCreator {
-        return this.getSerializableNumericIdentifierCreator(GDTI_VALIDATOR);
+        return this.getSerializableNumericIdentifierCreator(IdentifierTypes.GDTI);
     }
 
     /**
      * Get GINC creator.
      */
     get gincCreator(): NonNumericIdentifierCreator {
-        return this.getNonNumericIdentifierCreator(GINC_VALIDATOR);
+        return this.getNonNumericIdentifierCreator(IdentifierTypes.GINC);
     }
 
     /**
      * Get GSIN creator.
      */
     get gsinCreator(): NonGTINNumericIdentifierCreator {
-        return this.getNonGTINNumericIdentifierCreator(GSIN_VALIDATOR);
+        return this.getNonGTINNumericIdentifierCreator(IdentifierTypes.GSIN);
     }
 
     /**
      * Get GCN creator.
      */
     get gcnCreator(): SerializableNumericIdentifierCreator {
-        return this.getSerializableNumericIdentifierCreator(GCN_VALIDATOR);
+        return this.getSerializableNumericIdentifierCreator(IdentifierTypes.GCN);
     }
 
     /**
      * Get CPID creator.
      */
     get cpidCreator(): NonNumericIdentifierCreator {
-        return this.getNonNumericIdentifierCreator(CPID_VALIDATOR);
+        return this.getNonNumericIdentifierCreator(IdentifierTypes.CPID);
     }
 
     /**
      * Get GMN creator.
      */
     get gmnCreator(): NonNumericIdentifierCreator {
-        return this.getNonNumericIdentifierCreator(GMN_VALIDATOR);
+        return this.getNonNumericIdentifierCreator(IdentifierTypes.GMN);
     }
 }

package/src/prefix-provider.ts

@@ -1,4 +1,4 @@
-import type { PrefixType } from "./prefix-type";
+import type { PrefixType } from "./prefix-type.js";
 
 /**
  * Prefix provider.
@@ -20,12 +20,12 @@ export interface PrefixProvider {
     readonly gs1CompanyPrefix: string;
     
     /**
-     * Prefix as U.P.C. Company Prefix if prefix type is {@link PrefixTypes.UPCCompanyPrefix} or undefined if not.
+     * Prefix as U.P.C. Company Prefix if prefix type is {@linkcode PrefixTypes.UPCCompanyPrefix} or undefined if not.
      */
     readonly upcCompanyPrefix: string | undefined;
     
     /**
-     * Prefix as GS1-8 Prefix if prefix type is {@link PrefixTypes.GS18Prefix} or undefined if not.
+     * Prefix as GS1-8 Prefix if prefix type is {@linkcode PrefixTypes.GS18Prefix} or undefined if not.
      */
     readonly gs18Prefix: string | undefined;
 }

package/src/prefix-type.ts

@@ -18,7 +18,12 @@ export const PrefixTypes = {
     GS18Prefix: "GS1-8 Prefix"
 } as const;
 
+/**
+ * Prefix type key.
+ */
+export type PrefixTypeKey = keyof typeof PrefixTypes;
+
 /**
  * Prefix type.
  */
-export type PrefixType = typeof PrefixTypes[keyof typeof PrefixTypes];
+export type PrefixType = typeof PrefixTypes[PrefixTypeKey];