@veloxdevworks/barcodes

Experimental — this package has not yet been validated through the npm registry. APIs may change without notice. Use in production at your own risk.

High‑performance, fully type‑safe barcode generation for Node and the browser, powered by a modern C++ engine compiled to WebAssembly.

This package exposes the Velox Barcodes core library (QR, Data Matrix, Aztec, PDF417, Code 128, EAN/UPC, Code 39, ITF, Codabar, MSI, and more) through a clean TypeScript API with strong typing and pixel‑perfect output (SVG, PNG, BMP).

Why use @veloxdevworks/barcodes?

• Production‑grade formats: Support for both 2D (QR, Data Matrix, Aztec, PDF417…) and 1D (EAN/UPC, Code128, Code39, ITF, Codabar, MSI…) in a single API.
• Native‑quality performance: All heavy lifting is done in optimized C++ and compiled to WebAssembly via Emscripten.
• Pixel‑accurate output: Renders to SVG, PNG, and BMP with tests verifying magic bytes and SVG structure.
• End‑to‑end type safety: Strong TypeScript enums and option types mirroring the C++ core so misconfiguration is caught at compile time.
• Deterministic, tested engine: Backed by extensive C++ unit tests and Jest tests that exercise the actual WASM bindings.

Typical use cases:

• Generating shipping labels, tickets, or loyalty codes in a Node backend.
• Embedding QR/Data Matrix codes into dashboards or admin tools.
• Batch‑producing barcodes for PDFs or print workflows with predictable layout.

Installation

npm install @veloxdevworks/barcodes

Basic usage

Generate a QR code as PNG in Node:

import {
  init,
  generate,
  BarcodeType,
  ImageFormat,
} from "@veloxdevworks/barcodes";

async function main() {
  await init(); // loads the WASM module once

  const result = await generate("Hello Velox", BarcodeType.QR_CODE, {
    format: ImageFormat.PNG,
  });

  // result.bytes is a Uint8Array with PNG bytes
  // write it to disk, send it over HTTP, or embed in a response
  console.log("QR PNG bytes:", result.bytes.length);
}

main().catch(console.error);

Generate an SVG string for embedding in HTML:

import {
  init,
  generateSVG,
  BarcodeType,
} from "@veloxdevworks/barcodes";

async function qrInlineSvg() {
  await init();
  const svg = await generateSVG("https://example.com", BarcodeType.QR_CODE);

  // You can now inject `svg` into a page, template, or React component
  console.log(svg.slice(0, 120) + "...");
}

Customization

You can control output format, module size, margins, and colors using GenerationOptions:

import {
  init,
  generate,
  BarcodeType,
  ImageFormat,
} from "@veloxdevworks/barcodes";

async function styledBarcode() {
  await init();

  const res = await generate("Custom", BarcodeType.QR_CODE, {
    format: ImageFormat.PNG,
    output: {
      moduleSize: 8,
      margin: 0,
      foreground: { r: 0, g: 0, b: 0 },       // black modules
      background: { r: 255, g: 255, b: 255 }, // white background
    },
  });

  console.log("Custom PNG size:", res.bytes.length);
}

API reference

All functions are async and return Promises.

| Function | Returns | Description | |---|---|---| | init() | Promise<void> | Initialize the WASM engine. Idempotent. | | generate(data, type, options?) | Promise<BarcodeResult> | Encode and render a barcode. | | generateSVG(data, type, options?) | Promise<string> | Convenience: returns the SVG markup string directly. | | validate(data, type) | Promise<boolean> | Check if data is valid for type. | | getMaxCapacity(type, options?) | Promise<number> | Maximum payload capacity for type. |

BarcodeResult

interface BarcodeResult {
  bytes: Uint8Array;   // raw image data (SVG XML, PNG bytes, BMP bytes, …)
  width: number;       // logical width in modules/pixels
  height: number;      // logical height in modules/pixels
  format: ImageFormat; // echo of the requested format
  type: BarcodeType;   // echo of the requested barcode type
}

GenerationOptions

interface GenerationOptions {
  format?: ImageFormat;  // default: SVG
  output?: {
    moduleSize?: number;                              // default: 4
    margin?: number;                                  // default: 10
    foreground?: { r: number; g: number; b: number }; // default: black
    background?: { r: number; g: number; b: number }; // default: white
  };
}