@aidc-toolkit/gs1 0.9.5 → 0.9.7-beta

package/dist/index.d.cts

@@ -1,6 +1,8 @@
-import { CharacterSetCreator, StringValidation, StringValidator, CharacterSetValidator, CharacterSetValidation, Exclusion } from '@aidc-toolkit/utility';
+import { CharacterSetCreator, StringValidation, StringValidator, CharacterSetValidation, Exclusion, TransformerInput, TransformerOutput } from '@aidc-toolkit/utility';
 import * as ts_mixer_dist_types_types_js from 'ts-mixer/dist/types/types.js';
 
+declare const gs1NS = "aidct_gs1";
+
 /**
  * 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 Exclusion.AllNumeric}.
@@ -165,7 +167,7 @@ declare enum PrefixType {
  * Character set supported by the reference portion of an identification key or the serial component of a numeric
  * identification key.
  */
-declare enum CharacterSet {
+declare enum ContentCharacterSet {
     /**
      * Numeric.
      */
@@ -212,11 +214,11 @@ interface IdentificationKeyValidator<V extends IdentificationKeyValidation = Ide
     /**
      * Get the reference character set.
      */
-    get referenceCharacterSet(): CharacterSet;
+    get referenceCharacterSet(): ContentCharacterSet;
     /**
      * Get the reference validator.
      */
-    get referenceValidator(): CharacterSetValidator;
+    get referenceCreator(): CharacterSetCreator;
     /**
      * Validate an identification key and throw an error if validation fails.
      *
@@ -250,19 +252,19 @@ declare abstract class AbstractIdentificationKeyValidator<V extends Identificati
      */
     private readonly _referenceCharacterSet;
     /**
-     * Reference validator.
+     * Reference creator.
      */
-    private readonly _referenceValidator;
+    private readonly _referenceCreator;
     /**
-     * Get the character set validator for a character set.
+     * Get the character set creator for a character set.
      *
      * @param characterSet
      * Character set.
      *
      * @returns
-     * Character set validator.
+     * Character set creator.
      */
-    protected static validatorFor(characterSet: CharacterSet): CharacterSetValidator;
+    protected static creatorFor(characterSet: ContentCharacterSet): CharacterSetCreator;
     /**
      * Constructor.
      *
@@ -278,7 +280,7 @@ declare abstract class AbstractIdentificationKeyValidator<V extends Identificati
      * @param referenceCharacterSet
      * Reference character set.
      */
-    protected constructor(identificationKeyType: IdentificationKeyType, prefixType: PrefixType, length: number, referenceCharacterSet: CharacterSet);
+    protected constructor(identificationKeyType: IdentificationKeyType, prefixType: PrefixType, length: number, referenceCharacterSet: ContentCharacterSet);
     /**
      * @inheritDoc
      */
@@ -294,11 +296,11 @@ declare abstract class AbstractIdentificationKeyValidator<V extends Identificati
     /**
      * @inheritDoc
      */
-    get referenceCharacterSet(): CharacterSet;
+    get referenceCharacterSet(): ContentCharacterSet;
     /**
      * @inheritDoc
      */
-    get referenceValidator(): CharacterSetValidator;
+    get referenceCreator(): CharacterSetCreator;
     /**
      * Pad an identification key on the left with zero-value character for validation purposes. This is done to align an
      * identification key with a position offset for any error message that may be thrown by the reference validator.
@@ -514,9 +516,9 @@ declare class SerializableNumericIdentificationKeyValidator extends NonGTINNumer
      */
     private readonly _serialComponentValidation;
     /**
-     * Serial component validator.
+     * Serial component creator.
      */
-    private readonly _serialComponentValidator;
+    private readonly _serialComponentCreator;
     /**
      * Constructor.
      *
@@ -532,7 +534,7 @@ declare class SerializableNumericIdentificationKeyValidator extends NonGTINNumer
      * @param serialComponentCharacterSet
      * Serial component character set.
      */
-    constructor(identificationKeyType: IdentificationKeyType, length: number, serialComponentLength: number, serialComponentCharacterSet: CharacterSet);
+    constructor(identificationKeyType: IdentificationKeyType, length: number, serialComponentLength: number, serialComponentCharacterSet: ContentCharacterSet);
     /**
      * Get the serial component length.
      */
@@ -540,15 +542,15 @@ declare class SerializableNumericIdentificationKeyValidator extends NonGTINNumer
     /**
      * Get the serial component character set.
      */
-    get serialComponentCharacterSet(): CharacterSet;
+    get serialComponentCharacterSet(): ContentCharacterSet;
     /**
      * Get the serial component validation parameters.
      */
     protected get serialComponentValidation(): CharacterSetValidation;
     /**
-     * Get the serial component validator.
+     * Get the serial component creator.
      */
-    get serialComponentValidator(): CharacterSetValidator;
+    get serialComponentCreator(): CharacterSetCreator;
     /**
      * @inheritDoc
      */
@@ -591,7 +593,7 @@ declare class NonNumericIdentificationKeyValidator extends AbstractIdentificatio
      * @param requiresCheckCharacterPair
      * True if the identification key requires a check character pair.
      */
-    constructor(identificationKeyType: IdentificationKeyType, length: number, referenceCharacterSet: CharacterSet, requiresCheckCharacterPair?: boolean);
+    constructor(identificationKeyType: IdentificationKeyType, length: number, referenceCharacterSet: ContentCharacterSet, requiresCheckCharacterPair?: boolean);
     /**
      * Determine if the identification key requires a check character pair.
      */
@@ -674,10 +676,6 @@ declare const GMN_VALIDATOR: NonNumericIdentificationKeyValidator;
  * Keys are created based on a prefix defined in a prefix manager to which the identification key creator is bound.
  */
 interface IdentificationKeyCreator extends IdentificationKeyValidator {
-    /**
-     * Get the reference creator.
-     */
-    get referenceCreator(): CharacterSetCreator;
     /**
      * Get the prefix manager to which this identification key creator is bound.
      */
@@ -722,12 +720,8 @@ declare abstract class AbstractIdentificationKeyCreator implements Identificatio
     abstract get identificationKeyType(): IdentificationKeyType;
     abstract get prefixType(): PrefixType;
     abstract get length(): number;
-    abstract get referenceCharacterSet(): CharacterSet;
-    abstract get referenceValidator(): CharacterSetValidator;
-    /**
-     * @inheritDoc
-     */
-    get referenceCreator(): CharacterSetCreator;
+    abstract get referenceCharacterSet(): ContentCharacterSet;
+    abstract get referenceCreator(): CharacterSetCreator;
     /**
      * @inheritDoc
      */
@@ -750,36 +744,20 @@ interface NumericIdentificationKeyCreator extends NumericIdentificationKeyValida
      * Get the capacity (`10**referenceLength`).
      */
     get capacity(): number;
-    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 identification key(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}.
+     *
+     * @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
+     * Identification key(s).
+     */
+    create: <T extends TransformerInput<number | bigint>>(valueOrValues: T, sparse?: boolean) => TransformerOutput<T, string>;
     /**
      * Create all identification keys for the prefix from `0` to `capacity - 1`.
      *
@@ -839,11 +817,7 @@ declare abstract class AbstractNumericIdentificationKeyCreator extends AbstractI
     /**
      * @inheritDoc
      */
-    create(value: number | bigint, sparse?: boolean): string;
-    /**
-     * @inheritDoc
-     */
-    create(values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
+    create<T extends TransformerInput<number | bigint>>(valueOrValues: T, sparse?: boolean): TransformerOutput<T, string>;
     /**
      * Create all identification keys from a partial identification key. Call is recursive until remaining reference
      * length is 0.
@@ -901,41 +875,22 @@ declare class GTINCreator extends GTINCreator_base {
      */
     get prefix(): string;
     /**
-     * Create a GTIN-14 with an indicator digit and a reference based on a numeric value. The value is converted to a
-     * reference of the appropriate length using {@linkcode NUMERIC_CREATOR}.
-     *
-     * @param indicatorDigit
-     * Indicator digit.
-     *
-     * @param value
-     * Numeric value of the reference.
-     *
-     * @param sparse
-     * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * GTIN-14.
-     */
-    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.create}, so the values are created only as needed.
+     * Create GTIN-14(s) with an indicator digit and reference(s) based on numeric value(s). The value(s) is/are
+     * converted to reference(s) of the appropriate length using {@linkcode NUMERIC_CREATOR}.
      *
      * @param indicatorDigit
      * Indicator digit.
      *
-     * @param values
-     * Values.
+     * @param valueOrValues
+     * Numeric value(s).
      *
      * @param sparse
-     * If true, the values are mapped to a sparse sequence resistant to discovery. Default is false.
+     * If true, the value(s) is/are mapped to a sparse sequence resistant to discovery. Default is false.
      *
      * @returns
-     * Iterable iterator over created GTIN-14s.
+     * GTIN-14(s).
      */
-    createGTIN14(indicatorDigit: string, values: Iterable<number | bigint>, sparse?: boolean): IterableIterator<string>;
+    createGTIN14<T extends TransformerInput<number | bigint>>(indicatorDigit: string, valueOrValues: T, sparse?: boolean): TransformerOutput<T, string>;
     /**
      * Zero suppress a GTIN-12.
      *
@@ -1021,50 +976,29 @@ declare class SerializableNumericIdentificationKeyCreator extends SerializableNu
      * @param serialComponentCharacterSet
      * Serial component character set.
      */
-    constructor(prefixManager: PrefixManager, identificationKeyType: IdentificationKeyType, length: number, serialComponentLength: number, serialComponentCharacterSet: CharacterSet);
+    constructor(prefixManager: PrefixManager, identificationKeyType: IdentificationKeyType, length: number, serialComponentLength: number, serialComponentCharacterSet: ContentCharacterSet);
     /**
-     * Get the serial component creator.
-     */
-    get serialComponentCreator(): CharacterSetCreator;
-    /**
-     * Concatenate a validated base identification key with a serial component.
+     * Concatenate a validated base identification key with serial component(s).
      *
      * @param baseIdentificationKey
      * Base identification key.
      *
-     * @param serialComponent
-     * Serial component.
+     * @param serialComponentOrComponents
+     * Serial component(s).
      *
      * @returns
-     * Serialized identification key.
+     * Serialized identification key(s).
      */
     private concatenateValidated;
     /**
-     * Create a serialized identification key with a reference based on a numeric value and a serial component. The
-     * value is converted to a reference of the appropriate length using {@linkcode NUMERIC_CREATOR}.
+     * Create serialized identification key(s) with a reference based on a numeric value concatenated with serial
+     * component(s). The value is converted to a reference of the appropriate length using {@linkcode NUMERIC_CREATOR}.
      *
      * @param value
-     * Numeric value of the references.
-     *
-     * @param serialComponent
-     * Serial component.
-     *
-     * @param sparse
-     * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
-     *
-     * @returns
-     * Serialized identification key.
-     */
-    createSerialized(value: number, serialComponent: string, sparse?: boolean): string;
-    /**
-     * Create multiple serialized identification keys with a reference based on a numeric value and multiple serial
-     * components. The value is converted to a reference of the appropriate length using {@linkcode NUMERIC_CREATOR}.
-     *
-     * @param value
-     * Numeric value.
+     * Numeric value of the reference.
      *
-     * @param serialComponents
-     * Serial components.
+     * @param serialComponentOrComponents
+     * Serial component(s).
      *
      * @param sparse
      * If true, the value is mapped to a sparse sequence resistant to discovery. Default is false.
@@ -1072,33 +1006,20 @@ declare class SerializableNumericIdentificationKeyCreator extends SerializableNu
      * @returns
      * Serialized identification keys.
      */
-    createSerialized(value: number, serialComponents: Iterable<string>, sparse?: boolean): IterableIterator<string>;
-    /**
-     * Concatenate a base identification key with a serial component.
-     *
-     * @param baseIdentificationKey
-     * Base identification key.
-     *
-     * @param serialComponent
-     * Serial component.
-     *
-     * @returns
-     * Serialized identification key.
-     */
-    concatenate(baseIdentificationKey: string, serialComponent: string): string;
+    createSerialized<T extends TransformerInput<string>>(value: number, serialComponentOrComponents: T, sparse?: boolean): TransformerOutput<T, string>;
     /**
-     * Concatenate a base identification key with multiple serial components.
+     * Concatenate a base identification key with serial component(s).
      *
      * @param baseIdentificationKey
      * Base identification key.
      *
-     * @param serialComponents
-     * Serial components.
+     * @param serialComponentOrComponents
+     * Serial component(s).
      *
      * @returns
-     * Serialized identification keys.
+     * Serialized identification key(s).
      */
-    concatenate(baseIdentificationKey: string, serialComponents: Iterable<string>): IterableIterator<string>;
+    concatenate<T extends TransformerInput<string>>(baseIdentificationKey: string, serialComponentOrComponents: T): TransformerOutput<T, string>;
 }
 declare const NonNumericIdentificationKeyCreator_base: ts_mixer_dist_types_types_js.Class<any[], NonNumericIdentificationKeyValidator & AbstractIdentificationKeyCreator, typeof NonNumericIdentificationKeyValidator & typeof AbstractIdentificationKeyCreator>;
 /**
@@ -1128,27 +1049,21 @@ declare class NonNumericIdentificationKeyCreator extends NonNumericIdentificatio
      * @param requiresCheckCharacterPair
      * True if the identification key requires a check character pair.
      */
-    constructor(prefixManager: PrefixManager, identificationKeyType: IdentificationKeyType, length: number, referenceCharacterSet: CharacterSet, requiresCheckCharacterPair?: boolean);
+    constructor(prefixManager: PrefixManager, identificationKeyType: IdentificationKeyType, length: number, referenceCharacterSet: ContentCharacterSet, requiresCheckCharacterPair?: boolean);
     /**
-     * Create an identification key with a reference.
-     *
-     * @param reference
-     * Reference.
-     *
-     * @returns
-     * Identification key.
+     * Get the reference validation parameters.
      */
-    create(reference: string): string;
+    protected get referenceValidation(): CharacterSetValidation;
     /**
-     * Create multiple identification keys with references.
+     * Create identification key(s) with reference(s).
      *
-     * @param references
-     * References.
+     * @param referenceOrReferences
+     * Reference(s).
      *
      * @returns
-     * Identification keys.
+     * Identification key(s).
      */
-    create(references: Iterable<string>): IterableIterator<string>;
+    create<T extends TransformerInput<string>>(referenceOrReferences: T): TransformerOutput<T, string>;
 }
 /**
  * Prefix manager. This is the core class for identification key creation.
@@ -1433,4 +1348,4 @@ declare class PrefixManager {
     get gmnCreator(): NonNumericIdentificationKeyCreator;
 }
 
-export { AI39_CREATOR, AI82_CREATOR, CPID_VALIDATOR, CharacterSet, GCN_VALIDATOR, GDTI_VALIDATOR, GIAI_VALIDATOR, GINC_VALIDATOR, GLN_VALIDATOR, GMN_VALIDATOR, GRAI_VALIDATOR, GSIN_VALIDATOR, GSRN_VALIDATOR, GTIN12_VALIDATOR, GTIN13_VALIDATOR, GTIN8_VALIDATOR, GTINCreator, GTINLevel, GTINType, GTINValidator, GTIN_VALIDATORS, type IdentificationKeyCreator, IdentificationKeyType, type IdentificationKeyValidation, type IdentificationKeyValidator, LeaderType, NonGTINNumericIdentificationKeyCreator, NonGTINNumericIdentificationKeyValidator, NonNumericIdentificationKeyCreator, type NonNumericIdentificationKeyValidation, NonNumericIdentificationKeyValidator, type NumericIdentificationKeyCreator, type NumericIdentificationKeyValidator, PrefixManager, PrefixType, SSCC_VALIDATOR, SerializableNumericIdentificationKeyCreator, SerializableNumericIdentificationKeyValidator, checkCharacterPair, checkDigit, checkDigitSum, fiveDigitPriceWeightCheckDigit, fourDigitPriceWeightCheckDigit, hasValidCheckCharacterPair, hasValidCheckDigit };
+export { AI39_CREATOR, AI82_CREATOR, CPID_VALIDATOR, ContentCharacterSet, GCN_VALIDATOR, GDTI_VALIDATOR, GIAI_VALIDATOR, GINC_VALIDATOR, GLN_VALIDATOR, GMN_VALIDATOR, GRAI_VALIDATOR, GSIN_VALIDATOR, GSRN_VALIDATOR, GTIN12_VALIDATOR, GTIN13_VALIDATOR, GTIN8_VALIDATOR, GTINCreator, GTINLevel, GTINType, GTINValidator, GTIN_VALIDATORS, type IdentificationKeyCreator, IdentificationKeyType, type IdentificationKeyValidation, type IdentificationKeyValidator, LeaderType, NonGTINNumericIdentificationKeyCreator, NonGTINNumericIdentificationKeyValidator, NonNumericIdentificationKeyCreator, type NonNumericIdentificationKeyValidation, NonNumericIdentificationKeyValidator, type NumericIdentificationKeyCreator, type NumericIdentificationKeyValidator, PrefixManager, PrefixType, SSCC_VALIDATOR, SerializableNumericIdentificationKeyCreator, SerializableNumericIdentificationKeyValidator, checkCharacterPair, checkDigit, checkDigitSum, fiveDigitPriceWeightCheckDigit, fourDigitPriceWeightCheckDigit, gs1NS, hasValidCheckCharacterPair, hasValidCheckDigit };