specqr 1.0.0-rc.1

package/src/index.js

@@ -0,0 +1,255 @@
+import { interleaveCodewords } from "./core/codewords.js";
+import { buildMatrix } from "./core/matrix.js";
+import {
+  createSegments,
+  encodeSegments,
+  encodeUtf8,
+  getSegmentByteCount,
+  getSegmentTextCharacterCount,
+  getSegmentsBitLength,
+  isBinaryInput,
+  normalizeManualSegments,
+  prependEciSegment,
+  prependFnc1Segment,
+  toByteArray
+} from "./encoding/modes.js";
+import { ERROR_CORRECTION_LEVEL_ORDER, getDataCodewordCount, getSize } from "./core/tables.js";
+import { createDiagnostics } from "./diagnostics.js";
+import { createGs1ElementString, GS1_FNC1_SEPARATOR, parseGs1HumanReadable } from "./gs1.js";
+import { DataTooLongError, InvalidGs1Error, InvalidOutputError } from "./errors.js";
+import { normalizeOptions } from "./options.js";
+import { renderCanvas } from "./render/canvas.js";
+import { renderPng, renderPngDataUrl } from "./render/png.js";
+import { renderSvg, renderSvgDataUrl } from "./render/svg.js";
+
+export { createGs1ElementString, GS1_FNC1_SEPARATOR, parseGs1HumanReadable } from "./gs1.js";
+
+export {
+  DataTooLongError,
+  InvalidCanvasTargetError,
+  InvalidColorError,
+  InvalidEciError,
+  InvalidGs1Error,
+  InvalidInputError,
+  InvalidModeError,
+  InvalidOutputError,
+  InvalidVersionError,
+  SpecQRError
+} from "./errors.js";
+
+export class QRCode {
+  static generate(input, options = {}) {
+    return generate(input, options);
+  }
+
+  static generateSegments(segments, options = {}) {
+    return generateSegments(segments, options);
+  }
+
+  static drawToCanvas(target, input, options = {}) {
+    return drawToCanvas(target, input, options);
+  }
+
+  static createGs1ElementString(elements) {
+    return createGs1ElementString(elements);
+  }
+
+  static parseGs1HumanReadable(input) {
+    return parseGs1HumanReadable(input);
+  }
+}
+
+export function generate(input, options = {}) {
+  const normalized = normalizeOptions(options);
+  const plan = selectPlanForInput(input, normalized);
+  return renderResult(plan, normalized, getInputByteCount(input));
+}
+
+export function generateSegments(segments, options = {}) {
+  const normalized = normalizeOptions(options);
+  const normalizedSegments = normalizeManualSegments(segments);
+  const plan = selectPlanForManualSegments(normalizedSegments, normalized);
+  return renderResult(plan, normalized, getSegmentsInputByteCount(normalizedSegments));
+}
+
+export function drawToCanvas(target, input, options = {}) {
+  const normalized = normalizeOptions({
+    ...options,
+    output: "matrix",
+    diagnostics: false
+  });
+  const matrix = generate(input, {
+    ...normalized,
+    output: "matrix",
+    diagnostics: false
+  });
+
+  return renderCanvas(target, matrix, normalized);
+}
+
+function renderResult(plan, normalized, inputBytes) {
+  const capacityBits = getDataCodewordCount(plan.version, plan.errorCorrectionLevel) * 8;
+  const data = encodeSegments(plan.segments, plan.version, plan.errorCorrectionLevel);
+  const interleaved = interleaveCodewords(data, plan.version, plan.errorCorrectionLevel);
+  const built = buildMatrix(
+    interleaved.codewords,
+    plan.version,
+    plan.errorCorrectionLevel,
+    normalized.maskPattern
+  );
+  const svg = normalized.output === "svg" || normalized.output === "svg-data-url" || normalized.diagnostics
+    ? renderSvg(built.matrix, normalized)
+    : undefined;
+
+  if (normalized.diagnostics) {
+    return {
+      matrix: built.matrix,
+      svg,
+      diagnostics: createDiagnostics({
+        plan,
+        built,
+        options: normalized,
+        inputBytes,
+        capacityBits,
+        interleaved,
+        getSize,
+        getDiagnosticMode,
+        getFirstEciAssignmentNumber,
+        getFirstFnc1Mode,
+        getSegmentDiagnostics: (segment) => ({
+          mode: segment.mode,
+          assignmentNumber: segment.assignmentNumber,
+          characterCount: getSegmentTextCharacterCount(segment),
+          byteCount: getSegmentByteCount(segment),
+          bitLength: getSegmentsBitLength([segment], plan.version)
+        })
+      })
+    };
+  }
+
+  switch (normalized.output) {
+    case "matrix":
+      return built.matrix;
+    case "svg":
+      return svg;
+    case "svg-data-url":
+      return renderSvgDataUrl(built.matrix, normalized);
+    case "png":
+      return renderPng(built.matrix, normalized);
+    case "png-data-url":
+      return renderPngDataUrl(built.matrix, normalized);
+    default:
+      throw new InvalidOutputError(`Unsupported output: ${normalized.output}`);
+  }
+}
+
+function selectPlanForInput(input, options) {
+  if (options.gs1 && isBinaryInput(input)) {
+    throw new InvalidGs1Error("gs1 input must be a GS1 element string, not binary input");
+  }
+  return selectPlan(
+    (version) => prependFnc1Segment(
+      createSegments(input, options.mode, version, options.optimizeSegments, options.eci),
+      options.gs1
+    ),
+    options
+  );
+}
+
+function selectPlanForManualSegments(segments, options) {
+  return selectPlan(
+    () => prependFnc1Segment(prependEciSegment(segments, options.eci), options.gs1),
+    options
+  );
+}
+
+function selectPlan(createSegmentsForVersion, options) {
+  if (options.version !== "auto") {
+    return withBoostedErrorCorrection({
+      ...ensureFits(createSegmentsForVersion, options.version, options),
+      versionSelection: "fixed"
+    }, options);
+  }
+
+  for (let version = options.minVersion; version <= options.maxVersion; version += 1) {
+    const plan = createPlan(createSegmentsForVersion, version, options);
+    if (plan.dataBitLength <= getDataCodewordCount(version, options.errorCorrectionLevel) * 8) {
+      return withBoostedErrorCorrection({
+        ...plan,
+        versionSelection: "auto-minimum"
+      }, options);
+    }
+  }
+
+  throw new DataTooLongError(
+    `Input requires more capacity than versions ${options.minVersion}..${options.maxVersion} at error correction ${options.errorCorrectionLevel}`
+  );
+}
+
+function ensureFits(createSegmentsForVersion, version, options) {
+  const plan = createPlan(createSegmentsForVersion, version, options);
+  if (plan.dataBitLength > getDataCodewordCount(version, options.errorCorrectionLevel) * 8) {
+    const capacityBits = getDataCodewordCount(version, options.errorCorrectionLevel) * 8;
+    throw new DataTooLongError(
+      `Input requires ${plan.dataBitLength} bits, but version ${version}-${options.errorCorrectionLevel} has ${capacityBits} data bits`
+    );
+  }
+
+  return plan;
+}
+
+function createPlan(createSegmentsForVersion, version, options) {
+  const segments = createSegmentsForVersion(version);
+  return {
+    version,
+    segments,
+    dataBitLength: getSegmentsBitLength(segments, version),
+    errorCorrectionLevel: options.errorCorrectionLevel,
+    requestedErrorCorrectionLevel: options.errorCorrectionLevel,
+    boostedErrorCorrection: false
+  };
+}
+
+function withBoostedErrorCorrection(plan, options) {
+  if (!options.boostErrorCorrection) {
+    return plan;
+  }
+
+  let errorCorrectionLevel = options.errorCorrectionLevel;
+  const startIndex = ERROR_CORRECTION_LEVEL_ORDER.indexOf(errorCorrectionLevel);
+
+  for (let index = startIndex + 1; index < ERROR_CORRECTION_LEVEL_ORDER.length; index += 1) {
+    const candidate = ERROR_CORRECTION_LEVEL_ORDER[index];
+    if (plan.dataBitLength <= getDataCodewordCount(plan.version, candidate) * 8) {
+      errorCorrectionLevel = candidate;
+    }
+  }
+
+  return {
+    ...plan,
+    errorCorrectionLevel,
+    boostedErrorCorrection: errorCorrectionLevel !== options.errorCorrectionLevel
+  };
+}
+
+function getDiagnosticMode(segments) {
+  const dataSegments = segments.filter((segment) => !["eci", "fnc1"].includes(segment.mode));
+  const mode = dataSegments[0]?.mode ?? "byte";
+  return dataSegments.every((segment) => segment.mode === mode) ? mode : "mixed";
+}
+
+function getFirstEciAssignmentNumber(segments) {
+  return segments.find((segment) => segment.mode === "eci")?.assignmentNumber ?? null;
+}
+
+function getFirstFnc1Mode(segments) {
+  return segments.some((segment) => segment.mode === "fnc1") ? "first-position" : null;
+}
+
+function getInputByteCount(input) {
+  return isBinaryInput(input) ? toByteArray(input).length : encodeUtf8(input).length;
+}
+
+function getSegmentsInputByteCount(segments) {
+  return segments.reduce((total, segment) => total + getSegmentByteCount(segment), 0);
+}

