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

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.js";
+import { checkDigit, checkDigitSum } from "./check.js";
+import type { NumericIdentifierCreator } from "./numeric-identifier-creator.js";
+import type { NumericIdentifierDescriptor } from "./numeric-identifier-descriptor.js";
+import { type LeaderType, LeaderTypes } from "./numeric-identifier-type.js";
+import type { NumericIdentifierValidation } from "./numeric-identifier-validator.js";
+import type { PrefixProvider } from "./prefix-provider.js";
+
+/**
+ * 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.js";
+import { hasValidCheckDigit } from "./check.js";
+import { i18nextGS1 } from "./locale/i18n.js";
+import type { NumericIdentifierDescriptor } from "./numeric-identifier-descriptor.js";
+import { LeaderTypes } from "./numeric-identifier-type.js";
+import type { NumericIdentifierValidation, NumericIdentifierValidator } from "./numeric-identifier-validator.js";
+
+/**
+ * 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

@@ -1,6 +1,6 @@
 import { NUMERIC_CREATOR, utilityNS } from "@aidc-toolkit/utility";
-import { AI82_CREATOR } from "./character-set";
-import { i18nextGS1 } from "./locale/i18n";
+import { AI82_CREATOR } from "./character-set.js";
+import { i18nextGS1 } from "./locale/i18n.js";
 
 /**
  * Results of multiplying digits by 3.
@@ -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];

package/src/creators.ts

@@ -0,0 +1,113 @@
+import {
+    isGTINDescriptor,
+    isNonGTINNumericIdentifierDescriptor,
+    isNonNumericIdentifierDescriptor,
+    isNumericIdentifierDescriptor,
+    isSerializableNumericIdentifierDescriptor
+} from "./descriptors.js";
+import type { GTINCreator } from "./gtin-creator.js";
+import type { IdentifierCreator } from "./identifier-creator.js";
+import type { IdentifierType, IdentifierTypes } from "./identifier-type.js";
+import type { NonGTINNumericIdentifierCreator } from "./non-gtin-numeric-identifier-creator.js";
+import type { NonGTINNumericIdentifierType } from "./non-gtin-numeric-identifier-type.js";
+import type { NonNumericIdentifierCreator } from "./non-numeric-identifier-creator.js";
+import type { NonNumericIdentifierType } from "./non-numeric-identifier-type.js";
+import type { NumericIdentifierCreator } from "./numeric-identifier-creator.js";
+import type { SerializableNumericIdentifierCreator } from "./serializable-numeric-identifier-creator.js";
+import type { SerializableNumericIdentifierType } from "./serializable-numeric-identifier-type.js";
+
+/**
+ * Determine the identifier creator type for an identifier type.
+ *
+ * @template TIdentifierType
+ * Identifier type type.
+ */
+export type IdentifierTypeCreator<TIdentifierType extends IdentifierType> = TIdentifierType extends NonNumericIdentifierType ?
+    NonNumericIdentifierCreator :
+    TIdentifierType extends SerializableNumericIdentifierType ?
+        SerializableNumericIdentifierCreator :
+        TIdentifierType extends NonGTINNumericIdentifierType ?
+            NonGTINNumericIdentifierCreator :
+            TIdentifierType extends typeof IdentifierTypes.GTIN ?
+                GTINCreator :
+                IdentifierCreator;
+
+/**
+ * Identifier creators entry type based on identifier type type.
+ *
+ * @template TIdentifierType
+ * Identifier type type.
+ */
+export type IdentifierCreatorsEntry<TIdentifierType extends IdentifierType> = IdentifierTypeCreator<TIdentifierType>;
+
+/**
+ * Identifier creators record type.
+ */
+export type IdentifierCreatorsRecord = {
+    [TIdentifierType in IdentifierType]: IdentifierCreatorsEntry<TIdentifierType>;
+};
+
+/**
+ * Determine if identifier creator is a numeric identifier creator.
+ *
+ * @param identifierCreator
+ * Identifier creator.
+ *
+ * @returns
+ * True if identifier creator is a numeric identifier creator.
+ */
+export function isNumericIdentifierCreator(identifierCreator: IdentifierCreator): identifierCreator is NumericIdentifierCreator {
+    return isNumericIdentifierDescriptor(identifierCreator);
+}
+
+/**
+ * Determine if identifier creator is a GTIN creator.
+ *
+ * @param identifierCreator
+ * Identifier creator.
+ *
+ * @returns
+ * True if identifier creator is a GTIN creator.
+ */
+export function isGTINCreator(identifierCreator: IdentifierCreator): identifierCreator is GTINCreator {
+    return isGTINDescriptor(identifierCreator);
+}
+
+/**
+ * Determine if identifier creator is a non-GTIN numeric identifier creator.
+ *
+ * @param identifierCreator
+ * Identifier creator.
+ *
+ * @returns
+ * True if identifier creator is a non-GTIN numeric identifier creator.
+ */
+export function isNonGTINNumericIdentifierCreator(identifierCreator: IdentifierCreator): identifierCreator is NonGTINNumericIdentifierCreator {
+    return isNonGTINNumericIdentifierDescriptor(identifierCreator);
+}
+
+/**
+ * Determine if identifier creator is a serializable numeric identifier creator.
+ *
+ * @param identifierCreator
+ * Identifier creator.
+ *
+ * @returns
+ * True if identifier creator is a serializable numeric identifier creator.
+ */
+export function isSerializableNumericIdentifierCreator(identifierCreator: IdentifierCreator): identifierCreator is SerializableNumericIdentifierCreator {
+    return isSerializableNumericIdentifierDescriptor(identifierCreator);
+}
+
+/**
+ * Determine if identifier creator is a non-numeric identifier creator.
+ *
+ * @param identifierCreator
+ * Identifier creator.
+ *
+ * @returns
+ * True if identifier creator is a non-numeric identifier creator.
+ */
+export function isNonNumericIdentifierCreator(identifierCreator: IdentifierCreator): identifierCreator is NonNumericIdentifierCreator {
+    return isNonNumericIdentifierDescriptor(identifierCreator);
+}