qr-core 1.0.0

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

@@ -0,0 +1,3 @@
+export * from "./mask.js";
+export * from "./segmentation.js";
+export * from "./version.js";

package/dist/src/strategies/index.js

@@ -0,0 +1,3 @@
+export * from "./mask.js";
+export * from "./segmentation.js";
+export * from "./version.js";

package/dist/src/strategies/mask.d.ts

@@ -0,0 +1,16 @@
+import type { Matrix } from "../matrix/bit-matrix.js";
+import type { EccLevel, MaskId } from "../types/index.js";
+export interface MaskResult {
+    mask: MaskId;
+    penalties: number[];
+}
+/**
+ * Strategy for selecting the best mask pattern.
+ */
+export interface MaskStrategy {
+    select(matrix: Matrix, ecc: EccLevel): MaskResult;
+}
+/**
+ * Evaluates all 8 masks and picks the one with the lowest penalty.
+ */
+export declare const BestMaskStrategy: MaskStrategy;

package/dist/src/strategies/mask.js

@@ -0,0 +1,9 @@
+import { selectAndApplyBestMask } from "../mask/selection.js";
+/**
+ * Evaluates all 8 masks and picks the one with the lowest penalty.
+ */
+export const BestMaskStrategy = {
+    select(matrix, ecc) {
+        return selectAndApplyBestMask(matrix, ecc);
+    },
+};

package/dist/src/strategies/segmentation.d.ts

@@ -0,0 +1,12 @@
+import type { Segment } from "../encoding/segmentation.js";
+/**
+ * Strategy for splitting input data into segments with optimal encoding modes.
+ */
+export interface SegmentationStrategy {
+    apply(input: string): Segment[];
+}
+/**
+ * Default greedy strategy that switches mode when a character requires it.
+ * Not optimal but efficient and simple.
+ */
+export declare const GreedySegmentationStrategy: SegmentationStrategy;

package/dist/src/strategies/segmentation.js

@@ -0,0 +1,41 @@
+import { segmentize } from "../encoding/segmentation.js";
+/**
+ * Default greedy strategy that switches mode when a character requires it.
+ * Not optimal but efficient and simple.
+ */
+export const GreedySegmentationStrategy = {
+    apply(input) {
+        const greedy = segmentize(input);
+        // Optimization: If mixed segments, check if pure Byte mode is smaller.
+        // "Hello World" case: Greedy splits into Alpha/Byte/Alpha/Byte = high overhead.
+        // Pure Byte is often better for short ASCII strings.
+        if (greedy.length > 1) {
+            const byteSeg = { mode: "byte", data: input, count: input.length };
+            const greedyBits = estimateCost(greedy);
+            const byteBits = estimateCost([byteSeg]);
+            if (byteBits < greedyBits) {
+                return [byteSeg];
+            }
+        }
+        return greedy;
+    },
+};
+function estimateCost(segments) {
+    let bits = 0;
+    for (const s of segments) {
+        // Overhead: Mode(4) + Count(var). Use V1 constants (conservative overhead cost).
+        // Numeric: 10, Alpha: 9, Byte: 8
+        if (s.mode === "numeric")
+            bits += 4 + 10 + Math.ceil(s.count / 3) * 10;
+        // Alpha: 11 bits per 2 chars. 6 for last.
+        else if (s.mode === "alphanumeric") {
+            const pairs = Math.floor(s.count / 2);
+            const odd = s.count % 2;
+            bits += 4 + 9 + pairs * 11 + odd * 6;
+        }
+        // Byte
+        else
+            bits += 4 + 8 + s.count * 8;
+    }
+    return bits;
+}

package/dist/src/strategies/version.d.ts

@@ -0,0 +1,12 @@
+import type { Segment } from "../encoding/segmentation.js";
+import type { EccLevel } from "../types/index.js";
+/**
+ * Strategy for selecting the smallest QR version that fits the data.
+ */
+export interface VersionStrategy {
+    select(segments: Segment[], ecc: EccLevel): number;
+}
+/**
+ * Iterates from MIN_VERSION to MAX_VERSION to find the first one that fits.
+ */
+export declare const SmallestVersionStrategy: VersionStrategy;

package/dist/src/strategies/version.js

