▣ qrmaker-ts

Generador de códigos QR modular, zero-dependency y totalmente tipado en TypeScript.

Codificación Numeric / Alphanumeric / Byte / Kanji · Corrección Reed-Solomon L/M/Q/H · 40 versiones · 8 patrones de máscara · Renderizado SVG / Canvas / GIF / HTML / ASCII con colores y formas de módulo personalizables — sin dependencias, isomórfico (Node, Bun, Deno y navegador).

✨ Características

• 🧩 Arquitectura modular — 8 capas desacopladas (types, utils, math, encoding, patterns, core, renderers, output).
• 🔢 4 modos de codificación — Numeric, Alphanumeric, Byte (UTF-8) y Kanji (Shift-JIS).
• 🛡️ 4 niveles de corrección — L (7%), M (15%), Q (25%), H (30%) con Reed-Solomon e interleaving.
• 🌐 40 versiones — Auto-detección de la versión mínima o selección manual (1–40).
• 🎭 8 máscaras — Selección automática de la mejor máscara por "lost point".
• 🖼️ 6 formatos de salida — SVG, Canvas 2D, GIF (Data URL), HTML table, ASCII y <img>.
• 🎨 Personalización — Colores oscuro/claro, tamaño de celda, margen y formas de módulo (solo SVG).
• 🪶 Zero-dependencies — Un solo bundle ESM minificado (dist/index.js · 42KB); sin node_modules.
• 🏝️ Isomórfico — Funciona en Node, Bun, Deno y navegador con el mismo bundle.

📦 Instalación

Desde el registry

npm install qrmaker-ts

import { QRCode } from "qrmaker-ts";

Build local (zero-dependencies)

Requiere esbuild, tsc y bun instalados globalmente.

git clone git+ssh://[email protected]/edison-manrique/qrmaker-ts.git
cd qrmaker-ts
bun run release   # genera dist/index.js (42KB minified) + dist/types/

🚀 Quick Start

import { QRCode } from "qrmaker-ts";

const qr = new QRCode(); // 0 = auto-detectar versión, nivel M
qr.addData("https://ejemplo.com"); // modo Byte por defecto
qr.make();

console.log(qr.toSVG());

Encadenamiento

const svg = new QRCode(0, "H")
  .addData("12345", "Numeric")
  .addData("HELLO", "Alphanumeric")
  .addData("Hola 🌍", "Byte")
  .make()
  .toSVG({ cellSize: 4, margin: 16 });

🖼️ Formatos de Salida

const qr = new QRCode(0, "M").addData("Hola Mundo").make();

qr.toSVG({ cellSize: 4, margin: 16 }); // SVG vectorial
qr.toHTML({ cellSize: 3 }); // <table> HTML
qr.toASCII({ cellSize: 1 }); // arte para terminal
qr.toDataURL({ cellSize: 4 }); // data:image/gif;base64,...
qr.toImgTag({ cellSize: 4, alt: "QR" }); // <img src="data:...">
qr.toCanvas({ cellSize: 4 }); // HTMLCanvasElement (browser)

// Isomórfico: dibuja sobre un contexto 2D existente (node-canvas, skia, browser)
qr.renderTo2dContext(ctx, { cellSize: 4 });

Opciones comunes

| Opción | Tipo | Default | Descripción | | ------------ | -------- | ------------ | --------------------------- | | cellSize | number | 2 | Tamaño de cada módulo en px | | margin | number | cellSize*4 | Margen (quiet zone) en px | | darkColor | string | #000000 | Color de módulos oscuros | | lightColor | string | #ffffff | Color de módulos claros |

Opciones SVG

| Opción | Tipo | Default | Descripción | | --------------- | ------------- | -------- | ------------------------------------------ | | scalable | boolean | false | Omite width/height (responsive) | | moduleShape | ModuleShape | square | Forma de los módulos | | title / alt | string | — | Accesibilidad (<title>, <description>) |

🎨 Formas de Módulo (solo SVG)

qr.toSVG({ moduleShape: "circle" });

