ForgeSworn QR

QR 0.3.14 · MIT · No runtime dependencies

@forgesworn/qr

Make and read QR codes in TypeScript, with no dependencies. One small package encodes text or bytes into a symbol, renders it as SVG, canvas or terminal text, and decodes symbols from camera frames, screenshots and photographs. It runs in browsers, workers and Node.

import { decode, encode, toSvg } from '@forgesworn/qr'

const svg = toSvg(encode('https://example.com/'))        // make one
const text = decode(ctx.getImageData(0, 0, w, h))?.text  // read one

Documentation · npm · Releases · Choosing QR

Native Rust: forgesworn-qr · Rust API docs · Rust guide

JSR · Kotlin on Maven Central

Why use it?

Generate and read codes with the same typed package, process frames locally, and choose your own camera UI. The optional WASM backend and tracked sessions help with repeated frames; the plain TypeScript entry needs no WASM setup. Accuracy takes priority: speed changes must preserve successful regression reads and must not introduce incorrect payloads.

The recorded photograph comparison reads 180/184 versus ZXing-WASM's 171/184, and the positive stress set reads 172/224 versus 150/224. Version 0.3.14's qualified curved-image comparison reads 861/1,376 versus 646/1,376, adding 143 exact reads over 0.3.13 while preserving earlier successful results. This includes 118/256 versus 77/256 on a separate synthetic set frozen before evaluation. ZXing still reads 14 curved frames QR misses, and is faster on the recorded random-noise workload. These finite sets do not prove superiority on every image or camera. See choosing a library for trade-offs and reproducible evidence.

Contents

Install

npm install @forgesworn/qr

ESM only (import, not require). Node.js 22.13 or later, or any browser with ES2022 modules. Types are included. The API is still pre-1.0, so pin the version; changes are listed in CHANGELOG.md.

JSR uses the same TypeScript API, including the optional WASM entry point:

import { encode, toSvg } from 'jsr:@forgesworn/qr@0.3.14'
import { loadWasm, wasmUrl } from 'jsr:@forgesworn/qr@0.3.14/wasm'

For Deno projects, deno add jsr:@forgesworn/qr@0.3.14 adds the package to your configuration. Continue to use npm for the ordinary Node/bundler installation. See distribution for registry publication status and verification.

Recipes: making codes

The recipes show the imports and operations needed for each integration. Browser examples assume the named elements exist in your page. encode is synchronous and returns a plain object; the renderers turn that object into something to show.

An SVG in the page

import { encode, toSvg } from '@forgesworn/qr'

const qr = encode('https://example.com/')
const svg = toSvg(qr, { title: 'Link to example.com' })

document.querySelector('#qr')!.innerHTML = svg

The SVG has a viewBox and no fixed size, so it fills its container: size it with CSS. title becomes the accessible name. As an image source:

import { encode, toSvg } from '@forgesworn/qr'

const img = document.querySelector('img')!
img.src = 'data:image/svg+xml;utf8,' + encodeURIComponent(toSvg(encode('https://example.com/')))

A canvas, and a PNG to download

import { drawCanvas, encode } from '@forgesworn/qr'

const canvas = document.querySelector('canvas')!
drawCanvas(canvas, encode('https://example.com/'), { width: 512 })

canvas.toBlob((png) => {
  if (!png) return
  const link = document.createElement('a')
  link.href = URL.createObjectURL(png)
  link.download = 'code.png'
  link.click()
  setTimeout(() => URL.revokeObjectURL(link.href), 0)
})

drawCanvas resizes the canvas to exactly width pixels square and puts module edges on whole pixels. width must be a whole number of at least one pixel a module, margin included, or it throws a RangeError. It takes an OffscreenCanvas too.

A terminal, or a file, from Node

import { writeFileSync } from 'node:fs'
import { encode, toSvg, toTerminal } from '@forgesworn/qr'

const qr = encode('https://example.com/')
console.log(toTerminal(qr))                  // dark terminal; { ink: 'dark' } for a light one
writeFileSync('code.svg', toSvg(qr))

Colours, margin and error correction

import { encode, toSvg } from '@forgesworn/qr'