@@ -0,0 +1,22 @@
+import { QrException } from "../core/error.js";
+import { buildBitstream } from "../encoding/bitstream.js";
+import { MAX_VERSION, MIN_VERSION } from "../spec/constants.js";
+/**
+ * Iterates from MIN_VERSION to MAX_VERSION to find the first one that fits.
+ */
+export const SmallestVersionStrategy = {
+    select(segments, ecc) {
+        for (let v = MIN_VERSION; v <= MAX_VERSION; v++) {
+            try {
+                // Try to build bitstream specifically for this version to check capacity
+                // This is less efficient than just checking capacity tables but safer
+                // as it accounts for mode overheads correctly
+                // TODO: Optimize by checking capacity table directly first
+                buildBitstream(segments, v, ecc);
+                return v;
+            }
+            catch (_e) { }
+        }
+        throw new QrException("DATA_TOO_LARGE", "Data exceeds maximum QR capacity");
+    },
+};

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

@@ -0,0 +1,51 @@
+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;
+    version?: number | "auto";
+    mask?: MaskId | "auto";
+    mode?: QrMode;
+    charset?: "utf-8" | "iso-8859-1";
+    quietZone?: number;
+    strict?: boolean;
+}
+export interface BitMatrix {
+    readonly size: number;
+    get(x: number, y: number): 0 | 1;
+    toPacked?(): Uint8Array;
+    toRows?(): ReadonlyArray<Uint8Array>;
+}
+export interface SegmentInfo {
+    mode: Exclude<QrMode, "auto">;
+    charCount: number;
+}
+export interface QrMeta {
+    quietZone: number;
+    modeUsed: Exclude<QrMode, "auto"> | "mixed";
+    segments: ReadonlyArray<SegmentInfo>;
+    maskPenalties?: ReadonlyArray<number>;
+    chosenPenalty?: number;
+    details?: Readonly<Record<string, unknown>>;
+}
+export type QrErrorCode = "INVALID_OPTIONS" | "UNSUPPORTED_MODE" | "DATA_TOO_LARGE" | "INVALID_VERSION" | "INVALID_MASK" | "ENCODING_FAILED" | "INTERNAL_INVARIANT_BROKEN";
+export interface QrError {
+    code: QrErrorCode;
+    message: string;
+    details?: unknown;
+}
+export type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export interface QrCode {
+    version: number;
+    ecc: EccLevel;
+    mask: MaskId;
+    size: number;
+    matrix: BitMatrix;
+    meta?: QrMeta;
+}

package/dist/src/types/index.js

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

package/dist/tests/golden/golden.test.d.ts

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

package/dist/tests/golden/golden.test.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { encode } from "../../src/api/index";
+const vectorsDir = path.join(__dirname, "../vectors");
+const vectorFiles = fs
+    .readdirSync(vectorsDir)
+    .filter((f) => f.endsWith(".json"));
+let vectors = [];
+for (const file of vectorFiles) {
+    const content = JSON.parse(fs.readFileSync(path.join(vectorsDir, file), "utf-8"));
+    vectors = vectors.concat(content);
+}
+describe("Golden Vectors", () => {
+    for (const vec of vectors) {
+        it(`should match vector: ${vec.name}`, () => {
+            // Normalize inputs
+            // biome-ignore lint/suspicious/noExplicitAny: generic casting for options
+            const opts = { ...vec.options };
+            const result = encode(vec.input.value, opts);
+            expect(result.version).toBe(vec.expected.version);
+            expect(result.size).toBe(vec.expected.size);
+            // In a real golden test, we would compare the entire matrix hash/bits
+        });
+    }
+});

package/dist/tests/unit/api.test.d.ts

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

package/dist/tests/unit/api.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { encode, encodeSafe } from "../../src/api/index";
+describe("Public API", () => {
+    it("should encode simple string", () => {
+        const result = encode("Hello World");
+        expect(result.version).toBeGreaterThan(0);
+        expect(result.size).toBeGreaterThan(0);
+        expect(result.matrix).toBeDefined();
+    });
+    it("should allow forcing version", () => {
+        const result = encode("A", { version: 5 });
+        expect(result.version).toBe(5);
+        expect(result.size).toBe(21 + 4 * (5 - 1));
+    });
+    it("should throw if data too large for fixed version", () => {
+        // Version 1 can only hold ~17 bytes (Ecc L)
+        // "A" * 100 needs version ~4
+        const largeData = "A".repeat(100);
+        // Expect message to contain "Data requires version"
+        expect(() => encode(largeData, { version: 1 })).toThrow(/Data requires version/);
+    });
+    it("should safe encode without throwing", () => {
+        const largeData = "A".repeat(100);
+        const result = encodeSafe(largeData, { version: 1 });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("DATA_TOO_LARGE");
+        }
+    });
+    it("should support Uint8Array input", () => {
+        const input = new Uint8Array([65, 66, 67]);
+        const result = encode(input, { mode: "byte" });
+        expect(result.version).toBe(1);
+    });
+});

