@aidc-toolkit/gs1 1.0.31-beta → 1.0.33-beta

package/src/prefix-validator.ts

@@ -2,6 +2,7 @@ import { type CharacterSetValidation, NUMERIC_CREATOR } from "@aidc-toolkit/util
 import { i18nextGS1 } from "./locale/i18n.js";
 import type { PrefixProvider } from "./prefix-provider.js";
 import { type PrefixType, PrefixTypes } from "./prefix-type.js";
+import type { ParseKeys } from "i18next";
 
 /**
  * Prefix validation parameters.
@@ -36,7 +37,7 @@ const GS1_COMPANY_PREFIX_MAXIMUM_LENGTH = 12;
 /**
  * U.P.C. Company Prefix minimum length.
  */
-const UPC_COMPANY_PREFIX_MINIMUM_LENGTH = 6;
+const UPC_COMPANY_PREFIX_MINIMUM_LENGTH = 5;
 
 /**
  * U.P.C. Company Prefix maximum length.
@@ -130,31 +131,31 @@ export const PrefixValidator = {
      * @param isNumericIdentifier
      * If true, the prefix is from a numeric identifier and its character set will be validated by the caller.
      *
-     * @param positionOffset
-     * Position offset within a larger string.
+     * @param errorMessageParseKey
+     * Parse key for error message when validating GS1 Company Prefix type.
      */
-    validate(prefixType: PrefixType, allowUPCCompanyPrefix: boolean, allowGS18Prefix: boolean, prefix: string, isFromIdentifier = false, isNumericIdentifier = false, positionOffset?: number): void {
-        let baseValidation: PrefixValidation;
+    validate(prefixType: PrefixType, allowUPCCompanyPrefix: boolean, allowGS18Prefix: boolean, prefix: string, isFromIdentifier = false, isNumericIdentifier = false, errorMessageParseKey?: ParseKeys): void {
+        let validation: PrefixValidation;
 
         // Validate the prefix type and determine the prefix validation parameters.
         switch (prefixType) {
             case PrefixTypes.GS1CompanyPrefix:
                 if (!prefix.startsWith("0")) {
-                    baseValidation = GS1_COMPANY_PREFIX_VALIDATION;
+                    validation = GS1_COMPANY_PREFIX_VALIDATION;
                 } else if (!prefix.startsWith("00000")) {
                     if (!allowUPCCompanyPrefix) {
-                        throw new RangeError(i18nextGS1.t("Prefix.gs1CompanyPrefixCantStartWith0"));
+                        throw new RangeError(i18nextGS1.t(errorMessageParseKey ?? "Prefix.gs1CompanyPrefixCantStartWith0"));
                     }
 
-                    baseValidation = UPC_COMPANY_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION;
+                    validation = UPC_COMPANY_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION;
                 } else if (!prefix.startsWith("000000")) {
                     if (!allowGS18Prefix) {
-                        throw new RangeError(i18nextGS1.t("Prefix.gs1CompanyPrefixCantStartWith00000"));
+                        throw new RangeError(i18nextGS1.t(errorMessageParseKey ?? "Prefix.gs1CompanyPrefixCantStartWith00000"));
                     }
 
-                    baseValidation = GS1_8_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION;
+                    validation = GS1_8_PREFIX_AS_GS1_COMPANY_PREFIX_VALIDATION;
                 } else {
-                    throw new RangeError(i18nextGS1.t("Prefix.gs1CompanyPrefixCantStartWith000000"));
+                    throw new RangeError(i18nextGS1.t(errorMessageParseKey ?? "Prefix.gs1CompanyPrefixCantStartWith000000"));
                 }
                 break;
 
@@ -163,7 +164,7 @@ export const PrefixValidator = {
                     throw new RangeError(i18nextGS1.t("Prefix.upcCompanyPrefixCantStartWith0000"));
                 }
 
-                baseValidation = UPC_COMPANY_PREFIX_VALIDATION;
+                validation = UPC_COMPANY_PREFIX_VALIDATION;
                 break;
 
             case PrefixTypes.GS18Prefix:
@@ -171,21 +172,16 @@ export const PrefixValidator = {
                     throw new RangeError(i18nextGS1.t("Prefix.gs18PrefixCantStartWith0"));
                 }
 
-                baseValidation = GS1_8_PREFIX_VALIDATION;
+                validation = GS1_8_PREFIX_VALIDATION;
                 break;
         }
 
-        const mergedValidation: PrefixValidation = {
-            ...baseValidation,
-            positionOffset
-        };
-
-        // If from key and numeric, key validation will take care of character set validation.
+        // If from identifier and numeric, identifier validation will take care of character set validation.
         if (!isFromIdentifier) {
-            NUMERIC_CREATOR.validate(prefix, mergedValidation);
+            NUMERIC_CREATOR.validate(prefix, validation);
         } else if (!isNumericIdentifier) {
             // Validate only the minimum length, allowing at least one character for the (possibly non-numeric) reference.
-            NUMERIC_CREATOR.validate(prefix.substring(0, Math.min(mergedValidation.minimumLength, prefix.length - 1)), mergedValidation);
+            NUMERIC_CREATOR.validate(prefix.substring(0, Math.min(validation.minimumLength, prefix.length - 1)), validation);
         }
     },
 
@@ -214,11 +210,11 @@ export const PrefixValidator = {
                 break;
 
             case PrefixTypes.UPCCompanyPrefix:
-                gs1CompanyPrefix = "0" + prefix;
+                gs1CompanyPrefix = `0${prefix}`;
                 break;
 
             case PrefixTypes.GS18Prefix:
-                gs1CompanyPrefix = "00000" + prefix;
+                gs1CompanyPrefix = `00000${prefix}`;
                 break;
         }
 

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

@@ -8,6 +8,21 @@ import { NonGTINNumericIdentifierValidator } from "./non-gtin-numeric-identifier
 import type { SerializableNumericIdentifierDescriptor } from "./serializable-numeric-identifier-descriptor.js";
 import type { SerializableNumericIdentifierType } from "./serializable-numeric-identifier-type.js";
 
+/**
+ * Serializable numeric identifier split.
+ */
+export interface SerializableNumericIdentifierSplit {
+    /**
+     * Base identifier.
+     */
+    baseIdentifier: string;
+
+    /**
+     * Serial component.
+     */
+    serialComponent: string;
+}
+
 /**
  * Serializable numeric identifier validator. Validates both serialized and non-serialized forms of numeric identifiers
  * that support serialization.
@@ -94,4 +109,25 @@ export class SerializableNumericIdentifierValidator extends NonGTINNumericIdenti
             this.serialComponentCreator.validate(identifier.substring(this.length), this.#serialComponentValidation);
         }
     }
+
+    /**
+     * Split a serializable numeric identifier into its component parts.
+     *
+     * @param identifier
+     * Identifier.
+     *
+     * @param validation
+     * Identifier validation parameters.
+     *
+     * @returns
+     * Base identifier and serial component (possibly empty) as object.
+     */
+    split(identifier: string, validation?: IdentifierValidation): SerializableNumericIdentifierSplit {
+        this.validate(identifier, validation);
+
+        return {
+            baseIdentifier: identifier.substring(0, this.length),
+            serialComponent: identifier.substring(this.length)
+        };
+    }
 }

