@aidc-toolkit/gs1 0.0.1 → 0.9.1

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Platform**
+ - OS: [e.g. Windows, iOS]
+ - Browser [e.g. chrome, safari]
+ - Browser Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.idea/runConfigurations/build_dev.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="build-dev" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="build-dev" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/eslint.config.js

@@ -6,6 +6,9 @@ import esLintConfigLove from "eslint-config-love";
 import { esLintConfigAIDCToolkit } from "@aidc-toolkit/dev";
 
 export default tseslint.config(
+    {
+        ignores: ["eslint.config.js", "dist"]
+    },
     js.configs.recommended,
     ...tseslint.configs.strictTypeChecked,
     stylistic.configs["recommended-flat"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/gs1",
-  "version": "0.0.1",
+  "version": "0.9.1",
   "description": "GS1 AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -20,25 +20,26 @@
   },
   "scripts": {
     "eslint": "eslint .",
-    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "build": "tsup src/index.ts --clean --format cjs,esm --dts",
+    "build-dev": "npm run build && tsc src/index.ts --outDir dist --target esnext --moduleResolution nodenext --module nodenext --emitDeclarationOnly --declaration --declarationMap",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "^0.0.1",
-    "@eslint/js": "^9.10.0",
-    "@stylistic/eslint-plugin": "^2.7.2",
-    "eslint-config-love": "^64.0.0",
-    "eslint-plugin-jsdoc": "^50.2.2",
+    "@aidc-toolkit/dev": "^0.9.1",
+    "@eslint/js": "^9.11.1",
+    "@stylistic/eslint-plugin": "^2.8.0",
+    "eslint-config-love": "^71.0.0",
+    "eslint-plugin-jsdoc": "^50.3.0",
     "ts-node": "^10.9.2",
-    "tsup": "^8.2.4",
-    "typescript": "^5.5.4",
-    "typescript-eslint": "^8.4.0",
-    "vitest": "^2.0.5"
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.7.0",
+    "vitest": "^2.1.1"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "^0.0.1",
-    "@aidc-toolkit/utility": "^0.0.1",
-    "i18next": "^23.14.0",
+    "@aidc-toolkit/core": "^0.9.1",
+    "@aidc-toolkit/utility": "^0.9.1",
+    "i18next": "^23.15.1",
     "ts-mixer": "^6.0.4"
   }
 }

package/src/check.ts