const qr = encode('https://example.com/', { ecc: 'H' })   // 'L' | 'M' (default) | 'Q' | 'H'
const svg = toSvg(qr, { dark: '#1a1a2e', light: null, margin: 2 })   // light: null leaves the background clear

A higher level survives more damage and makes a larger symbol. Keep the margin at 4 modules unless the code sits on a plain background already; readers need the quiet zone.

Your own drawing

modules is a row-by-row Uint8Array of size * size entries, 1 for dark, with no quiet zone. isDark(qr, x, y) reads it, and is false outside the symbol.

import { encode, isDark } from '@forgesworn/qr'

const qr = encode('https://example.com/')
let dots = ''
for (let y = 0; y < qr.size; y++) {
  for (let x = 0; x < qr.size; x++) {
    if (isDark(qr, x, y)) dots += `<circle cx="${x + 0.5}" cy="${y + 0.5}" r="0.45"/>`
  }
}
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 ${qr.size + 8} ${qr.size + 8}">${dots}</svg>`

With no mode, text is split into the segments that take the fewest bits. An uppercase body after a lowercase scheme packs as alphanumeric, so it fits a smaller symbol than it would as bytes.

import { encode } from '@forgesworn/qr'

const invoice = 'lightning:LNBC' + '0123456789ACDEFGHJKLMNPQRSTUVWXYZ'.repeat(8)   // 278 characters, made up
const qr = encode(invoice)
qr.segments   // [{ mode: 'byte', count: 9 }, { mode: 'alphanumeric', count: 269 }]
qr.version    // 10, 57 modules a side; as bytes it would be version 12, 65 a side

Bytes, not text

import { encode } from '@forgesworn/qr'

const qr = encode(new Uint8Array([0xde, 0xad, 0xbe, 0xef]))   // always one byte segment

When the data does not fit

import { encode, QrCapacityError, type ErrorCorrection, type QrCode } from '@forgesworn/qr'

/** The most robust code that still fits, or undefined if none does. */
function fit(text: string): QrCode | undefined {
  for (const ecc of ['H', 'Q', 'M', 'L'] as ErrorCorrection[]) {
    try {
      return encode(text, { ecc })
    } catch (error) {
      if (!(error instanceof QrCapacityError)) throw error
    }
  }
  return undefined
}

QrCapacityError extends RangeError. Bad options (a version outside 1-40, an unknown level) throw a plain RangeError, and data that is neither a string nor a Uint8Array throws a TypeError.

Recipes: reading codes

decode takes pixels, not an element: { data, width, height } with RGBA (what a canvas gives) or one grey byte a pixel. It returns the result, or undefined when it finds no code it is sure of. It manages no camera; the loop below is all there is to it.

Scan with the camera

import { decode } from '@forgesworn/qr'

/** Starts scanning; calls `onRead` once with the first code read. Returns a function that stops the camera. */
async function scan(video: HTMLVideoElement, onRead: (text: string) => void): Promise<() => void> {
  const stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } })
  video.srcObject = stream
  video.playsInline = true
  try {
    await video.play()
  } catch (error) {
    for (const track of stream.getTracks()) track.stop()
    video.srcObject = null
    throw error
  }

  const canvas = document.createElement('canvas')
  const ctx = canvas.getContext('2d', { willReadFrequently: true })!
  let running = true
  let last = 0

  const stop = () => {
    running = false
    for (const track of stream.getTracks()) track.stop()
    if (video.srcObject === stream) video.srcObject = null
  }
  const tick = (now: number) => {
    if (!running) return
    if (now - last >= 100 && video.videoWidth > 0) {   // ten looks a second is plenty
      last = now
      canvas.width = video.videoWidth
      canvas.height = video.videoHeight
      ctx.drawImage(video, 0, 0)
      const found = decode(ctx.getImageData(0, 0, canvas.width, canvas.height))
      if (found) {
        stop()
        onRead(found.text)
        return
      }
    }
    requestAnimationFrame(tick)
  }
  requestAnimationFrame(tick)
  return stop
}

const stop = await scan(document.querySelector('video')!, (text) => console.log(text))

Cameras need a secure page (HTTPS or localhost) and the user's permission. Start with a bounded frame size such as 1280×720 and measure on your devices. Small or distant codes may need more resolution; larger frames cost more time and memory. Use a worker for decoding when page responsiveness matters.