package/src/variable-measure.ts

@@ -0,0 +1,268 @@
+import { NUMERIC_CREATOR } from "@aidc-toolkit/utility";
+import { checkDigit, hasValidCheckDigit, isValidPriceOrWeightCheckDigit, priceOrWeightCheckDigit } from "./check.js";
+import { i18nextGS1 } from "./locale/i18n.js";
+
+/**
+ * Restricted Circulation Number reference.
+ */
+export interface RCNReference {
+    /**
+     * Item reference.
+     */
+    itemReference: number;
+
+    /**
+     * Price or weight (whole number only).
+     */
+    priceOrWeight: number;
+}
+
+/**
+ * Variable measure trade item support functions.
+ */
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class -- Wrapper for future functionality.
+export class VariableMeasure {
+    /**
+     * Parse a Restricted Circulation Number (RCN) using a variable measure trade item format. The format is a 12- or
+     * 13-character string (for RCN-12 or RCN-13 respectively), containing the following:
+     *
+     * - '2' - The first character of the RCN.
+     * - '0'-'9' - The second character of the RCN (RCN-13 only).
+     * - 'I' - One or more, in sequence, for the item reference.
+     * - 'P' - One or more, in sequence, for the price or weight.
+     * - 'V' - Zero or one, for the price or weight check digit.
+     * - 'C' - The check digit of the entire RCN.
+     *
+     * The 'I', 'P', and 'V' formats may be in any order.
+     *
+     * Some examples:
+     *
+     * - `2IIIIIVPPPPC` - RCN-12 with a five-digit item reference, a price or weight check digit, and a four-digit price
+     * or weight.
+     * - `23IIIIVPPPPPC` - RCN-13 with a four-digit item reference, a price or weight check digit, and a five-digit price
+     * or weight.
+     * - `2IIIIIIPPPPC` - RCN-12 with a six-digit item reference and a four-digit price or eight.
+     * - `29IIIIIPPPPPC` - RCN-13 with a five-digit item reference and a five-digit price or weight.
+     *
+     * @param format
+     * Format.
+     *
+     * @param rcn
+     * RCN.
+     *
+     * @returns
+     * RCN reference.
+     */
+    static parseRCN(format: string, rcn: string): RCNReference {
+        const formatLength = format.length;
+
+        if (rcn.length !== formatLength) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidRCNLength"));
+        }
+
+        let validFormat = formatLength === 12 || formatLength === 13;
+        let validRCNPrefix = true;
+
+        let buildingItemReference = false;
+        let itemReference = "";
+
+        let buildingPriceOrWeight = false;
+        let priceOrWeight = "";
+
+        let priceOrWeightCheckDigit = "";
+
+        for (let index = 0; validFormat && index < formatLength; index++) {
+            const formatChar = format.charAt(index);
+            const rcnChar = rcn.charAt(index);
+
+            if (index === 0) {
+                validFormat = formatChar === "2";
+                validRCNPrefix = rcnChar === "2";
+            } else if (formatLength === 13 && index === 1) {
+                validFormat = NUMERIC_CREATOR.characterIndex(formatChar) !== undefined;
+                validRCNPrefix = rcnChar === formatChar;
+            } else if (index === formatLength - 1) {
+                validFormat = formatChar === "C";
+            } else {
+                switch (formatChar) {
+                    case "I":
+                        if (!buildingItemReference) {
+                            // Item reference can't appear more than once.
+                            validFormat = itemReference === "";
+
+                            buildingItemReference = true;
+                            buildingPriceOrWeight = false;
+                        }
+
+                        itemReference += rcnChar;
+                        break;
+
+                    case "P":
+                        if (!buildingPriceOrWeight) {
+                            // Price or weight can't appear more than once.
+                            validFormat = priceOrWeight === "";
+
+                            buildingPriceOrWeight = true;
+                            buildingItemReference = false;
+                        }
+
+                        priceOrWeight += rcnChar;
+                        break;
+
+                    case "V":
+                        // Price or weight check digit can't appear more than once.
+                        validFormat = priceOrWeightCheckDigit === "";
+
+                        buildingItemReference = false;
+                        buildingPriceOrWeight = false;
+
+                        priceOrWeightCheckDigit = rcnChar;
+                        break;
+
+                    default:
+                        validFormat = false;
+                        break;
+                }
+            }
+        }
+
+        validFormat &&= itemReference !== "" && priceOrWeight !== "";
+
+        if (!validFormat) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidVariableMeasureRCNFormat"));
+        }
+
+        if (!validRCNPrefix) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidVariableMeasureRCNPrefix"));
+        }
+
+        if (priceOrWeightCheckDigit !== "" && !isValidPriceOrWeightCheckDigit(priceOrWeight, priceOrWeightCheckDigit)) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidVariableMeasurePriceOrWeight"));
+        }
+
+        if (!hasValidCheckDigit(rcn)) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidCheckDigit"));
+        }
+
+        return {
+            itemReference: Number(itemReference),
+            priceOrWeight: Number(priceOrWeight)
+        };
+    }
+
+    /**
+     * Create a Restricted Circulation Number (RCN) using a variable measure trade item format. See {@linkcode parseRCN}
+     * for format details.
+     *
+     * @param format
+     * Format.
+     *
+     * @param itemReference
+     * Item reference.
+     *
+     * @param priceOrWeight
+     * Price or weight (whole number only).
+     *
+     * @returns
+     * RCN-12 or RCN-13.
+     */
+    static createRCN(format: string, itemReference: number, priceOrWeight: number): string {
+        const formatLength = format.length;
+
+        let validFormat = formatLength === 12 || formatLength === 13;
+
+        let rcnPrefix = "";
+
+        let buildingItemReference = false;
+        let itemReferenceString = "";
+        let itemReferenceLength = 0;
+
+        let buildingPriceOrWeight = false;
+        let priceOrWeightString = "";
+        let priceOrWeightLength = 0;
+
+        let calculatePriceOrWeightCheckDigit = false;
+
+        // RCN may be built in almost any order, so defer to builders that will be in ordered array.
+        const rcnPrefixBuilder = (partialRCN: string): string => partialRCN + rcnPrefix;
+        const itemReferenceBuilder = (partialRCN: string): string => partialRCN + itemReferenceString;
+        const priceOrWeightBuilder = (partialRCN: string): string => partialRCN + priceOrWeightString;
+        const priceOrWeightCheckDigitBuilder = (partialRCN: string): string => partialRCN + priceOrWeightCheckDigit(priceOrWeightString);
+        const checkDigitBuilder = (partialRCN: string): string => partialRCN + checkDigit(partialRCN);
+
+        const rcnBuilders = [rcnPrefixBuilder];
+
+        for (let index = 0; validFormat && index < formatLength; index++) {
+            const formatChar = format.charAt(index);
+
+            if (index === 0) {
+                validFormat = formatChar === "2";
+                rcnPrefix = formatChar;
+            } else if (formatLength === 13 && index === 1) {
+                validFormat = NUMERIC_CREATOR.characterIndex(formatChar) !== undefined;
+                rcnPrefix += formatChar;
+            } else if (index === formatLength - 1) {
+                validFormat = formatChar === "C";
+            } else {
+                switch (formatChar) {
+                    case "I":
+                        if (!buildingItemReference) {
+                            // Item reference can't appear more than once.
+                            validFormat = itemReferenceLength === 0;
+
+                            buildingItemReference = true;
+                            buildingPriceOrWeight = false;
+
+                            rcnBuilders.push(itemReferenceBuilder);
+                        }
+
+                        itemReferenceLength++;
+                        break;
+
+                    case "P":
+                        if (!buildingPriceOrWeight) {
+                            // Price or weight can't appear more than once.
+                            validFormat = priceOrWeightLength === 0;
+
+                            buildingPriceOrWeight = true;
+                            buildingItemReference = false;
+
+                            rcnBuilders.push(priceOrWeightBuilder);
+                        }
+
+                        priceOrWeightLength++;
+                        break;
+
+                    case "V":
+                        // Price or weight check digit can't appear more than once.
+                        validFormat = !calculatePriceOrWeightCheckDigit;
+
+                        buildingItemReference = false;
+                        buildingPriceOrWeight = false;
+
+                        calculatePriceOrWeightCheckDigit = true;
+
+                        rcnBuilders.push(priceOrWeightCheckDigitBuilder);
+                        break;
+
+                    default:
+                        validFormat = false;
+                        break;
+                }
+            }
+        }
+
+        validFormat &&= itemReferenceLength !== 0 && priceOrWeightLength !== 0;
+
+        if (!validFormat) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidVariableMeasureRCNFormat"));
+        }
+
+        itemReferenceString = NUMERIC_CREATOR.create(itemReferenceLength, itemReference);
+        priceOrWeightString = NUMERIC_CREATOR.create(priceOrWeightLength, priceOrWeight);
+
+        rcnBuilders.push(checkDigitBuilder);
+
+        return rcnBuilders.reduce((partialRCN, rcnBuilder) => rcnBuilder(partialRCN), "");
+    }
+}

