@sythos/js_barcode_universal 0.1.0

package/src/core/bit-matrix.js

@@ -0,0 +1,241 @@
+/*!
+ * 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.
+ */
+
+/**
+ * A 2D bit grid — the common currency of this library.
+ *
+ * Every writer produces one; every reader consumes one; every renderer draws
+ * one. Keeping it as the single interchange type is what lets formats and
+ * output targets stay independent of each other.
+ *
+ * Storage is row-packed into a Uint32Array: one allocation, cache-friendly row
+ * scans, and cheap whole-row operations for the 1D readers.
+ *
+ * Convention: a set bit is a DARK module (ink). This matches how symbols are
+ * described in every specification, and renderers invert as needed.
+ *
+ * @module core/bit-matrix
+ */
+
+export class BitMatrix {
+  /**
+   * @param {number} width
+   * @param {number} height
+   */
+  constructor(width, height = width) {
+    if (width < 1 || height < 1) {
+      throw new Error(`BitMatrix: dimensions must be positive, got ${width}x${height}`);
+    }
+    this.width = width;
+    this.height = height;
+    this.rowWords = Math.ceil(width / 32);
+    this.bits = new Uint32Array(this.rowWords * height);
+  }
+
+  /**
+   * @param {number} x @param {number} y
+   * @returns {boolean} True if the module is dark.
+   */
+  get(x, y) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return false;
+    return ((this.bits[y * this.rowWords + (x >>> 5)] >>> (x & 31)) & 1) === 1;
+  }
+
+  /** @param {number} x @param {number} y */
+  set(x, y) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return;
+    this.bits[y * this.rowWords + (x >>> 5)] |= 1 << (x & 31);
+  }
+
+  /** @param {number} x @param {number} y */
+  unset(x, y) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return;
+    this.bits[y * this.rowWords + (x >>> 5)] &= ~(1 << (x & 31));
+  }
+
+  /** @param {number} x @param {number} y */
+  flip(x, y) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return;
+    this.bits[y * this.rowWords + (x >>> 5)] ^= 1 << (x & 31);
+  }
+
+  /**
+   * @param {number} x @param {number} y @param {boolean} value
+   */
+  setValue(x, y, value) {
+    if (value) this.set(x, y);
+    else this.unset(x, y);
+  }
+
+  /** Fill a rectangle. @param {number} x @param {number} y @param {number} w @param {number} h */
+  setRegion(x, y, w, h) {
+    for (let j = y; j < y + h; j++) {
+      for (let i = x; i < x + w; i++) this.set(i, j);
+    }
+  }
+
+  clear() {
+    this.bits.fill(0);
+  }
+
+  /** @returns {BitMatrix} */
+  clone() {
+    const m = new BitMatrix(this.width, this.height);
+    m.bits.set(this.bits);
+    return m;
+  }
+
+  /**
+   * Copy row `y` into a reusable array, avoiding an allocation per row in the
+   * 1D scanning loops which run this thousands of times per image.
+   *
+   * @param {number} y
+   * @param {Uint8Array} [out]
+   * @returns {Uint8Array}
+   */
+  getRow(y, out) {
+    const row = out && out.length >= this.width ? out : new Uint8Array(this.width);
+    const base = y * this.rowWords;
+    for (let x = 0; x < this.width; x++) {
+      row[x] = (this.bits[base + (x >>> 5)] >>> (x & 31)) & 1;
+    }
+    return row;
+  }
+
+  /**
+   * Add a uniform light border. Symbols need a quiet zone to be scannable at
+   * all, so this is applied by default when rendering.
+   *
+   * @param {number} size Modules of margin on every side.
+   * @returns {BitMatrix}
+   */
+  withMargin(size) {
+    if (size <= 0) return this.clone();
+    const m = new BitMatrix(this.width + size * 2, this.height + size * 2);
+    for (let y = 0; y < this.height; y++) {
+      for (let x = 0; x < this.width; x++) {
+        if (this.get(x, y)) m.set(x + size, y + size);
+      }
+    }
+    return m;
+  }
+
+  /**
+   * Nearest-neighbour upscale. Integer factors only — a barcode resampled with
+   * interpolation stops being readable.
+   *
+   * @param {number} factor
+   * @returns {BitMatrix}
+   */
+  scale(factor) {
+    const f = Math.max(1, Math.floor(factor));
+    if (f === 1) return this.clone();
+    const m = new BitMatrix(this.width * f, this.height * f);
+    for (let y = 0; y < this.height; y++) {
+      for (let x = 0; x < this.width; x++) {
+        if (this.get(x, y)) m.setRegion(x * f, y * f, f, f);
+      }
+    }
+    return m;
+  }
+
+  /**
+   * Bounding box of the dark modules, or null if the matrix is empty.
+   * @returns {{x: number, y: number, width: number, height: number} | null}
+   */
+  getBounds() {
+    let minX = this.width, minY = this.height, maxX = -1, maxY = -1;
+    for (let y = 0; y < this.height; y++) {
+      for (let x = 0; x < this.width; x++) {
+        if (this.get(x, y)) {
+          if (x < minX) minX = x;
+          if (x > maxX) maxX = x;
+          if (y < minY) minY = y;
+          if (y > maxY) maxY = y;
+        }
+      }
+    }
+    if (maxX < 0) return null;
+    return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+  }
+
+  /**
+   * Rotate 180 degrees, in place. Cheaper than re-detecting when a reader
+   * discovers a symbol is upside down.
+   */
+  rotate180() {
+    const w = this.width, h = this.height;
+    for (let y = 0; y < Math.ceil(h / 2); y++) {
+      for (let x = 0; x < w; x++) {
+        const oy = h - 1 - y, ox = w - 1 - x;
+        if (y === oy && x >= ox) break;
+        const a = this.get(x, y);
+        const b = this.get(ox, oy);
+        this.setValue(x, y, b);
+        this.setValue(ox, oy, a);
+      }
+    }
+  }
+
+  /**
+   * Build from a string of '1'/'X'/'#' (dark) and anything else (light),
+   * newline-separated. Test fixtures are far more legible this way.
+   *
+   * @param {string} text
+   * @returns {BitMatrix}
+   */
+  static parse(text) {
+    const lines = text.trim().split('\n').map((l) => l.trim()).filter((l) => l.length);
+    const height = lines.length;
+    const width = Math.max(...lines.map((l) => l.length));
+    const m = new BitMatrix(width, height);
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < lines[y].length; x++) {
+        const c = lines[y][x];
+        if (c === '1' || c === 'X' || c === 'x' || c === '#') m.set(x, y);
+      }
+    }
+    return m;
+  }
+
+  /**
+   * @param {string} [dark] @param {string} [light]
+   * @returns {string}
+   */
+  toString(dark = '##', light = '  ') {
+    const rows = [];
+    for (let y = 0; y < this.height; y++) {
+      let s = '';
+      for (let x = 0; x < this.width; x++) s += this.get(x, y) ? dark : light;
+      rows.push(s);
+    }
+    return rows.join('\n');
+  }
+}