Read an uploaded picture or a screenshot

import { decode } from '@forgesworn/qr'

async function readFile(file: Blob): Promise<string | undefined> {
  const bitmap = await createImageBitmap(file)
  try {
    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height)
    const ctx = canvas.getContext('2d')!
    ctx.drawImage(bitmap, 0, 0)
    return decode(ctx.getImageData(0, 0, bitmap.width, bitmap.height))?.text
  } finally {
    bitmap.close()
  }
}

document.querySelector('input[type=file]')!.addEventListener('change', async (event) => {
  const file = (event.target as HTMLInputElement).files?.[0]
  if (file) console.log((await readFile(file)) ?? 'no code found')
})

Keep the page smooth: decode in a worker

// main.ts
const worker = new Worker(new URL('./scan-worker.ts', import.meta.url), { type: 'module' })
worker.onmessage = (event: MessageEvent<string | undefined>) => {
  if (event.data !== undefined) console.log(event.data)
}

function look(frame: ImageData): void {
  worker.postMessage(frame, [frame.data.buffer])   // moves the pixels, no copy
}
// scan-worker.ts
import { decode } from '@forgesworn/qr'

addEventListener('message', (event: MessageEvent<ImageData>) => {
  postMessage(decode(event.data)?.text)
})

Most bundlers understand new Worker(new URL(...), { type: 'module' }) as written. Send the next frame only when the last has answered, so frames do not queue.

Read pixels in Node

Node has no image decoder of its own. Use any that gives raw RGBA or grey bytes, and hand them over with their size:

import { decode } from '@forgesworn/qr'

function read(rgba: Uint8Array, width: number, height: number): string | undefined {
  return decode({ data: rgba, width, height })?.text
}

Greyscale camera planes

A camera's luminance (Y) plane is already what the decoder wants, and skips the colour conversion. rowStride is the number of pixels from one row to the next, for planes with padding.

import { decode } from '@forgesworn/qr'

function readPlane(y: Uint8Array, width: number, height: number, rowStride: number): string | undefined {
  return decode({ data: y, width, height }, { channels: 1, rowStride })?.text
}

The data must hold at least rowStride * (height - 1) + width bytes, and rowStride may not be less than width. A Node Buffer is a Uint8Array and works as it is. decode copies what it needs: it neither changes your buffer nor keeps it.

Repeated camera frames

Use an independent decoder for each camera stream:

import { createDecoder, type ImageLike } from '@forgesworn/qr'

const reader = createDecoder()
function readFrame(frame: ImageLike) {
  return reader.decode(frame) // the same image and options as decode()
}
reader.reset()               // call when stopping or switching cameras

It reuses luminance storage and tries the previous symbol's region first. When that region misses, it searches the full frame in the same call. Each call reads fresh pixels; it never returns a cached payload. With several codes visible, it favours the previous region. Cropping can change the reported location slightly. reset() forgets the region and releases working storage. Keep using a worker and avoid queueing frames, as in the recipe above.

Everything a read gives you

import { decode, type DecodeResult, type ImageLike } from '@forgesworn/qr'

function describe(frame: ImageLike): string {
  const found: DecodeResult | undefined = decode(frame)
  if (!found) return 'nothing read'

  const { topLeft, topRight, bottomLeft } = found.location   // finder pattern centres, in pixels
  const width = Math.hypot(topRight.x - topLeft.x, topRight.y - topLeft.y)
  const height = Math.hypot(bottomLeft.x - topLeft.x, bottomLeft.y - topLeft.y)
  return [
    `text: ${found.text}`,
    `bytes: ${found.bytes.length}`,                           // the payload as stored, for data that is not text
    `version ${found.version}, level ${found.ecc}, ${found.corrected} codewords corrected`,
    found.inverted ? 'light on dark' : 'dark on light',
    found.mirrored ? 'mirrored' : 'not mirrored',
    `about ${Math.round(width)} by ${Math.round(height)} pixels between finders`,
  ].join('\n')
}

The three points of location are the centres of the finder patterns, each 3.5 modules in from a corner of the symbol, so the symbol's outline lies a little outside them. alignment is the alignment pattern's centre when one was used.