@@ -108,8 +108,6 @@ export function hasValidCheckDigit(s: string): boolean {
  *
  * @returns
  * Accumulated sum of the weight result for each digit at the digit's position.
- *
- * @throws RangeError
  */
 function priceWeightSum(weightsResults: ReadonlyArray<readonly number[]>, s: string): number {
     if (s.length !== weightsResults.length) {
@@ -184,8 +182,6 @@ const CHECK_CHARACTERS = [
  *
  * @returns
  * Check character pair.
- *
- * @throws RangeError
  */
 export function checkCharacterPair(s: string): string {
     // Weights are applied from right to left.

package/src/idkey.ts

@@ -2,7 +2,8 @@ import {
     CharacterSetCreator,
     type CharacterSetValidation,
     type CharacterSetValidator,
-    Exclusion, IterationHelper, type IterationSource, NUMERIC_CREATOR,
+    Exclusion,
+    NUMERIC_CREATOR,
     RegExpValidator,
     type StringValidation,
     type StringValidator
@@ -139,7 +140,7 @@ export interface IdentificationKeyValidation extends StringValidation {
  * Identification key validator. Validates an identification key against its definition in section 3 of the {@link
  * https://www.gs1.org/genspecs | GS1 General Specifications}.
  */
-export interface IdentificationKeyValidator extends StringValidator {
+export interface IdentificationKeyValidator<V extends IdentificationKeyValidation = IdentificationKeyValidation> extends StringValidator<V> {
     /**
      * Get the identification key type. Per the GS1 General Specifications, the identification key type determines
      * the remaining properties.
@@ -177,13 +178,13 @@ export interface IdentificationKeyValidator extends StringValidator {
      * @param validation
      * Identification key validation parameters.
      */
-    validate: (identificationKey: string, validation?: IdentificationKeyValidation) => void;
+    validate: (identificationKey: string, validation?: V) => void;
 }
 
 /**
  * Abstract identification key validator. Implements common functionality for an identification key validator.
  */
-abstract class AbstractIdentificationKeyValidator implements IdentificationKeyValidator {
+abstract class AbstractIdentificationKeyValidator<V extends IdentificationKeyValidation = IdentificationKeyValidation> implements IdentificationKeyValidator<V> {
     /**
      * Identification key type.
      */
@@ -261,22 +262,37 @@ abstract class AbstractIdentificationKeyValidator implements IdentificationKeyVa
         this._referenceValidator = AbstractIdentificationKeyValidator.validatorFor(referenceCharacterSet);
     }
 
+    /**
+     * @inheritDoc
+     */
     get identificationKeyType(): IdentificationKeyType {
         return this._identificationKeyType;
     }
 
+    /**
+     * @inheritDoc
+     */
     get prefixType(): PrefixType {
         return this._prefixType;
     }
 
+    /**
+     * @inheritDoc
+     */
     get length(): number {
         return this._length;
     }
 
+    /**
+     * @inheritDoc
+     */
     get referenceCharacterSet(): CharacterSet {
         return this._referenceCharacterSet;
     }
 
+    /**
+     * @inheritDoc
+     */
     get referenceValidator(): CharacterSetValidator {
         return this._referenceValidator;
     }
@@ -313,7 +329,7 @@ abstract class AbstractIdentificationKeyValidator implements IdentificationKeyVa
         PrefixManager.validatePrefix(this.prefixType, true, false, partialIdentificationKey, true, this.referenceCharacterSet === CharacterSet.Numeric, positionOffset);
     }
 
-    abstract validate(identificationKey: string, validation?: IdentificationKeyValidation): void;
+    abstract validate(identificationKey: string, validation?: V): void;
 }
 
 /**
@@ -383,10 +399,16 @@ abstract class AbstractNumericIdentificationKeyValidator extends AbstractIdentif
         this._prefixPosition = Number(this.leaderType === LeaderType.ExtensionDigit);
     }
 
+    /**
+     * @inheritDoc
+     */
     get leaderType(): LeaderType {
         return this._leaderType;
     }
 
+    /**
+     * @inheritDoc
+     */
     validate(identificationKey: string, validation?: IdentificationKeyValidation): void {
         // Validate the prefix, with care taken for its position within the identification key.
         if (this._prefixPosition === 0) {
@@ -501,11 +523,17 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
         super(IdentificationKeyType.GTIN, prefixType, gtinType, LeaderType.IndicatorDigit);
     }
 
+    /**
+     * @inheritDoc
+     */
     get gtinType(): GTINType {
         // Length maps to GTIN type enumeration.
-        return this.length as GTINType;
+        return this.length satisfies GTINType;
     }
 
+    /**
+     * @inheritDoc
+     */
     protected override validatePrefix(partialIdentificationKey: string, positionOffset?: number): void {
         // Delegate to prefix manager requiring exact match for prefix type.
         PrefixManager.validatePrefix(this.prefixType, false, false, partialIdentificationKey, true, true, positionOffset);
@@ -519,8 +547,6 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
      *
      * @returns
      * GTIN-12.
-     *
-     * @throws RangeError
      */
     static zeroExpand(zeroSuppressedGTIN12: string): string {
         NUMERIC_CREATOR.validate(zeroSuppressedGTIN12, GTINValidator.ZERO_SUPPRESSED_GTIN12_VALIDATION);
@@ -563,8 +589,6 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
      *
      * @param gtinLevel
      * Level at which GTIN is to be validated.
-     *
-     * @throws RangeError
      */
     static validateAny(gtin: string, gtinLevel: GTINLevel = GTINLevel.Any): void {
         // Assume length-validated GTIN is the GTIN (true for all except zero-suppressed GTIN-12).
@@ -638,11 +662,9 @@ export class GTINValidator extends AbstractNumericIdentificationKeyValidator {
      *
      * @param gtin14
      * GTIN-14.
-     *
-     * @throws RangeError
      */
     static validateGTIN14(gtin14: string): void {
-        if (gtin14.length !== GTINType.GTIN14 as number) {
+        if (gtin14.length as GTINType !== GTINType.GTIN14) {
             throw new RangeError(i18next.t("IdentificationKey.invalidGTIN14Length", {
                 ns: gs1NS
             }));
@@ -758,6 +780,9 @@ export class SerializableNumericIdentificationKeyValidator extends NonGTINNumeri
         return this._serialComponentValidator;
     }
 
+    /**
+     * @inheritDoc
+     */
     override validate(identificationKey: string, validation?: IdentificationKeyValidation): void {
         super.validate(identificationKey.substring(0, this.length), validation);
 
@@ -771,17 +796,24 @@ export class SerializableNumericIdentificationKeyValidator extends NonGTINNumeri
  * Non-numeric identification key validation parameters.
  */
 export interface NonNumericIdentificationKeyValidation extends IdentificationKeyValidation {
+    /**
+     * Exclusion support for reference. Prevents non-numeric identification key from being mistaken for numeric
+     * identification key.
+     */
     exclusion?: Exclusion.None | Exclusion.AllNumeric | undefined;
 }
 
 /**
  * Non-numeric identification key validator.
  */
-export class NonNumericIdentificationKeyValidator extends AbstractIdentificationKeyValidator {
+export class NonNumericIdentificationKeyValidator extends AbstractIdentificationKeyValidator<NonNumericIdentificationKeyValidation> {
     /**
      * Validator to ensure that an identification key (minus check character pair) is not all numeric.
      */
     private static readonly NOT_ALL_NUMERIC_VALIDATOR = new class extends RegExpValidator {
+        /**
+         * @inheritDoc
+         */
         protected override createErrorMessage(_s: string): string {
             return i18next.t("IdentificationKey.referenceCantBeAllNumeric", {
                 ns: gs1NS
@@ -822,6 +854,15 @@ export class NonNumericIdentificationKeyValidator extends AbstractIdentification
         return this._requiresCheckCharacterPair;
     }
 
+    /**
+     * Validate a non-numeric identification key and throw an exception if validation fails.
+     *
+     * @param identificationKey
+     * Identification key.
+     *
+     * @param validation
+     * Validation parameters.
+     */
     validate(identificationKey: string, validation?: NonNumericIdentificationKeyValidation): void {
         const partialIdentificationKey = this.requiresCheckCharacterPair ? identificationKey.substring(0, identificationKey.length - 2) : identificationKey;
 
@@ -979,8 +1020,6 @@ abstract class AbstractIdentificationKeyCreator implements IdentificationKeyCrea
      *
      * @param checkAllowance
      * Number of characters to allow for check digit or check character pair.
-     *
-     * @throws Error
      */
     protected init(prefixManager: PrefixManager, prefix: string, checkAllowance: number): void {
         // Verify that prefix manager has not already been assigned.
@@ -1005,19 +1044,32 @@ abstract class AbstractIdentificationKeyCreator implements IdentificationKeyCrea
 
     abstract get referenceValidator(): CharacterSetValidator;
 
+    /**
+     * @inheritDoc
+     */
     get referenceCreator(): CharacterSetCreator {
         return this.referenceValidator as CharacterSetCreator;
     }
 
+    /**
+     * @inheritDoc
+     */
     get prefixManager(): PrefixManager {
+        // Prefix manager is expected to have been initialized by this point.
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         return this._prefixManager!;
     }
 
+    /**
+     * @inheritDoc
+     */
     get prefix(): string {
         return this.prefixManager.gs1CompanyPrefix;
     }
 
+    /**
+     * @inheritDoc
+     */
     get referenceLength(): number {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         return this._referenceLength!;
@@ -1035,58 +1087,37 @@ export interface NumericIdentificationKeyCreator extends NumericIdentificationKe
      */
     get capacity(): number;
 
-    /**
-     * Create an identification key with a reference based on a numeric value. The value is converted to a reference of
-     * the appropriate length using {@linkcode NUMERIC_CREATOR}.
-     *
-     * @param value
-     * Numeric value.
-     *
-     * @param sparse
-     * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Identification key.
-     */
-    create: (value: number, sparse?: boolean) => string;
-
-    /**
-     * Create a sequence of identification keys with references based on a sequence of numeric values. The values are
-     * converted to references of the appropriate length using {@linkcode NUMERIC_CREATOR}. References are created with
-     * values from `startValue` to `startValue + count - 1`.
-     *
-     * The implementation uses {@link CharacterSetCreator.createSequence}, so the values are created only as needed.
-     *
-     * @param startValue
-     * Start numeric value.
-     *
-     * @param count
-     * Count of identification keys to create.
-     *
-     * @param sparse
-     * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Iterable iterator over created identification keys.
-     */
-    createSequence: (startValue: number, count: number, sparse?: boolean) => IterableIterator<string>;
-
-    /**
-     * Create multiple identification keys with references based on numeric values. The values are converted to
-     * references of the appropriate length using {@linkcode NUMERIC_CREATOR}.
-     *
-     * The implementation uses {@link CharacterSetCreator.createMultiple}, so the values are created only as needed.
-     *
-     * @param valuesSource
-     * Source of values.
-     *
-     * @param sparse
-     * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Iterable iterator over created identification keys.
-     */
-    createMultiple: (valuesSource: IterationSource<number>, sparse?: boolean) => IterableIterator<string>;
+    create: {
+        /**
+         * Create an identification key with a reference based on a numeric value. The value is converted to a reference of
+         * the appropriate length using {@linkcode NUMERIC_CREATOR}.
+         *
+         * @param value
+         * Numeric value.
+         *
+         * @param sparse
+         * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
+         *
+         * @returns
+         * Identification key.
+         */
+        (value: number | bigint, sparse?: boolean): string;
+
+        /**
+         * Create identification keys with references based on numeric values. The values are converted to references of
+         * the appropriate length using {@linkcode NUMERIC_CREATOR}.
+         *
+         * @param values
+         * Numeric values.
+         *
+         * @param sparse
+         * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
+         *
+         * @returns
+         * Identification keys.
+         */
+        (values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
+    };
 
     /**
      * Create all identification keys for the prefix from `0` to `capacity - 1`.
@@ -1122,8 +1153,6 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
      *
      * @param prefix
      * Prefix within prefix manager to use to calculate reference length.
-     *
-     * @throws Error
      */
     protected override init(prefixManager: PrefixManager, prefix: string): void {
         super.init(prefixManager, prefix, 1);
@@ -1134,6 +1163,9 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
 
     abstract get leaderType(): LeaderType;
 
+    /**
+     * @inheritDoc
+     */
     get capacity(): number {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         return this._capacity!;
@@ -1168,16 +1200,19 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
         return partialIdentificationKey + checkDigit(partialIdentificationKey);
     }
 
-    create(value: number, sparse = false): string {
-        return NUMERIC_CREATOR.create(this.referenceLength, value, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
-    }
+    /**
+     * @inheritDoc
+     */
+    create(value: number | bigint, sparse?: boolean): string;
 
-    createSequence(startValue: number, count: number, sparse = false): IterableIterator<string> {
-        return NUMERIC_CREATOR.createSequence(this.referenceLength, startValue, count, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
-    }
+    /**
+     * @inheritDoc
+     */
+    create(values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
 
-    createMultiple(valuesSource: IterationSource<number>, sparse = false): IterableIterator<string> {
-        return NUMERIC_CREATOR.createMultiple(this.referenceLength, valuesSource, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    create(valueOrValues: number | bigint | Iterable<number | bigint>, sparse = false): string | IterableIterator<string> {
+        return NUMERIC_CREATOR.create(this.referenceLength, valueOrValues, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildIdentificationKey(reference));
     }
 
     /**
@@ -1232,6 +1267,9 @@ abstract class AbstractNumericIdentificationKeyCreator extends AbstractIdentific
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     createAll(): IterableIterator<string> {
         const hasExtensionDigit = this.leaderType === LeaderType.ExtensionDigit;
         const prefix = this.prefix;
@@ -1285,26 +1323,11 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
         this.init(prefixManager, prefixManager.prefix);
     }
 
-    override get prefix(): string {
-        return this.prefixManager.prefix;
-    }
-
     /**
-     * Build a GTIN-14 from an indicator digit, the prefix, and a reference.
-     *
-     * @param indicatorDigit
-     * Indicator digit.
-     *
-     * @param reference
-     * Reference.
-     *
-     * @returns
-     * GTIN-14.
+     * @inheritDoc
      */
-    private buildGTIN14(indicatorDigit: string, reference: string): string {
-        const partialIdentificationKey = indicatorDigit + this.prefixManager.gs1CompanyPrefix + reference;
-
-        return partialIdentificationKey + checkDigit(partialIdentificationKey);
+    override get prefix(): string {
+        return this.prefixManager.prefix;
     }
 
     /**
@@ -1315,7 +1338,7 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      * Indicator digit.
      *
      * @param value
-     * Numeric value.
+     * Numeric value of the reference.
      *
      * @param sparse
      * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
@@ -1323,51 +1346,19 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      * @returns
      * GTIN-14.
      */
-    createGTIN14(indicatorDigit: string, value: number, sparse = false): string {
-        NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.REQUIRED_INDICATOR_DIGIT_VALIDATION);
-
-        return NUMERIC_CREATOR.create(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, value, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildGTIN14(indicatorDigit, reference));
-    }
-
-    /**
-     * Create a sequence of GTIN-14s with an indicator digit and references based on a sequence of numeric values.
-     * The values are converted to references of the appropriate length using {@linkcode NUMERIC_CREATOR}. References
-     * are created with values from `startValue` to `startValue + count - 1`.
-     *
-     * The implementation uses {@link CharacterSetCreator.createSequence}, so the values are created only as needed.
-     *
-     * @param indicatorDigit
-     * Indicator digit.
-     *
-     * @param startValue
-     * Start numeric value.
-     *
-     * @param count
-     * Count of identification keys to create.
-     *
-     * @param sparse
-     * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Iterable iterator over created GTIN-14s.
-     */
-    createGTIN14Sequence(indicatorDigit: string, startValue: number, count: number, sparse = false): IterableIterator<string> {
-        NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.REQUIRED_INDICATOR_DIGIT_VALIDATION);
-
-        return NUMERIC_CREATOR.createSequence(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, startValue, count, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildGTIN14(indicatorDigit, reference));
-    }
+    createGTIN14(indicatorDigit: string, value: number | bigint, sparse?: boolean): string;
 
     /**
      * Create multiple GTIN-14s with an indicator digit and references based on numeric values. The values are converted
      * to references of the appropriate length using {@linkcode NUMERIC_CREATOR}.
      *
-     * The implementation uses {@link CharacterSetCreator.createMultiple}, so the values are created only as needed.
+     * The implementation uses {@link CharacterSetCreator.create}, so the values are created only as needed.
      *
      * @param indicatorDigit
      * Indicator digit.
      *
-     * @param valuesSource
-     * Source of values.
+     * @param values
+     * Values.
      *
      * @param sparse
      * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
@@ -1375,10 +1366,17 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      * @returns
      * Iterable iterator over created GTIN-14s.
      */
-    createGTIN14Multiple(indicatorDigit: string, valuesSource: IterationSource<number>, sparse = false): IterableIterator<string> {
+    createGTIN14(indicatorDigit: string, values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    createGTIN14(indicatorDigit: string, valueOrValues: number | bigint | Iterable<number | bigint>, sparse = false): string | IterableIterator<string> {
         NUMERIC_CREATOR.validate(indicatorDigit, GTINCreator.REQUIRED_INDICATOR_DIGIT_VALIDATION);
 
-        return NUMERIC_CREATOR.createMultiple(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, valuesSource, Exclusion.None, sparse ? this.tweak : undefined, reference => this.buildGTIN14(indicatorDigit, reference));
+        return NUMERIC_CREATOR.create(GTINType.GTIN13 - this.prefixManager.gs1CompanyPrefix.length - 1, valueOrValues, Exclusion.None, sparse ? this.tweak : undefined, (reference) => {
+            const partialIdentificationKey = indicatorDigit + this.prefixManager.gs1CompanyPrefix + reference;
+
+            return partialIdentificationKey + checkDigit(partialIdentificationKey);
+        });
     }
 
     /**
@@ -1389,8 +1387,6 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      *
      * @returns
      * Zero-suppressed GTIN-12.
-     *
-     * @throws RangeError
      */
     static zeroSuppress(gtin12: string): string {
         GTIN12_VALIDATOR.validate(gtin12);
@@ -1466,8 +1462,6 @@ export class GTINCreator extends Mixin(GTINValidator, AbstractNumericIdentificat
      *
      * @returns
      * Normalized GTIN.
-     *
-     * @throws RangeError
      */
     static normalize(gtin: string): string {
         const gtinLength = gtin.length;
@@ -1615,11 +1609,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key.
      */
-    private concatenateValidated(baseIdentificationKey: string, serialComponent: string): string {
-        this.serialComponentCreator.validate(serialComponent, this.serialComponentValidation);
-
-        return baseIdentificationKey + serialComponent;
-    }
+    private concatenateValidated(baseIdentificationKey: string, serialComponent: string): string;
 
     /**
      * Concatenate a validated base identification key with multiple serial components.
@@ -1627,14 +1617,27 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @param baseIdentificationKey
      * Base identification key.
      *
-     * @param serialComponentsSource
-     * Source of serial components.
+     * @param serialComponents
+     * Serial components.
      *
      * @returns
      * Serialized identification keys.
      */
-    private concatenateValidatedMultiple(baseIdentificationKey: string, serialComponentsSource: IterationSource<string>): IterableIterator<string> {
-        return IterationHelper.from(serialComponentsSource).map(serialComponent => this.concatenateValidated(baseIdentificationKey, serialComponent));
+    private concatenateValidated(baseIdentificationKey: string, serialComponents: Iterable<string>): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    private concatenateValidated(baseIdentificationKey: string, serialComponent: string | Iterable<string>): string | IterableIterator<string> {
+        let result: string | IterableIterator<string>;
+
+        if (typeof serialComponent === "string") {
+            this.serialComponentCreator.validate(serialComponent, this.serialComponentValidation);
+
+            result = baseIdentificationKey + serialComponent;
+        } else {
+            result = Iterator.from(serialComponent).map(serialComponent => this.concatenateValidated(baseIdentificationKey, serialComponent));
+        }
+
+        return result;
     }
 
     /**
@@ -1642,7 +1645,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * value is converted to a reference of the appropriate length using {@linkcode NUMERIC_CREATOR}.
      *
      * @param value
-     * Numeric value.
+     * Numeric value of the references.
      *
      * @param serialComponent
      * Serial component.
@@ -1653,9 +1656,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key.
      */
-    createSerialized(value: number, serialComponent: string, sparse = false): string {
-        return this.concatenateValidated(this.create(value, sparse), serialComponent);
-    }
+    createSerialized(value: number, serialComponent: string, sparse?: boolean): string;
 
     /**
      * Create multiple serialized identification keys with a reference based on a numeric value and multiple serial
@@ -1664,8 +1665,8 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @param value
      * Numeric value.
      *
-     * @param serialComponentsSource
-     * Source of serial components.
+     * @param serialComponents
+     * Serial components.
      *
      * @param sparse
      * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
@@ -1673,8 +1674,11 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification keys.
      */
-    createMultipleSerialized(value: number, serialComponentsSource: IterationSource<string>, sparse = false): IterableIterator<string> {
-        return this.concatenateValidatedMultiple(this.create(value, sparse), serialComponentsSource);
+    createSerialized(value: number, serialComponents: Iterable<string>, sparse?: boolean): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    createSerialized(value: number, serialComponent: string | Iterable<string>, sparse = false): string | IterableIterator<string> {
+        return this.concatenateValidated(this.create(value, sparse), serialComponent);
     }
 
     /**
@@ -1689,11 +1693,7 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @returns
      * Serialized identification key.
      */
-    concatenate(baseIdentificationKey: string, serialComponent: string): string {
-        this.validate(baseIdentificationKey);
-
-        return this.concatenateValidated(baseIdentificationKey, serialComponent);
-    }
+    concatenate(baseIdentificationKey: string, serialComponent: string): string;
 
     /**
      * Concatenate a base identification key with multiple serial components.
@@ -1701,16 +1701,19 @@ export class SerializableNumericIdentificationKeyCreator extends Mixin(Serializa
      * @param baseIdentificationKey
      * Base identification key.
      *
-     * @param serialComponentsSource
-     * Source of serial components.
+     * @param serialComponents
+     * Serial components.
      *
      * @returns
      * Serialized identification keys.
      */
-    concatenateMultiple(baseIdentificationKey: string, serialComponentsSource: IterationSource<string>): IterableIterator<string> {
+    concatenate(baseIdentificationKey: string, serialComponents: Iterable<string>): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    concatenate(baseIdentificationKey: string, serialComponent: string | Iterable<string>): string | IterableIterator<string> {
         this.validate(baseIdentificationKey);
 
-        return this.concatenateValidatedMultiple(baseIdentificationKey, serialComponentsSource);
+        return this.concatenateValidated(baseIdentificationKey, serialComponent);
     }
 }
 
@@ -1766,25 +1769,34 @@ export class NonNumericIdentificationKeyCreator extends Mixin(NonNumericIdentifi
      * @returns
      * Identification key.
      */
-    create(reference: string): string {
-        this.referenceValidator.validate(reference, this._referenceValidation);
-
-        const partialIdentificationKey = this.prefix + reference;
-
-        return this.requiresCheckCharacterPair ? partialIdentificationKey + checkCharacterPair(partialIdentificationKey) : partialIdentificationKey;
-    }
+    create(reference: string): string;
 
     /**
      * Create multiple identification keys with references.
      *
-     * @param referencesSource
-     * Source of references.
+     * @param references
+     * References.
      *
      * @returns
      * Identification keys.
      */
-    createMultiple(referencesSource: IterationSource<string>): IterableIterator<string> {
-        return IterationHelper.from(referencesSource).map(reference => this.create(reference));
+    create(references: Iterable<string>): IterableIterator<string>;
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    create(referenceOrReferences: string | Iterable<string>): string | IterableIterator<string> {
+        let result: string | IterableIterator<string>;
+
+        if (typeof referenceOrReferences === "string") {
+            this.referenceValidator.validate(referenceOrReferences, this._referenceValidation);
+
+            const partialIdentificationKey = this.prefix + referenceOrReferences;
+
+            result = this.requiresCheckCharacterPair ? partialIdentificationKey + checkCharacterPair(partialIdentificationKey) : partialIdentificationKey;
+        } else {
+            result = Iterator.from(referenceOrReferences).map(reference => this.create(reference));
+        }
+
+        return result;
     }
 }
 
@@ -2124,8 +2136,6 @@ export class PrefixManager {
      *
      * @param positionOffset
      * Position offset within a larger string.
-     *
-     * @throws RangeError
      */
     static validatePrefix(prefixType: PrefixType, allowUPCCompanyPrefix: boolean, allowGS18Prefix: boolean, prefix: string, isFromIdentificationKey = false, isNumericIdentificationKey = false, positionOffset?: number): void {
         let baseValidation: CharacterSetValidation;
@@ -2205,8 +2215,6 @@ export class PrefixManager {
      *
      * @returns
      * Identification key creator.
-     *
-     * @throws RangeError
      */
     private getIdentificationKeyCreator<T extends IdentificationKeyCreator>(identificationKeyType: IdentificationKeyType, constructorCallback: () => T): T {
         let creator = this._identificationKeyCreatorsMap.get(identificationKeyType) as (T | undefined);

package/test/check.test.ts

@@ -1,6 +1,6 @@
+import { I18NEnvironment, i18nInit } from "@aidc-toolkit/core";
 import { NUMERIC_CREATOR } from "@aidc-toolkit/utility";
 import { describe, expect, test } from "vitest";
-import { I18NEnvironment, i18nInit } from "../../core/dist/index.js";
 import {
     checkCharacterPair,
     checkDigit,

package/test/idkey.test.ts

@@ -1,5 +1,5 @@
 import { I18NEnvironment, i18nInit } from "@aidc-toolkit/core";
-import { CharacterSetCreator, Exclusion, IterationHelper, NUMERIC_CREATOR } from "@aidc-toolkit/utility";
+import { CharacterSetCreator, Exclusion, NUMERIC_CREATOR, Sequencer } from "@aidc-toolkit/utility";
 import { describe, expect, test } from "vitest";
 import {
     AI39_CREATOR,
@@ -373,8 +373,8 @@ describe("Sparse creation", () => {
 
     prefixManager.tweakFactor = 0;
 
-    const sparseGTINs = Array.from(prefixManager.gtinCreator.createSequence(0, 10, true));
-    const straightGTINs = Array.from(prefixManager.gtinCreator.createSequence(0, 10));
+    const sparseGTINs = Array.from(prefixManager.gtinCreator.create(new Sequencer(0, 10), true));
+    const straightGTINs = Array.from(prefixManager.gtinCreator.create(new Sequencer(0, 10)));
 
     test("Tweak factor 0", () => {
         expect(sparseGTINs).toStrictEqual(straightGTINs);
@@ -421,11 +421,11 @@ function testNumericIdentificationKeyCreator(creator: NumericIdentificationKeyCr
             expect(creator.referenceLength).toBe(referenceLength);
             expect(creator.capacity).toBe(Number(CharacterSetCreator.powerOf10(referenceLength)));
 
-            const sequenceIterator = creator.createSequence(0, referenceCount)[Symbol.iterator]();
+            const sequenceIterator = Iterator.from(creator.create(new Sequencer(0, referenceCount)));
 
             let allCount = 0;
 
-            IterationHelper.from(creator.createAll()).forEach((identificationKey, index) => {
+            Iterator.from(creator.createAll()).forEach((identificationKey, index) => {
                 validate(identificationKey, index, false);
 
                 expect(Number((hasExtensionDigit ? identificationKey.charAt(0) : "") + identificationKey.substring(referenceSubstringStart, referenceSubstringEnd))).toBe(index);
@@ -447,7 +447,7 @@ function testNumericIdentificationKeyCreator(creator: NumericIdentificationKeyCr
                 identificationKeys.push(creator.create(randomValue));
             }
 
-            expect(Array.from(creator.createMultiple(randomValues))).toStrictEqual(identificationKeys);
+            expect(Array.from(creator.create(randomValues))).toStrictEqual(identificationKeys);
         });
 
         test("Sparse", () => {
@@ -460,7 +460,7 @@ function testNumericIdentificationKeyCreator(creator: NumericIdentificationKeyCr
 
             let sequenceCount = 0;
 
-            IterationHelper.from(creator.createSequence(0, sparseReferenceCount, true)).forEach((identificationKey, index) => {
+            Iterator.from(creator.create(new Sequencer(0, sparseReferenceCount), true)).forEach((identificationKey, index) => {
                 validate(identificationKey, index, true);
 
                 sequential = sequential && Number((hasExtensionDigit ? identificationKey.charAt(0) : "") + identificationKey.substring(referenceSubstringStart, referenceSubstringEnd)) === index;
@@ -484,7 +484,7 @@ function testNumericIdentificationKeyCreator(creator: NumericIdentificationKeyCr
                 identificationKeys.push(creator.create(randomValue, true));
             }
 
-            expect(Array.from(creator.createMultiple(randomValues, true))).toStrictEqual(identificationKeys);
+            expect(Array.from(creator.create(randomValues, true))).toStrictEqual(identificationKeys);
         });
 
         test("Validation position", () => {
@@ -555,7 +555,7 @@ function testGTINCreator(creator: GTINCreator): void {
         test("GTIN-14 straight", () => {
             let sequenceCount = 0;
 
-            IterationHelper.from(creator.createGTIN14Sequence("5", 0, referenceCount)).forEach((gtin, index) => {
+            Iterator.from(creator.createGTIN14("5", new Sequencer(0, referenceCount))).forEach((gtin, index) => {
                 expect(Number(gtin.substring(referenceSubstringStart, referenceSubstringEnd))).toBe(index);
 
                 validate(gtin, index, false);
@@ -575,7 +575,7 @@ function testGTINCreator(creator: GTINCreator): void {
                 identificationKeys.push(creator.createGTIN14("5", randomValue));
             }
 
-            expect(Array.from(creator.createGTIN14Multiple("5", randomValues))).toStrictEqual(identificationKeys);
+            expect(Array.from(creator.createGTIN14("5", randomValues))).toStrictEqual(identificationKeys);
         });
 
         test("GTIN-14 sparse", () => {
@@ -588,7 +588,7 @@ function testGTINCreator(creator: GTINCreator): void {
 
             let sequenceCount = 0;
 
-            IterationHelper.from(creator.createGTIN14Sequence("5", 0, sparseReferenceCount, true)).forEach((gtin, index) => {
+            Iterator.from(creator.createGTIN14("5", new Sequencer(0, sparseReferenceCount), true)).forEach((gtin, index) => {
                 sequential = sequential && Number(gtin.substring(referenceSubstringStart, referenceSubstringEnd)) === index;
 
                 validate(gtin, index, true);
@@ -612,7 +612,7 @@ function testGTINCreator(creator: GTINCreator): void {
                 identificationKeys.push(creator.createGTIN14("5", randomValue, true));
             }
 
-            expect(Array.from(creator.createGTIN14Multiple("5", randomValues, true))).toStrictEqual(identificationKeys);
+            expect(Array.from(creator.createGTIN14("5", randomValues, true))).toStrictEqual(identificationKeys);
         });
 
         if (creator.gtinType === GTINType.GTIN12) {
@@ -878,8 +878,8 @@ function testSerializableNumericIdentificationKeyCreator(creator: SerializableNu
 
             expect(creator.createSerialized(0, serial, true)).toBe(serializedIdentificationKey);
             expect(creator.concatenate(identificationKey, serial)).toBe(serializedIdentificationKey);
-            expect(Array.from(creator.createMultipleSerialized(0, serials, true))).toStrictEqual(serializedIdentificationKeys);
-            expect(Array.from(creator.concatenateMultiple(identificationKey, serials))).toStrictEqual(serializedIdentificationKeys);
+            expect(Array.from(creator.createSerialized(0, serials, true))).toStrictEqual(serializedIdentificationKeys);
+            expect(Array.from(creator.concatenate(identificationKey, serials))).toStrictEqual(serializedIdentificationKeys);
 
             const fullLengthSerial = "0".repeat(creator.serialComponentLength);
             const fullLengthPlusOneSerial = fullLengthSerial + "0";
@@ -887,12 +887,12 @@ function testSerializableNumericIdentificationKeyCreator(creator: SerializableNu
 
             expect(() => creator.createSerialized(0, fullLengthSerial, true)).not.toThrow(RangeError);
             expect(() => creator.concatenate(identificationKey, fullLengthSerial)).not.toThrow(RangeError);
-            expect(() => Array.from(creator.createMultipleSerialized(0, [...serials, fullLengthSerial], true))).not.toThrow(RangeError);
-            expect(() => Array.from(creator.concatenateMultiple(identificationKey, [...serials, fullLengthSerial]))).not.toThrow(RangeError);
+            expect(() => Array.from(creator.createSerialized(0, [...serials, fullLengthSerial], true))).not.toThrow(RangeError);
+            expect(() => Array.from(creator.concatenate(identificationKey, [...serials, fullLengthSerial]))).not.toThrow(RangeError);
             expect(() => creator.createSerialized(0, fullLengthPlusOneSerial, true)).toThrow(fullLengthPlusOneSerialErrorMessage);
             expect(() => creator.concatenate(identificationKey, fullLengthPlusOneSerial)).toThrow(fullLengthPlusOneSerialErrorMessage);
-            expect(() => Array.from(creator.createMultipleSerialized(0, [...serials, fullLengthPlusOneSerial], true))).toThrow(fullLengthPlusOneSerialErrorMessage);
-            expect(() => Array.from(creator.concatenateMultiple(identificationKey, [...serials, fullLengthPlusOneSerial]))).toThrow(fullLengthPlusOneSerialErrorMessage);
+            expect(() => Array.from(creator.createSerialized(0, [...serials, fullLengthPlusOneSerial], true))).toThrow(fullLengthPlusOneSerialErrorMessage);
+            expect(() => Array.from(creator.concatenate(identificationKey, [...serials, fullLengthPlusOneSerial]))).toThrow(fullLengthPlusOneSerialErrorMessage);
 
             let invalidSerial: string;
 
@@ -914,8 +914,8 @@ function testSerializableNumericIdentificationKeyCreator(creator: SerializableNu
 
             expect(() => creator.createSerialized(0, invalidSerial, true)).toThrow(invalidSerialErrorMessage);
             expect(() => creator.concatenate(identificationKey, invalidSerial)).toThrow(invalidSerialErrorMessage);
-            expect(() => Array.from(creator.createMultipleSerialized(0, [...serials, invalidSerial], true))).toThrow(invalidSerialErrorMessage);
-            expect(() => Array.from(creator.concatenateMultiple(identificationKey, [...serials, invalidSerial]))).toThrow(invalidSerialErrorMessage);
+            expect(() => Array.from(creator.createSerialized(0, [...serials, invalidSerial], true))).toThrow(invalidSerialErrorMessage);
+            expect(() => Array.from(creator.concatenate(identificationKey, [...serials, invalidSerial]))).toThrow(invalidSerialErrorMessage);
         });
     });
 }
@@ -937,12 +937,12 @@ function testNonNumericIdentificationKeyCreator<T extends NonNumericIdentificati
 
             let sequenceCount = 0;
 
-            IterationHelper.from(creator.createMultiple(creator.referenceCreator.createSequence(TEST_REFERENCE_LENGTH, 0, referenceCount))).forEach((identificationKey, index) => {
+            Iterator.from(creator.create(creator.referenceCreator.create(TEST_REFERENCE_LENGTH, new Sequencer(0, referenceCount)))).forEach((identificationKey, index) => {
                 expect(() => {
                     creator.validate(identificationKey);
                 }).not.toThrow(RangeError);
 
-                expect(Number(creator.referenceCreator.value(identificationKey.substring(referenceSubstringStart, referenceSubstringEnd)))).toBe(index);
+                expect(Number(creator.referenceCreator.valueFor(identificationKey.substring(referenceSubstringStart, referenceSubstringEnd)))).toBe(index);
 
                 expect(identificationKey.length).toBeLessThanOrEqual(creator.length);
                 expect(identificationKey.substring(0, prefixLength)).toBe(prefix);
@@ -961,14 +961,14 @@ function testNonNumericIdentificationKeyCreator<T extends NonNumericIdentificati
 
             let sequenceCount = 0;
 
-            IterationHelper.from(creator.createMultiple(creator.referenceCreator.createSequence(TEST_REFERENCE_LENGTH, 0, referenceCount, Exclusion.None, 123456n))).forEach((identificationKey, index) => {
+            Iterator.from(creator.create(creator.referenceCreator.create(TEST_REFERENCE_LENGTH, new Sequencer(0, referenceCount), Exclusion.None, 123456n))).forEach((identificationKey, index) => {
                 expect(() => {
                     creator.validate(identificationKey);
                 }).not.toThrow(RangeError);
 
-                expect(Number(creator.referenceCreator.value(identificationKey.substring(referenceSubstringStart, referenceSubstringEnd), Exclusion.None, 123456n))).toBe(index);
+                expect(Number(creator.referenceCreator.valueFor(identificationKey.substring(referenceSubstringStart, referenceSubstringEnd), Exclusion.None, 123456n))).toBe(index);
 
-                sequential = sequential && Number(creator.referenceCreator.value(identificationKey.substring(referenceSubstringStart, referenceSubstringEnd))) === index;
+                sequential = sequential && Number(creator.referenceCreator.valueFor(identificationKey.substring(referenceSubstringStart, referenceSubstringEnd))) === index;
 
                 expect(identificationKey.length).toBeLessThanOrEqual(creator.length);
                 expect(identificationKey.substring(0, prefixLength)).toBe(prefix);

package/typedoc.json

@@ -6,5 +6,6 @@
   "name": "GS1",
   "entryPoints": [
     "src/index.ts"
-  ]
+  ],
+  "gitRevision": "main"
 }