overview

API overview

The public API is deliberately small. It follows one piece of data through three clear stages:

1. an encoder turns text or bytes into a BitMatrix;
2. a renderer turns that matrix into SVG, PNG, canvas pixels or an ImageData-shaped object;
3. a decoder validates an image and returns zero or more decoded results.

That separation keeps the barcode code independent from the browser, Node.js (or Bun as an alternative), Workers and whatever image adapter your application already uses. The package is ESM-first, ships JavaScript and TypeScript declarations, and has no runtime dependencies.

For installation choices, see Installation. For a quick end-to-end start, see Getting started.

The root entry point

Most applications need only the package root:

import {
  decode,
  decodeStrict,
  encode,
  listFormats,
  toImageData,
  toSVG,
} from '@sythos/js_barcode_universal';

The stable root surface contains these main groups:

Group	Exports	What it does
Registry	listFormats, VERSION	Describes the release and its read/write capability flags.
Encoding	encode plus format-specific encoders	Creates a BitMatrix from a payload.
Reading	decode, decodeStrict plus format-specific decoders/detectors	Reads RGBA image data or an exact sampled matrix.
Rendering	toSVG, toSVGDataURI, toPNG, toPNGDataURI, toImageData, toCanvas	Produces portable output.
Accelerated drawing	renderToCanvasAuto, renderToCanvasAutoAsync, isWebGL2Available, isWebGPUAvailable	Selects a canvas drawing backend.
Image primitives	LuminanceSource, binarize, binarizeGlobal, binarizeHybrid	Converts image-shaped data into detector input.
Core primitives	BitMatrix, BarcodeError, EncodeError, NotFoundError, FormatError, ChecksumError	Exposes the common matrix and error types.

The declarations in src/index.d.ts are the root API contract. The TypeScript implementation and the declarations beside it live under src/ts/; those files are useful references, but an application should import the package root or one of the documented exports.

A complete round trip

This example runs in Node.js, Bun as an alternative, or any ESM-capable browser. It creates a QR Code, renders it into the plain image shape accepted by the reader, and reads it back:

import {
  decode,
  encode,
  toImageData,
} from '@sythos/js_barcode_universal';

const payload = 'Greetings My Lord Sythos';
const matrix = encode(payload, { format: 'qr', ecc: 'M' });
const image = toImageData(matrix, { scale: 8, margin: 4 });
const results = decode(image, { formats: ['qr'] });

if (results.length !== 1 || results[0].text !== payload) {
  throw new Error('The generated symbol was not verified');
}

console.log(results[0].format, results[0].text);
// qr Greetings My Lord Sythos

encode() returns modules, not pixels. It does not add a quiet zone. The renderer adds the margin because a screen preview, an SVG export and a printed label may need different output dimensions.

Ask the registry instead of guessing

Format names are intentionally data-driven. listFormats() returns FormatInfo[] entries with an id, human label, kind, canWrite and canRead flag:

import { listFormats } from '@sythos/js_barcode_universal';

const readable = listFormats().filter((item) => item.canRead);
const writeOnly = listFormats().filter((item) => item.canWrite && !item.canRead);

console.log(readable.map((item) => item.id));
console.log(writeOnly.map((item) => item.id));
// Pharmacode is currently the notable write-only entry.

listFormats() is specifically the encode()/decode() dispatcher's own registry — it is not a complete inventory of everything this SDK ships. Eight formats and variants exist outside it, for two different reasons, and neither goes through listFormats(), encode() or decode():

• KarTrak ACI and JAB Code are colour-coded: they produce a PolychromeMatrix, not a BitMatrix, so they cannot go through the BitMatrix-based dispatcher at all. Use @sythos/js_barcode_universal/kartrak and @sythos/js_barcode_universal/jabcode directly.
• vCard, VIN, SPARQCode, Swiss QR-bill, SEPA/EPC QR and AAMVA DL/ID data are not symbologies — each is a structured payload convention built on an already-registered format (qr, code39 or pdf417), so none has an id of its own to register. Use @sythos/js_barcode_universal/payloads directly.

See the full row-by-row list, including which subpath each one lives at, in the format catalogue.

EAN-2 and EAN-5 are marked as supplements. They are not standalone EAN/UPC parents in a retail layout; use the dedicated add-on helpers when composing a complete symbol. The registry is the release-time authority, so an application that builds a format picker should consume it rather than hard-code a count.

Reading is intentionally conservative

decode() returns [] when an image does not contain a symbol that passes the requested detector and validation checks. That is a normal outcome for a camera frame. It does not return a partial payload simply because some modules look plausible.

Use decodeStrict() only at a boundary where “nothing found” is exceptional:

import { decodeStrict } from '@sythos/js_barcode_universal';

try {
  const result = decodeStrict(image, { formats: ['pdf417'] });
  console.log(result.text);
} catch (error) {
  // NotFoundError, FormatError or ChecksumError can reach this boundary.
  console.error('No validated PDF417 symbol:', error.message);
}

Inside a continuous camera loop, prefer decode() and treat an empty array as “scan the next frame”. See Reading and decoding for the input contract, camera profile and result metadata.

Errors and validation

The root exports five error classes:

Error	Typical meaning
BarcodeError	Common base class for SDK barcode errors.
EncodeError	Payload or encoding options cannot produce the requested symbol.
NotFoundError	A strict operation found no valid symbol.
FormatError	A sampled matrix or format structure is malformed.
ChecksumError	Error correction or checksum validation failed.

The exact operation decides whether an error is thrown or converted into an empty result. Never use decoded text as a command, URL or trusted identifier without applying the validation and allowlisting rules of your own application.

Source and package boundaries

The package’s public subpaths are declared in package.json and documented in Subpath exports. Deep imports into unlisted source files are not part of the compatibility contract. The committed browser examples remain the most concrete platform references:

• Create example for generation and rendering;
• Read example for image input and camera reading.