found.structuredAppend ({ index, total, parity }) is present when the code is one part of a message split across several, and found.fnc1 when it is a GS1 or industry code.

Only dark-on-light codes

import { decode, type ImageLike } from '@forgesworn/qr'

const readNormal = (frame: ImageLike) => decode(frame, { inversion: 'normal' })   // 'inverted' | 'both' (default)

Naming the polarity avoids searching the other polarity. The saving depends on the image and which search budgets are reached.

Check a code you just made

import { decodeModules, encode } from '@forgesworn/qr'

const qr = encode('https://example.com/')
console.assert(decodeModules(qr.modules, qr.size)?.text === 'https://example.com/')

API

Everything the package exports:

function encode(data: string | Uint8Array, options?: EncodeOptions): QrCode
function isDark(qr: QrCode, x: number, y: number): boolean
function toSvg(qr: QrCode, options?: SvgOptions): string
function drawCanvas(canvas: CanvasLike, qr: QrCode, options?: CanvasOptions): void
function toTerminal(qr: QrCode, options?: TerminalOptions): string
function decode(image: ImageLike, options?: DecodeOptions): DecodeResult | undefined
function createDecoder(): Decoder
function decodeModules(modules: ArrayLike<number | boolean>, size: number): (Payload & { mirrored: boolean }) | undefined
class QrCapacityError extends RangeError {}

type ErrorCorrection = 'L' | 'M' | 'Q' | 'H'
type Mode = 'numeric' | 'alphanumeric' | 'byte'

interface EncodeOptions {
  ecc?: ErrorCorrection   // default 'M'
  version?: number        // 1-40; default: the smallest that fits
  minVersion?: number     // default 1
  mask?: number           // 0-7; default: the lowest penalty
  mode?: Mode             // the whole text as one segment; default: the fewest-bits mix
  eci?: boolean           // mark byte data as UTF-8; default false
}

interface QrCode {
  version: number
  ecc: ErrorCorrection
  mask: number
  mode: Mode                                // the widest mode among the segments
  segments: readonly { mode: Mode; count: number }[]
  size: number                              // modules a side, 17 + 4 * version, no quiet zone
  modules: Uint8Array                       // size * size, row by row, 1 for dark
}

interface SvgOptions { margin?: number; dark?: string; light?: string | null; title?: string }
/** An HTMLCanvasElement, an OffscreenCanvas, or anything shaped like one. */
interface CanvasLike { width: number; height: number; getContext(type: '2d'): { fillStyle: unknown; fillRect(x: number, y: number, width: number, height: number): void } | null }
interface CanvasOptions { width?: number; margin?: number; dark?: string; light?: string | null }
interface TerminalOptions { margin?: number; ink?: 'light' | 'dark' }

interface ImageLike { data: Uint8Array | Uint8ClampedArray; width: number; height: number }
interface Decoder {
  decode(image: ImageLike, options?: DecodeOptions): DecodeResult | undefined
  reset(): void
}
interface DecodeOptions {
  rowStride?: number                        // pixels from row to row; default width
  channels?: 1 | 4                          // default: worked out from the data length
  inversion?: 'normal' | 'inverted' | 'both'   // default 'both'
}

interface Payload {
  text: string
  bytes: Uint8Array
  version: number
  ecc: ErrorCorrection
  mask: number
  eci: readonly number[]                    // ECI assignments in the order met
  corrected: number                         // codewords error correction put right
  structuredAppend?: { index: number; total: number; parity: number }
  fnc1?: { position: 'first' | 'second'; applicationIndicator?: string }
}
interface DecodeResult extends Payload {
  mirrored: boolean
  inverted: boolean
  location: { topLeft: Point; topRight: Point; bottomLeft: Point; alignment: Point | undefined }
}
interface Point { x: number; y: number }

Defaults worth knowing: margin is 4 modules everywhere; dark is '#000' and light is '#fff'; a canvas is 8 pixels a module unless width says otherwise.

