specqr 1.0.0-rc.1

package/src/encoding/shift-jis.js

@@ -0,0 +1,97 @@
+import { InvalidModeError } from "../errors.js";
+
+let kanjiModeMap = null;
+let decoderAvailable = true;
+const SHIFT_JIS_TRAIL_BYTES = createShiftJisTrailBytes();
+
+export function canEncodeKanjiModeCharacter(character) {
+  if (character.length === 0 || character.charCodeAt(0) < 0x80) {
+    return false;
+  }
+  return getKanjiModeMap().has(character);
+}
+
+export function assertKanjiModeText(text) {
+  for (const character of Array.from(text)) {
+    if (!canEncodeKanjiModeCharacter(character)) {
+      throw new InvalidModeError(`kanji mode cannot encode character: ${character}`);
+    }
+  }
+}
+
+export function getKanjiModeValue(character) {
+  const code = getKanjiModeMap().get(character);
+  if (code === undefined) {
+    throw new InvalidModeError(`kanji mode cannot encode character: ${character}`);
+  }
+
+  const adjusted = code <= 0x9FFC ? code - 0x8140 : code - 0xC140;
+  return ((adjusted >>> 8) * 0xC0) + (adjusted & 0xFF);
+}
+
+export function getKanjiModeByteCount(text) {
+  assertKanjiModeText(text);
+  return Array.from(text).length * 2;
+}
+
+function getKanjiModeMap() {
+  if (kanjiModeMap) {
+    return kanjiModeMap;
+  }
+
+  const decoder = createShiftJisDecoder();
+  if (!decoder) {
+    return new Map();
+  }
+
+  kanjiModeMap = new Map();
+  addRange(kanjiModeMap, decoder, 0x81, 0x9F);
+  addRange(kanjiModeMap, decoder, 0xE0, 0xEB);
+  return kanjiModeMap;
+}
+
+function createShiftJisDecoder() {
+  if (!decoderAvailable || typeof TextDecoder !== "function") {
+    return null;
+  }
+
+  try {
+    return new TextDecoder("shift_jis", { fatal: true });
+  } catch {
+    decoderAvailable = false;
+    return null;
+  }
+}
+
+function addRange(map, decoder, leadStart, leadEnd) {
+  for (let lead = leadStart; lead <= leadEnd; lead += 1) {
+    for (const trail of SHIFT_JIS_TRAIL_BYTES) {
+      const code = (lead << 8) | trail;
+      const character = decodeCharacter(decoder, lead, trail);
+      if (character && !map.has(character)) {
+        map.set(character, code);
+      }
+    }
+  }
+}
+
+function decodeCharacter(decoder, lead, trail) {
+  try {
+    const decoded = decoder.decode(Uint8Array.from([lead, trail]));
+    const characters = Array.from(decoded);
+    return characters.length === 1 && characters[0] !== "\uFFFD" ? characters[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+function createShiftJisTrailBytes() {
+  const bytes = [];
+  for (let value = 0x40; value <= 0x7E; value += 1) {
+    bytes.push(value);
+  }
+  for (let value = 0x80; value <= 0xFC; value += 1) {
+    bytes.push(value);
+  }
+  return bytes;
+}

package/src/errors.js

@@ -0,0 +1,61 @@
+export class SpecQRError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+  }
+}
+
+export class DataTooLongError extends SpecQRError {
+  constructor(message) {
+    super(message, "DATA_TOO_LONG");
+  }
+}
+
+export class InvalidInputError extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_INPUT");
+  }
+}
+
+export class InvalidVersionError extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_VERSION");
+  }
+}
+
+export class InvalidModeError extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_MODE");
+  }
+}
+
+export class InvalidColorError extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_COLOR");
+  }
+}
+
+export class InvalidEciError extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_ECI");
+  }
+}
+
+export class InvalidGs1Error extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_GS1");
+  }
+}
+
+export class InvalidOutputError extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_OUTPUT");
+  }
+}
+
+export class InvalidCanvasTargetError extends SpecQRError {
+  constructor(message) {
+    super(message, "INVALID_CANVAS_TARGET");
+  }
+}

