@aidc-toolkit/gs1 0.9.20-beta → 0.9.21-beta

package/src/identifier-type.ts

@@ -0,0 +1,69 @@
+/**
+ * Identifier types.
+ */
+export const IdentifierTypes = {
+    /**
+     * Global Trade Item Number.
+     */
+    GTIN: "GTIN",
+
+    /**
+     * Global Location Number.
+     */
+    GLN: "GLN",
+
+    /**
+     * Serial Shipping Container Code.
+     */
+    SSCC: "SSCC",
+
+    /**
+     * Global Returnable Asset Identifier.
+     */
+    GRAI: "GRAI",
+
+    /**
+     * Global Individual Asset Identifier.
+     */
+    GIAI: "GIAI",
+
+    /**
+     * Global Service Relation Number.
+     */
+    GSRN: "GSRN",
+
+    /**
+     * Global Document Type Identifier.
+     */
+    GDTI: "GDTI",
+
+    /**
+     * Global Identification Number for Consignment.
+     */
+    GINC: "GINC",
+
+    /**
+     * Global Shipment Identification Number.
+     */
+    GSIN: "GSIN",
+
+    /**
+     * Global Coupon Number.
+     */
+    GCN: "GCN",
+
+    /**
+     * Component/Part Identifier.
+     */
+    CPID: "CPID",
+
+    /**
+     * Global Model Number.
+     */
+    GMN: "GMN"
+} as const;
+
+/**
+ * Identifier type.
+ */
+export type IdentifierType = typeof IdentifierTypes[keyof typeof IdentifierTypes];

package/src/identifier-validator.ts

