qr-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QR Core Contributors
+
+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.

package/README.md

@@ -0,0 +1,126 @@
+# qr-core
+
+Deterministic, zero-dependency QR Code Model 2 encoder for TypeScript/JavaScript. Outputs a binary module matrix and metadata only (no rendering), aligned with the project RFC.
+
+## Highlights
+
+- **Deterministic output**: Same input + same options ⇒ identical version, mask, and matrix.
+- **Strict typing**: TypeScript 5.x, strict mode.
+- **RFC-aligned**: Numeric, alphanumeric, and byte modes; versions 1–40; ECC L/M/Q/H.
+- **Read‑only matrix**: Consumers cannot mutate the QR matrix.
+- **Zero dependencies**: Small, portable, runtime-agnostic.
+
+## Installation
+
+```bash
+npm install qr-core
+```
+
+## Quick Start
+
+```ts
+import { encode } from "qr-core";
+
+const qr = encode("HELLO WORLD");
+console.log(qr.version, qr.mask, qr.size);
+console.log(qr.matrix.get(0, 0));
+```
+
+## Usage
+
+```ts
+import { encode, encodeSafe } from "qr-core";
+
+// Basic
+const qr = encode("https://example.com");
+
+// Advanced options
+const qr2 = encode("https://example.com", {
+  ecc: "H",          // L | M | Q | H
+  version: 5,         // 1..40 or "auto"
+  mask: "auto",      // 0..7 or "auto"
+  mode: "auto",      // numeric | alphanumeric | byte | auto
+  charset: "utf-8",  // utf-8 | iso-8859-1
+  quietZone: 4,       // metadata only
+  strict: true
+});
+
+// Non-throwing variant
+const result = encodeSafe("1234", { mode: "numeric" });
+if (result.ok) {
+  console.log(result.value.version);
+} else {
+  console.error(result.error.code, result.error.message);
+}
+```
+
+## API
+
+### `encode(input, options?) => QrCode`
+
+- `input`: `string | Uint8Array`
+- `options`: `EncodeOptions` (see below)
+- **throws** `QrException` on invalid input/options when `strict=true`
+
+### `encodeSafe(input, options?) => Result<QrCode, QrError>`
+
+Non-throwing wrapper that returns `{ ok: true, value }` or `{ ok: false, error }`.
+
+### Types
+
+```ts
+export type EccLevel = "L" | "M" | "Q" | "H";
+export type QrMode = "auto" | "byte" | "alphanumeric" | "numeric";
+export type MaskId = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+export interface EncodeOptions {
+  ecc?: EccLevel;                   // default: "M"
+  version?: number | "auto";       // default: "auto"
+  mask?: MaskId | "auto";          // default: "auto"
+  mode?: QrMode;                    // default: "auto"
+  charset?: "utf-8" | "iso-8859-1";// default: "utf-8"
+  quietZone?: number;               // default: 4 (metadata only)
+  strict?: boolean;                 // default: true
+}
+
+export interface BitMatrix {
+  readonly size: number;
+  get(x: number, y: number): 0 | 1;
+  toPacked?(): Uint8Array;          // row-major, MSB-first, row padded to byte
+  toRows?(): ReadonlyArray<Uint8Array>;
+}
+
+export interface QrCode {
+  version: number;
+  ecc: EccLevel;
+  mask: MaskId;
+  size: number;
+  matrix: BitMatrix;
+  meta?: QrMeta;
+}
+```
+
+## Matrix Packing Format
+
+If `toPacked()` is available, it returns **row-major**, **MSB‑first** bits. Each row is padded to the next byte boundary with zero bits. Coordinates use `(0,0)` as the **top‑left** module.
+
+## Benchmarks
+
+Run `npm run bench` to reproduce.
+
+| Scenario | Description | p50 (ms) | p95 (ms) |
+| :--- | :--- | :---: | :---: |
+| **Small** | Auto version/mask, ecc M ("HELLO WORLD") | **0.066** | **0.138** |
+| **Medium** | Auto version/mask, ecc M (~500 bytes URL‑ish payload) | **1.262** | **1.403** |
+| **Large** | Auto version/mask, ecc L (3000 bytes) | **3.849** | **3.984** |
+
+> Benchmarks captured on 2026‑01‑31 with Node v24.7.0 (darwin arm64). Goal from RFC: version‑40 near‑capacity with auto‑mask < 5ms — **met**.
+
+## Status & Roadmap
+
+- v1 scope: numeric, alphanumeric, byte; versions 1–40; ECC L/M/Q/H; auto version/mask; deterministic output.
+- Non‑goals in v1: rendering, Kanji, ECI, Structured Append, Micro QR.
+
+## License
+
+MIT

