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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/gs1",
-  "version": "1.0.24-beta",
+  "version": "1.0.25-beta",
   "description": "GS1 AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -23,12 +23,12 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "beta",
-    "vitest": "^4.0.14"
+    "@aidc-toolkit/dev": "1.0.25-beta",
+    "vitest": "^4.0.15"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "beta",
-    "@aidc-toolkit/utility": "beta",
+    "@aidc-toolkit/core": "1.0.25-beta",
+    "@aidc-toolkit/utility": "1.0.25-beta",
     "ts-mixer": "^6.0.4"
   }
 }

package/src/abstract-identifier-creator.ts

@@ -0,0 +1,97 @@
+import type { CharacterSetCreator } from "@aidc-toolkit/utility";
+import type { IdentifierCreator } from "./identifier-creator";
+import type { IdentifierDescriptor } from "./identifier-descriptor";
+import type { IdentifierValidation } from "./identifier-validator";
+import type { PrefixProvider } from "./prefix-provider";
+
+/**
+ * Abstract identifier creator. Implements common functionality for an identifier creator, bound to a {@link
+ * PrefixProvider | prefix provider}.
+ *
+ * @template TIdentifierDescriptor
+ * Identifier descriptor type.
+ *
+ * @template TIdentifierValidation
+ * Identifier validation type.
+ */
+export abstract class AbstractIdentifierCreator<TIdentifierDescriptor extends IdentifierDescriptor, TIdentifierValidation extends IdentifierValidation> implements IdentifierCreator<TIdentifierDescriptor, TIdentifierValidation> {
+    /**
+     * Prefix provider.
+     */
+    private _prefixProvider!: PrefixProvider;
+
+    /**
+     * Reference length.
+     */
+    private _referenceLength!: number;
+
+    /**
+     * Initialize the prefix provider. This method is in lieu of a constructor due to the mixin architecture.
+     *
+     * @param prefixProvider
+     * Prefix provider.
+     *
+     * @param prefix
+     * Prefix within prefix provider to use to calculate reference length.
+     *
+     * @param checkAllowance
+     * Number of characters to allow for check digit or check character pair.
+     */
+    protected init(prefixProvider: PrefixProvider, prefix: string, checkAllowance: number): void {
+        this._prefixProvider = prefixProvider;
+
+        // Reference length allows for prefix and optionally check digit or check character pair.
+        this._referenceLength = this.length - prefix.length - checkAllowance;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    abstract get identifierType(): TIdentifierDescriptor["identifierType"];
+
+    /**
+     * @inheritDoc
+     */
+    abstract get prefixType(): TIdentifierDescriptor["prefixType"];
+
+    /**
+     * @inheritDoc
+     */
+    abstract get length(): number;
+
+    /**
+     * @inheritDoc
+     */
+    abstract get referenceCharacterSet(): TIdentifierDescriptor["referenceCharacterSet"];
+
+    /**
+     * @inheritDoc
+     */
+    abstract get referenceCreator(): CharacterSetCreator;
+
+    /**
+     * @inheritDoc
+     */
+    get prefixProvider(): PrefixProvider {
+        return this._prefixProvider;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get prefix(): string {
+        return this.prefixProvider.gs1CompanyPrefix;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get referenceLength(): number {
+        return this._referenceLength;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    abstract validate(identifier: string, validation?: TIdentifierValidation): void;
+}

package/src/abstract-identifier-validator.ts

@@ -0,0 +1,140 @@
+import { type CharacterSetCreator, NUMERIC_CREATOR } from "@aidc-toolkit/utility";
+import { AI39_CREATOR, AI82_CREATOR } from "./character-set";
+import { type ContentCharacterSet, ContentCharacterSets } from "./content-character-set";
+import type { IdentifierDescriptor } from "./identifier-descriptor";
+import type { IdentifierValidation, IdentifierValidator } from "./identifier-validator";
+import { PrefixTypes } from "./prefix-type";
+import { PrefixValidator } from "./prefix-validator";
+
+/**
+ * Abstract identifier validator. Implements common functionality for an identifier validator.
+ *
+ * @template TIdentifierDescriptor
+ * Identifier descriptor type.
+ *
+ * @template TIdentifierValidation
+ * Identifier validation type.
+ */
+export abstract class AbstractIdentifierValidator<TIdentifierDescriptor extends IdentifierDescriptor, TIdentifierValidation extends IdentifierValidation> implements IdentifierValidator<TIdentifierDescriptor, 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: TIdentifierDescriptor["identifierType"];
+
+    /**
+     * Length.
+     */
+    private readonly _length: number;
+
+    /**
+     * Reference character set.
+     */
+    private readonly _referenceCharacterSet: TIdentifierDescriptor["referenceCharacterSet"];
+
+    /**
+     * 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 identifierDescriptor
+     * Identifier descriptor.
+     */
+    protected constructor(identifierDescriptor: IdentifierDescriptor) {
+        this._identifierType = identifierDescriptor.identifierType;
+        this._length = identifierDescriptor.length;
+        this._referenceCharacterSet = identifierDescriptor.referenceCharacterSet;
+        this._referenceCreator = AbstractIdentifierValidator.creatorFor(identifierDescriptor.referenceCharacterSet);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get identifierType(): TIdentifierDescriptor["identifierType"] {
+        return this._identifierType;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get prefixType(): TIdentifierDescriptor["prefixType"] {
+        // All identifier types except GTIN support only the GS1 Company Prefix.
+        return PrefixTypes.GS1CompanyPrefix;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get length(): number {
+        return this._length;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get referenceCharacterSet(): TIdentifierDescriptor["referenceCharacterSet"] {
+        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 positionOffset
+     * Position offset within a larger string.
+     *
+     * @returns
+     * Padded identifier.
+     */
+    protected padIdentifier(identifier: string, positionOffset?: number): string {
+        // Identifier is returned as is if position offset is undefined.
+        return positionOffset === undefined ? identifier : this.referenceCreator.character(0).repeat(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/abstract-numeric-identifier-creator.ts

@@ -0,0 +1,168 @@
+import {
+    CharacterSetCreator,
+    Exclusions,
+    NUMERIC_CREATOR,
+    type TransformerInput,
+    type TransformerOutput
+} from "@aidc-toolkit/utility";
+import { AbstractIdentifierCreator } from "./abstract-identifier-creator";
+import { checkDigit, checkDigitSum } from "./check";
+import type { NumericIdentifierCreator } from "./numeric-identifier-creator";
+import type { NumericIdentifierDescriptor } from "./numeric-identifier-descriptor";
+import { type LeaderType, LeaderTypes } from "./numeric-identifier-type";
+import type { NumericIdentifierValidation } from "./numeric-identifier-validator";
+import type { PrefixProvider } from "./prefix-provider";
+
+/**
+ * Abstract numeric identifier creator. Implements common functionality for a numeric identifier creator.
+ *
+ * @template TNumericIdentifierDescriptor
+ * Numeric identifier descriptor type.
+ */
+export abstract class AbstractNumericIdentifierCreator<TNumericIdentifierDescriptor extends NumericIdentifierDescriptor> extends AbstractIdentifierCreator<TNumericIdentifierDescriptor, NumericIdentifierValidation> implements NumericIdentifierCreator<TNumericIdentifierDescriptor> {
+    /**
+     * Capacity.
+     */
+    private _capacity!: number;
+
+    /**
+     * Tweak for sparse creation.
+     */
+    private _tweak = 0n;
+
+    /**
+     * Initialize the prefix provider. This method is in lieu of a constructor due to the mixin architecture.
+     *
+     * @param prefixProvider
+     * Prefix provider.
+     *
+     * @param prefix
+     * Prefix within prefix manager to use to calculate reference length.
+     */
+    protected override init(prefixProvider: PrefixProvider, prefix: string): void {
+        super.init(prefixProvider, prefix, 1);
+
+        // Capacity is always in number range.
+        this._capacity = Number(CharacterSetCreator.powerOf10(this.referenceLength));
+    }
+
+    /**
+     * Get the leader type.
+     */
+    abstract get leaderType(): LeaderType;
+
+    /**
+     * @inheritDoc
+     */
+    get capacity(): number {
+        return this._capacity;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get tweak(): bigint {
+        return this._tweak;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    set tweak(value: bigint) {
+        this._tweak = value;
+    }
+
+    /**
+     * Build an identifier from a reference by merging it with the prefix and adding the check digit.
+     *
+     * @param reference
+     * Identifier reference.
+     *
+     * @returns
+     * Identifier.
+     */
+    private buildIdentifier(reference: string): string {
+        const partialIdentifier = this.leaderType === LeaderTypes.ExtensionDigit ? reference.substring(0, 1) + this.prefix + reference.substring(1) : this.prefix + reference;
+
+        return partialIdentifier + checkDigit(partialIdentifier);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    create<TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput, sparse = false): TransformerOutput<TTransformerInput, string> {
+        return NUMERIC_CREATOR.create(this.referenceLength, valueOrValues, Exclusions.None, sparse ? this.tweak : undefined, reference => this.buildIdentifier(reference));
+    }
+
+    /**
+     * Create all identifiers from a partial identifier. Call is recursive until remaining reference
+     * length is 0.
+     *
+     * @param partialIdentifier
+     * Partial identifier. Initial value is `this.prefix`.
+     *
+     * @param remainingReferenceLength
+     * Remaining reference length. Initial value is `this.referenceLength`.
+     *
+     * @param extensionWeight
+     * If this value is not zero, the identifier has an extension digit, this call is setting it, and this value is
+     * applied to the calculation of the check digit.
+     *
+     * @param weight
+     * If the extension weight is zero, this value is applied to the calculation of the check digit.
+     *
+     * @param partialCheckDigitSum
+     * Partial check digit sum for the partial identifier.
+     *
+     * @yields
+     * Identifier.
+     */
+    private static * createAllPartial(partialIdentifier: string, remainingReferenceLength: number, extensionWeight: number, weight: number, partialCheckDigitSum: number): Generator<string> {
+        if (remainingReferenceLength === 0) {
+            // Finalize check digit calculation and append.
+            yield partialIdentifier + NUMERIC_CREATOR.character(9 - (partialCheckDigitSum + 9) % 10);
+        } else {
+            const nextRemainingReferenceLength = remainingReferenceLength - 1;
+
+            let nextPartialCheckDigitSum = partialCheckDigitSum;
+
+            if (extensionWeight !== 0) {
+                // Apply every digit to the extension digit.
+                for (const c of NUMERIC_CREATOR.characterSet) {
+                    yield * AbstractNumericIdentifierCreator.createAllPartial(c + partialIdentifier, nextRemainingReferenceLength, 0, weight, nextPartialCheckDigitSum);
+
+                    nextPartialCheckDigitSum += extensionWeight;
+                }
+            } else {
+                const nextWeight = 4 - weight;
+
+                // Apply every digit to the current character in the identifier.
+                for (const c of NUMERIC_CREATOR.characterSet) {
+                    yield * AbstractNumericIdentifierCreator.createAllPartial(partialIdentifier + c, nextRemainingReferenceLength, 0, nextWeight, nextPartialCheckDigitSum);
+
+                    nextPartialCheckDigitSum += weight;
+                }
+            }
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    createAll(): Iterable<string> {
+        const hasExtensionDigit = this.leaderType === LeaderTypes.ExtensionDigit;
+        const prefix = this.prefix;
+        const length = this.length;
+        const referenceLength = this.referenceLength;
+
+        // Start weight is for reference excluding extension digit, which has its weight calculated separately.
+        const startWeight = 3 - 2 * ((referenceLength + 1 - Number(hasExtensionDigit)) % 2);
+
+        // Returning separate Iterable object makes iteration repeatable.
+        return {
+            [Symbol.iterator]() {
+                return AbstractNumericIdentifierCreator.createAllPartial(prefix, referenceLength, hasExtensionDigit ? 3 - 2 * length % 2 : 0, startWeight, checkDigitSum(startWeight === 3, prefix));
+            }
+        };
+    }
+}

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

@@ -0,0 +1,69 @@
+import { AbstractIdentifierValidator } from "./abstract-identifier-validator";
+import { hasValidCheckDigit } from "./check";
+import { i18nextGS1 } from "./locale/i18n";
+import type { NumericIdentifierDescriptor } from "./numeric-identifier-descriptor";
+import { LeaderTypes } from "./numeric-identifier-type";
+import type { NumericIdentifierValidation, NumericIdentifierValidator } from "./numeric-identifier-validator";
+
+/**
+ * Abstract numeric identifier validator.
+ *
+ * @template TNumericIdentifierDescriptor
+ * Numeric identifier descriptor type.
+ */
+export abstract class AbstractNumericIdentifierValidator<TNumericIdentifierDescriptor extends NumericIdentifierDescriptor> extends AbstractIdentifierValidator<TNumericIdentifierDescriptor, NumericIdentifierValidation> implements NumericIdentifierValidator<TNumericIdentifierDescriptor> {
+    /**
+     * Leader type.
+     */
+    private readonly _leaderType: TNumericIdentifierDescriptor["leaderType"];
+
+    /**
+     * Prefix position, determined by the leader type.
+     */
+    private readonly _prefixPosition: number;
+
+    /**
+     * Constructor.
+     *
+     * @param identifierDescriptor
+     * Identifier descriptor.
+     */
+    constructor(identifierDescriptor: NumericIdentifierDescriptor) {
+        super(identifierDescriptor);
+
+        this._leaderType = identifierDescriptor.leaderType;
+        this._prefixPosition = Number(this.leaderType === LeaderTypes.ExtensionDigit);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get leaderType(): TNumericIdentifierDescriptor["leaderType"] {
+        return this._leaderType;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    validate(identifier: string, validation?: NumericIdentifierValidation): void {
+        // Validate the prefix, with care taken for its position within the identifier.
+        if (this._prefixPosition === 0) {
+            super.validatePrefix(identifier, validation?.positionOffset);
+        } else {
+            super.validatePrefix(identifier.substring(this._prefixPosition), validation?.positionOffset === undefined ? this._prefixPosition : validation.positionOffset + this._prefixPosition);
+        }
+
+        // Validate the length.
+        if (identifier.length !== this.length) {
+            throw new RangeError(i18nextGS1.t("Identifier.identifierTypeLength", {
+                identifierType: this.identifierType,
+                length: this.length
+            }));
+        }
+
+        // Validating the check digit will also validate the characters.
+        if (!hasValidCheckDigit(this.padIdentifier(identifier, validation?.positionOffset))) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidCheckDigit"));
+        }
+    }
+}

package/src/character-set.ts

@@ -1,8 +1,8 @@
 import { CharacterSetCreator, CharacterSetValidator, Exclusions } from "@aidc-toolkit/utility";
 
 /**
- * GS1 AI encodable character set 82 creator as defined in section 7.11 of the {@link https://www.gs1.org/genspecs | GS1
- * General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
+ * GS1 AI encodable character set 82 creator as defined in section 7.11 of the {@link
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
  */
 export const AI82_CREATOR = new CharacterSetCreator([
     "!", "\"", "%", "&", "'", "(", ")", "*", "+", ",", "-", ".", "/",
@@ -16,14 +16,14 @@ export const AI82_CREATOR = new CharacterSetCreator([
 ], Exclusions.AllNumeric);
 
 /**
- * GS1 AI encodable character set 82 validator as defined in section 7.11 of the {@link https://www.gs1.org/genspecs |
- * GS1 General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
+ * GS1 AI encodable character set 82 validator as defined in section 7.11 of the {@link
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
  */
 export const AI82_VALIDATOR = AI82_CREATOR as CharacterSetValidator;
 
 /**
- * GS1 AI encodable character set 39 creator as defined in section 7.11 of the {@link https://www.gs1.org/genspecs | GS1
- * General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
+ * GS1 AI encodable character set 39 creator as defined in section 7.11 of the {@link
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
  */
 export const AI39_CREATOR = new CharacterSetCreator([
     "#", "-", "/",
@@ -33,14 +33,14 @@ export const AI39_CREATOR = new CharacterSetCreator([
 ], Exclusions.AllNumeric);
 
 /**
- * GS1 AI encodable character set 39 validator as defined in section 7.11 of the {@link https://www.gs1.org/genspecs |
- * GS1 General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
+ * GS1 AI encodable character set 39 validator as defined in section 7.11 of the {@link
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}. Supports {@linkcode Exclusions.AllNumeric}.
  */
 export const AI39_VALIDATOR = AI39_CREATOR as CharacterSetValidator;
 
 /**
- * GS1 AI encodable character set 64 validator as defined in section 7.11 of the {@link https://www.gs1.org/genspecs |
- * GS1 General Specifications}. Doesn't support any exclusions.
+ * GS1 AI encodable character set 64 validator as defined in section 7.11 of the {@link
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}. Doesn't support any exclusions.
  */
 export const AI64_VALIDATOR = new CharacterSetValidator([
     "-",

package/src/check.ts

@@ -38,8 +38,8 @@ const INVERSE_FIVE_MINUS_WEIGHT_RESULTS: readonly number[] = [
 ];
 
 /**
- * Calculate the check digit sum for a numeric string as per section 7.9.1 of the {@link https://www.gs1.org/genspecs |
- * GS1 General Specifications}.
+ * Calculate the check digit sum for a numeric string as per section 7.9.1 of the {@link
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}.
  *
  * @param exchangeWeights
  * If true, start the weights at 1 instead of 3 on the right.
@@ -71,8 +71,8 @@ export function checkDigitSum(exchangeWeights: boolean, s: string): number {
 }
 
 /**
- * Calculate the check digit for a numeric string as per section 7.9.1 of the {@link https://www.gs1.org/genspecs | GS1
- * General Specifications}.
+ * Calculate the check digit for a numeric string as per section 7.9.1 of the {@link
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}.
  *
  * @param s
  * Numeric string.
@@ -129,8 +129,8 @@ function priceOrWeightSum(weightsResults: ReadonlyArray<readonly number[]>, s: s
 }
 
 /**
- * Calculate the price or weight check digit for a four-or five-digit numeric string as per section 7.9.3 of the {@link
- * https://www.gs1.org/genspecs | GS1 General Specifications}.
+ * Calculate the price or weight check digit for a four-or five-digit numeric string as per sections 7.9.2-7.9.4 of the
+ * {@link https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}.
  *
  * @param s
  * Numeric string exactly four or five characters long.
@@ -192,7 +192,7 @@ const CHECK_CHARACTERS = [
 
 /**
  * Calculate the check character for a GS1 AI encodable character set 82 string as per section 7.9.5 of the {@link
- * https://www.gs1.org/genspecs | GS1 General Specifications}.
+ * https://ref.gs1.org/standards/genspecs/ | GS1 General Specifications}.
  *
  * @param s
  * GS1 AI encodable character set 82 string.

package/src/content-character-set.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 key.
+ */
+export type ContentCharacterSetKey = keyof typeof ContentCharacterSets;
+
+/**
+ * Content character set.
+ */
+export type ContentCharacterSet = typeof ContentCharacterSets[ContentCharacterSetKey];