package/src/node.d.ts

@@ -0,0 +1,7 @@
+import type { Buffer } from "node:buffer";
+import type { QRCodeOptions, QRInput, QRSegmentInput } from "./index.js";
+
+export function toPngBuffer(input: QRInput, options?: QRCodeOptions): Buffer;
+export function toPngBufferFromSegments(segments: QRSegmentInput[], options?: QRCodeOptions): Buffer;
+export function writePngFile(filePath: string, input: QRInput, options?: QRCodeOptions): Promise<void>;
+export function writePngFileFromSegments(filePath: string, segments: QRSegmentInput[], options?: QRCodeOptions): Promise<void>;

package/src/node.js

@@ -0,0 +1,26 @@
+import { writeFile } from "node:fs/promises";
+import { generate, generateSegments } from "./index.js";
+
+export function toPngBuffer(input, options = {}) {
+  return Buffer.from(generate(input, {
+    ...options,
+    output: "png",
+    diagnostics: false
+  }));
+}
+
+export function toPngBufferFromSegments(segments, options = {}) {
+  return Buffer.from(generateSegments(segments, {
+    ...options,
+    output: "png",
+    diagnostics: false
+  }));
+}
+
+export async function writePngFile(filePath, input, options = {}) {
+  await writeFile(filePath, toPngBuffer(input, options));
+}
+
+export async function writePngFileFromSegments(filePath, segments, options = {}) {
+  await writeFile(filePath, toPngBufferFromSegments(segments, options));
+}

