@aidc-toolkit/gs1 0.9.18-beta → 0.9.19-beta

package/src/idkey.ts

@@ -2,13 +2,13 @@ import {
     CharacterSetCreator,
     type CharacterSetValidation,
     Exclusion,
+    mapIterable,
     NUMERIC_CREATOR,
     RegExpValidator,
     type StringValidation,
     type StringValidator,
     type TransformerInput,
-    type TransformerOutput,
-    mapIterable
+    type TransformerOutput
 } from "@aidc-toolkit/utility";
 import { Mixin } from "ts-mixer";
 import { AI39_CREATOR, AI82_CREATOR } from "./character-set.js";
@@ -17,7 +17,9 @@ import {
     checkDigit,
     checkDigitSum,
     hasValidCheckCharacterPair,
-    hasValidCheckDigit
+    hasValidCheckDigit,
+    isValidPriceOrWeightCheckDigit,
+    priceOrWeightCheckDigit
 } from "./check.js";
 import { i18nextGS1 } from "./locale/i18n.js";
 
@@ -470,6 +472,21 @@ export enum GTINLevel {
     OtherThanRetailConsumer
 }
 
+/**
+ * Restricted Circulation Number reference.
+ */
+export interface RCNReference {
+    /**
+     * Item reference.
+     */
+    itemReference: number;
+
+    /**
+     * Price or weight (whole number only).
+     */
+    priceOrWeight: number;
+}
+
 /**
  * GTIN validator.
  */
@@ -632,10 +649,8 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
 
         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;
+        let gtin14 = gtin.padStart(GTINType.GTIN14, "0");
 
         // If indicator digit provided and is different, recalculate the check digit.
         if (indicatorDigit.length !== 0 && indicatorDigit !== gtin14.charAt(0)) {
@@ -805,6 +820,134 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
 
         GTINCreator.validateAny(gtin14);
     }