package/dist/bench/bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bench/bench.js

@@ -0,0 +1,38 @@
+import { encode } from "../src/index.js";
+function bench(name, fn, iterations = 100) {
+    // Warmup
+    for (let i = 0; i < 10; i++)
+        fn();
+    const times = [];
+    for (let i = 0; i < iterations; i++) {
+        const start = performance.now();
+        fn();
+        const end = performance.now();
+        times.push(end - start);
+    }
+    times.sort((a, b) => a - b);
+    const p50 = times[Math.floor(times.length * 0.5)] || 0;
+    const p95 = times[Math.floor(times.length * 0.95)] || 0;
+    const avg = times.reduce((a, b) => a + b, 0) / times.length;
+    console.log(`${name}:`);
+    console.log(`  p50: ${p50.toFixed(3)}ms`);
+    console.log(`  p95: ${p95.toFixed(3)}ms`);
+    console.log(`  avg: ${avg.toFixed(3)}ms`);
+}
+async function runBenchmarks() {
+    console.log("Running benchmarks...\n");
+    const smallPayload = "HELLO WORLD";
+    bench("Small Payload (auto version/mask, ecc M)", () => {
+        encode(smallPayload, { ecc: "M" });
+    });
+    const mediumPayload = "https://example.com/search?q=" + "A".repeat(480);
+    bench("Medium Payload (~500 bytes, auto version/mask, ecc M)", () => {
+        encode(mediumPayload, { ecc: "M" });
+    });
+    const largePayload = "A".repeat(3000);
+    // Version 40-L holds 3181 data codewords; 3000 bytes fits.
+    bench("Large Payload (3000 bytes, auto version/mask, ecc L)", () => {
+        encode(largePayload, { ecc: "L" });
+    });
+}
+runBenchmarks();

package/dist/src/api/index.d.ts

@@ -0,0 +1,9 @@
+import type { EncodeOptions, QrCode, QrError, Result } from "../types/index.js";
+/**
+ * High-level API to encode data into a QrCode structure.
+ */
+export declare function encode(input: string | Uint8Array, options?: EncodeOptions): QrCode;
+/**
+ * Safe variant of encode returning a Result object.
+ */
+export declare function encodeSafe(input: string | Uint8Array, options?: EncodeOptions): Result<QrCode, QrError>;

package/dist/src/api/index.js