@@ -0,0 +1,235 @@
+import {
+    type CharacterSetCreator,
+    NUMERIC_CREATOR,
+    type StringValidation,
+    type StringValidator
+} from "@aidc-toolkit/utility";
+import { AI39_CREATOR, AI82_CREATOR } from "./character-set.js";
+import type { IdentifierType } from "./identifier-type.js";
+import type { PrefixType } from "./prefix-type.js";
+import { PrefixValidator } from "./prefix-validator.js";
+
+/**
+ * Character sets supported by the reference portion of an identifier or the serial component of a numeric identifier.
+ */
+export const ContentCharacterSets = {
+    /**
+     * Numeric.
+     */
+    Numeric: "Numeric",
+
+    /**
+     * GS1 AI encodable character set 82.
+     */
+    AI82: "AI82",
+
+    /**
+     * GS1 AI encodable character set 39.
+     */
+    AI39: "AI39"
+} as const;
+
+/**
+ * Content character set.
+ */
+export type ContentCharacterSet = typeof ContentCharacterSets[keyof typeof ContentCharacterSets];
+
+/**
+ * Identifier validation parameters.
+ */
+export interface IdentifierValidation extends StringValidation {
+    /**
+     * Position offset within a larger string. Strings are sometimes composed of multiple substrings; this parameter
+     * ensures that the error notes the proper position in the string.
+     */
+    positionOffset?: number | undefined;
+}
+
+/**
+ * Identifier validator. Validates an identifier against its definition in section 3 of the {@link
+ * https://www.gs1.org/genspecs | GS1 General Specifications}.
+ *
+ * @template TIdentifierValidation
+ * Identifier validation type.
+ */
+export interface IdentifierValidator<TIdentifierValidation extends IdentifierValidation = IdentifierValidation> extends StringValidator<TIdentifierValidation> {
+    /**
+     * Get the identifier type. Per the GS1 General Specifications, the identifier type determines the remaining
+     * properties.
+     */
+    get identifierType(): IdentifierType;
+
+    /**
+     * Get the prefix type supported by the identifier type. For all identifier types except the GTIN, this is
+     * {@linkcode PrefixTypes.GS1CompanyPrefix}. For the GTIN, the prefix type determines the length.
+     */
+    get prefixType(): PrefixType;
+
+    /**
+     * Get the length. For numeric identifier types, the length is fixed; for alphanumeric identifier types, the length
+     * is the maximum.
+     */
+    get length(): number;
+
+    /**
+     * Get the reference character set.
+     */
+    get referenceCharacterSet(): ContentCharacterSet;
+
+    /**
+     * Get the reference creator.
+     */
+    get referenceCreator(): CharacterSetCreator;
+
+    /**
+     * Validate an identifier and throw an error if validation fails.
+     *
+     * @param identifier
+     * Identifier.
+     *
+     * @param validation
+     * Identifier validation parameters.
+     */
+    validate: (identifier: string, validation?: TIdentifierValidation) => void;
+}
+
+/**
+ * Abstract identifier validator. Implements common functionality for an identifier validator.
+ */
+export abstract class AbstractIdentifierValidator<TIdentifierValidation extends IdentifierValidation = IdentifierValidation> implements IdentifierValidator<TIdentifierValidation> {
+    private static readonly CHARACTER_SET_CREATORS: Record<ContentCharacterSet, CharacterSetCreator> = {
+        [ContentCharacterSets.Numeric]: NUMERIC_CREATOR,
+        [ContentCharacterSets.AI82]: AI82_CREATOR,
+        [ContentCharacterSets.AI39]: AI39_CREATOR
+    };
+
+    /**
+     * Identifier type.
+     */
+    private readonly _identifierType: IdentifierType;
+
+    /**
+     * Prefix type.
+     */
+    private readonly _prefixType: PrefixType;
+
+    /**
+     * Length.
+     */
+    private readonly _length: number;
+
+    /**
+     * Reference character set.
+     */
+    private readonly _referenceCharacterSet: ContentCharacterSet;
+
+    /**
+     * Reference creator.
+     */
+    private readonly _referenceCreator: CharacterSetCreator;
+
+    /**
+     * Get the character set creator for a character set.
+     *
+     * @param characterSet
+     * Character set.
+     *
+     * @returns
+     * Character set creator.
+     */
+    protected static creatorFor(characterSet: ContentCharacterSet): CharacterSetCreator {
+        return AbstractIdentifierValidator.CHARACTER_SET_CREATORS[characterSet];
+    }
+
+    /**
+     * Constructor.
+     *
+     * @param identifierType
+     * Identifier type.
+     *
+     * @param prefixType
+     * Prefix type.
+     *
+     * @param length
+     * Length.
+     *
+     * @param referenceCharacterSet
+     * Reference character set.
+     */
+    protected constructor(identifierType: IdentifierType, prefixType: PrefixType, length: number, referenceCharacterSet: ContentCharacterSet) {
+        this._identifierType = identifierType;
+        this._prefixType = prefixType;
+        this._length = length;
+        this._referenceCharacterSet = referenceCharacterSet;
+        this._referenceCreator = AbstractIdentifierValidator.creatorFor(referenceCharacterSet);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get identifierType(): IdentifierType {
+        return this._identifierType;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get prefixType(): PrefixType {
+        return this._prefixType;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get length(): number {
+        return this._length;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get referenceCharacterSet(): ContentCharacterSet {
+        return this._referenceCharacterSet;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get referenceCreator(): CharacterSetCreator {
+        return this._referenceCreator;
+    }
+
+    /**
+     * Pad an identifier on the left with zero-value character for validation purposes. This is done to align an
+     * identifier with a position offset for any error message that may be thrown by the reference validator.
+     *
+     * @param identifier
+     * Identifier.
+     *
+     * @param validation
+     * Identifier validation parameters.
+     *
+     * @returns
+     * Padded identifier.
+     */
+    protected padIdentifier(identifier: string, validation: IdentifierValidation | undefined): string {
+        // Identifier is returned as is if position offset is undefined.
+        return validation?.positionOffset === undefined ? identifier : this.referenceCreator.character(0).repeat(validation.positionOffset).concat(identifier);
+    }
+
+    /**
+     * Validate the prefix within an identifier.
+     *
+     * @param partialIdentifier
+     * Partial identifier.
+     *
+     * @param positionOffset
+     * Position offset within a larger string.
+     */
+    protected validatePrefix(partialIdentifier: string, positionOffset?: number): void {
+        // Delegate to prefix validator with support for U.P.C. Company Prefix but not GS1-8 Prefix.
+        PrefixValidator.validate(this.prefixType, true, false, partialIdentifier, true, this.referenceCharacterSet === ContentCharacterSets.Numeric, positionOffset);
+    }
+
+    abstract validate(identifier: string, validation?: TIdentifierValidation): void;
+}

package/src/index.ts

@@ -17,4 +17,19 @@
 export * from "./locale/i18n.js";
 export * from "./character-set.js";
 export * from "./check.js";
-export * from "./idkey.js";
+export * from "./prefix-type.js";
+export * from "./prefix-validator.js";
+export * from "./identifier-type.js";
+export * from "./identifier-validator.js";
+export * from "./numeric-identifier-validator.js";
+export * from "./gtin-validator.js";
+export * from "./non-gtin-numeric-identifier-validator.js";
+export * from "./serializable-numeric-identifier-validator.js";
+export * from "./non-numeric-identifier-validator.js";
+export * from "./identifier-creator.js";
+export * from "./numeric-identifier-creator.js";
+export * from "./gtin-creator.js";
+export * from "./non-gtin-numeric-identifier-creator.js";
+export * from "./serializable-numeric-identifier-creator.js";
+export * from "./non-numeric-identifier-creator.js";
+export * from "./prefix-manager.js";

package/src/locale/en/locale-strings.ts

@@ -4,8 +4,8 @@ export const localeStrings = {
         priceOrWeightComponent: "price or weight",
         lengthOfStringForCheckCharacterPairMustBeLessThanOrEqualTo: "Length {{length, number}} of string for check character pair must be less than or equal to {{maximumLength, number}}"
     },
-    IdentificationKey: {
-        identificationKeyTypeLength: "{{identificationKeyType}} must be {{length, number}} digits long",
+    Identifier: {
+        identifierTypeLength: "{{identifierType}} must be {{length, number}} digits long",
         invalidCheckDigit: "Invalid check digit",
         invalidGTINLength: "GTIN must be 13, 12, 8, or 14 digits long",
         invalidGTIN14Length: "GTIN must be 14 digits long",
@@ -36,6 +36,6 @@ export const localeStrings = {
         gs1CompanyPrefixCantStartWith000000: "GS1 Company Prefix can't start with \"000000\"",
         upcCompanyPrefixCantStartWith0000: "U.P.C. Company Prefix can't start with \"0000\"",
         gs18PrefixCantStartWith0: "GS1-8 Prefix can't start with \"0\"",
-        identificationKeyTypeNotSupportedByGS18Prefix: "{{identificationKeyType}} not supported by GS1-8 Prefix"
+        identifierTypeNotSupportedByGS18Prefix: "{{identifierType}} not supported by GS1-8 Prefix"
     }
 } as const;

package/src/locale/fr/locale-strings.ts

@@ -4,8 +4,8 @@ export const localeStrings = {
         priceOrWeightComponent: "prix ou poids",
         lengthOfStringForCheckCharacterPairMustBeLessThanOrEqualTo: "La longueur {{length, number}} de la chaîne pour la paire de caractères de vérification doit être inférieure ou égale à {{maximum Length}}"
     },
-    IdentificationKey: {
-        identificationKeyTypeLength: "{{identificationKeyType}} doit comporter {{length, number}} chiffres",
+    Identifier: {
+        identifierTypeLength: "{{identifierType}} doit comporter {{length, number}} chiffres",
         invalidCheckDigit: "Chiffre de contrôle non valide",
         invalidGTINLength: "Le GTIN doit comporter 13, 12, 8 ou 14 chiffres",
         invalidGTIN14Length: "Le GTIN doit comporter 14 chiffres",
@@ -36,6 +36,6 @@ export const localeStrings = {
         gs1CompanyPrefixCantStartWith000000: "Le préfixe de l'entreprise GS1 ne peut pas commencer par \"000000\"",
         upcCompanyPrefixCantStartWith0000: "Le préfixe de l'entreprise U.P.C. ne peut pas commencer par \"0000\"",
         gs18PrefixCantStartWith0: "Le préfixe GS1-8 ne peut pas commencer par \"0\"",
-        identificationKeyTypeNotSupportedByGS18Prefix: "{{identificationKeyType}} non pris en charge par le préfixe GS1-8"
+        identifierTypeNotSupportedByGS18Prefix: "{{identifierType}} non pris en charge par le préfixe GS1-8"
     }
 } as const;

package/src/non-gtin-numeric-identifier-creator.ts

@@ -0,0 +1,33 @@
+import { Mixin } from "ts-mixer";
+import type { IdentifierType } from "./identifier-type.js";
+import { NonGTINNumericIdentifierValidator } from "./non-gtin-numeric-identifier-validator.js";
+import { AbstractNumericIdentifierCreator } from "./numeric-identifier-creator.js";
+import { type LeaderType, LeaderTypes } from "./numeric-identifier-validator.js";
+import type { PrefixProvider } from "./prefix-provider";
+
+/**
+ * Non-GTIN numeric identifier creator.
+ */
+export class NonGTINNumericIdentifierCreator extends Mixin(NonGTINNumericIdentifierValidator, AbstractNumericIdentifierCreator) {
+    /**
+     * Constructor. Typically called internally by a prefix manager but may be called by other code with another prefix
+     * provider type.
+     *
+     * @param prefixProvider
+     * Prefix provider.
+     *
+     * @param identifierType
+     * Identifier type.
+     *
+     * @param length
+     * Length.
+     *
+     * @param leaderType
+     * Leader type.
+     */
+    constructor(prefixProvider: PrefixProvider, identifierType: IdentifierType, length: number, leaderType: LeaderType = LeaderTypes.None) {
+        super(identifierType, length, leaderType);
+
+        this.init(prefixProvider, prefixProvider.gs1CompanyPrefix);
+    }
+}

package/src/non-gtin-numeric-identifier-validator.ts

@@ -0,0 +1,54 @@
+import { type IdentifierType, IdentifierTypes } from "./identifier-type.js";
+import {
+    AbstractNumericIdentifierValidator,
+    type LeaderType,
+    LeaderTypes,
+    type NumericIdentifierType
+} from "./numeric-identifier-validator.js";
+import { PrefixTypes } from "./prefix-type.js";
+
+/**
+ * Non-GTIN numeric identifier type.
+ */
+export type NonGTINNumericIdentifierType = Exclude<NumericIdentifierType, typeof IdentifierTypes.GTIN>;
+
+/**
+ * Non-GTIN numeric identifier validator.
+ */
+export class NonGTINNumericIdentifierValidator extends AbstractNumericIdentifierValidator {
+    /**
+     * Constructor.
+     *
+     * @param identifierType
+     * Identifier type.
+     *
+     * @param length
+     * Length.
+     *
+     * @param leaderType
+     * Leader type.
+     */
+    constructor(identifierType: IdentifierType, length: number, leaderType: LeaderType = LeaderTypes.None) {
+        super(identifierType, PrefixTypes.GS1CompanyPrefix, length, leaderType);
+    }
+}
+
+/**
+ * GLN validator.
+ */
+export const GLN_VALIDATOR = new NonGTINNumericIdentifierValidator(IdentifierTypes.GLN, 13);
+
+/**
+ * SSCC validator.
+ */
+export const SSCC_VALIDATOR = new NonGTINNumericIdentifierValidator(IdentifierTypes.SSCC, 18, LeaderTypes.ExtensionDigit);
+
+/**
+ * GSRN validator.
+ */
+export const GSRN_VALIDATOR = new NonGTINNumericIdentifierValidator(IdentifierTypes.GSRN, 18);
+
+/**
+ * GSIN validator.
+ */
+export const GSIN_VALIDATOR = new NonGTINNumericIdentifierValidator(IdentifierTypes.GSIN, 17);

package/src/non-numeric-identifier-creator.ts

@@ -0,0 +1,111 @@
+import {
+    type CharacterSetValidation,
+    mapIterable,
+    type TransformerInput,
+    type TransformerOutput
+} from "@aidc-toolkit/utility";
+import { Mixin } from "ts-mixer";
+import { checkCharacterPair } from "./check.js";
+import { AbstractIdentifierCreator } from "./identifier-creator.js";
+import type { IdentifierType } from "./identifier-type.js";
+import type { ContentCharacterSet } from "./identifier-validator.js";
+import { i18nextGS1 } from "./locale/i18n.js";
+import { NonNumericIdentifierValidator } from "./non-numeric-identifier-validator.js";
+import type { PrefixProvider } from "./prefix-provider";
+
+/**
+ * Non-numeric identifier creator.
+ */
+export class NonNumericIdentifierCreator extends Mixin(NonNumericIdentifierValidator, AbstractIdentifierCreator) {
+    /**
+     * Reference validation parameters.
+     */
+    private readonly _referenceValidation: CharacterSetValidation;
+
+    /**
+     * Constructor. Typically called internally by a prefix manager but may be called by other code with another prefix
+     * provider type.
+     *
+     * @param prefixProvider
+     * Prefix provider.
+     *
+     * @param identifierType
+     * Identifier type.
+     *
+     * @param length
+     * Length.
+     *
+     * @param referenceCharacterSet
+     * Reference character set.
+     *
+     * @param requiresCheckCharacterPair
+     * True if the identifier requires a check character pair.
+     */
+    constructor(prefixProvider: PrefixProvider, identifierType: IdentifierType, length: number, referenceCharacterSet: ContentCharacterSet, requiresCheckCharacterPair = false) {
+        super(identifierType, length, referenceCharacterSet, requiresCheckCharacterPair);
+
+        this.init(prefixProvider, prefixProvider.gs1CompanyPrefix, 2 * Number(requiresCheckCharacterPair));
+
+        this._referenceValidation = {
+            minimumLength: 1,
+            // Maximum reference length has to account for prefix and check character pair.
+            maximumLength: this.referenceLength,
+            component: () => i18nextGS1.t("Identifier.reference")
+        };
+    }
+
+    /**
+     * Get the reference validation parameters.
+     */
+    protected get referenceValidation(): CharacterSetValidation {
+        return this._referenceValidation;
+    }
+
+    /**
+     * Create identifier(s) with reference(s).
+     *
+     * @template TTransformerInput
+     * Transformer input type.
+     *
+     * @param referenceOrReferences
+     * Reference(s).
+     *
+     * @returns
+     * Identifier(s).
+     */
+    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>;
+
+        const referenceCreator = this.referenceCreator;
+        const referenceValidation = this.referenceValidation;
+        const prefix = this.prefix;
+        const requiresCheckCharacterPair = this.requiresCheckCharacterPair;
+
+        /**
+         * Validate a reference and create an identifier.
+         *
+         * @param reference
+         * Reference.
+         *
+         * @returns
+         * Identifier.
+         */
+        function validateAndCreate(reference: string): string {
+            referenceCreator.validate(reference, referenceValidation);
+
+            const partialIdentifier = prefix + reference;
+
+            return requiresCheckCharacterPair ? partialIdentifier + checkCharacterPair(partialIdentifier) : partialIdentifier;
+        }
+
+        if (typeof referenceOrReferences !== "object") {
+            result = validateAndCreate(referenceOrReferences);
+        } else {
+            result = mapIterable(referenceOrReferences, validateAndCreate);
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type determination is handled above.
+        return result as TransformerOutput<TTransformerInput, string>;
+    }
+}

package/src/non-numeric-identifier-validator.ts

@@ -0,0 +1,128 @@
+import { Exclusions, RegExpValidator } from "@aidc-toolkit/utility";
+import { hasValidCheckCharacterPair } from "./check.js";
+import { type IdentifierType, IdentifierTypes } from "./identifier-type.js";
+import {
+    AbstractIdentifierValidator,
+    type ContentCharacterSet,
+    ContentCharacterSets,
+    type IdentifierValidation
+} from "./identifier-validator.js";
+import { i18nextGS1 } from "./locale/i18n.js";
+import type { NumericIdentifierType } from "./numeric-identifier-validator.js";
+import { PrefixTypes } from "./prefix-type.js";
+
+/**
+ * Non-numeric identifier type.
+ */
+export type NonNumericIdentifierType = Exclude<IdentifierType, NumericIdentifierType>;
+
+/**
+ * Non-numeric identifier validation parameters.
+ */
+export interface NonNumericIdentifierValidation extends IdentifierValidation {
+    /**
+     * Exclusion support for reference. Prevents non-numeric identifier from being mistaken for numeric
+     * identifier.
+     */
+    exclusion?: typeof Exclusions.None | typeof Exclusions.AllNumeric | undefined;
+}
+
+/**
+ * Non-numeric identifier validator.
+ */
+export class NonNumericIdentifierValidator extends AbstractIdentifierValidator<NonNumericIdentifierValidation> {
+    /**
+     * Validator to ensure that an identifier (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 i18nextGS1.t("Identifier.referenceCantBeAllNumeric");
+        }
+    }(/\D/);
+
+    /**
+     * True if the identifier requires a check character pair.
+     */
+    private readonly _requiresCheckCharacterPair: boolean;
+
+    /**
+     * Constructor.
+     *
+     * @param identifierType
+     * Identifier type.
+     *
+     * @param length
+     * Length.
+     *
+     * @param referenceCharacterSet
+     * Reference character set.
+     *
+     * @param requiresCheckCharacterPair
+     * True if the identifier requires a check character pair.
+     */
+    constructor(identifierType: IdentifierType, length: number, referenceCharacterSet: ContentCharacterSet, requiresCheckCharacterPair = false) {
+        super(identifierType, PrefixTypes.GS1CompanyPrefix, length, referenceCharacterSet);
+
+        this._requiresCheckCharacterPair = requiresCheckCharacterPair;
+    }
+
+    /**
+     * Determine if the identifier requires a check character pair.
+     */
+    get requiresCheckCharacterPair(): boolean {
+        return this._requiresCheckCharacterPair;
+    }
+
+    /**
+     * Validate a non-numeric identifier and throw an error if validation fails.
+     *
+     * @param identifier
+     * Identifier.
+     *
+     * @param validation
+     * Validation parameters.
+     */
+    validate(identifier: string, validation?: NonNumericIdentifierValidation): void {
+        const partialIdentifier = this.requiresCheckCharacterPair ? identifier.substring(0, identifier.length - 2) : identifier;
+
+        super.validatePrefix(partialIdentifier, validation?.positionOffset);
+
+        if (!this.requiresCheckCharacterPair) {
+            this.referenceCreator.validate(identifier, {
+                maximumLength: this.length,
+                positionOffset: validation?.positionOffset
+            });
+            // Validating the check character pair will also validate the characters.
+        } else if (!hasValidCheckCharacterPair(this.padIdentifier(identifier, validation))) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidCheckCharacterPair"));
+        }
+
+        // Check for all-numeric identifier (minus check character pair) if excluded.
+        if (validation?.exclusion === Exclusions.AllNumeric) {
+            NonNumericIdentifierValidator.NOT_ALL_NUMERIC_VALIDATOR.validate(partialIdentifier);
+        }
+    }
+}
+
+/**
+ * GIAI validator.
+ */
+export const GIAI_VALIDATOR = new NonNumericIdentifierValidator(IdentifierTypes.GIAI, 30, ContentCharacterSets.AI82);
+
+/**
+ * GINC validator.
+ */
+export const GINC_VALIDATOR = new NonNumericIdentifierValidator(IdentifierTypes.GINC, 30, ContentCharacterSets.AI82);
+
+/**
+ * CPID validator.
+ */
+export const CPID_VALIDATOR = new NonNumericIdentifierValidator(IdentifierTypes.CPID, 30, ContentCharacterSets.AI39);
+
+/**
+ * GMN validator.
+ */
+export const GMN_VALIDATOR = new NonNumericIdentifierValidator(IdentifierTypes.GMN, 25, ContentCharacterSets.AI82, true);