Text. A string is encoded as UTF-8. When reading, text follows the symbol's ECI if it has one; under an ECI the platform cannot read, what cannot be read is U+FFFD and never a guess. Without one, byte data is UTF-8 when it is valid UTF-8, Shift_JIS when it has the shape of Shift_JIS text, and Latin-1 otherwise; kanji and hanzi segments read as text. bytes is there for payloads that are not text. SPEC.md has the detail.

What decode throws. Nothing for a picture with no code: that is undefined. It throws TypeError or RangeError only for arguments that cannot be a picture: data that is not a Uint8Array or Uint8ClampedArray, a size that does not match the data, or three bytes a pixel (pass RGBA or grey).

Wrong text. The decoder refuses a block that needed more corrections than the standard allows, and holds its later, harder searches of a frame to a stricter check than the first. The tests require damaged symbols to read as nothing or as exactly what was written.

Speed. The recorded M4 Max/native Node 24.21.0 run measures clean 720p RGBA decoding at 4.661 ms for TypeScript and 1.590 ms for optional WASM. Random noise takes 55.485 ms and 20.569 ms respectively. These are workload- and hardware-specific medians, not a latency guarantee or phone measurement. PERFORMANCE.md records the inputs, warm-up, competing readers, medians, tails and limitations. Use a worker and keep only one frame in flight.

Common mistakes

Migrating from another library

The shapes are close to what most QR libraries use, so a switch is mostly renaming. Three differences apply whatever you come from: this package is ESM only, encoding and decoding are synchronous, and a failed read is undefined. Optional WASM initialisation with loadWasm is asynchronous.

From qrcode (generating)

qrcode @forgesworn/qr
await QRCode.toString(text, { type: 'svg' }) toSvg(encode(text))
await QRCode.toCanvas(canvas, text, { width }) drawCanvas(canvas, encode(text), { width })
await QRCode.toDataURL(text) draw to a canvas, then canvas.toDataURL(); or an SVG data URL (see the SVG recipe)
await QRCode.toString(text, { type: 'terminal' }) toTerminal(encode(text))
QRCode.create(text) encode(text)
errorCorrectionLevel: 'M' ecc: 'M', on encode
version, maskPattern version, mask, on encode
margin, color: { dark, light } margin, dark, light, on the renderer
scale width on drawCanvas; an SVG scales with CSS
qr.modules.get(row, col) isDark(qr, col, row)
qr.modules.size qr.size
// before
import QRCode from 'qrcode'
const svg = await QRCode.toString('https://example.com/', { type: 'svg', errorCorrectionLevel: 'Q', margin: 2 })

// after
import { encode, toSvg } from '@forgesworn/qr'
const svg = toSvg(encode('https://example.com/', { ecc: 'Q' }), { margin: 2 })

Options split in two: what goes into the symbol (ecc, version, mask) belongs to encode, and how it looks (margin, colours, size) to the renderer. There is no PNG or file writer; a canvas or the SVG string covers both.

From qrcode-generator (generating)

qrcode-generator @forgesworn/qr
const qr = qrcode(0, 'M'); qr.addData(text); qr.make() const qr = encode(text, { ecc: 'M' })
qrcode(typeNumber, level) with a fixed type number encode(text, { version: typeNumber, ecc: level })
qr.getModuleCount() qr.size
qr.isDark(row, col) isDark(qr, col, row)
qr.createSvgTag() toSvg(qr)
qr.createDataURL() an SVG data URL (see the SVG recipe)
qr.addData(text, 'Alphanumeric') encode(text, { mode: 'alphanumeric' }), or no mode and let it choose

From jsQR (reading)

jsQR @forgesworn/qr
jsQR(imageData.data, imageData.width, imageData.height) decode(imageData)
{ inversionAttempts: 'dontInvert' } { inversion: 'normal' }
{ inversionAttempts: 'onlyInvert' } { inversion: 'inverted' }
{ inversionAttempts: 'attemptBoth' } { inversion: 'both' }, the default
null when nothing reads undefined
code.data found.text
code.binaryData (number array) found.bytes (Uint8Array)
code.version found.version
code.location.topLeftFinderPattern and the other two found.location.topLeft, .topRight, .bottomLeft
code.location.topLeftCorner and the other corners not given: the location is the finder centres
// before
import jsQR from 'jsqr'
const code = jsQR(frame.data, frame.width, frame.height, { inversionAttempts: 'dontInvert' })
if (code) handle(code.data)