@@ -0,0 +1,224 @@
+import { err, ok, QrException } from "../core/error.js";
+import { buildBitstream } from "../encoding/bitstream.js";
+import { interleave } from "../encoding/interleave.js";
+import { setupFunctionPatterns, writeVersionInfo } from "../layout/patterns.js";
+import { zigzag } from "../mapping/zigzag.js";
+import { applyMask, writeFormatInformation } from "../mask/selection.js";
+import { Matrix, ReadOnlyMatrix } from "../matrix/bit-matrix.js";
+import { ALPHANUMERIC_CHARSET } from "../spec/constants.js";
+import { BestMaskStrategy } from "../strategies/mask.js";
+// Strategies
+import { GreedySegmentationStrategy } from "../strategies/segmentation.js";
+import { SmallestVersionStrategy } from "../strategies/version.js";
+/**
+ * High-level API to encode data into a QrCode structure.
+ */
+export function encode(input, options = {}) {
+    const ecc = options.ecc ?? "M";
+    const quietZone = options.quietZone ?? 4;
+    const isStrict = options.strict ?? true;
+    const charset = options.charset ?? "utf-8";
+    validateOptions(options, ecc, charset, quietZone);
+    // 1. Segmentation
+    let segments;
+    if (typeof input === "string") {
+        if (options.mode && options.mode !== "auto") {
+            if (options.mode === "numeric" && !isNumeric(input)) {
+                throw new QrException("UNSUPPORTED_MODE", "Input is not representable in numeric mode.");
+            }
+            if (options.mode === "alphanumeric" && !isAlphanumeric(input)) {
+                throw new QrException("UNSUPPORTED_MODE", "Input is not representable in alphanumeric mode.");
+            }
+            segments = [{ mode: options.mode, data: input, count: input.length }];
+        }
+        else {
+            segments = GreedySegmentationStrategy.apply(input);
+        }
+        segments = prepareSegments(segments, charset, isStrict);
+    }
+    else {
+        if (options.mode && options.mode !== "auto" && options.mode !== "byte") {
+            throw new QrException("UNSUPPORTED_MODE", "Uint8Array input can only be encoded with byte mode.");
+        }
+        segments = [
+            {
+                mode: "byte",
+                data: "",
+                count: input.length,
+                bytes: input,
+            },
+        ];
+    }
+    // 2. Version Selection
+    let version;
+    let minVersion = 1;
+    minVersion = SmallestVersionStrategy.select(segments, ecc);
+    if (options.version === "auto" || options.version === undefined) {
+        version = minVersion;
+    }
+    else {
+        const requested = options.version;
+        if (requested < minVersion) {
+            if (isStrict) {
+                throw new QrException("DATA_TOO_LARGE", `Data requires version ${minVersion}, but ${requested} requested.`);
+            }
+            version = minVersion;
+        }
+        else {
+            version = requested;
+        }
+    }
+    // 3. Bitstream & ECC
+    const bitstream = buildBitstream(segments, version, ecc);
+    const interleaved = interleave(bitstream.toBytes(), version, ecc);
+    // 4. Matrix Initialization
+    const size = 21 + 4 * (version - 1);
+    const matrix = new Matrix(size);
+    setupFunctionPatterns(matrix, version);
+    // 5. Data Placement
+    zigzag(matrix, interleaved);
+    // 6. Masking
+    let maskId;
+    let penalties;
+    if (options.mask !== undefined && options.mask !== "auto") {
+        maskId = options.mask;
+        applyMask(matrix, maskId);
+        writeFormatInformation(matrix, ecc, maskId);
+    }
+    else {
+        const result = BestMaskStrategy.select(matrix, ecc);
+        maskId = result.mask;
+        penalties = result.penalties;
+    }
+    // 7. Version Info (for V7+)
+    if (version >= 7) {
+        writeVersionInfo(matrix, version);
+    }
+    const meta = {
+        quietZone,
+        modeUsed: segments.length > 1 ? "mixed" : segments[0]?.mode || "byte",
+        segments: segments.map((s) => ({
+            mode: s.mode,
+            charCount: s.count,
+        })),
+    };
+    if (penalties) {
+        meta.maskPenalties = penalties;
+        const chosen = penalties[maskId];
+        if (chosen === undefined)
+            throw new Error("Internal error: Chosen penalty undefined");
+        meta.chosenPenalty = chosen;
+    }
+    return {
+        version,
+        ecc,
+        mask: maskId,
+        size,
+        matrix: new ReadOnlyMatrix(matrix),
+        meta,
+    };
+}
+/**
+ * Safe variant of encode returning a Result object.
+ */
+export function encodeSafe(input, options) {
+    try {
+        return ok(encode(input, options));
+    }
+    catch (e) {
+        if (e instanceof QrException) {
+            return err(e);
+        }
+        return err(new QrException("INTERNAL_INVARIANT_BROKEN", e instanceof Error ? e.message : String(e), e));
+    }
+}
+function validateOptions(options, ecc, charset, quietZone) {
+    if (!isEcc(ecc)) {
+        throw new QrException("INVALID_OPTIONS", `Invalid ecc level: ${ecc}`);
+    }
+    if (options.version !== undefined && options.version !== "auto") {
+        if (!isIntegerInRange(options.version, 1, 40)) {
+            throw new QrException("INVALID_VERSION", `Invalid version: ${options.version}`);
+        }
+    }
+    if (options.mask !== undefined && options.mask !== "auto") {
+        if (!isIntegerInRange(options.mask, 0, 7)) {
+            throw new QrException("INVALID_MASK", `Invalid mask: ${options.mask}`);
+        }
+    }
+    if (!isIntegerInRange(quietZone, 0, 64)) {
+        throw new QrException("INVALID_OPTIONS", `Invalid quietZone: ${quietZone}`);
+    }
+    if (charset !== "utf-8" && charset !== "iso-8859-1") {
+        throw new QrException("INVALID_OPTIONS", `Invalid charset: ${charset}`);
+    }
+    if (options.mode !== undefined && options.mode !== "auto") {
+        if (options.mode !== "numeric" &&
+            options.mode !== "alphanumeric" &&
+            options.mode !== "byte") {
+            throw new QrException("INVALID_OPTIONS", `Invalid mode: ${options.mode}`);
+        }
+    }
+}
+function isEcc(value) {
+    return value === "L" || value === "M" || value === "Q" || value === "H";
+}
+function isIntegerInRange(value, min, max) {
+    return Number.isInteger(value) && value >= min && value <= max;
+}
+function isNumeric(input) {
+    if (input.length === 0)
+        return true;
+    return /^[0-9]+$/.test(input);
+}
+function isAlphanumeric(input) {
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === undefined || !ALPHANUMERIC_CHARSET.includes(ch))
+            return false;
+    }
+    return true;
+}
+function prepareSegments(segments, charset, strict) {
+    return segments.map((segment) => {
+        switch (segment.mode) {
+            case "numeric":
+                if (!isNumeric(segment.data)) {
+                    throw new QrException("UNSUPPORTED_MODE", "Input is not representable in numeric mode.");
+                }
+                return { ...segment, count: segment.data.length };
+            case "alphanumeric":
+                if (!isAlphanumeric(segment.data)) {
+                    throw new QrException("UNSUPPORTED_MODE", "Input is not representable in alphanumeric mode.");
+                }
+                return { ...segment, count: segment.data.length };
+            case "byte": {
+                const bytes = encodeByteString(segment.data, charset, strict);
+                return { ...segment, bytes, count: bytes.length };
+            }
+        }
+    });
+}
+function encodeByteString(input, charset, strict) {
+    if (charset === "utf-8") {
+        return new TextEncoder().encode(input);
+    }
+    const bytes = [];
+    for (let i = 0; i < input.length; i++) {
+        const codePoint = input.codePointAt(i);
+        if (codePoint === undefined)
+            continue;
+        if (codePoint > 0xff) {
+            if (strict) {
+                throw new QrException("ENCODING_FAILED", "Input contains characters outside ISO-8859-1 range.");
+            }
+            bytes.push(0x3f);
+        }
+        else {
+            bytes.push(codePoint);
+        }
+        if (codePoint > 0xffff)
+            i++;
+    }
+    return new Uint8Array(bytes);
+}