package/src/options.js

@@ -0,0 +1,117 @@
+import { ERROR_CORRECTION_LEVELS } from "./core/tables.js";
+import {
+  InvalidEciError,
+  InvalidGs1Error,
+  InvalidInputError,
+  InvalidModeError,
+  InvalidOutputError,
+  InvalidVersionError
+} from "./errors.js";
+
+const DEFAULT_OPTIONS = {
+  errorCorrectionLevel: "M",
+  version: "auto",
+  minVersion: 1,
+  maxVersion: 40,
+  maskPattern: "auto",
+  mode: "auto",
+  encoding: "utf-8",
+  margin: 4,
+  scale: 8,
+  foreground: "#000000",
+  background: "#ffffff",
+  output: "svg",
+  optimizeSegments: true,
+  boostErrorCorrection: false,
+  eci: false,
+  gs1: false,
+  diagnostics: false,
+  printDpi: null
+};
+
+export function normalizeOptions(options = {}) {
+  const normalized = { ...DEFAULT_OPTIONS, ...options };
+
+  if (!ERROR_CORRECTION_LEVELS[normalized.errorCorrectionLevel]) {
+    throw new InvalidInputError(
+      `errorCorrectionLevel must be one of L, M, Q, H; got ${normalized.errorCorrectionLevel}`
+    );
+  }
+
+  if (!["auto", "numeric", "alphanumeric", "byte", "kanji"].includes(normalized.mode)) {
+    throw new InvalidModeError(
+      `mode must be "auto", "numeric", "alphanumeric", "byte", or "kanji"; got ${normalized.mode}`
+    );
+  }
+
+  if (typeof normalized.encoding !== "string" || normalized.encoding.toLowerCase() !== "utf-8") {
+    throw new InvalidInputError(`Only utf-8 encoding is implemented in P0; got ${normalized.encoding}`);
+  }
+  normalized.encoding = "utf-8";
+
+  if (normalized.eci === true) {
+    normalized.eci = 26;
+  } else if (normalized.eci !== false) {
+    if (!Number.isInteger(normalized.eci) || normalized.eci < 0 || normalized.eci >= 1000000) {
+      throw new InvalidEciError(`eci must be false, true, or an integer from 0 to 999999; got ${normalized.eci}`);
+    }
+  }
+
+  if (typeof normalized.gs1 !== "boolean") {
+    throw new InvalidGs1Error(`gs1 must be a boolean; got ${typeof normalized.gs1}`);
+  }
+  if (normalized.gs1 && normalized.eci !== false) {
+    throw new InvalidGs1Error("gs1 and eci cannot be combined in this FNC1 first position implementation");
+  }
+
+  validateVersionBound("minVersion", normalized.minVersion);
+  validateVersionBound("maxVersion", normalized.maxVersion);
+  if (normalized.minVersion > normalized.maxVersion) {
+    throw new InvalidVersionError("minVersion must be less than or equal to maxVersion");
+  }
+
+  if (normalized.version !== "auto") {
+    validateVersionBound("version", normalized.version);
+  }
+
+  if (normalized.maskPattern !== "auto") {
+    if (!Number.isInteger(normalized.maskPattern) || normalized.maskPattern < 0 || normalized.maskPattern > 7) {
+      throw new InvalidInputError(`maskPattern must be "auto" or an integer from 0 to 7; got ${normalized.maskPattern}`);
+    }
+  }
+
+  if (!Number.isInteger(normalized.margin) || normalized.margin < 0) {
+    throw new InvalidInputError(`margin must be a non-negative integer; got ${normalized.margin}`);
+  }
+
+  if (!Number.isInteger(normalized.scale) || normalized.scale < 1) {
+    throw new InvalidInputError(`scale must be a positive integer; got ${normalized.scale}`);
+  }
+
+  const outputs = ["matrix", "svg", "svg-data-url", "png", "png-data-url"];
+  if (!outputs.includes(normalized.output)) {
+    throw new InvalidOutputError(`output must be one of ${outputs.join(", ")}; got ${normalized.output}`);
+  }
+
+  if (typeof normalized.optimizeSegments !== "boolean") {
+    throw new InvalidInputError(`optimizeSegments must be a boolean; got ${typeof normalized.optimizeSegments}`);
+  }
+
+  if (typeof normalized.boostErrorCorrection !== "boolean") {
+    throw new InvalidInputError(`boostErrorCorrection must be a boolean; got ${typeof normalized.boostErrorCorrection}`);
+  }
+
+  if (normalized.printDpi !== null) {
+    if (!Number.isFinite(normalized.printDpi) || normalized.printDpi <= 0) {
+      throw new InvalidInputError(`printDpi must be a positive number or null; got ${normalized.printDpi}`);
+    }
+  }
+
+  return normalized;
+}
+
+function validateVersionBound(name, value) {
+  if (!Number.isInteger(value) || value < 1 || value > 40) {
+    throw new InvalidVersionError(`${name} must be an integer from 1 to 40; got ${value}`);
+  }
+}

