isahaq-barcode 1.9.0 → 2.0.0

package/src/types/BarcodeTypes.js

@@ -1,128 +1,507 @@
 /**
  * Barcode Types - Supported barcode types and their configurations
+ *
+ * Every type listed here maps to a real symbology encoder (bwip-js / BWIPP),
+ * so `isValid(type) === true` guarantees the type can actually be generated.
  */
 
+/**
+ * Single source of truth for the supported symbologies.
+ *
+ * - `bcid`     bwip-js/BWIPP symbology id used for encoding
+ * - `encode`   extra encoder options required by that symbology
+ * - `category` grouping used by getByCategory()/getCategories()
+ * - `minLength`/`maxLength`/`charset` are used by the Validator
+ */
+const REGISTRY = {
+  // Linear Barcodes
+  code128: {
+    bcid: 'code128',
+    name: 'Code 128',
+    category: 'LINEAR',
+    description: 'Code 128 - High-density linear barcode',
+    minLength: 1,
+    maxLength: 80,
+    charset: 'ASCII',
+  },
+  code128a: {
+    bcid: 'code128',
+    name: 'Code 128 A',
+    category: 'LINEAR',
+    description: 'Code 128 Subset A - Uppercase and control characters',
+    minLength: 1,
+    maxLength: 80,
+    charset: 'ASCII A',
+  },
+  code128b: {
+    bcid: 'code128',
+    name: 'Code 128 B',
+    category: 'LINEAR',
+    description: 'Code 128 Subset B - Full printable ASCII',
+    minLength: 1,
+    maxLength: 80,
+    charset: 'ASCII B',
+  },
+  code128c: {
+    bcid: 'code128',
+    name: 'Code 128 C',
+    category: 'LINEAR',
+    description: 'Code 128 Subset C - Numeric pairs (double density)',
+    minLength: 2,
+    maxLength: 80,
+    charset: 'Numeric',
+  },
+  code128auto: {
+    bcid: 'code128',
+    name: 'Code 128 Auto',
+    category: 'LINEAR',
+    description: 'Code 128 with automatic subset selection',
+    minLength: 1,
+    maxLength: 80,
+    charset: 'ASCII',
+  },
+  code39: {
+    bcid: 'code39',
+    name: 'Code 39',
+    category: 'LINEAR',
+    description: 'Code 39 - Alphanumeric barcode',
+    minLength: 1,
+    maxLength: 43,
+    charset: '0-9, A-Z, space, -.$/+%',
+  },
+  code39extended: {
+    bcid: 'code39ext',
+    name: 'Code 39 Extended',
+    category: 'LINEAR',
+    description: 'Code 39 Extended - Full ASCII via shift characters',
+    minLength: 1,
+    maxLength: 43,
+    charset: 'Extended ASCII',
+  },
+  code39checksum: {
+    bcid: 'code39',
+    encode: { includecheck: true },
+    name: 'Code 39 + Checksum',
+    category: 'LINEAR',
+    description: 'Code 39 with mod-43 check character',
+    minLength: 1,
+    maxLength: 43,
+    charset: '0-9, A-Z, space, -.$/+%',
+  },
+  code39auto: {
+    bcid: 'code39',
+    name: 'Code 39 Auto',
+    category: 'LINEAR',
+    description: 'Code 39 with automatic character handling',
+    minLength: 1,
+    maxLength: 43,
+    charset: '0-9, A-Z, space, -.$/+%',
+  },
+  code93: {
+    bcid: 'code93',
+    // Code 93 mandates the two C/K check characters
+    encode: { includecheck: true },
+    name: 'Code 93',
+    category: 'LINEAR',
+    description: 'Code 93 - Compact alphanumeric barcode',
+    minLength: 1,
+    maxLength: 43,
+    charset: '0-9, A-Z, -.$/+%',
+  },
+  code25: {
+    bcid: 'code2of5',
+    name: 'Code 25',
+    category: 'LINEAR',
+    description: 'Code 2 of 5 - Numeric only barcode',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  code25auto: {
+    bcid: 'code2of5',
+    name: 'Code 25 Auto',
+    category: 'LINEAR',
+    description: 'Code 2 of 5 with automatic handling',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  code32: {
+    bcid: 'code32',
+    name: 'Code 32',
+    category: 'LINEAR',
+    description: 'Code 32 - Italian pharmacode',
+    minLength: 8,
+    maxLength: 9,
+    charset: 'Numeric',
+  },
+  standard25: {
+    bcid: 'industrial2of5',
+    name: 'Standard 2 of 5',
+    category: 'LINEAR',
+    description: 'Standard (Industrial) 2 of 5 - Numeric only',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  standard25checksum: {
+    bcid: 'industrial2of5',
+    encode: { includecheck: true },
+    name: 'Standard 2 of 5 + Checksum',
+    category: 'LINEAR',
+    description: 'Standard 2 of 5 with check digit',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  interleaved25: {
+    bcid: 'interleaved2of5',
+    name: 'Interleaved 2 of 5',
+    category: 'LINEAR',
+    description: 'Interleaved 2 of 5 - Numeric, even number of digits',
+    minLength: 2,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  interleaved25checksum: {
+    bcid: 'interleaved2of5',
+    encode: { includecheck: true },
+    name: 'Interleaved 2 of 5 + Checksum',
+    category: 'LINEAR',
+    description: 'Interleaved 2 of 5 with check digit',
+    minLength: 2,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  interleaved25auto: {
+    bcid: 'interleaved2of5',
+    encode: { includecheck: true },
+    name: 'Interleaved 2 of 5 Auto',
+    category: 'LINEAR',
+    description: 'Interleaved 2 of 5 with automatic check digit padding',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  msi: {
+    bcid: 'msi',
+    name: 'MSI',
+    category: 'LINEAR',
+    description: 'MSI (Modified Plessey) - Numeric only',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  msichecksum: {
+    bcid: 'msi',
+    encode: { includecheck: true },
+    name: 'MSI + Checksum',
+    category: 'LINEAR',
+    description: 'MSI with mod-10 check digit',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+  msiauto: {
+    bcid: 'msi',
+    encode: { includecheck: true },
+    name: 'MSI Auto',
+    category: 'LINEAR',
+    description: 'MSI with automatic check digit',
+    minLength: 1,
+    maxLength: 40,
+    charset: 'Numeric',
+  },
+
+  // EAN/UPC Family
+  ean13: {
+    bcid: 'ean13',
+    encode: { guardwhitespace: true },
+    name: 'EAN-13',
+    category: 'EAN_UPC',
+    description: 'EAN-13 - European Article Number',
+    minLength: 12,
+    maxLength: 13,
+    charset: 'Numeric',
+  },
+  ean8: {
+    bcid: 'ean8',
+    encode: { guardwhitespace: true },
+    name: 'EAN-8',
+    category: 'EAN_UPC',
+    description: 'EAN-8 - European Article Number (short)',
+    minLength: 7,
+    maxLength: 8,
+    charset: 'Numeric',
+  },
+  ean2: {
+    bcid: 'ean2',
+    encode: { guardwhitespace: true },
+    name: 'EAN-2',
+    category: 'EAN_UPC',
+    description: 'EAN-2 - Two digit add-on',
+    minLength: 2,
+    maxLength: 2,
+    charset: 'Numeric',
+  },
+  ean5: {
+    bcid: 'ean5',
+    encode: { guardwhitespace: true },
+    name: 'EAN-5',
+    category: 'EAN_UPC',
+    description: 'EAN-5 - Five digit add-on',
+    minLength: 5,
+    maxLength: 5,
+    charset: 'Numeric',
+  },
+  upca: {
+    bcid: 'upca',
+    encode: { guardwhitespace: true },
+    name: 'UPC-A',
+    category: 'EAN_UPC',
+    description: 'UPC-A - Universal Product Code',
+    minLength: 11,
+    maxLength: 12,
+    charset: 'Numeric',
+  },
+  upce: {
+    bcid: 'upce',
+    encode: { guardwhitespace: true },
+    name: 'UPC-E',
+    category: 'EAN_UPC',
+    description: 'UPC-E - Universal Product Code (compressed)',
+    minLength: 7,
+    maxLength: 8,
+    charset: 'Numeric',
+  },
+  itf14: {
+    bcid: 'itf14',
+    name: 'ITF-14',
+    category: 'EAN_UPC',
+    description: 'ITF-14 - Shipping container code',
+    minLength: 13,
+    maxLength: 14,
+    charset: 'Numeric',
+  },
+
+  // Postal Barcodes
+  postnet: {
+    bcid: 'postnet',
+    name: 'POSTNET',
+    category: 'POSTAL',
+    description: 'POSTNET - US Postal Service numeric code',
+    minLength: 5,
+    maxLength: 11,
+    charset: 'Numeric',
+  },
+  planet: {
+    bcid: 'planet',
+    name: 'PLANET',
+    category: 'POSTAL',
+    description: 'PLANET - US Postal Service tracking code',
+    minLength: 11,
+    maxLength: 13,
+    charset: 'Numeric',
+  },
+  rms4cc: {
+    bcid: 'royalmail',
+    name: 'RM4SCC',
+    category: 'POSTAL',
+    description: 'RM4SCC - Royal Mail 4-state customer code',
+    minLength: 1,
+    maxLength: 20,
+    charset: '0-9, A-Z',
+  },
+  kix: {
+    bcid: 'kix',
+    name: 'KIX',
+    category: 'POSTAL',
+    description: 'KIX - Dutch Post code',
+    minLength: 1,
+    maxLength: 20,
+    charset: '0-9, A-Z',
+  },
+  imb: {
+    bcid: 'onecode',
+    name: 'Intelligent Mail',
+    category: 'POSTAL',
+    description: 'USPS Intelligent Mail (OneCode) barcode',
+    minLength: 20,
+    maxLength: 31,
+    charset: 'Numeric',
+  },
+
+  // Specialized Barcodes
+  codabar: {
+    bcid: 'rationalizedCodabar',
+    name: 'Codabar',
+    category: 'SPECIALIZED',
+    description: 'Codabar - Numeric with A-D start/stop characters',
+    minLength: 1,
+    maxLength: 60,
+    charset: '0-9, -$:/.+, A-D start/stop',
+  },
+  code11: {
+    bcid: 'code11',
+    name: 'Code 11',
+    category: 'SPECIALIZED',
+    description: 'Code 11 - Telecommunications barcode',
+    minLength: 1,
+    maxLength: 40,
+    charset: '0-9, -',
+  },
+  pharmacode: {
+    bcid: 'pharmacode',
+    name: 'Pharmacode',
+    category: 'SPECIALIZED',
+    description: 'Pharmacode - Pharmaceutical binary code (3-131070)',
+    minLength: 1,
+    maxLength: 6,
+    charset: 'Numeric',
+  },
+  pharmacodetwotracks: {
+    bcid: 'pharmacode2',
+    name: 'Two-track Pharmacode',
+    category: 'SPECIALIZED',
+    description: 'Two-track Pharmacode - Pharmaceutical code (4-64570080)',
+    minLength: 1,
+    maxLength: 8,
+    charset: 'Numeric',
+  },
+
+  // 2D Matrix Codes
+  qrcode: {
+    bcid: 'qrcode',
+    name: 'QR Code',
+    category: 'MATRIX_2D',
+    description: 'QR Code - 2D matrix barcode',
+    minLength: 1,
+    maxLength: 2953,
+    charset: 'Unicode',
+  },
+  datamatrix: {
+    bcid: 'datamatrix',
+    name: 'Data Matrix',
+    category: 'MATRIX_2D',
+    description: 'Data Matrix - 2D matrix barcode',
+    minLength: 1,
+    maxLength: 2335,
+    charset: 'Unicode',
+  },
+  aztec: {
+    bcid: 'azteccode',
+    name: 'Aztec Code',
+    category: 'MATRIX_2D',
+    description: 'Aztec Code - 2D matrix barcode',
+    minLength: 1,
+    maxLength: 3832,
+    charset: 'Unicode',
+  },
+  pdf417: {
+    bcid: 'pdf417',
+    name: 'PDF417',
+    category: 'MATRIX_2D',
+    description: 'PDF417 - 2D stacked barcode',
+    minLength: 1,
+    maxLength: 1850,
+    charset: 'Unicode',
+  },
+  microqr: {
+    bcid: 'microqrcode',
+    name: 'Micro QR Code',
+    category: 'MATRIX_2D',
+    description: 'Micro QR Code - Compact 2D matrix barcode',
+    minLength: 1,
+    maxLength: 35,
+    charset: 'Alphanumeric',
+  },
+  maxicode: {
+    bcid: 'maxicode',
+    encode: { mode: 4 },
+    name: 'MaxiCode',
+    category: 'MATRIX_2D',
+    description: 'MaxiCode - UPS fixed-size 2D barcode',
+    minLength: 1,
+    maxLength: 93,
+    charset: 'ASCII',
+  },
+
+  // Stacked Linear Codes
+  code16k: {
+    bcid: 'code16k',
+    name: 'Code 16K',
+    category: 'STACKED',
+    description: 'Code 16K - Stacked Code 128 rows',
+    minLength: 1,
+    maxLength: 154,
+    charset: 'ASCII',
+  },
+  code49: {
+    bcid: 'code49',
+    name: 'Code 49',
+    category: 'STACKED',
+    description: 'Code 49 - Stacked alphanumeric barcode',
+    minLength: 1,
+    maxLength: 49,
+    charset: '0-9, A-Z, -.$/+%',
+  },
+};
+
+/**
+ * Type constant name (CODE128) -> type id (code128)
+ */
+const TYPES = Object.keys(REGISTRY).reduce((acc, type) => {
+  acc[type.toUpperCase()] = type;
+  return acc;
+}, {});
+
+/**
+ * Category -> type ids
+ */
+const CATEGORIES = Object.entries(REGISTRY).reduce((acc, [type, info]) => {
+  acc[info.category] = acc[info.category] || [];
+  acc[info.category].push(type);
+  return acc;
+}, {});
+
 class BarcodeTypes {
-  static TYPES = {
-    // Linear Barcodes
-    CODE128: 'code128',
-    CODE128A: 'code128a',
-    CODE128B: 'code128b',
-    CODE128C: 'code128c',
-    CODE128AUTO: 'code128auto',
-    CODE39: 'code39',
-    CODE39EXTENDED: 'code39extended',
-    CODE39CHECKSUM: 'code39checksum',
-    CODE39AUTO: 'code39auto',
-    CODE93: 'code93',
-    CODE25: 'code25',
-    CODE25AUTO: 'code25auto',
-    CODE32: 'code32',
-    STANDARD25: 'standard25',
-    STANDARD25CHECKSUM: 'standard25checksum',
-    INTERLEAVED25: 'interleaved25',
-    INTERLEAVED25CHECKSUM: 'interleaved25checksum',
-    INTERLEAVED25AUTO: 'interleaved25auto',
-    MSI: 'msi',
-    MSICHECKSUM: 'msichecksum',
-    MSIAUTO: 'msiauto',
-
-    // EAN/UPC Family
-    EAN13: 'ean13',
-    EAN8: 'ean8',
-    EAN2: 'ean2',
-    EAN5: 'ean5',
-    UPCA: 'upca',
-    UPCE: 'upce',
-    ITF14: 'itf14',
-
-    // Postal Barcodes
-    POSTNET: 'postnet',
-    PLANET: 'planet',
-    RMS4CC: 'rms4cc',
-    KIX: 'kix',
-    IMB: 'imb',
-
-    // Specialized Barcodes
-    CODABAR: 'codabar',
-    CODE11: 'code11',
-    PHARMACODE: 'pharmacode',
-    PHARMACODETWOTRACKS: 'pharmacodetwotracks',
-
-    // 2D Matrix Codes
-    QRCODE: 'qrcode',
-    DATAMATRIX: 'datamatrix',
-    AZTEC: 'aztec',
-    PDF417: 'pdf417',
-    MICROQR: 'microqr',
-    MAXICODE: 'maxicode',
-
-    // Stacked Linear Codes
-    CODE16K: 'code16k',
-    CODE49: 'code49',
-  };
-
-  static CATEGORIES = {
-    LINEAR: [
-      'code128',
-      'code128a',
-      'code128b',
-      'code128c',
-      'code128auto',
-      'code39',
-      'code39extended',
-      'code39checksum',
-      'code39auto',
-      'code93',
-      'code25',
-      'code25auto',
-      'code32',
-      'standard25',
-      'standard25checksum',
-      'interleaved25',
-      'interleaved25checksum',
-      'interleaved25auto',
-      'msi',
-      'msichecksum',
-      'msiauto',
-    ],
-    EAN_UPC: ['ean13', 'ean8', 'ean2', 'ean5', 'upca', 'upce', 'itf14'],
-    POSTAL: ['postnet', 'planet', 'rms4cc', 'kix', 'imb'],
-    SPECIALIZED: ['codabar', 'code11', 'pharmacode', 'pharmacodetwotracks'],
-    MATRIX_2D: [
-      'qrcode',
-      'datamatrix',
-      'aztec',
-      'pdf417',
-      'microqr',
-      'maxicode',
-    ],
-    STACKED: ['code16k', 'code49'],
-  };
+  static TYPES = TYPES;
+  static CATEGORIES = CATEGORIES;
 
   /**
    * Get all supported barcode types
-   * @returns {Array} Array of all barcode types
+   * @returns {string[]} Array of all barcode types
    */
   static getAll() {
-    return Object.values(this.TYPES);
+    return Object.keys(REGISTRY);
+  }
+
+  /**
+   * Get all supported barcode types (alias of getAll)
+   * @returns {string[]} Array of all barcode types
+   */
+  static getTypes() {
+    return this.getAll();
   }
 
   /**
    * Get barcode types by category
-   * @param {string} category - The category name
-   * @returns {Array} Array of barcode types in the category
+   * @param {string} category - The category name (linear, ean_upc, postal, ...)
+   * @returns {string[]} Array of barcode types in the category
    */
   static getByCategory(category) {
-    return this.CATEGORIES[category.toUpperCase()] || [];
+    if (!category) {
+      return [];
+    }
+    return CATEGORIES[String(category).toUpperCase()] || [];
   }
 
   /**
    * Get all categories
-   * @returns {Array} Array of category names
+   * @returns {string[]} Array of category names
    */
   static getCategories() {
-    return Object.keys(this.CATEGORIES);
+    return Object.keys(CATEGORIES);
   }
 
   /**
@@ -131,43 +510,24 @@ class BarcodeTypes {
    * @returns {boolean} True if valid
    */
   static isValid(type) {
-    return Object.values(this.TYPES).includes(type);
+    return typeof type === 'string' && Object.hasOwn(REGISTRY, type);
   }
 
   /**
-   * Get barcode type configuration
+   * Get barcode type configuration used for validation
    * @param {string} type - The barcode type
-   * @returns {Object} Configuration object
+   * @returns {{minLength: number, maxLength: number, charset: string}} Configuration
    */
   static getConfig(type) {
-    const configs = {
-      code128: { minLength: 1, maxLength: 80, charset: 'ASCII' },
-      code128a: { minLength: 1, maxLength: 80, charset: 'ASCII A' },
-      code128b: { minLength: 1, maxLength: 80, charset: 'ASCII B' },
-      code128c: { minLength: 2, maxLength: 80, charset: 'Numeric' },
-      code39: {
-        minLength: 1,
-        maxLength: 43,
-        charset: '0-9, A-Z, space, -.$/+%',
-      },
-      code39extended: {
-        minLength: 1,
-        maxLength: 43,
-        charset: 'Extended ASCII',
-      },
-      code93: { minLength: 1, maxLength: 43, charset: '0-9, A-Z, -.$/+%' },
-      ean13: { minLength: 12, maxLength: 13, charset: 'Numeric' },
-      ean8: { minLength: 7, maxLength: 8, charset: 'Numeric' },
-      upca: { minLength: 11, maxLength: 12, charset: 'Numeric' },
-      upce: { minLength: 6, maxLength: 8, charset: 'Numeric' },
-      qrcode: { minLength: 1, maxLength: 2953, charset: 'Unicode' },
-      datamatrix: { minLength: 1, maxLength: 2335, charset: 'Unicode' },
-      pdf417: { minLength: 1, maxLength: 1850, charset: 'Unicode' },
+    const info = REGISTRY[type];
+    if (!info) {
+      return { minLength: 1, maxLength: 100, charset: 'Unknown' };
+    }
+    return {
+      minLength: info.minLength,
+      maxLength: info.maxLength,
+      charset: info.charset,
     };
-
-    return (
-      configs[type] || { minLength: 1, maxLength: 100, charset: 'Unknown' }
-    );
   }
 
   /**
@@ -176,19 +536,50 @@ class BarcodeTypes {
    * @returns {string} Description
    */
   static getDescription(type) {
-    const descriptions = {
-      code128: 'Code 128 - High-density linear barcode',
-      code39: 'Code 39 - Alphanumeric barcode',
-      ean13: 'EAN-13 - European Article Number',
-      ean8: 'EAN-8 - European Article Number (short)',
-      upca: 'UPC-A - Universal Product Code',
-      upce: 'UPC-E - Universal Product Code (compressed)',
-      qrcode: 'QR Code - 2D matrix barcode',
-      datamatrix: 'Data Matrix - 2D matrix barcode',
-      pdf417: 'PDF417 - 2D stacked barcode',
+    return REGISTRY[type] ? REGISTRY[type].description : 'Unknown barcode type';
+  }
+
+  /**
+   * Get full information about a barcode type
+   * @param {string} type - The barcode type
+   * @returns {Object|null} Type information, or null when the type is unknown
+   */
+  static getTypeInfo(type) {
+    const info = REGISTRY[type];
+    if (!info) {
+      return null;
+    }
+
+    return {
+      type,
+      name: info.name,
+      description: info.description,
+      category: info.category,
+      symbology: info.bcid,
+      minLength: info.minLength,
+      maxLength: info.maxLength,
+      charset: info.charset,
     };
+  }
 
-    return descriptions[type] || 'Unknown barcode type';
+  /**
+   * Get the underlying symbology id (bwip-js bcid) for a type
+   * @param {string} type - The barcode type
+   * @returns {string|null} Symbology id
+   */
+  static getSymbology(type) {
+    return REGISTRY[type] ? REGISTRY[type].bcid : null;
+  }
+
+  /**
+   * Get encoder options required by a type (check digits, guard bars, ...)
+   * @param {string} type - The barcode type
+   * @returns {Object} Encoder options
+   */
+  static getEncodeOptions(type) {
+    return REGISTRY[type] && REGISTRY[type].encode
+      ? { ...REGISTRY[type].encode }
+      : {};
   }
 }