package/dist/src/core/bit-buffer.d.ts

@@ -0,0 +1,11 @@
+export declare class BitBuffer {
+    private buffer;
+    private _length;
+    get length(): number;
+    get byteLength(): number;
+    put(num: number, length: number): void;
+    putBit(bit: number): void;
+    putBytes(bytes: Uint8Array): void;
+    toBytes(): Uint8Array;
+    bitByteAlign(): void;
+}

package/dist/src/core/bit-buffer.js

@@ -0,0 +1,53 @@
+export class BitBuffer {
+    buffer = [];
+    _length = 0;
+    get length() {
+        return this._length;
+    }
+    get byteLength() {
+        return (this._length + 7) >>> 3;
+    }
+    put(num, length) {
+        if (length === 0)
+            return;
+        // We iterate from MSB to LSB
+        for (let i = 0; i < length; i++) {
+            const bit = (num >>> (length - 1 - i)) & 1;
+            this.putBit(bit);
+        }
+    }
+    putBit(bit) {
+        const bufIndex = this._length >>> 3;
+        if (this.buffer.length <= bufIndex) {
+            this.buffer.push(0);
+        }
+        if (bit) {
+            const current = this.buffer[bufIndex];
+            // Initialize if undefined (though push(0) above should handle this)
+            // But relying on array index validity is key.
+            if (current !== undefined) {
+                this.buffer[bufIndex] = current | (0x80 >>> (this._length & 7));
+            }
+            else {
+                // This branch should theoretically be unreachable due to the push check above
+                this.buffer[bufIndex] = 0x80 >>> (this._length & 7);
+            }
+        }
+        this._length++;
+    }
+    putBytes(bytes) {
+        for (const byte of bytes) {
+            this.put(byte, 8);
+        }
+    }
+    toBytes() {
+        return new Uint8Array(this.buffer);
+    }
+    // Helper to pad with zeroes to next byte boundary
+    bitByteAlign() {
+        const remainder = this._length & 7;
+        if (remainder > 0) {
+            this.put(0, 8 - remainder);
+        }
+    }
+}