package/src/render/base64.js

@@ -0,0 +1,25 @@
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+export function bytesToBase64(bytes) {
+  let result = "";
+  let index = 0;
+
+  for (; index + 2 < bytes.length; index += 3) {
+    const value = (bytes[index] << 16) | (bytes[index + 1] << 8) | bytes[index + 2];
+    result += BASE64_ALPHABET[(value >>> 18) & 0x3F];
+    result += BASE64_ALPHABET[(value >>> 12) & 0x3F];
+    result += BASE64_ALPHABET[(value >>> 6) & 0x3F];
+    result += BASE64_ALPHABET[value & 0x3F];
+  }
+
+  if (index < bytes.length) {
+    const remaining = bytes.length - index;
+    const value = bytes[index] << 16 | (remaining === 2 ? bytes[index + 1] << 8 : 0);
+    result += BASE64_ALPHABET[(value >>> 18) & 0x3F];
+    result += BASE64_ALPHABET[(value >>> 12) & 0x3F];
+    result += remaining === 2 ? BASE64_ALPHABET[(value >>> 6) & 0x3F] : "=";
+    result += "=";
+  }
+
+  return result;
+}

package/src/render/canvas.js

@@ -0,0 +1,51 @@
+import { InvalidCanvasTargetError } from "../errors.js";
+
+export function renderCanvas(target, matrix, options) {
+  const context = getCanvasContext(target);
+  const canvas = context.canvas ?? target;
+  const size = matrix.length;
+  const margin = options.margin;
+  const scale = options.scale;
+  const dimension = (size + margin * 2) * scale;
+
+  if (canvas && "width" in canvas) {
+    canvas.width = dimension;
+  }
+  if (canvas && "height" in canvas) {
+    canvas.height = dimension;
+  }
+
+  context.fillStyle = options.background;
+  context.fillRect(0, 0, dimension, dimension);
+  context.fillStyle = options.foreground;
+
+  for (let y = 0; y < size; y += 1) {
+    for (let x = 0; x < size; x += 1) {
+      if (matrix[y][x]) {
+        context.fillRect((x + margin) * scale, (y + margin) * scale, scale, scale);
+      }
+    }
+  }
+
+  return canvas ?? target;
+}
+
+function getCanvasContext(target) {
+  if (!target) {
+    throw new InvalidCanvasTargetError("drawToCanvas target is required");
+  }
+
+  if (typeof target.getContext === "function") {
+    const context = target.getContext("2d");
+    if (!context) {
+      throw new InvalidCanvasTargetError("Canvas target did not provide a 2D rendering context");
+    }
+    return context;
+  }
+
+  if (typeof target.fillRect === "function") {
+    return target;
+  }
+
+  throw new InvalidCanvasTargetError("drawToCanvas target must be a canvas element or 2D rendering context");
+}