package/dist/tests/unit/bit-matrix.test.d.ts

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

package/dist/tests/unit/bit-matrix.test.js

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { Matrix } from "../../src/matrix/bit-matrix";
+describe("BitMatrix", () => {
+    it("should initialize with correct size and default values", () => {
+        const size = 21;
+        const matrix = new Matrix(size);
+        expect(matrix.size).toBe(size);
+        expect(matrix.get(0, 0)).toBe(0);
+        expect(matrix.get(size - 1, size - 1)).toBe(0);
+    });
+    it("should set and get values", () => {
+        const matrix = new Matrix(21);
+        matrix.set(5, 5, true);
+        expect(matrix.get(5, 5)).toBe(1);
+        matrix.set(5, 5, false);
+        expect(matrix.get(5, 5)).toBe(0);
+    });
+    it("should handle reserved modules", () => {
+        const matrix = new Matrix(21);
+        matrix.setReserved(10, 10, true);
+        expect(matrix.isReserved(10, 10)).toBe(true);
+        expect(matrix.get(10, 10)).toBe(1);
+        // Normal set should not overwrite reserved
+        matrix.set(10, 10, false);
+        expect(matrix.get(10, 10)).toBe(1);
+    });
+    it("should throw on out of bounds access", () => {
+        const matrix = new Matrix(21);
+        expect(() => matrix.get(-1, 0)).toThrow();
+        expect(() => matrix.get(0, 21)).toThrow();
+        expect(() => matrix.set(21, 0, true)).toThrow();
+        expect(() => matrix.setReserved(0, -1, true)).toThrow();
+    });
+    it("should serialize to packed bytes correct MSB-first order", () => {
+        // Size 9 -> 2 bytes per row
+        // Row 0: 10000000 1.......
+        const matrix = new Matrix(9);
+        matrix.set(0, 0, true); // First bit
+        matrix.set(8, 0, true); // 9th bit (first bit of second byte)
+        const packed = matrix.toPacked();
+        expect(packed.length).toBe(9 * 2);
+        // Row 0
+        expect(packed[0]).toBe(0x80); // 10000000
+        expect(packed[1]).toBe(0x80); // 10000000 (padded)
+    });
+});

package/dist/tests/unit/core.test.d.ts

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

package/dist/tests/unit/core.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { BitBuffer } from "../../src/core/bit-buffer";
+import { EXP, inv, LOG, mul } from "../../src/core/gf";
+import { computeEcc } from "../../src/core/rs";
+describe("GF(256)", () => {
+    it("should have correct table sizes", () => {
+        expect(EXP.length).toBe(512);
+        expect(LOG.length).toBe(256);
+    });
+    it("EXP[0] should be 1", () => {
+        expect(EXP[0]).toBe(1);
+        expect(EXP[255]).toBe(1);
+    });
+    it("LOG[1] should be 0", () => {
+        expect(LOG[1]).toBe(0);
+    });
+    it("multiplication should be correct", () => {
+        expect(mul(0, 5)).toBe(0);
+        expect(mul(5, 0)).toBe(0);
+        expect(mul(1, 10)).toBe(10);
+        // 2 * 2 = 4
+        expect(mul(2, 2)).toBe(4);
+        // Inverse check
+        const a = 123;
+        const invA = inv(a);
+        expect(mul(a, invA)).toBe(1);
+    });
+});
+describe("BitBuffer", () => {
+    it("should append bits correctly", () => {
+        const bb = new BitBuffer();
+        bb.put(0b1, 1);
+        bb.put(0b0, 1);
+        bb.put(0b1, 1);
+        // current: 101 (5)
+        // length: 3
+        expect(bb.length).toBe(3);
+        const bytes = bb.toBytes();
+        // 10100000 = 0xA0
+        expect(bytes[0]).toBe(0xa0);
+    });
+    it("should handle multi-bit put", () => {
+        const bb = new BitBuffer();
+        // append 0xABC (101010111100) 12 bits
+        bb.put(0xabc, 12);
+        expect(bb.length).toBe(12);
+        const bytes = bb.toBytes();
+        // 10101011 1100xxxx
+        // 0xAB     0xC0
+        expect(bytes[0]).toBe(0xab);
+        expect((bytes[1] ?? 0) & 0xf0).toBe(0xc0);
+    });
+});
+describe("Reed-Solomon", () => {
+    it("should return all zeros for zero data", () => {
+        const data = new Uint8Array([0, 0, 0]);
+        const ecc = computeEcc(data, 5);
+        expect(ecc).toEqual(new Uint8Array(5));
+    });
+    // Simple known vector check could be added here if we had one.
+    // Using a known property check:
+    // If we encode M(x), then M(x)x^n + R(x) is a codeword.
+    // This means it evaluates to 0 at the roots of G(x)?
+    // Roots of G(x) are 2^0, 2^1 ... 2^{n-1}.
+    // Let's check with eccLen=2. Roots 2^0=1, 2^1=2.
+    // Codeword C(x) should satisfy C(1)=0 and C(2)=0.
+    it("should produce valid codewords (eval to 0 at roots)", () => {
+        const message = new Uint8Array([10, 20, 30]);
+        const eccLen = 2; // Roots: 1, 2
+        const ecc = computeEcc(message, eccLen);
+        // Construct full codeword: message * x^n + ecc
+        // Coefficients: [10, 20, 30, ecc[0], ecc[1]]
+        const codeword = new Uint8Array([...message, ...ecc]);
+        // Evaluate at root 1 (2^0) = 1
+        // Eval(x) = c0*x^4 + c1*x^3 + ...
+        function evalPoly(poly, x) {
+            let res = 0;
+            for (const coeff of poly) {
+                res = mul(res, x) ^ coeff;
+            }
+            return res;
+        }
+        const root0 = EXP[0] ?? 0; // 1
+        const root1 = EXP[1] ?? 0; // 2
+        expect(evalPoly(codeword, root0)).toBe(0);
+        expect(evalPoly(codeword, root1)).toBe(0);
+    });
+});