package/src/core/errors.js

@@ -0,0 +1,61 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Error types.
+ *
+ * Decoding uses exceptions for control flow internally: a detector that fails
+ * on one candidate should be cheap to abandon, and a `try` around a candidate
+ * loop reads better than threading `null` through six call frames. The public
+ * API converts them to results.
+ *
+ * @module core/errors
+ */
+
+/** Base class so consumers can `catch (e) { if (e instanceof BarcodeError) ... }`. */
+export class BarcodeError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** Input could not be encoded — bad payload, or it does not fit the symbology. */
+export class EncodeError extends BarcodeError {}
+
+/** No symbol was found in the image. Not an error condition for `decode()`. */
+export class NotFoundError extends BarcodeError {}
+
+/** A symbol was found, but its geometry or content is malformed. */
+export class FormatError extends BarcodeError {}
+
+/** A symbol was found and read, but error correction could not repair it. */
+export class ChecksumError extends BarcodeError {}

package/src/core/galois-field.js

@@ -0,0 +1,204 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Finite field arithmetic.
+ *
+ * One class serves every field this suite needs:
+ *
+ *   GF(2^4)   Aztec, small layer counts
+ *   GF(2^6)   Aztec
+ *   GF(2^8)   QR Code, Data Matrix, Aztec
+ *   GF(2^10)  Aztec
+ *   GF(2^12)  Aztec
+ *   GF(929)   PDF417  <- a PRIME field, not a binary one
+ *
+ * ## The prime-field trap
+ *
+ * Multiplication unifies cleanly: exp/log tables work for the multiplicative
+ * group of any finite field. Addition does NOT.
+ *
+ *   binary GF(2^m):  a + b  ==  a - b  ==  a XOR b      (self-inverse)
+ *   prime  GF(p):    a + b  ==  (a+b) % p
+ *                    a - b  ==  (a-b+p) % p             (NOT self-inverse)
+ *
+ * So `add`, `sub` and `neg` are methods on the field, never inlined. Any code
+ * that writes a bare `^` for field arithmetic works perfectly for every binary
+ * field and silently corrupts PDF417 — the failure is invisible until a real
+ * scanner rejects the symbol. Route every operation through the field object.
+ *
+ * @module core/galois-field
+ */
+
+export class GaloisField {
+  /**
+   * @param {object} opts
+   * @param {number} opts.size      Field order: 2^m for binary, p for prime.
+   * @param {boolean} [opts.prime]  True for a prime field (mod arithmetic).
+   * @param {number} [opts.primitive] Primitive polynomial, binary fields only.
+   * @param {number} [opts.generator] Multiplicative generator. Defaults to 2
+   *   for binary fields (x), and must be given explicitly for prime fields.
+   * @param {string} [opts.name]
+   */
+  constructor({ size, prime = false, primitive = 0, generator = 2, name = '' }) {
+    this.size = size;
+    this.prime = prime;
+    this.primitive = primitive;
+    this.generator = generator;
+    this.name = name || (prime ? `GF(${size})` : `GF(2^${Math.log2(size)})`);
+
+    /** Multiplicative order: every non-zero element is generator^i for some i < order. */
+    this.order = size - 1;
+
+    const exp = new Int32Array(this.order * 2);
+    const log = new Int32Array(size).fill(-1);
+
+    let x = 1;
+    for (let i = 0; i < this.order; i++) {
+      exp[i] = x;
+      log[x] = i;
+      if (prime) {
+        x = (x * generator) % size;
+      } else {
+        x <<= 1;
+        if (x >= size) x ^= primitive;
+      }
+    }
+    // Wrapped copy lets mul() skip a modulo on the common path.
+    for (let i = 0; i < this.order; i++) exp[this.order + i] = exp[i];
+
+    // A short cycle still returns to 1 after `order` steps whenever its length
+    // divides `order`, so "did we end at 1" does not detect a bad generator.
+    // The reliable test is coverage: a true generator visits every non-zero
+    // element exactly once, leaving no -1 in the log table.
+    for (let v = 1; v < size; v++) {
+      if (log[v] === -1) {
+        throw new Error(
+          `${this.name}: generator ${generator} does not generate the ` +
+          `multiplicative group (element ${v} is unreachable). ` +
+          (prime ? 'Choose a primitive root.' : 'Check the primitive polynomial.')
+        );
+      }
+    }
+
+    this.expTable = exp;
+    this.logTable = log;
+  }
+
+  /** Additive identity is 0 and multiplicative identity is 1 in every field here. */
+  get zero() { return 0; }
+  get one() { return 1; }
+
+  /**
+   * a + b.
+   * @param {number} a @param {number} b @returns {number}
+   */
+  add(a, b) {
+    return this.prime ? (a + b) % this.size : a ^ b;
+  }
+
+  /**
+   * a - b. Distinct from add() in prime fields — see the module note.
+   * @param {number} a @param {number} b @returns {number}
+   */
+  sub(a, b) {
+    return this.prime ? (a - b + this.size) % this.size : a ^ b;
+  }
+
+  /**
+   * -a.
+   * @param {number} a @returns {number}
+   */
+  neg(a) {
+    return this.prime ? (this.size - a) % this.size : a;
+  }
+
+  /**
+   * a * b.
+   * @param {number} a @param {number} b @returns {number}
+   */
+  mul(a, b) {
+    if (a === 0 || b === 0) return 0;
+    return this.expTable[this.logTable[a] + this.logTable[b]];
+  }
+
+  /**
+   * a / b.
+   * @param {number} a @param {number} b @returns {number}
+   */
+  div(a, b) {
+    if (b === 0) throw new Error(`${this.name}: division by zero`);
+    if (a === 0) return 0;
+    return this.expTable[this.logTable[a] - this.logTable[b] + this.order];
+  }
+
+  /**
+   * 1 / a.
+   * @param {number} a @returns {number}
+   */
+  inv(a) {
+    if (a === 0) throw new Error(`${this.name}: zero has no inverse`);
+    return this.expTable[this.order - this.logTable[a]];
+  }
+
+  /**
+   * generator^i, for any integer i (negative included).
+   * @param {number} i @returns {number}
+   */
+  exp(i) {
+    let k = i % this.order;
+    if (k < 0) k += this.order;
+    return this.expTable[k];
+  }
+
+  /**
+   * Discrete log base generator.
+   * @param {number} a @returns {number}
+   */
+  log(a) {
+    if (a === 0) throw new Error(`${this.name}: log of zero`);
+    return this.logTable[a];
+  }
+}
+
+/** QR Code, Data Matrix uses its own — see below. x^8 + x^4 + x^3 + x^2 + 1 */
+export const GF256_QR = new GaloisField({ size: 256, primitive: 0x011d, name: 'GF(256)/QR' });
+
+/** Data Matrix ECC200. x^8 + x^5 + x^3 + x^2 + 1 */
+export const GF256_DM = new GaloisField({ size: 256, primitive: 0x012d, name: 'GF(256)/DataMatrix' });
+
+/** PDF417. Prime field; 3 is a primitive root modulo 929. */
+export const GF929 = new GaloisField({ size: 929, prime: true, generator: 3, name: 'GF(929)' });
+
+/** Aztec, by layer count. */
+export const GF16 = new GaloisField({ size: 16, primitive: 0x13, name: 'GF(16)' });
+export const GF64 = new GaloisField({ size: 64, primitive: 0x43, name: 'GF(64)' });
+export const GF1024 = new GaloisField({ size: 1024, primitive: 0x409, name: 'GF(1024)' });
+export const GF4096 = new GaloisField({ size: 4096, primitive: 0x1069, name: 'GF(4096)' });

package/src/core/index.js

@@ -0,0 +1,56 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Core primitives, re-exported.
+ *
+ * @module core
+ */
+
+export { BitMatrix } from './bit-matrix.js';
+export { BitWriter, BitReader } from './bit-buffer.js';
+export {
+  GaloisField,
+  GF256_QR,
+  GF256_DM,
+  GF929,
+  GF16,
+  GF64,
+  GF1024,
+  GF4096,
+} from './galois-field.js';
+export { rsEncode, rsDecode, generatorPoly } from './reed-solomon.js';
+export {
+  BarcodeError,
+  EncodeError,
+  NotFoundError,
+  FormatError,
+  ChecksumError,
+} from './errors.js';