package/src/render/color.js

@@ -0,0 +1,68 @@
+import { InvalidColorError } from "../errors.js";
+
+const NAMED_COLORS = new Map([
+  ["black", [0, 0, 0, 255]],
+  ["white", [255, 255, 255, 255]],
+  ["transparent", [0, 0, 0, 0]]
+]);
+
+export function parseRgbaColor(value, label = "color", strict = false) {
+  const text = String(value).trim().toLowerCase();
+  const named = NAMED_COLORS.get(text);
+  if (named) {
+    return named.slice();
+  }
+
+  if (!text.startsWith("#")) {
+    if (strict) {
+      throw new InvalidColorError(`${label} must be a hex color, "black", "white", or "transparent"`);
+    }
+    return null;
+  }
+
+  const hex = text.slice(1);
+  if (!/^[0-9a-f]+$/u.test(hex)) {
+    if (strict) {
+      throw new InvalidColorError(`${label} has unsupported color format: ${value}`);
+    }
+    return null;
+  }
+
+  if (hex.length === 3 || hex.length === 4) {
+    return [
+      Number.parseInt(hex[0] + hex[0], 16),
+      Number.parseInt(hex[1] + hex[1], 16),
+      Number.parseInt(hex[2] + hex[2], 16),
+      hex.length === 4 ? Number.parseInt(hex[3] + hex[3], 16) : 255
+    ];
+  }
+  if (hex.length === 6 || hex.length === 8) {
+    return [
+      Number.parseInt(hex.slice(0, 2), 16),
+      Number.parseInt(hex.slice(2, 4), 16),
+      Number.parseInt(hex.slice(4, 6), 16),
+      hex.length === 8 ? Number.parseInt(hex.slice(6, 8), 16) : 255
+    ];
+  }
+
+  if (strict) {
+    throw new InvalidColorError(`${label} has unsupported color format: ${value}`);
+  }
+  return null;
+}
+
+export function getContrastRatio(foreground, background) {
+  const light = relativeLuminance(foreground);
+  const dark = relativeLuminance(background);
+  const lighter = Math.max(light, dark);
+  const darker = Math.min(light, dark);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function relativeLuminance(color) {
+  const [red, green, blue] = color.map((channel) => {
+    const value = channel / 255;
+    return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+}