package/dist/src/core/error.d.ts

@@ -0,0 +1,8 @@
+import type { QrError, QrErrorCode, Result } from "../types/index.js";
+export declare class QrException extends Error implements QrError {
+    readonly code: QrErrorCode;
+    readonly details?: unknown;
+    constructor(code: QrErrorCode, message: string, details?: unknown);
+}
+export declare function ok<T>(value: T): Result<T, never>;
+export declare function err<E>(error: E): Result<never, E>;

package/dist/src/core/error.js

@@ -0,0 +1,16 @@
+export class QrException extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "QrException";
+        this.code = code;
+        this.details = details;
+    }
+}
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}

package/dist/src/core/gf.d.ts

@@ -0,0 +1,4 @@
+export declare const EXP: Uint8Array<ArrayBuffer>;
+export declare const LOG: Uint8Array<ArrayBuffer>;
+export declare function mul(a: number, b: number): number;
+export declare function inv(n: number): number;

package/dist/src/core/gf.js

@@ -0,0 +1,52 @@
+const PRIMITIVE = 0x11d;
+export const EXP = new Uint8Array(512); // Double size to avoid modulo in mul
+export const LOG = new Uint8Array(256);
+// Initialize tables
+(function initTables() {
+    let x = 1;
+    for (let i = 0; i < 255; i++) {
+        EXP[i] = x;
+        LOG[x] = i;
+        x <<= 1;
+        if (x & 0x100) {
+            x ^= PRIMITIVE;
+        }
+    }
+    // Fill the rest of EXP (periodic)
+    for (let i = 255; i < 512; i++) {
+        // Safe because i-255 is in [0, 255] range and EXP is initialized up to 254 in previous loop
+        // and initialized with 0s by default. Logic ensures we read valid data.
+        const val = EXP[i - 255];
+        EXP[i] = val !== undefined ? val : 0;
+    }
+})();
+export function mul(a, b) {
+    if (a === 0 || b === 0)
+        return 0;
+    // Check bounds or rely on safe access helper?
+    // Arrays are fixed size.
+    // LOG[a] can be undefined if a >= 256, but input is byte.
+    // We assume a, b are bytes.
+    const logA = LOG[a];
+    const logB = LOG[b];
+    // This is mathematically impossible if a,b are bytes != 0.
+    // But for type safety we must check.
+    if (logA === undefined || logB === undefined) {
+        throw new Error(`Invalid input for GF multiplication: ${a}, ${b}`);
+    }
+    const expIndex = logA + logB;
+    // expIndex max 508. EXP size 512.
+    const result = EXP[expIndex];
+    if (result === undefined) {
+        throw new Error(`Internal GF error: EXP table underflow/overflow at index ${expIndex}`);
+    }
+    return result;
+}
+export function inv(n) {
+    if (n === 0)
+        throw new Error("Division by zero");
+    const logN = LOG[n];
+    if (logN === undefined)
+        throw new Error(`Invalid input for GF inversion: ${n}`);
+    return EXP[255 - logN] ?? 0; // Fallback 0 should essentially never happen given table construction
+}

