@aidc-toolkit/gs1 1.0.28-beta → 1.0.32-beta

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/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);