// after
import { decode } from '@forgesworn/qr'
const found = decode(frame, { inversion: 'normal' })
if (found) handle(found.text)

From a scanner that runs the camera for you

Libraries such as qr-scanner, html5-qrcode and @zxing/browser open the camera, draw a viewfinder and call you back. This package only reads pixels, so the camera loop becomes yours: the camera recipe is the whole of it, about thirty lines, and the worker recipe moves the work off the page. In exchange you choose the frame size, the scan rate and the interface. Formats other than QR codes are not read.

How the decoder works

For each frame, in order, stopping at the first read:

  1. Greyscale. RGBA becomes one grey byte a pixel; a grey plane is used as it is.
  2. Black and white. A threshold is taken for every 8 x 8 block from the blocks around it, so shadows and uneven light do not swallow the code.
  3. Finder patterns. Rows are scanned for the 1:1:3:1:1 runs of a finder pattern, each sighting checked down its column, back along its row and along a diagonal.
  4. Placement. Three finders that could be the corners of one symbol give its size and a perspective map; the alignment pattern refines it.
  5. Reading. Modules are sampled through the map, the format and version are read, and Reed-Solomon corrects the codewords. A block needing more corrections than the standard allows is refused.
  6. A second look. If nothing read, up to four placements whose two format copies agree are sampled again more carefully, following curved or bent symbols.
  7. Reduced size. If still nothing, the picture is searched again shrunk by 8, 4 and 2, for close-ups and codes shown on screens, with a stricter check on what counts as a read.
  8. Evidence-directed recovery. Eligible inverted images get a separate luminance pass. Independently agreeing version copies can correct a failed size estimate; agreeing headers can admit previously unselected finder triples. A final curved-map retry uses an exact version word and consistent readable format information, then revisits missed alignment nodes. Its result still needs both final format copies to agree. Candidates from the inverted-luminance pass retain their own thresholds and run after the original-image candidates. All these retries share the existing map and second-look budgets.
  9. Retained grids. After those paths fail, bounded strict reads can recover already sampled grids. If the selected refined grid supplies a different agreed header but cannot be read, the decoder can try that same hypothesis on the direct alignment mesh captured by the same refinement call. This adds no image sampling or alignment search and cannot displace an earlier successful result.

Steps 3 to 5 run for dark-on-light and then light-on-dark unless inversion names one. The work a frame can take is capped, and there are no thresholds or effort levels to tune: the frame size, the scan rate and inversion are the controls. SPEC.md gives every step exactly.

How it is tested

Kotlin

A pure-JVM port of the encoder and decoder lives in kotlin/ (module core, package dev.forgesworn.qr, JVM 17, no dependencies beyond the Kotlin standard library). It is checked against the same vectors and frames as the TypeScript library, and gives the same results. The sources are in kotlin/core/src/main/kotlin and are written to be vendored as they stand.

For the Maven Central distribution, configure Gradle with:

repositories { mavenCentral() }
dependencies { implementation("io.github.forgesworn:qr:0.3.14") }

See distribution for publication status. The Maven group is io.github.forgesworn; the Kotlin import package remains dev.forgesworn.qr.

import dev.forgesworn.qr.*

val qr = encode("https://example.com", EncodeOptions(ecc = ErrorCorrection.Q))
qr.isDark(0, 0) // modules are row by row, no quiet zone

// luminance: one byte a pixel, 0 black to 255 white, as a camera's Y plane gives
val found = decode(luminance, width, height, rowStride = stride)
found?.text

decode returns null when it finds no readable code. There is also a decode(IntArray, ...) overload for packed ARGB pixels and decodeModules(modules, size) for a module grid. Run the tests with cd kotlin && ./gradlew test.

Rust and WebAssembly

A Rust port lives in rust/: the encoder, the SVG and terminal renderers and the whole decoder, with no dependencies. It is held to the same vectors. Beyond them, its decoder was compared with the TypeScript on 603 pictures kept outside this repository, each at four quarter turns: the same payload, the same location to the last bit and the same counted work on all 2,412 in that earlier qualification. Install the native crate with cargo add forgesworn-qr@0.3.14; see the Rust guide and API documentation for its input contracts.