package/dist/src/core/rs.d.ts

@@ -0,0 +1 @@
+export declare function computeEcc(data: Uint8Array, eccLen: number): Uint8Array;

package/dist/src/core/rs.js

@@ -0,0 +1,60 @@
+import { EXP, LOG, mul } from "./gf.js";
+const GEN_POLY_CACHE = new Map();
+function getGeneratorPoly(eccLen) {
+    const cached = GEN_POLY_CACHE.get(eccLen);
+    if (cached)
+        return cached;
+    const poly = new Uint8Array(eccLen + 1);
+    poly[0] = 1;
+    // We multiply successively by (x - 2^i) for i=0..eccLen-1
+    // In GF(2^8), subtraction is same as addition (XOR).
+    // So we multiply by (x + 2^i).
+    for (let i = 0; i < eccLen; i++) {
+        const root = EXP[i];
+        if (root === undefined)
+            throw new Error("Internal error: EXP lookup failed");
+        // Multiply poly by (x + root)
+        // Coeffs shift: new_coeff[j] = coeff[j] ^ (coeff[j-1] * root)
+        // We iterate backwards to use the 'old' values of j-1.
+        for (let j = i + 1; j >= 1; j--) {
+            const current = poly[j];
+            const prev = poly[j - 1];
+            if (current === undefined || prev === undefined) {
+                throw new Error("Internal error: Poly index out of bounds");
+            }
+            poly[j] = current ^ mul(prev, root);
+        }
+    }
+    GEN_POLY_CACHE.set(eccLen, poly);
+    return poly;
+}
+export function computeEcc(data, eccLen) {
+    const genPoly = getGeneratorPoly(eccLen);
+    const remainder = new Uint8Array(eccLen);
+    const log = LOG;
+    const exp = EXP;
+    for (const byte of data) {
+        const firstCoeff = remainder[0] ?? 0;
+        const factor = firstCoeff ^ byte;
+        // Shift remainder left
+        // Using copyWithin is faster than set/subarray for small arrays?
+        // remainder.set(remainder.subarray(1), 0);
+        // remainder.copyWithin(0, 1); // standard
+        remainder.copyWithin(0, 1);
+        remainder[eccLen - 1] = 0;
+        if (factor !== 0) {
+            const logFactor = log[factor] ?? 0;
+            for (let i = 0; i < eccLen; i++) {
+                const genCoeff = genPoly[i + 1];
+                if (genCoeff !== 0 && genCoeff !== undefined) {
+                    // Inlined mul
+                    const logVal = log[genCoeff] ?? 0;
+                    const expVal = exp[logVal + logFactor] ?? 0;
+                    const current = remainder[i] ?? 0;
+                    remainder[i] = current ^ expVal;
+                }
+            }
+        }
+    }
+    return remainder;
+}

package/dist/src/encoding/bitstream.d.ts

@@ -0,0 +1,7 @@
+import { BitBuffer } from "../core/bit-buffer.js";
+import type { EccLevel } from "../types/index.js";
+import type { Segment } from "./segmentation.js";
+/**
+ * Combines encoded segments and applies padding to create the final data bitstream.
+ */
+export declare function buildBitstream(segments: Segment[], version: number, ecc: EccLevel): BitBuffer;