package/src/verified-by-gs1.ts

@@ -0,0 +1,54 @@
+import type { Hyperlink } from "@aidc-toolkit/core";
+import { GTINValidator } from "./gtin-validator.js";
+import { type IdentifierType, IdentifierTypes } from "./identifier-type.js";
+import { IdentifierValidators } from "./identifier-validators.js";
+
+const VERIFIED_BY_GS1_REFERENCE_BASE = "https://www.gs1.org/services/verified-by-gs1/results?";
+
+/**
+ * Create a Verified by GS1 hyperlink.
+ *
+ * @param identifierType
+ * Identifier type.
+ *
+ * @param identifier
+ * Identifier.
+ *
+ * @param text
+ * Text for hyperlink. If not provided, the identifier is used.
+ *
+ * @param details
+ * Details to display when hovering over hyperlink.
+ *
+ * @returns
+ * Verified by GS1 hyperlink.
+ */
+// eslint-disable-next-line @typescript-eslint/no-useless-default-assignment -- Undefined is necessary to allow bypass of text.
+export function verifiedByGS1(identifierType: IdentifierType, identifier: string, text: string | undefined = undefined, details?: string): Hyperlink {
+    let normalizedIdentifier: string;
+    let useKeyTypeParameter: boolean;
+
+    if (identifierType === IdentifierTypes.GTIN) {
+        // Normalization will validate resulting GTIN.
+        normalizedIdentifier = GTINValidator.normalize(identifier);
+
+        useKeyTypeParameter = true;
+    } else {
+        const identifierValidator = IdentifierValidators[identifierType];
+
+        identifierValidator.validate(identifier);
+
+        normalizedIdentifier = identifier;
+        useKeyTypeParameter = identifierType === IdentifierTypes.GLN;
+    }
+
+    const lowerCaseIdentifierType = identifierType.toLowerCase();
+
+    const reference = useKeyTypeParameter ? `${VERIFIED_BY_GS1_REFERENCE_BASE}${lowerCaseIdentifierType}=${normalizedIdentifier}` : `${VERIFIED_BY_GS1_REFERENCE_BASE}key=${normalizedIdentifier}&key_type=${lowerCaseIdentifierType}`;
+
+    return {
+        reference,
+        text: text ?? identifier,
+        details
+    };
+}