package/dist/tests/unit/encoding.test.d.ts

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

package/dist/tests/unit/encoding.test.js

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { BitBuffer } from "../../src/core/bit-buffer";
+import { encodeAlphanumeric, encodeByte, encodeNumeric, } from "../../src/encoding/encoders";
+import { interleave } from "../../src/encoding/interleave";
+import { segmentize } from "../../src/encoding/segmentation";
+describe("Encoders", () => {
+    it("should encode numeric data", () => {
+        const buffer = new BitBuffer();
+        // "01234567" -> "012" (10 bits) + "345" (10 bits) + "67" (7 bits)
+        encodeNumeric("01234567", buffer);
+        // 012 = 0000001100
+        // 345 = 0101011001
+        // 67  = 1000011
+        expect(buffer.length).toBe(27);
+    });
+    it("should encode alphanumeric data", () => {
+        const buffer = new BitBuffer();
+        // "AC-42" -> "AC" (11) + "-4" (11) + "2" (6)
+        encodeAlphanumeric("AC-42", buffer);
+        expect(buffer.length).toBe(11 + 11 + 6);
+    });
+    it("should encode byte data", () => {
+        const buffer = new BitBuffer();
+        encodeByte("Hello", buffer);
+        expect(buffer.length).toBe(5 * 8);
+    });
+});
+describe("Segmentation", () => {
+    it("should segment simple numeric", () => {
+        const segments = segmentize("0123456789");
+        expect(segments).toHaveLength(1);
+        expect(segments[0]?.mode).toBe("numeric");
+    });
+    it("should segment simple alphanumeric", () => {
+        const segments = segmentize("HELLO WORLD");
+        expect(segments).toHaveLength(1);
+        expect(segments[0]?.mode).toBe("alphanumeric");
+    });
+    it("should segment mixed content", () => {
+        // "123ABC123" -> numeric, alphanumeric, numeric
+        // Our greedy segmenter might merge if it's suboptimal, but let's see current behavior.
+        // "123" (num) "ABC" (alnum) "123" (num)
+        const segments = segmentize("123ABC123");
+        // Actually, greedy might switch eagerly.
+        // "123" -> numeric
+        // "A" -> switch to Alnum
+        // "123" -> switch to Numeric
+        expect(segments.map((s) => s.mode)).toEqual([
+            "numeric",
+            "alphanumeric",
+            "numeric",
+        ]);
+    });
+});
+describe("Interleave", () => {
+    it("should interleave data and ecc correctly", () => {
+        // Mock data that fits version 1-L (19 data bytes)
+        const data = new Uint8Array(19).fill(0x11);
+        // Version 1-L: 19 data bytes, 7 ECC bytes. Total 26.
+        const result = interleave(data, 1, "L");
+        expect(result.length).toBe(26);
+    });
+});

package/dist/tests/unit/layout.test.d.ts

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