+
+    /**
+     * 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 parseVariableMeasureRCN(format: string, rcn: string): RCNReference {
+        const formatLength = format.length;
+
+        if (rcn.length !== formatLength) {
+            throw new RangeError(i18nextGS1.t("IdentificationKey.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("IdentificationKey.invalidVariableMeasureRCNFormat"));
+        }
+
+        if (!validRCNPrefix) {
+            throw new RangeError(i18nextGS1.t("IdentificationKey.invalidVariableMeasureRCNPrefix"));
+        }
+
+        if (priceOrWeightCheckDigit !== "" && !isValidPriceOrWeightCheckDigit(priceOrWeight, priceOrWeightCheckDigit)) {
+            throw new RangeError(i18nextGS1.t("IdentificationKey.invalidVariableMeasurePriceOrWeight"));
+        }
+
+        if (!hasValidCheckDigit(rcn)) {
+            throw new RangeError(i18nextGS1.t("IdentificationKey.invalidCheckDigit"));
+        }
+
+        return {
+            itemReference: Number(itemReference),
+            priceOrWeight: Number(priceOrWeight)
+        };
+    }
 }
 
 /**
@@ -1225,7 +1368,8 @@ export interface NumericIdentificationKeyCreator extends NumericIdentificationKe
 }
 
 /**
- * Abstract numeric identification key creator. Implements common functionality for a numeric identification key creator.
+ * Abstract numeric identification key creator. Implements common functionality for a numeric identification key
+ * creator.
  */
 abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentificationKeyCreator implements NumericIdentificationKeyCreator {
     /**
@@ -1435,6 +1579,122 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
             return partialIdentificationKey + checkDigit(partialIdentificationKey);
         });
     }
+
+    /**
+     * Create a Restricted Circulation Number (RCN) using a variable measure trade item format. See {@linkcode
+     * GTINValidator.parseVariableMeasureRCN} 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 createVariableMeasureRCN(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("IdentificationKey.invalidVariableMeasureRCNFormat"));
+        }
+
+        itemReferenceString = NUMERIC_CREATOR.create(itemReferenceLength, itemReference);
+        priceOrWeightString = NUMERIC_CREATOR.create(priceOrWeightLength, priceOrWeight);
+
+        rcnBuilders.push(checkDigitBuilder);
+
+        return rcnBuilders.reduce((partialRCN, rcnBuilder) => rcnBuilder(partialRCN), "");
+    }
 }
 
 /**
@@ -1934,7 +2194,7 @@ export class PrefixManager {
 
         // Creator tweak factor is defined for numeric identification keys only.
         if (creatorTweakFactor !== undefined) {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Explicit cast without testing is necessary as "instanceof" doesn't work for mixin types.
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion,no-param-reassign -- Explicit cast without testing is necessary as "instanceof" doesn't work for mixin types. Method purpose is to set the tweak.
             (creator as AbstractNumericIdentificationKeyCreator).tweak = this.tweakFactor * creatorTweakFactor;
         }
     }
@@ -2110,7 +2370,7 @@ export class PrefixManager {
      */
     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 (TIdentificationKeyCreator | undefined);
+        let creator = this._identificationKeyCreatorsMap.get(identificationKeyType) as TIdentificationKeyCreator | undefined;
 
         if (creator === undefined) {
             if (this.prefixType === PrefixType.GS18Prefix && identificationKeyType !== IdentificationKeyType.GTIN) {

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

@@ -16,6 +16,10 @@ export const localeStrings = {
         invalidGTIN13AtRetail: "GTIN-13 at retail consumer trade item level can't start with zero",
         invalidGTINAtRetail: "GTIN not supported at retail consumer trade item level",
         invalidGTINAtOtherThanRetail: "GTIN not supported at other than retail consumer trade item level",
+        invalidRCNLength: "RCN length must match format length",
+        invalidVariableMeasureRCNFormat: "Invalid variable measure RCN format",
+        invalidVariableMeasureRCNPrefix: "Invalid variable measure RCN prefix",
+        invalidVariableMeasurePriceOrWeight: "Invalid variable measure price or weight",
         indicatorDigit: "indicator digit",
         serialComponent: "serial component",
         reference: "reference",

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

@@ -16,6 +16,10 @@ export const localeStrings = {
         invalidGTIN13AtRetail: "Le GTIN-13 au niveau des articles de consommation au détail ne peut pas commencer par zéro",
         invalidGTINAtRetail: "Le GTIN n'est pas pris en charge au niveau des articles de consommation au détail",
         invalidGTINAtOtherThanRetail: "Le GTIN n'est pas pris en charge à d'autres niveaux que ceux des articles de consommation au détail",
+        invalidRCNLength: "La longueur du RCN doit correspondre à la longueur du format",
+        invalidVariableMeasureRCNFormat: "Format RCN de mesure variable non valide",
+        invalidVariableMeasureRCNPrefix: "Préfixe RCN de mesure variable non valide",
+        invalidVariableMeasurePriceOrWeight: "Mesure variable invalide : prix ou poids",
         indicatorDigit: "chiffre indicateur",
         serialComponent: "composant série",
         reference: "référence",

package/src/locale/i18n.ts

@@ -1,6 +1,6 @@
-import { i18nAssertValidResources, i18nCoreInit, type I18NEnvironment } from "@aidc-toolkit/core";
+import { i18nAssertValidResources, i18nCoreInit, type I18nEnvironment } from "@aidc-toolkit/core";
 import { i18nUtilityInit, utilityResources } from "@aidc-toolkit/utility";
-import i18next, { type i18n } from "i18next";
+import i18next, { type i18n, type Resource } from "i18next";
 import { localeStrings as enLocaleStrings } from "./en/locale-strings.js";
 import { localeStrings as frLocaleStrings } from "./fr/locale-strings.js";
 
@@ -16,7 +16,7 @@ i18nAssertValidResources(enLocaleStrings, "fr", frLocaleStrings);
 /**
  * GS1 resources.
  */
-export const gs1Resources = {
+export const gs1Resources: Resource = {
     en: {
         aidct_gs1: enLocaleStrings
     },
@@ -40,7 +40,7 @@ export const i18nextGS1: i18n = i18next.createInstance();
  * @returns
  * Void promise.
  */
-export async function i18nGS1Init(environment: I18NEnvironment, debug = false): Promise<void> {
+export async function i18nGS1Init(environment: I18nEnvironment, debug = false): Promise<void> {
     await i18nUtilityInit(environment, debug);
     await i18nCoreInit(i18nextGS1, environment, debug, gs1NS, utilityResources, gs1Resources);
 }

package/test/check.test.ts

@@ -1,4 +1,4 @@
-import { I18NEnvironment } from "@aidc-toolkit/core";
+import { I18nEnvironment } from "@aidc-toolkit/core";
 import { NUMERIC_CREATOR } from "@aidc-toolkit/utility";
 import { describe, expect, test } from "vitest";
 import {
@@ -6,12 +6,13 @@ import {
     checkDigit,
     checkDigitSum,
     hasValidCheckCharacterPair,
-    hasValidCheckDigit, hasValidPriceWeightCheckDigit,
+    hasValidCheckDigit,
     i18nGS1Init,
-    priceWeightCheckDigit
+    isValidPriceOrWeightCheckDigit,
+    priceOrWeightCheckDigit
 } from "../src";
 
-await i18nGS1Init(I18NEnvironment.CLI, true);
+await i18nGS1Init(I18nEnvironment.CLI, true);
 
 describe("Check digit", () => {
     const testNumericString = "1234567890";
@@ -39,7 +40,7 @@ describe("Check digit", () => {
     });
 });
 
-describe("Price/weight check digit", () => {
+describe("Price or weight check digit", () => {
     function weight2Minus(characterIndex: number): number {
         const product = characterIndex * 2;
 
@@ -68,8 +69,10 @@ describe("Price/weight check digit", () => {
 
         const sum = weight2Minus(characterIndexes[0]) + weight2Minus(characterIndexes[1]) + weight3(characterIndexes[2]) + weight5Minus(characterIndexes[3]);
 
-        expect(priceWeightCheckDigit(s)).toBe(NUMERIC_CREATOR.character(sum * 3 % 10));
-        expect(hasValidPriceWeightCheckDigit(s + priceWeightCheckDigit(s))).toBe(true);
+        const checkDigit = priceOrWeightCheckDigit(s);
+
+        expect(checkDigit).toBe(NUMERIC_CREATOR.character(sum * 3 % 10));
+        expect(isValidPriceOrWeightCheckDigit(s, checkDigit)).toBe(true);
     }
 
     function testFiveDigitPriceWeightCheckDigit(s: string): void {
@@ -78,8 +81,10 @@ describe("Price/weight check digit", () => {
 
         const sum = weight5Plus(characterIndexes[0]) + weight2Minus(characterIndexes[1]) + weight5Minus(characterIndexes[2]) + weight5Plus(characterIndexes[3]) + weight2Minus(characterIndexes[4]);
 
-        expect(weight5Minus(Number(priceWeightCheckDigit(s)))).toBe(9 - (sum + 9) % 10);
-        expect(hasValidPriceWeightCheckDigit(s + priceWeightCheckDigit(s))).toBe(true);
+        const checkDigit = priceOrWeightCheckDigit(s);
+
+        expect(weight5Minus(Number(checkDigit))).toBe(9 - (sum + 9) % 10);
+        expect(isValidPriceOrWeightCheckDigit(s, checkDigit)).toBe(true);
     }
 
     test("Four-digit", () => {
@@ -109,9 +114,9 @@ describe("Price/weight check digit", () => {
     });
 
     test("Invalid", () => {
-        expect(() => priceWeightCheckDigit("l2345")).toThrow("Invalid character 'l' at position 1 of price or weight");
-        expect(() => priceWeightCheckDigit("123")).toThrow("Length 3 of string for price or weight must be 4 or 5");
-        expect(() => priceWeightCheckDigit("123456")).toThrow("Length 6 of string for price or weight must be 4 or 5");
+        expect(() => priceOrWeightCheckDigit("l2345")).toThrow("Invalid character 'l' at position 1 of price or weight");
+        expect(() => priceOrWeightCheckDigit("123")).toThrow("Length 3 of string for price or weight must be 4 or 5");
+        expect(() => priceOrWeightCheckDigit("123456")).toThrow("Length 6 of string for price or weight must be 4 or 5");
     });
 });