package/src/gs1.js

@@ -0,0 +1,167 @@
+import { InvalidGs1Error } from "./errors.js";
+
+export const GS1_FNC1_SEPARATOR = "\x1D";
+
+const FIXED_LENGTH_AIS = new Map([
+  ["00", { length: 18, content: "numeric" }],
+  ["01", { length: 14, content: "numeric" }],
+  ["02", { length: 14, content: "numeric" }],
+  ["11", { length: 6, content: "numeric" }],
+  ["12", { length: 6, content: "numeric" }],
+  ["13", { length: 6, content: "numeric" }],
+  ["15", { length: 6, content: "numeric" }],
+  ["16", { length: 6, content: "numeric" }],
+  ["17", { length: 6, content: "numeric" }],
+  ["20", { length: 2, content: "numeric" }],
+  ["410", { length: 13, content: "numeric" }],
+  ["411", { length: 13, content: "numeric" }],
+  ["412", { length: 13, content: "numeric" }],
+  ["413", { length: 13, content: "numeric" }],
+  ["414", { length: 13, content: "numeric" }],
+  ["415", { length: 13, content: "numeric" }]
+]);
+
+const VARIABLE_LENGTH_AIS = new Map([
+  ["10", { maxLength: 20, content: "text" }],
+  ["21", { maxLength: 20, content: "text" }],
+  ["22", { maxLength: 20, content: "text" }],
+  ["30", { maxLength: 8, content: "numeric" }],
+  ["37", { maxLength: 8, content: "numeric" }],
+  ["240", { maxLength: 30, content: "text" }],
+  ["241", { maxLength: 30, content: "text" }],
+  ["400", { maxLength: 30, content: "text" }],
+  ["420", { maxLength: 20, content: "text" }]
+]);
+
+export function parseGs1HumanReadable(input) {
+  if (typeof input !== "string") {
+    throw new InvalidGs1Error("GS1 human-readable input must be a string");
+  }
+  if (input.length === 0) {
+    throw new InvalidGs1Error("GS1 human-readable input must not be empty");
+  }
+
+  const elements = [];
+  let position = 0;
+
+  while (position < input.length) {
+    if (input[position] !== "(") {
+      throw new InvalidGs1Error(
+        `GS1 human-readable input must contain an AI in parentheses at offset ${position}`
+      );
+    }
+
+    const close = input.indexOf(")", position + 1);
+    if (close === -1) {
+      throw new InvalidGs1Error(`GS1 AI starting at offset ${position} is missing a closing parenthesis`);
+    }
+
+    const ai = input.slice(position + 1, close);
+    const valueStart = close + 1;
+    const nextAiStart = input.indexOf("(", valueStart);
+    const valueEnd = nextAiStart === -1 ? input.length : nextAiStart;
+    const value = input.slice(valueStart, valueEnd);
+    const normalized = normalizeGs1Element({ ai, value }, elements.length);
+
+    elements.push({ ai: normalized.ai, value: normalized.value });
+    position = valueEnd;
+  }
+
+  return elements;
+}
+
+export function createGs1ElementString(elements) {
+  if (!Array.isArray(elements)) {
+    throw new InvalidGs1Error("GS1 elements must be an array of { ai, value } objects");
+  }
+  if (elements.length === 0) {
+    throw new InvalidGs1Error("GS1 elements must not be empty");
+  }
+
+  return elements
+    .map((element, index) => {
+      const normalized = normalizeGs1Element(element, index);
+      const needsSeparator = normalized.spec.variable && index < elements.length - 1;
+      return `${normalized.ai}${normalized.value}${needsSeparator ? GS1_FNC1_SEPARATOR : ""}`;
+    })
+    .join("");
+}
+
+function normalizeGs1Element(element, index) {
+  if (!element || typeof element !== "object") {
+    throw new InvalidGs1Error(`GS1 element ${index} must be an object`);
+  }
+
+  if (typeof element.ai !== "string") {
+    throw new InvalidGs1Error(`GS1 element ${index} AI must be a string`);
+  }
+  if (typeof element.value !== "string") {
+    throw new InvalidGs1Error(`GS1 element ${index} value must be a string to preserve leading zeroes`);
+  }
+
+  const ai = element.ai;
+  const value = element.value;
+  validateAi(ai, index);
+
+  const spec = getAiSpec(ai);
+  if (!spec) {
+    throw new InvalidGs1Error(`Unsupported GS1 AI ${ai}. Add explicit support before using it.`);
+  }
+
+  validateValue(ai, value, spec);
+  return { ai, value, spec };
+}
+
+function validateAi(ai, index) {
+  if (!/^\d{2,4}$/.test(ai)) {
+    throw new InvalidGs1Error(`GS1 element ${index} has invalid AI ${JSON.stringify(ai)}; expected 2 to 4 digits`);
+  }
+}
+
+function getAiSpec(ai) {
+  const fixed = FIXED_LENGTH_AIS.get(ai);
+  if (fixed) {
+    return { ...fixed, variable: false };
+  }
+
+  const variable = VARIABLE_LENGTH_AIS.get(ai);
+  if (variable) {
+    return { ...variable, variable: true };
+  }
+
+  if (/^310[0-5]$/.test(ai) || /^320[0-5]$/.test(ai)) {
+    return { length: 6, content: "numeric", variable: false };
+  }
+
+  if (/^9[1-9]$/.test(ai)) {
+    return { maxLength: 90, content: "text", variable: true };
+  }
+
+  return null;
+}
+
+function validateValue(ai, value, spec) {
+  if (value.length === 0) {
+    throw new InvalidGs1Error(`GS1 AI ${ai} value must not be empty`);
+  }
+  if (value.includes(GS1_FNC1_SEPARATOR)) {
+    throw new InvalidGs1Error(`GS1 AI ${ai} value must not contain the FNC1 separator`);
+  }
+  if (/[()]/u.test(value)) {
+    throw new InvalidGs1Error(`GS1 AI ${ai} value must be raw data without human-readable parentheses`);
+  }
+  if (!/^[\x20-\x7E]+$/u.test(value)) {
+    throw new InvalidGs1Error(`GS1 AI ${ai} value must use printable ASCII characters`);
+  }
+  if (spec.content === "numeric" && !/^\d+$/u.test(value)) {
+    throw new InvalidGs1Error(`GS1 AI ${ai} value must contain digits only`);
+  }
+
+  if (spec.variable) {
+    if (value.length > spec.maxLength) {
+      throw new InvalidGs1Error(`GS1 AI ${ai} value must be at most ${spec.maxLength} characters`);
+    }
+  } else if (value.length !== spec.length) {
+    throw new InvalidGs1Error(`GS1 AI ${ai} value must be exactly ${spec.length} characters`);
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,215 @@
+export type ErrorCorrectionLevel = "L" | "M" | "Q" | "H";
+export type Version = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
+  11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 |
+  21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 |
+  31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40;
+
+export type QRMatrix = boolean[][];
+export type QROutput = "matrix" | "svg" | "svg-data-url" | "png" | "png-data-url";
+export type QRBinaryInput = Uint8Array | ArrayBuffer | ArrayBufferView | readonly number[];
+export type QRInput = string | QRBinaryInput;
+
+export type QRTextSegmentMode = "numeric" | "alphanumeric" | "kanji";
+export type QRSegmentInput =
+  | { mode: "fnc1" }
+  | { mode: "eci"; assignmentNumber: number }
+  | { mode: QRTextSegmentMode; data: string }
+  | { mode: QRTextSegmentMode; text: string }
+  | { mode: "byte"; data: string | QRBinaryInput | readonly number[] }
+  | { mode: "byte"; text: string }
+  | { mode: "byte"; bytes: QRBinaryInput | readonly number[] };
+
+export interface QRCanvasLike {
+  width: number;
+  height: number;
+  getContext(contextId: "2d"): QRCanvasContextLike | null;
+}
+
+export interface QRCanvasContextLike {
+  canvas?: QRCanvasLike;
+  fillStyle: string;
+  fillRect(x: number, y: number, width: number, height: number): void;
+}
+
+export type QRCanvasTarget = QRCanvasLike | QRCanvasContextLike;
+
+export interface QRCodeOptions {
+  errorCorrectionLevel?: ErrorCorrectionLevel;
+  version?: Version | "auto";
+  minVersion?: Version;
+  maxVersion?: Version;
+  maskPattern?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | "auto";
+  mode?: "auto" | "numeric" | "alphanumeric" | "byte" | "kanji";
+  encoding?: "utf-8";
+  margin?: number;
+  scale?: number;
+  foreground?: string;
+  background?: string;
+  output?: QROutput;
+  optimizeSegments?: boolean;
+  boostErrorCorrection?: boolean;
+  eci?: boolean | number;
+  gs1?: boolean;
+  diagnostics?: boolean;
+  printDpi?: number | null;
+}
+
+export interface QRSegmentDiagnostics {
+  mode: "fnc1" | "eci" | "numeric" | "alphanumeric" | "byte" | "kanji";
+  assignmentNumber?: number;
+  characterCount: number;
+  byteCount: number;
+  bitLength: number;
+}
+
+export interface QRWarning {
+  code:
+    | "QUIET_ZONE_TOO_SMALL"
+    | "COLOR_CONTRAST_UNKNOWN"
+    | "COLOR_CONTRAST_LOW"
+    | "COLOR_CONTRAST_MODERATE"
+    | "COLOR_ALPHA_USED"
+    | "CAPACITY_NEAR_LIMIT"
+    | "PRINT_MODULE_TOO_SMALL"
+    | "RASTER_SCALE_SMALL"
+    | "SCAN_RISK";
+  severity: "info" | "warning";
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface QRColorDiagnostics {
+  ratio: number | null;
+  foregroundAlpha: number | null;
+  backgroundAlpha: number | null;
+  isInspectable: boolean;
+  isStrong: boolean;
+  isSufficient: boolean;
+}
+
+export interface QRPrintDiagnostics {
+  dpi: number | null;
+  modulePixels: number;
+  moduleSizeMm: number | null;
+  symbolSizeMm: number | null;
+  recommendedMinimumModuleSizeMm: number;
+  isModuleSizeSufficient: boolean | null;
+}
+
+export interface QRQuietZoneDiagnostics {
+  modules: number;
+  recommendedModules: number;
+  isSufficient: boolean;
+}
+
+export interface QRDiagnostics {
+  version: Version;
+  size: number;
+  errorCorrectionLevel: ErrorCorrectionLevel;
+  requestedErrorCorrectionLevel: ErrorCorrectionLevel;
+  boostedErrorCorrection: boolean;
+  versionSelection: "fixed" | "auto-minimum";
+  versionSelectionReason: string;
+  maskPattern: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+  maskPenalty: number;
+  maskPenalties: Array<{ maskPattern: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7; penalty: number }>;
+  maskSelectionReason: string;
+  mode: "numeric" | "alphanumeric" | "byte" | "kanji" | "mixed";
+  eciAssignmentNumber: number | null;
+  fnc1: "first-position" | null;
+  gs1: boolean;
+  segments: QRSegmentDiagnostics[];
+  dataBitLength: number;
+  capacityBits: number;
+  remainingBits: number;
+  capacityUtilization: number;
+  inputBytes: number;
+  dataCodewords: number;
+  errorCorrectionCodewords: number;
+  totalCodewords: number;
+  quietZone: QRQuietZoneDiagnostics;
+  colors: QRColorDiagnostics;
+  print: QRPrintDiagnostics;
+  warnings: QRWarning[];
+}
+
+export interface QRCodeDiagnosticResult {
+  matrix: QRMatrix;
+  svg: string;
+  diagnostics: QRDiagnostics;
+}
+
+export function generate(input: QRInput, options?: QRCodeOptions & { diagnostics: true }): QRCodeDiagnosticResult;
+export function generate(input: QRInput, options?: QRCodeOptions & { output: "matrix"; diagnostics?: false }): QRMatrix;
+export function generate(input: QRInput, options?: QRCodeOptions & { output: "png"; diagnostics?: false }): Uint8Array;
+export function generate(input: QRInput, options?: QRCodeOptions & { output?: "svg" | "svg-data-url" | "png-data-url"; diagnostics?: false }): string;
+
+export function generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { diagnostics: true }): QRCodeDiagnosticResult;
+export function generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { output: "matrix"; diagnostics?: false }): QRMatrix;
+export function generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { output: "png"; diagnostics?: false }): Uint8Array;
+export function generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { output?: "svg" | "svg-data-url" | "png-data-url"; diagnostics?: false }): string;
+
+export function drawToCanvas<T extends QRCanvasTarget>(target: T, input: QRInput, options?: QRCodeOptions): T;
+
+export interface GS1Element {
+  ai: string;
+  value: string;
+}
+
+export const GS1_FNC1_SEPARATOR: "\x1D";
+export function createGs1ElementString(elements: GS1Element[]): string;
+export function parseGs1HumanReadable(input: string): GS1Element[];
+
+export class SpecQRError extends Error {
+  readonly code: string;
+}
+
+export class DataTooLongError extends SpecQRError {
+  readonly code: "DATA_TOO_LONG";
+}
+
+export class InvalidInputError extends SpecQRError {
+  readonly code: "INVALID_INPUT";
+}
+
+export class InvalidVersionError extends SpecQRError {
+  readonly code: "INVALID_VERSION";
+}
+
+export class InvalidModeError extends SpecQRError {
+  readonly code: "INVALID_MODE";
+}
+
+export class InvalidColorError extends SpecQRError {
+  readonly code: "INVALID_COLOR";
+}
+
+export class InvalidEciError extends SpecQRError {
+  readonly code: "INVALID_ECI";
+}
+
+export class InvalidGs1Error extends SpecQRError {
+  readonly code: "INVALID_GS1";
+}
+
+export class InvalidOutputError extends SpecQRError {
+  readonly code: "INVALID_OUTPUT";
+}
+
+export class InvalidCanvasTargetError extends SpecQRError {
+  readonly code: "INVALID_CANVAS_TARGET";
+}
+
+export class QRCode {
+  static generate(input: QRInput, options?: QRCodeOptions & { diagnostics: true }): QRCodeDiagnosticResult;
+  static generate(input: QRInput, options?: QRCodeOptions & { output: "matrix"; diagnostics?: false }): QRMatrix;
+  static generate(input: QRInput, options?: QRCodeOptions & { output: "png"; diagnostics?: false }): Uint8Array;
+  static generate(input: QRInput, options?: QRCodeOptions & { output?: "svg" | "svg-data-url" | "png-data-url"; diagnostics?: false }): string;
+  static generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { diagnostics: true }): QRCodeDiagnosticResult;
+  static generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { output: "matrix"; diagnostics?: false }): QRMatrix;
+  static generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { output: "png"; diagnostics?: false }): Uint8Array;
+  static generateSegments(segments: QRSegmentInput[], options?: QRCodeOptions & { output?: "svg" | "svg-data-url" | "png-data-url"; diagnostics?: false }): string;
+  static drawToCanvas<T extends QRCanvasTarget>(target: T, input: QRInput, options?: QRCodeOptions): T;
+  static createGs1ElementString(elements: GS1Element[]): string;
+  static parseGs1HumanReadable(input: string): GS1Element[];
+}