@sythos/js_barcode_universal 1.5.8 → 1.5.10

package/src/ts/oned/addons.ts

@@ -0,0 +1,420 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * UPC/EAN two- and five-digit supplements.
+ *
+ * Supplements are small symbols printed to the right of an EAN/UPC symbol.
+ * They use the ordinary EAN odd/even digit patterns, a 1011 start guard and
+ * 01 separators between digits. EAN-2 selects its parity from the numeric
+ * value modulo four. EAN-5 derives a checksum from the five digits and uses
+ * that value to select one of ten parity rows.
+ *
+ * This module intentionally keeps supplements separate from the base EAN/UPC
+ * writers. `composeEANAddon` and the `*WithAddon` helpers are opt-in; existing
+ * EAN/UPC APIs continue to return their original one-row matrices unchanged.
+ *
+ * @module oned/addons
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { EncodeError, FormatError } from '../core/errors.js';
+import {
+  EAN_L,
+  EAN_G,
+} from './patterns.js';
+import {
+  encodeEAN13,
+  encodeEAN8,
+  encodeUPCA,
+  encodeUPCE,
+} from './writers.js';
+
+/** EAN-2 parity rows, indexed by the two-digit value modulo four. */
+export const EAN2_PARITY = Object.freeze([
+  'AA', 'AB', 'BA', 'BB',
+]);
+
+/** EAN-5 parity rows, indexed by the supplemental checksum. */
+export const EAN5_PARITY = Object.freeze([
+  'BBAAA', 'BABAA', 'BAABA', 'BAAAB', 'ABBAA',
+  'AABBA', 'AAABB', 'ABABA', 'ABAAB', 'AABAB',
+]);
+
+/** Start guard used by both UPC/EAN supplemental symbols. */
+export const EAN_ADDON_START = '1011';
+
+/** Separator inserted between adjacent supplemental digits. */
+export const EAN_ADDON_SEPARATOR = '01';
+
+export const EAN2_WIDTH = EAN_ADDON_START.length + 2 * 7 + EAN_ADDON_SEPARATOR.length;
+export const EAN5_WIDTH = EAN_ADDON_START.length + 5 * 7 + EAN_ADDON_SEPARATOR.length * 4;
+
+/**
+ * @param {unknown} value
+ * @param {number} length
+ * @param {string} format
+ * @returns {string}
+ */
+function normalizeDigits(value, length, format) {
+  const digits = String(value);
+  if (!new RegExp(`^[0-9]{${length}}$`).test(digits)) {
+    throw new EncodeError(`${format}: payload must contain exactly ${length} digits`);
+  }
+  return digits;
+}
+
+/**
+ * EAN-5 supplemental checksum.
+ *
+ * The first, third and fifth digits carry weight three; the second and fourth
+ * carry weight nine. The checksum is not printed as a sixth digit: it selects
+ * the odd/even parity row for the five encoded digits.
+ *
+ * @param {string|number} value Five digits.
+ * @returns {number} Checksum value, 0-9.
+ */
+export function ean5Checksum(value) {
+  const digits = normalizeDigits(value, 5, 'EAN-5');
+  const weighted =
+    3 * (Number(digits[0]) + Number(digits[2]) + Number(digits[4])) +
+    9 * (Number(digits[1]) + Number(digits[3]));
+  return weighted % 10;
+}
+
+/** Alias for callers that use the EAN family check-digit terminology. */
+export const ean5CheckDigit = ean5Checksum;
+
+/**
+ * Resolve the EAN-2 parity row for a payload.
+ *
+ * @param {string|number} value Two digits.
+ * @returns {string} Two-character A/B parity row.
+ */
+export function ean2Parity(value) {
+  const digits = normalizeDigits(value, 2, 'EAN-2');
+  return EAN2_PARITY[Number(digits) % 4];
+}
+
+/**
+ * Resolve the EAN-5 parity row for a payload.
+ *
+ * @param {string|number} value Five digits.
+ * @returns {string} Five-character A/B parity row.
+ */
+export function ean5Parity(value) {
+  return EAN5_PARITY[ean5Checksum(value)];
+}
+
+/**
+ * Expand an A/B parity row into EAN digit patterns.
+ *
+ * @param {string} digits
+ * @param {string} parity
+ * @returns {string}
+ */
+function encodeDigitPatterns(digits, parity) {
+  let modules = EAN_ADDON_START;
+  for (let i = 0; i < digits.length; i++) {
+    if (i > 0) modules += EAN_ADDON_SEPARATOR;
+    const table = parity[i] === 'A' ? EAN_L : EAN_G;
+    modules += table[Number(digits[i])];
+  }
+  return modules;
+}
+
+/**
+ * Turn a module string into a one-row matrix and attach immutable source
+ * metadata for composition/rendering callers.
+ *
+ * @param {string} modules
+ * @param {{format: string, text: string, parity: string, checksum?: number}} metadata
+ * @returns {BitMatrix}
+ */
+function toAddonMatrix(modules, metadata) {
+  const matrix = new BitMatrix(modules.length, 1);
+  for (let x = 0; x < modules.length; x++) {
+    if (modules[x] === '1') matrix.set(x, 0);
+  }
+  matrix.eanAddon = Object.freeze({ ...metadata });
+  return matrix;
+}
+
+/**
+ * Encode an EAN-2 supplement.
+ *
+ * @param {string|number} value Exactly two decimal digits.
+ * @returns {BitMatrix} A 20-module, one-row supplement.
+ */
+export function encodeEAN2(value) {
+  const digits = normalizeDigits(value, 2, 'EAN-2');
+  const parity = ean2Parity(digits);
+  const matrix = toAddonMatrix(encodeDigitPatterns(digits, parity), {
+    format: 'ean2',
+    text: digits,
+    parity,
+  });
+  if (matrix.width !== EAN2_WIDTH) {
+    throw new EncodeError(`EAN-2: internal width is ${matrix.width}, expected ${EAN2_WIDTH}`);
+  }
+  return matrix;
+}
+
+/**
+ * Encode an EAN-5 supplement.
+ *
+ * @param {string|number} value Exactly five decimal digits.
+ * @returns {BitMatrix} A 47-module, one-row supplement.
+ */
+export function encodeEAN5(value) {
+  const digits = normalizeDigits(value, 5, 'EAN-5');
+  const checksum = ean5Checksum(digits);
+  const parity = EAN5_PARITY[checksum];
+  const matrix = toAddonMatrix(encodeDigitPatterns(digits, parity), {
+    format: 'ean5',
+    text: digits,
+    parity,
+    checksum,
+  });
+  if (matrix.width !== EAN5_WIDTH) {
+    throw new EncodeError(`EAN-5: internal width is ${matrix.width}, expected ${EAN5_WIDTH}`);
+  }
+  return matrix;
+}
+
+/**
+ * Encode either supported supplement length.
+ *
+ * @param {string|number} value Two or five decimal digits.
+ * @returns {BitMatrix}
+ */
+export function encodeEANAddon(value) {
+  const digits = String(value);
+  if (digits.length === 2) return encodeEAN2(digits);
+  if (digits.length === 5) return encodeEAN5(digits);
+  throw new EncodeError('EAN add-on: payload must contain exactly two or five digits');
+}
+
+/** Alias using the spelling used by some EAN documentation. */
+export const encodeEANAddOn = encodeEANAddon;
+
+/**
+ * @param {BitMatrix} matrix
+ * @param {number} offset
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function matches(matrix, offset, pattern) {
+  if (offset < 0 || offset + pattern.length > matrix.width) return false;
+  for (let i = 0; i < pattern.length; i++) {
+    if ((matrix.get(offset + i, 0) ? '1' : '0') !== pattern[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * @param {BitMatrix} matrix
+ * @param {number} start
+ * @param {2|5} digitCount
+ * @returns {{format:string,text:string,parity:string,checksum?:number,end:number}|null}
+ */
+function decodeAt(matrix, start, digitCount) {
+  const width = digitCount === 2 ? EAN2_WIDTH : EAN5_WIDTH;
+  if (!matches(matrix, start, EAN_ADDON_START)) return null;
+  if (start > 0 && matrix.get(start - 1, 0)) return null;
+
+  let offset = start + EAN_ADDON_START.length;
+  let text = '';
+  let parity = '';
+
+  for (let i = 0; i < digitCount; i++) {
+    let found = null;
+    for (let digit = 0; digit < 10; digit++) {
+      for (const [letter, table] of [['A', EAN_L], ['B', EAN_G]]) {
+        if (matches(matrix, offset, table[digit]) &&
+            (!found || found.letter !== letter || found.digit !== digit)) {
+          if (found) return null;
+          found = { digit, letter };
+        }
+      }
+    }
+    if (!found) return null;
+    text += String(found.digit);
+    parity += found.letter;
+    offset += 7;
+    if (i < digitCount - 1) {
+      if (!matches(matrix, offset, EAN_ADDON_SEPARATOR)) return null;
+      offset += EAN_ADDON_SEPARATOR.length;
+    }
+  }
+
+  if (offset - start !== width) return null;
+  if (digitCount === 2) {
+    if (EAN2_PARITY[Number(text) % 4] !== parity) return null;
+    return { format: 'ean2', text, parity, end: offset };
+  }
+
+  const checksum = ean5Checksum(text);
+  if (EAN5_PARITY[checksum] !== parity) return null;
+  return { format: 'ean5', text, parity, checksum, end: offset };
+}
+
+/**
+ * Validate and decode an EAN-2 supplement. A leading quiet zone is accepted;
+ * the decoder searches the row for a valid start guard so a composed base
+ * EAN/UPC matrix can be passed directly as well.
+ *
+ * @param {BitMatrix} matrix One-row, module-aligned supplement or composition.
+ * @returns {{format:'ean2',text:string,parity:string}}
+ * @throws {FormatError} When no valid supplement is found.
+ */
+export function decodeEAN2(matrix) {
+  if (!matrix || !Number.isInteger(matrix.width) || matrix.height !== 1) {
+    throw new FormatError('EAN-2: expected a one-row module matrix');
+  }
+  for (let start = 0; start + EAN2_WIDTH <= matrix.width; start++) {
+    const result = decodeAt(matrix, start, 2);
+    if (result) {
+      const { end, ...publicResult } = result;
+      void end;
+      return publicResult;
+    }
+  }
+  throw new FormatError('EAN-2: start, parity or digit pattern is invalid');
+}
+
+/**
+ * Validate and decode an EAN-5 supplement.
+ *
+ * @param {BitMatrix} matrix One-row, module-aligned supplement or composition.
+ * @returns {{format:'ean5',text:string,parity:string,checksum:number}}
+ * @throws {FormatError} When no valid supplement is found.
+ */
+export function decodeEAN5(matrix) {
+  if (!matrix || !Number.isInteger(matrix.width) || matrix.height !== 1) {
+    throw new FormatError('EAN-5: expected a one-row module matrix');
+  }
+  for (let start = 0; start + EAN5_WIDTH <= matrix.width; start++) {
+    const result = decodeAt(matrix, start, 5);
+    if (result) {
+      const { end, ...publicResult } = result;
+      void end;
+      return publicResult;
+    }
+  }
+  throw new FormatError('EAN-5: start, parity, checksum or digit pattern is invalid');
+}
+
+/**
+ * Decode either supported supplement length.
+ *
+ * @param {BitMatrix} matrix One-row, module-aligned supplement or composition.
+ * @returns {{format:'ean2'|'ean5',text:string,parity:string,checksum?:number}}
+ * @throws {FormatError} When neither supplement grammar matches.
+ */
+export function decodeEANAddon(matrix) {
+  try {
+    return decodeEAN5(matrix);
+  } catch (fiveError) {
+    try {
+      return decodeEAN2(matrix);
+    } catch (twoError) {
+      throw new FormatError(`EAN add-on: ${fiveError.message}; ${twoError.message}`);
+    }
+  }
+}
+
+/** Alias using the spelling used by some EAN documentation. */
+export const decodeEANAddOn = decodeEANAddon;
+
+/**
+ * Join a base EAN/UPC matrix and a supplement with the standard quiet gap.
+ *
+ * The helper does not alter either input. By default it inserts nine light
+ * modules, the conventional separation between the base symbol and an add-on.
+ * The result carries the supplement metadata under `eanAddon` for renderers or
+ * callers that need to label the composed symbol.
+ *
+ * @param {BitMatrix} base Base EAN/UPC matrix.
+ * @param {BitMatrix|string|number} addon Add-on matrix or two/five digits.
+ * @param {{gap?:number}} [options]
+ * @returns {BitMatrix}
+ */
+export function composeEANAddon(base, addon, options = {}) {
+  if (!base || !Number.isInteger(base.width) || base.height !== 1) {
+    throw new TypeError('EAN add-on: base must be a one-row module matrix');
+  }
+  const addonMatrix = typeof addon === 'string' || typeof addon === 'number'
+    ? encodeEANAddon(addon)
+    : addon;
+  if (!addonMatrix || !Number.isInteger(addonMatrix.width) || addonMatrix.height !== 1) {
+    throw new TypeError('EAN add-on: supplement must be a one-row module matrix or digits');
+  }
+
+  const gap = options.gap === undefined ? 9 : Number(options.gap);
+  if (!Number.isInteger(gap) || gap < 1) {
+    throw new EncodeError(`EAN add-on: gap must be a positive integer, got ${options.gap}`);
+  }
+
+  const result = new BitMatrix(base.width + gap + addonMatrix.width, 1);
+  for (let x = 0; x < base.width; x++) if (base.get(x, 0)) result.set(x, 0);
+  for (let x = 0; x < addonMatrix.width; x++) {
+    if (addonMatrix.get(x, 0)) result.set(base.width + gap + x, 0);
+  }
+  if (addonMatrix.eanAddon) result.eanAddon = { ...addonMatrix.eanAddon, gap };
+  return result;
+}
+
+/**
+ * Compose an EAN-13 symbol with an EAN-2 or EAN-5 supplement.
+ *
+ * @param {string} value Base EAN-13 payload.
+ * @param {string|number} addon Two or five supplemental digits.
+ * @param {{gap?:number}} [options]
+ * @returns {BitMatrix}
+ */
+export function encodeEAN13WithAddon(value, addon, options = {}) {
+  return composeEANAddon(encodeEAN13(value), addon, options);
+}
+
+/** @see encodeEAN13WithAddon */
+export function encodeEAN8WithAddon(value, addon, options = {}) {
+  return composeEANAddon(encodeEAN8(value), addon, options);
+}
+
+/** @see encodeEAN13WithAddon */
+export function encodeUPCAWithAddon(value, addon, options = {}) {
+  return composeEANAddon(encodeUPCA(value), addon, options);
+}
+
+/** @see encodeEAN13WithAddon */
+export function encodeUPCEWithAddon(value, addon, options = {}) {
+  return composeEANAddon(encodeUPCE(value), addon, options);
+}