| Forma | Valor | Vista | | ---------- | --------- | ----------- | | Cuadrado | square | ■ (default) | | Redondeado | rounded | ▢ | | Circular | circle | ● | | Rombo | diamond | ◆ | | Angular | sharp | ◥ |

Los finder patterns (esquinas) se mantienen cuadrados para garantizar la escaneabilidad con cualquier forma.

🧬 Modos de Codificación y Capacidad

| Modo | Caracteres | Tasa (bits/car.) | Máx. en 40‑L | | -------------- | --------------------------------------- | ------------------- | ------------ | | Numeric | 0-9 | 10 bits / 3 dígitos | 7.089 | | Alphanumeric | 0-9 A-Z $ % * + - . / : y espacio | 11 bits / 2 chars | 4.296 | | Byte | Cualquier byte (ISO/IEC 8859‑1 / UTF‑8) | 8 bits / byte | 2.953 | | Kanji | Shift‑JIS (JIS X 0208) | 13 bits / char | 1.817 |

"Máx. en 40‑L" = capacidad máxima de caracteres en la versión 40 con corrección L, tras descontar el overhead de modo/longitud (23.648 bits de datos útiles). La tasa y el máximo son métricas complementarias: máx ≈ bits útiles ÷ tasa.

Registrar conversor SJIS (modo Kanji)

import { registerConverterFromBase64 } from "qrmaker-ts";

// Tabla de mapeo Unicode→SJIS en base64
registerConverterFromBase64("SJIS", base64Table, 6879);

🛡️ Niveles de Corrección de Errores

| Nivel | Recuperación | Uso típico | | ----- | ------------ | ----------------------- | | L | ~7% | Máxima capacidad | | M | ~15% | Balance (default) | | Q | ~25% | Logos / daños moderados | | H | ~30% | Máxima robustez |

🧱 Arquitectura

src/
├── index.ts               # API pública
├── QRCode.ts              # Fachada principal
├── types/                 # Enums + interfaces (contratos)
├── utils/                 # BitBuffer, bytes, XML escape
├── math/                  # GF(256), Polynomial, Reed-Solomon
├── encoding/              # Encoders (Numeric/Alpha/Byte/Kanji)
│   └── modes/
├── patterns/              # Finders, alignment, timing, máscaras
├── core/                  # QRModule, QRMatrix, QRGenerator
├── renderers/             # SVG, HTML, Canvas, ASCII, Image
└── output/                # Base64, GIF (LZW), Data URL

🛠️ Desarrollo

bun run typecheck   # tsc --noEmit (estricto)
bun run release     # esbuild (minified, 42KB) + tsc (types)
bun run clean       # elimina dist/
bun test            # suite de pruebas
bun run serve       # levanta el playground (puerto auto 3000+)
bun run dev         # release + playground

Playground

Incluye una app de prueba en playground/ con render en vivo, estadísticas, descarga SVG / PNG / WebP / GIF y personalización de colores, formas y fuente ASCII.

bun run dev
# → http://localhost:3000

🧪 Ejemplo: PNG / WebP desde Canvas

const canvas = qr.toCanvas({ cellSize: 8, margin: 16 });

const png = canvas.toDataURL("image/png");
const webp = canvas.toDataURL("image/webp", 0.95); // cae a PNG si no soportado

⚖️ Disclaimer / Exención de Responsabilidad

Este software se proporciona "tal cual" (AS IS), sin garantía de ningún tipo, expresa o implícita. qrmaker-ts genera símbolos conforme al estándar ISO/IEC 18004, pero la escaneabilidad final depende de factores externos ajenos al código: resolución de impresión, contraste, tamaño físico, iluminación, calidad del lector/decodificador, etc.

El uso de este paquete es bajo su propio riesgo. El autor no se hace responsable por códigos no legibles, errores de decodificación, pérdida de datos, interrupciones de servicio o cualquier daño directo o indirecto derivado del uso de este código.

La palabra "QR Code" es una marca registrada de DENSO WAVE INCORPORATED.

📜 Licencia

Distribuido bajo la licencia Apache-2.0. Ver LICENSE.

👤 Autor

Edison Manrique — github.com/edison-manrique