package/test/character-set.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import { AI64_VALIDATOR } from "../src/index.js";
+
+describe("AI 64 character set validator", () => {
+    test("Character set", () => {
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz");
+        }).not.toThrow(RangeError);
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxy");
+        }).toThrow("Length 63 must be a multiple of 4");
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwx");
+        }).toThrow("Length 62 must be a multiple of 4");
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvw");
+        }).toThrow("Length 61 must be a multiple of 4");
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyzABC=");
+        }).not.toThrow(RangeError);
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyzAB==");
+        }).not.toThrow(RangeError);
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyzA===");
+        }).toThrow("Invalid character '=' at position 65");
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz====");
+        }).toThrow("Invalid character '=' at position 64");
+
+        expect(() => {
+            AI64_VALIDATOR.validate("=-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxy");
+        }).toThrow("Invalid character '=' at position 0");
+
+        expect(() => {
+            AI64_VALIDATOR.validate("-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ=_abcdefghijklmnopqrstuvwxy");
+        }).toThrow("Invalid character '=' at position 37");
+    });
+});

package/test/creator.test.ts

@@ -1,7 +1,7 @@
 import { describe } from "vitest";
 import { PrefixManager, PrefixTypes } from "../src/index.js";
 import { testGTINCreator } from "./gtin-creator.js";