package/src/ts/oned/index.ts

@@ -0,0 +1,106 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Linear symbologies.
+ *
+ * @module oned
+ */
+
+export {
+  encodeEAN13, encodeEAN8, encodeUPCA, encodeUPCE, encodeISBN,
+  encodeCode39, encodeCode93, encodeCode128,
+  encodeITF, encodeITF14, encodeCodabar, encodeCode11,
+  encodeMSI, encodePharmacode,
+  ean13CheckDigit,
+} from './writers.js';
+
+export {
+  EAN2_PARITY, EAN5_PARITY, EAN2_WIDTH, EAN5_WIDTH,
+  EAN_ADDON_START, EAN_ADDON_SEPARATOR,
+  ean2Parity, ean5Checksum, ean5CheckDigit, ean5Parity,
+  encodeEAN2, encodeEAN5, encodeEANAddon, encodeEANAddOn,
+  decodeEAN2, decodeEAN5, decodeEANAddon, decodeEANAddOn,
+  composeEANAddon,
+  encodeEAN13WithAddon, encodeEAN8WithAddon,
+  encodeUPCAWithAddon, encodeUPCEWithAddon,
+} from './addons.js';
+
+export {
+  decodeOneD, decodeOneDStrict,
+  decodeCode11, decodeMSI,
+  patternVariance, recordPattern, toNarrowWidePattern,
+} from './reader.js';
+
+export { validateTables } from './patterns.js';
+
+import {
+  encodeEAN13, encodeEAN8, encodeUPCA, encodeUPCE, encodeISBN,
+  encodeCode39, encodeCode93, encodeCode128,
+  encodeITF, encodeITF14, encodeCodabar, encodeCode11,
+  encodeMSI, encodePharmacode,
+} from './writers.js';
+import { encodeEAN2, encodeEAN5 } from './addons.js';
+
+/**
+ * Writers by format id, for the top-level `encode()` dispatcher.
+ *
+ * `readable` marks the formats this suite can also decode. Writing is a table
+ * lookup and easy to support broadly; reading needs a detector per symbology,
+ * so the two lists legitimately differ and the API says so rather than
+ * failing at runtime.
+ *
+ * @type {Record<string, {encode: Function, readable: boolean, label: string, role?: string}>}
+ */
+export const ONED_FORMATS = {
+  ean13: { encode: encodeEAN13, readable: true, label: 'EAN-13' },
+  ean8: { encode: encodeEAN8, readable: true, label: 'EAN-8' },
+  upca: { encode: encodeUPCA, readable: true, label: 'UPC-A' },
+  isbn: { encode: encodeISBN, readable: true, label: 'ISBN (Bookland EAN-13)' },
+  upce: { encode: encodeUPCE, readable: true, label: 'UPC-E' },
+  code128: { encode: encodeCode128, readable: true, label: 'Code 128' },
+  gs1128: {
+    encode: (v, o) => encodeCode128(v, { ...o, gs1: true }),
+    readable: true,
+    label: 'GS1-128',
+  },
+  code39: { encode: encodeCode39, readable: true, label: 'Code 39' },
+  code93: { encode: encodeCode93, readable: true, label: 'Code 93' },
+  itf: { encode: encodeITF, readable: true, label: 'ITF (Interleaved 2 of 5)' },
+  itf14: { encode: encodeITF14, readable: true, label: 'ITF-14' },
+  codabar: { encode: encodeCodabar, readable: true, label: 'Codabar' },
+  code11: { encode: encodeCode11, readable: true, label: 'Code 11' },
+  msi: { encode: encodeMSI, readable: true, label: 'MSI Plessey' },
+  pharmacode: { encode: encodePharmacode, readable: false, label: 'Pharmacode' },
+  // Supplements are reported as readable capabilities, but the image reader
+  // only accepts them when attached to a validated EAN/UPC parent symbol.
+  ean2: { encode: encodeEAN2, readable: true, role: 'supplement', label: 'EAN-2 supplement' },
+  ean5: { encode: encodeEAN5, readable: true, role: 'supplement', label: 'EAN-5 supplement' },
+};