@aidc-toolkit/gs1 0.9.20-beta → 1.0.22-beta

package/src/numeric-identifier-creator.ts

@@ -0,0 +1,200 @@
+import {
+    CharacterSetCreator,
+    Exclusions,
+    NUMERIC_CREATOR,
+    type TransformerInput,
+    type TransformerOutput
+} from "@aidc-toolkit/utility";
+import { checkDigit, checkDigitSum } from "./check.js";
+import { AbstractIdentifierCreator, type IdentifierCreator } from "./identifier-creator.js";
+import { type LeaderType, LeaderTypes, type NumericIdentifierValidator } from "./numeric-identifier-validator.js";
+import type { PrefixProvider } from "./prefix-provider";
+
+/**
+ * Numeric identifier creator. Creates one or many numeric identifiers.
+ */
+export interface NumericIdentifierCreator extends NumericIdentifierValidator, IdentifierCreator {
+    /**
+     * Get the capacity (`10**referenceLength`).
+     */
+    get capacity(): number;
+
+    /**
+     * Create identifier(s) with reference(s) based on numeric value(s). The value(s) is/are converted to
+     * references of the appropriate length using {@linkcode NUMERIC_CREATOR}.
+     *
+     * @template TTransformerInput
+     * Transformer input type.
+     *
+     * @param valueOrValues
+     * Numeric value(s).
+     *
+     * @param sparse
+     * If true, the value(s) are mapped to a sparse sequence resistant to discovery. Default is false.
+     *
+     * @returns
+     * Identifier(s).
+     */
+    create: <TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput, sparse?: boolean) => TransformerOutput<TTransformerInput, string>;
+
+    /**
+     * Create all identifiers for the prefix from `0` to `capacity - 1`.
+     *
+     * The implementation creates the strings only as needed using an internal generator function. Although the result
+     * is equivalent to calling `creator.create(new Sequence(0, creator.capacity))`, this method is significantly
+     * faster.
+     *
+     * @returns
+     * All identifiers for the prefix.
+     */
+    createAll: () => Iterable<string>;
+}
+
+/**
+ * Abstract numeric identifier creator. Implements common functionality for a numeric identifier
+ * creator.
+ */
+export abstract class AbstractNumericIdentifierCreator extends AbstractIdentifierCreator implements NumericIdentifierCreator {
+    /**
+     * 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));
+    }
+
+    abstract get leaderType(): LeaderType;
+
+    /**
+     * @inheritDoc
+     */
+    get capacity(): number {
+        return this._capacity;
+    }
+
+    /**
+     * Get the tweak for sparse creation.
+     */
+    get tweak(): bigint {
+        return this._tweak;
+    }
+
+    /**
+     * Set the tweak for sparse creation.
+     */
+    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/numeric-identifier-validator.ts

@@ -0,0 +1,128 @@
+import { hasValidCheckDigit } from "./check.js";
+import type { IdentifierType, IdentifierTypes } from "./identifier-type.js";
+import {
+    AbstractIdentifierValidator,
+    ContentCharacterSets,
+    type IdentifierValidation,
+    type IdentifierValidator
+} from "./identifier-validator.js";
+import { i18nextGS1 } from "./locale/i18n.js";
+import type { PrefixType } from "./prefix-type.js";
+
+/**
+ * Numeric identifier type.
+ */
+export type NumericIdentifierType =
+    typeof IdentifierTypes.GTIN |
+    typeof IdentifierTypes.GLN |
+    typeof IdentifierTypes.SSCC |
+    typeof IdentifierTypes.GRAI |
+    typeof IdentifierTypes.GSRN |
+    typeof IdentifierTypes.GDTI |
+    typeof IdentifierTypes.GSIN |
+    typeof IdentifierTypes.GCN;
+
+/**
+ * Leader type.
+ */
+export const LeaderTypes = {
+    /**
+     * No leader.
+     */
+    None: "None",
+
+    /**
+     * Indicator digit (GTIN only).
+     */
+    IndicatorDigit: "Indicator digit",
+
+    /**
+     * Extension digit (SSCC only).
+     */
+    ExtensionDigit: "Extension digit"
+};
+
+/**
+ * Leader type.
+ */
+export type LeaderType = typeof LeaderTypes[keyof typeof LeaderTypes];
+
+/**
+ * Numeric identifier validator. Validates a numeric identifier.
+ */
+export interface NumericIdentifierValidator extends IdentifierValidator {
+    /**
+     * Get the leader type.
+     */
+    get leaderType(): LeaderType;
+}
+
+/**
+ * Abstract numeric identifier validator. Implements common functionality for a numeric identifier
+ * validator.
+ */
+export abstract class AbstractNumericIdentifierValidator extends AbstractIdentifierValidator implements NumericIdentifierValidator {
+    /**
+     * Leader type.
+     */
+    private readonly _leaderType: LeaderType;
+
+    /**
+     * Prefix position, determined by the leader type.
+     */
+    private readonly _prefixPosition: number;
+
+    /**
+     * Constructor.
+     *
+     * @param identifierType
+     * Identifier type.
+     *
+     * @param prefixType
+     * Prefix type.
+     *
+     * @param length
+     * Length.
+     *
+     * @param leaderType
+     * Leader type.
+     */
+    protected constructor(identifierType: IdentifierType, prefixType: PrefixType, length: number, leaderType: LeaderType) {
+        super(identifierType, prefixType, length, ContentCharacterSets.Numeric);
+
+        this._leaderType = leaderType;
+        this._prefixPosition = Number(this.leaderType === LeaderTypes.ExtensionDigit);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    get leaderType(): LeaderType {
+        return this._leaderType;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    validate(identifier: string, validation?: IdentifierValidation): 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))) {
+            throw new RangeError(i18nextGS1.t("Identifier.invalidCheckDigit"));
+        }
+    }
+}