package/dist/tests/unit/layout.test.js

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { setupFunctionPatterns } from "../../src/layout/patterns";
+import { Matrix } from "../../src/matrix/bit-matrix";
+describe("Layout Patterns", () => {
+    it("should set up finder patterns", () => {
+        const matrix = new Matrix(21);
+        setupFunctionPatterns(matrix, 1);
+        // Top Left Finder
+        expect(matrix.isReserved(3, 3)).toBe(true); // Center of 3x3
+        // Finder is 7x7. (0,0) to (6,6). Center (3,3).
+        // (3,3) is dark.
+        expect(matrix.get(3, 3)).toBe(1);
+        // (0,0) is dark (outer ring)
+        expect(matrix.get(0, 0)).toBe(1);
+        // (1,1) is light (gap between outer and inner) - wait no
+        // 7x7 finder:
+        // xxxxxxx
+        // x.....x
+        // x.xxx.x
+        // x.xxx.x
+        // x.xxx.x
+        // x.....x
+        // xxxxxxx
+        // (0,0) dark
+        // (1,1) light?
+        // Logic: max(abs(x-3), abs(y-3))
+        // (1,1): abs(-2)=2. max(2,2)=2.
+        // isDark = (max === 3) || (max <= 1).
+        // 2 is not 3, nor <= 1. So light. Correct.
+        expect(matrix.get(1, 1)).toBe(0);
+    });
+    it("should set up timing patterns", () => {
+        const matrix = new Matrix(21);
+        setupFunctionPatterns(matrix, 1);
+        // Row 6, Cols 8..Size-8 (8..13 for V1)
+        // (8, 6) -> i=8. even -> dark (true)
+        // (9, 6) -> light
+        expect(matrix.isReserved(8, 6)).toBe(true);
+        expect(matrix.get(8, 6)).toBe(1);
+        expect(matrix.get(9, 6)).toBe(0);
+    });
+    it("should set up alignment patterns for V2", () => {
+        const matrix = new Matrix(25); // V2 size
+        setupFunctionPatterns(matrix, 2);
+        // V2 alignment at 6, 18
+        // (6,6) is finder.
+        // (18,18) should be alignment center.
+        // Alignment is 5x5 center (18,18).
+        expect(matrix.isReserved(18, 18)).toBe(true);
+        // Center is dark
+        expect(matrix.get(18, 18)).toBe(1);
+    });
+    it("should set up version info for V7", () => {
+        const matrix = new Matrix(45); // V7 size
+        setupFunctionPatterns(matrix, 7);
+        // Version info is 3x6 block above bottom-left finder and left of top-right finder.
+        // Bottom-left finder is at (0, Size-7).
+        // Version info above it: Row Size-11..Size-9. Col 0..5
+        // Let's check reservation.
+        expect(matrix.isReserved(0, 45 - 11)).toBe(true);
+    });
+});

package/dist/tests/unit/masking.test.d.ts

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

package/dist/tests/unit/masking.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { applyMask, selectAndApplyBestMask } from "../../src/mask/selection";
+import { Matrix } from "../../src/matrix/bit-matrix";
+describe("Masking", () => {
+    it("should allow applying a specific mask", () => {
+        const matrix = new Matrix(21);
+        // Mask 0: (x+y)%2 == 0
+        applyMask(matrix, 0);
+        // (0,0) -> even -> flip inv (0->1)
+        expect(matrix.get(0, 0)).toBe(1);
+        // (0,1) -> odd -> 0
+        expect(matrix.get(0, 1)).toBe(0);
+    });
+    it("should select the best mask", () => {
+        const matrix = new Matrix(21);
+        // Empty matrix -> penalty calculation will favor a mask that breaks up large white areas
+        // or one that doesn't create false patterns.
+        const result = selectAndApplyBestMask(matrix, "M");
+        expect(result.mask).toBeGreaterThanOrEqual(0);
+        expect(result.mask).toBeLessThanOrEqual(7);
+        expect(result.penalties).toHaveLength(8);
+        // Ensure format info was written
+        // (8,0) to (8,8) area
+        let formatInfoWritten = false;
+        for (let i = 0; i < 9; i++) {
+            if (matrix.isReserved(i, 8))
+                formatInfoWritten = true;
+        }
+        expect(formatInfoWritten).toBe(true);
+    });
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "qr-core",
+  "version": "1.0.0",
+  "description": "Deterministic, zero-dependency QR Code Model 2 encoder (matrix-only)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest",
+    "lint": "biome check src tests bench",
+    "format": "biome format --write src tests bench",
+    "bench": "npm run build && node dist/bench/bench.js"
+  },
+  "keywords": [
+    "qr",
+    "qrcode",
+    "qr-code",
+    "encoder",
+    "matrix",
+    "typescript",
+    "esm"
+  ],
+  "author": "QR Core Contributors",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@types/node": "^25.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}