The npm package includes an optional WebAssembly backend, imported separately from the TypeScript entry. The bundled module is about 210 kB (205 KiB) before compression. Fetch and instantiate it once, then reuse it for frames:

import { loadWasm, wasmUrl } from '@forgesworn/qr/wasm'

const response = await fetch(wasmUrl)
if (!response.ok) throw new Error(`QR module: HTTP ${response.status}`)
const qr = await loadWasm(await response.arrayBuffer())
try {
  const symbol = qr.encode('https://example.com/')
  const found = qr.decodeModules(symbol.modules, symbol.size)
  console.log(found?.text)
  // qr.decode(imageData) accepts the same pixels and options as decode().
} finally {
  qr.dispose() // stop using this instance
}

In Node, replace the fetch with readFile(new URL(wasmUrl)) from node:fs/promises. loadWasm performs no network or filesystem access. With a bundler, ensure it copies new URL('./qr.wasm', import.meta.url) as an asset, or supply bytes from your own deployed copy of @forgesworn/qr/qr.wasm. Self-host the module for control over asset delivery. The library chooses no CDN and adds no runtime dependencies. Your page policy must permit WebAssembly compilation when using this backend; use the TypeScript entry when it cannot.

The backend exposes encode, decode, decodeModules, createDecoder, reset, dispose and memoryBytes. It copies outputs before freeing native result handles, so earlier results survive later calls and disposal. Each instance reuses an input allocation; reset() frees that allocation and leaves the instance usable. WebAssembly memory retains its high-water size until the instance is collected. dispose() releases the instance and rejects further operations; it is safe to call repeatedly. Use one instance per worker and a worker for camera frames. qr.createDecoder() creates a tracked camera session with the same region search and same-call fallback as the TypeScript helper. Each session tracks independently and shares the instance's native input storage. Reset a session to forget its region; reset the parent to free input storage and forget all session regions. Disposing the parent invalidates its sessions.

The packaged WASM backend uses the host's character sets, following the same text rules as TypeScript for kanji, hanzi, ECI and implicit Shift_JIS. It does this while parsing each segment, preserving mixed encodings and rejecting invalid hanzi cells. It bundles no character tables. A host lacking a character set follows the documented platform fallback.

The standalone Rust port and its default WASM build still carry no character tables: unsupported characters use the documented replacement rules and hanzi is refused. The packaged module enables Rust's host-text feature and uses ABI 2; the standalone module uses ABI 1. Supply the packaged module to loadWasm.

cd rust
cargo test                                               # the conformance pack and the encoder vectors
cargo build --release --target wasm32-unknown-unknown    # the WebAssembly module

rust/bench/ also holds the scripts that compare the module with the TypeScript and time it.

forgesworn-qr-embedded is a separate, allocation-free no_std encoder for versions 1–8, with 602 bytes of caller buffers and optional optimal text planning. It shares this specification, standard tables and encoder conformance vectors. It has its own version lifecycle, starting at 0.1.0. The embedded guide documents installation, the API, measured savings and board-testing scope.

Development

npm install
npm run check              # typecheck and tests
npm run build              # compile to dist/ and verify/copy the bundled WASM
npm run generate-vectors   # regenerate the encode vectors (needs a JDK and network once)
npm run fetch-photos       # download the photograph test set (about 13 MB, needs a JDK)

The checked-in WASM asset is built from this repository's Rust sources with Rust 1.96.0. Install that toolchain and its wasm32-unknown-unknown target, then use npm run build:wasm after changing Rust. npm run check:wasm rebuilds and compares the exact bytes and provenance; CI does this on Linux. Normal npm builds need no Rust toolchain. npm run check:package installs a real packed tarball into a temporary consumer and checks both entries. npm run bench runs the local benchmark; PERFORMANCE.md records the method, measurements and their limits.

SPEC.md defines the behaviour; a change to behaviour changes it in the same commit.

Support

For issues and feature requests, see GitHub Issues.

If you find this library useful, consider sending a tip:

Licence

MIT

QR Code is a registered trademark of DENSO WAVE INCORPORATED.