@robonen/encoding

Encoding utilities for TypeScript — a dependency-free QR Code generator and the Reed-Solomon error-correction primitives that power it.

Generating a QR Code correctly is deceptively hard: segment-mode selection, version sizing, Reed-Solomon ECC over a finite field, block interleaving, and the eight masking patterns each have to be just right for a scanner to read the result. @robonen/encoding packages all of that into a small set of pure functions and immutable classes, with zero runtime dependencies and an output you render however you like — SVG, canvas, a DOM grid, or a terminal.

High-level QR in one call

encodeText and encodeBinary pick the smallest version and optimal segment modes for you, then hand back an immutable QrCode grid.

Render-agnostic output

A QrCode is just a square of modules. Read each one with getModule(x, y) and draw to SVG, canvas, or anything else — no rendering opinions baked in.

Standalone Reed-Solomon

The GF(2^8) error-correction core — multiply, computeDivisor, computeRemainder — is exported on its own, reusable beyond QR.

Zero dependencies, fully typed

Tree-shakeable ESM and CJS builds with no third-party runtime deps, hot loops backed by typed arrays, and end-to-end TypeScript types.

Install

pnpm add @robonen/encoding

Quick start

Encode a string into a QrCode and walk its modules to render it. EccMap.M selects the medium (~15% recovery) error-correction level; EccMap.L, .Q, and .H are also available.

import { encodeText, EccMap } from '@robonen/encoding';

// Smallest version + optimal segment modes are chosen automatically.
const qr = encodeText('https://robonen.dev', EccMap.M);

console.log(qr.size); // module count per side (21..177)

// Render however you like — here, plain text:
let out = '';
for (let y = 0; y < qr.size; y++) {
  for (let x = 0; x < qr.size; x++)
    out += qr.getModule(x, y) ? '##' : '  ';
  out += '\n';
}
console.log(out);

Need raw error-correction codewords without the QR machinery? The Reed-Solomon primitives stand on their own:

import { computeDivisor, computeRemainder } from '@robonen/encoding';

// Build a degree-10 generator polynomial over GF(2^8/0x11D)...
const divisor = computeDivisor(10);

// ...then derive the 10 error-correction codewords for your data block.
const data = [0x40, 0xd2, 0x75, 0x47, 0x76, 0x17, 0x32, 0x06, 0x27, 0x26];
const ecc = computeRemainder(data, divisor); // Uint8Array(10)

Where to next

encodeText and encodeBinary — the high-level entry points for text and binary payloads.
encodeSegments — the mid-level API for mixed-mode payloads and version/mask control.
QrCode — the immutable grid, with size, getModule, and getType.
computeRemainder and computeDivisor — the standalone Reed-Solomon core.

API Reference

Qr · 11

encodeBinarytested

Returns a QR Code representing the given binary data at the given error correction level. This function always encodes using the binary segment mode, not any text mode. The maximum number of bytes allowed is 2953.

encodeSegmentstested

Returns a QR Code representing the given segments with the given encoding parameters. The smallest possible QR Code version within the given range is automatically chosen for the output. This is a mid-level API; the high-level API is encodeText() and encodeBinary().

encodeTexttested

Returns a QR Code representing the given Unicode text string at the given error correction level. As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer Unicode code points (not UTF-16 code units) if the low error correction level is used. The smallest possible QR Code version is automatically chosen for the output.

isAlphanumerictested

Tests whether the given string can be encoded as a segment in alphanumeric mode.

isNumerictested

Tests whether the given string can be encoded as a segment in numeric mode.

makeAlphanumerictested

Returns a segment representing the given text string encoded in alphanumeric mode.

makeBytestested

Returns a segment representing the given binary data encoded in byte mode.

makeNumerictested

Returns a segment representing the given string of decimal digits encoded in numeric mode.

makeSegmentstested

Returns a new mutable list of zero or more segments to represent the given Unicode text string. The result may use various segment modes and switch modes to optimize the length of the bit stream.

QrCodetested

A QR Code symbol, which is a type of two-dimension barcode. Invented by Denso Wave and described in the ISO/IEC 18004 standard. Instances of this class represent an immutable square grid of dark and light cells.

QrSegmenttested

A segment of character/binary/control data in a QR Code symbol. Instances of this class are immutable.

Reed-solomon · 3

computeDivisortested

Returns a Reed-Solomon ECC generator polynomial for the given degree. Polynomial coefficients are stored from highest to lowest power, excluding the leading term which is always 1. For example the polynomial x^3 + 255x^2 + 8x + 93 is stored as the uint8 array [255, 8, 93].

computeRemaindertested

Returns the Reed-Solomon error correction codeword for the given data and divisor polynomials.

multiplytested

Returns the product of the two given field elements modulo GF(2^8/0x11D). The arguments and result are unsigned 8-bit integers.