-import { testNonGTINNumericIdentifierCreator } from "./non-gtin-numeric-identifier-creator.js";
+import { testNonSerializableNumericIdentifierCreator } from "./non-serializable-numeric-identifier-creator.js";
 import { testNonNumericIdentifierCreator } from "./non-numeric-identifier-creator.js";
 import { testSerializableNumericIdentifierCreator } from "./serializable-numeric-identifier-creator.js";
 
@@ -14,14 +14,14 @@ describe("Creators", () => {
     const shortPrefixManager = PrefixManager.get(PrefixTypes.GS1CompanyPrefix, "952123456");
     const longPrefixManager = PrefixManager.get(PrefixTypes.GS1CompanyPrefix, "952123456789");
 
-    testNonGTINNumericIdentifierCreator(shortPrefixManager.glnCreator);
-    testNonGTINNumericIdentifierCreator(longPrefixManager.ssccCreator);
+    testNonSerializableNumericIdentifierCreator(shortPrefixManager.glnCreator);
+    testNonSerializableNumericIdentifierCreator(longPrefixManager.ssccCreator);
     testSerializableNumericIdentifierCreator(shortPrefixManager.graiCreator);
     testNonNumericIdentifierCreator(shortPrefixManager.giaiCreator);
-    testNonGTINNumericIdentifierCreator(longPrefixManager.gsrnCreator);
+    testNonSerializableNumericIdentifierCreator(longPrefixManager.gsrnCreator);
     testSerializableNumericIdentifierCreator(shortPrefixManager.gdtiCreator);
     testNonNumericIdentifierCreator(shortPrefixManager.gincCreator);
-    testNonGTINNumericIdentifierCreator(longPrefixManager.gsinCreator);
+    testNonSerializableNumericIdentifierCreator(longPrefixManager.gsinCreator);
     testSerializableNumericIdentifierCreator(shortPrefixManager.gcnCreator);
     testNonNumericIdentifierCreator(shortPrefixManager.cpidCreator);
     testNonNumericIdentifierCreator(shortPrefixManager.gmnCreator);