isahaq-barcode 1.8.0 → 2.0.0

package/README.md

@@ -1,302 +1,281 @@
 # Isahaq Barcode Generator
 
-> A comprehensive Node.js barcode generation library supporting 32+ barcode types with Express.js integration and CLI tools
+> Barcode and QR code generation for Node.js and the browser. 45 symbologies, PNG / SVG / HTML / PDF output, a CLI, and a builder for QR codes with logos and watermarks.
 
 [![npm version](https://img.shields.io/npm/v/isahaq-barcode.svg)](https://www.npmjs.com/package/isahaq-barcode)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
----
-
-## Table of Contents
-
-- [Features](#-features)
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [Supported Barcode Types](#-supported-barcode-types)
-- [Usage Examples](#-usage-examples)
-- [Express.js Integration](#-expressjs-integration)
-- [CLI Usage](#-cli-usage)
-- [API Reference](#-api-reference)
-- [Contributing](#-contributing)
+Encoding is done by [bwip-js](https://github.com/metafloor/bwip-js) (a port of the
+BWIPP reference implementation), so every advertised type and output format
+produces a real, scannable symbology. `npm run verify:scan` proves it by decoding
+generated barcodes with ZXing.
 
 ---
 
-## ✨ Features
-
-| Feature               | Description                                              |
-| --------------------- | -------------------------------------------------------- |
-| **32+ Barcode Types** | Linear, 2D, postal, stacked, and auto-detection variants |
-| **Multiple Formats**  | PNG, SVG, HTML, JPG, PDF output support                  |
-| **Framework Ready**   | Express.js middleware and route helpers included         |
-| **CLI Tool**          | Generate barcodes directly from terminal                 |
-| **Advanced QR Codes** | Logos, watermarks, labels, and customization             |
-| **Validation**        | Built-in data validation for all barcode types           |
-| **Batch Processing**  | Generate multiple barcodes simultaneously                |
-| **High Performance**  | Optimized for enterprise-scale generation                |
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Upgrading from 1.x](#upgrading-from-1x)
+- [Supported barcode types](#supported-barcode-types)
+- [Output formats](#output-formats)
+- [Render options](#render-options)
+- [QR codes with logos, labels and watermarks](#qr-codes-with-logos-labels-and-watermarks)
+- [Validation](#validation)
+- [Batch generation](#batch-generation)
+- [Express.js integration](#expressjs-integration)
+- [Browser usage](#browser-usage)
+- [CLI](#cli)
+- [TypeScript](#typescript)
+- [API reference](#api-reference)
+- [Development](#development)
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install isahaq-barcode
 ```
 
-**Requirements:** Node.js 18.0 or higher
+Requires Node.js 18 or newer.
 
-## 🌐 Universal Compatibility
+`canvas` is an **optional** dependency. It is only needed for QR codes that
+composite a logo, label or watermark. Everything else - all barcode types, all
+output formats, plain QR codes - works without it, so installs never fail on a
+missing native toolchain.
 
-> **Great News:** This package now works in **both Node.js and browser environments**!
+```bash
+npm install canvas   # only if you need QR logos/labels/watermarks
+```
 
-### ✅ Server-Side (Node.js)
+## Quick start
 
-- **Full Features**: All barcode types, formats, and advanced features
-- **Canvas Support**: High-quality image generation with Node.js canvas
-- **File Operations**: Save files directly to filesystem
-- **CLI Tools**: Command-line interface available
+```javascript
+const fs = require('fs/promises');
+const BarcodeGenerator = require('isahaq-barcode');
 
-### ✅ Client-Side (Browser)
+// PNG (returns a Promise<Buffer>)
+await fs.writeFile(
+  'code128.png',
+  await BarcodeGenerator.png('1234567890', 'code128')
+);
 
-- **Core Features**: PNG, SVG, HTML generation
-- **QR Codes**: Full QR code generation with customization
-- **Barcode Types**: Code128, Code39, EAN13, UPC, and more
-- **No Dependencies**: Works with just jsbarcode and qrcode
+// SVG - async or sync, whichever suits the call site
+const svg = await BarcodeGenerator.svg('5901234123457', 'ean13');
+const svgNow = BarcodeGenerator.svgSync('5901234123457', 'ean13');
 
-### Recommended Usage Patterns
+// HTML fragment with an inline SVG
+const html = BarcodeGenerator.htmlSync('1234567890', 'code128');
 
-**✅ Server-Side (Recommended):**
+// PDF
+await fs.writeFile(
+  'label.pdf',
+  await BarcodeGenerator.pdf('1234567890', 'code128', { fitToBarcode: true })
+);
 
-```javascript
-// Node.js/Express.js server
-const BarcodeGenerator = require('isahaq-barcode');
-
-// Generate barcode on server
-app.get('/barcode/:data', (req, res) => {
-  const barcode = BarcodeGenerator.png(req.params.data, 'code128');
-  res.set('Content-Type', 'image/png');
-  res.send(barcode);
+// 2D symbologies - size them in pixels
+const qr = await BarcodeGenerator.png('https://example.com', 'qrcode', {
+  size: 400,
+});
+const dm = await BarcodeGenerator.svg('SHIPMENT-000123', 'datamatrix', {
+  size: 200,
 });
 ```
 
-**✅ Next.js API Routes:**
+## Upgrading from 1.x
 
-```javascript
-// pages/api/barcode.js or app/api/barcode/route.js
-import BarcodeGenerator from 'isahaq-barcode';
-
-export default function handler(req, res) {
-  const barcode = BarcodeGenerator.png(req.query.data, 'code128');
-  res.setHeader('Content-Type', 'image/png');
-  res.send(barcode);
-}
-```
-
-**✅ Client-Side (Browser/React/Vue):**
+Version 2 rewrote the rendering core. In 1.x only PNG output was a real barcode:
+SVG, HTML and PDF drew decorative bars from character codes, and unsupported
+types silently produced a Code 128. Fixing that required two API changes:
 
 ```javascript
-// Browser/React/Vue components
-import BarcodeGenerator from 'isahaq-barcode';
+// 1.x - synchronous
+const buffer = BarcodeGenerator.png('1234567890', 'code128');
+const svg = BarcodeGenerator.svg('1234567890', 'code128');
+const results = BarcodeGenerator.batch(items);
 
-// Generate barcode in browser
-const generateBarcode = async () => {
-  const barcode = await BarcodeGenerator.png('123456789', 'code128');
-  // Use the barcode buffer
-};
+// 2.x - promises, with sync variants for the text formats
+const buffer = await BarcodeGenerator.png('1234567890', 'code128');
+const svg = BarcodeGenerator.svgSync('1234567890', 'code128'); // or await .svg(...)
+const results = await BarcodeGenerator.batch(items);
 ```
 
-### Alternative for Client-Side
+See the [CHANGELOG](CHANGELOG.md) for the full list, including the removal of the
+`jpg`/`jpeg` render formats (they never worked) and the corrected EAN-8 / UPC-A
+check digit validation.
 
-For browser-based barcode generation, consider:
+## Supported barcode types
 
-- **jsbarcode** - Client-side barcode generation
-- **qrcode** - Client-side QR code generation
-- **Server-side API** - Use this package on your backend
+45 types across six categories. `BarcodeGenerator.getBarcodeTypeInfo(type)`
+returns the metadata for any of them.
 
-**Global CLI Installation:**
+| Category        | Types                                                                                                                                                                                                                                                                                                    |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Linear**      | `code128`, `code128a`, `code128b`, `code128c`, `code128auto`, `code39`, `code39extended`, `code39checksum`, `code39auto`, `code93`, `code25`, `code25auto`, `code32`, `standard25`, `standard25checksum`, `interleaved25`, `interleaved25checksum`, `interleaved25auto`, `msi`, `msichecksum`, `msiauto` |
+| **EAN / UPC**   | `ean13`, `ean8`, `ean2`, `ean5`, `upca`, `upce`, `itf14`                                                                                                                                                                                                                                                 |
+| **Postal**      | `postnet`, `planet`, `rms4cc`, `kix`, `imb`                                                                                                                                                                                                                                                              |
+| **Specialized** | `codabar`, `code11`, `pharmacode`, `pharmacodetwotracks`                                                                                                                                                                                                                                                 |
+| **2D matrix**   | `qrcode`, `datamatrix`, `aztec`, `pdf417`, `microqr`, `maxicode`                                                                                                                                                                                                                                         |
+| **Stacked**     | `code16k`, `code49`                                                                                                                                                                                                                                                                                      |
 
-```bash
-npm install -g isahaq-barcode
+```javascript
+BarcodeGenerator.getBarcodeTypes(); // all 45 ids
+BarcodeGenerator.getBarcodeCategories(); // ['LINEAR', 'EAN_UPC', ...]
+BarcodeGenerator.getBarcodeTypesByCategory('matrix_2d'); // ['qrcode', 'datamatrix', ...]
+
+BarcodeGenerator.getBarcodeTypeInfo('ean13');
+// {
+//   type: 'ean13', name: 'EAN-13', category: 'EAN_UPC', symbology: 'ean13',
+//   description: 'EAN-13 - European Article Number',
+//   minLength: 12, maxLength: 13, charset: 'Numeric'
+// }
 ```
 
----
+## Output formats
 
-## 🚀 Quick Start
+| Format | Method                  | Returns                      |
+| ------ | ----------------------- | ---------------------------- |
+| `png`  | `png()`                 | `Promise<Buffer>`            |
+| `svg`  | `svg()` / `svgSync()`   | `Promise<string>` / `string` |
+| `html` | `html()` / `htmlSync()` | `Promise<string>` / `string` |
+| `pdf`  | `pdf()`                 | `Promise<Buffer>`            |
 
-```javascript
-const BarcodeGenerator = require('isahaq-barcode');
-
-// Generate PNG barcode
-const pngBuffer = BarcodeGenerator.png('1234567890', 'code128');
+`generate()` takes the format as an argument:
 
-// Generate SVG barcode
-const svgString = BarcodeGenerator.svg('1234567890', 'ean13');
-
-// Generate QR code with logo
-const qrCode = BarcodeGenerator.modernQr({
-  data: 'https://example.com',
-  size: 300,
-  logoPath: 'path/to/logo.png',
-  label: 'Scan me!',
+```javascript
+const output = await BarcodeGenerator.generate('1234567890', 'code128', 'pdf', {
+  pageSize: 'A4',
 });
-
-await qrCode.saveToFile('qr-code.png');
 ```
 
----
-
-## 📊 Supported Barcode Types
-
-### Linear Barcodes (1D)
-
-| Type           | Variants                           | Use Case                      |
-| -------------- | ---------------------------------- | ----------------------------- |
-| **Code 128**   | A, B, C, Auto                      | General purpose, high density |
-| **Code 39**    | Standard, Extended, Checksum, Auto | Alphanumeric, automotive      |
-| **Code 93**    | -                                  | Compact alphanumeric          |
-| **EAN Family** | EAN-13, EAN-8, EAN-2, EAN-5        | Retail products (Europe)      |
-| **UPC Family** | UPC-A, UPC-E                       | Retail products (USA)         |
-| **Code 25**    | Standard, Interleaved, Auto        | Industrial, logistics         |
-| **ITF-14**     | -                                  | Shipping containers           |
-| **MSI**        | Standard, Checksum, Auto           | Inventory management          |
-| **Codabar**    | -                                  | Libraries, blood banks        |
-| **Code 11**    | -                                  | Telecommunications            |
-
-### 2D Barcodes
-
-| Type            | Data Capacity     | Use Case                |
-| --------------- | ----------------- | ----------------------- |
-| **QR Code**     | Up to 4,296 chars | URLs, payments, general |
-| **Data Matrix** | Up to 2,335 chars | Small item marking      |
-| **Aztec**       | Up to 3,832 chars | Transport tickets       |
-| **PDF417**      | Up to 1,850 chars | IDs, boarding passes    |
-| **Micro QR**    | Up to 35 chars    | Compact applications    |
-| **MaxiCode**    | Up to 93 chars    | Package tracking        |
-
-### Postal Barcodes
+## Render options
 
-**POSTNET** • **PLANET** • **RMS4CC** • **KIX** • **IMB**
+```javascript
+await BarcodeGenerator.png('1234567890', 'code128', {
+  width: 3, // module (narrow bar) width in px         default 2
+  height: 140, // bar height in px, 1D only            default 100
+  size: 400, // target size in px, 2D/stacked only
+  displayValue: true, // print the human readable text default true
+  fontSize: 24, // text size in px                     default 20
+  textAlign: 'center', // center | left | right | justify
+  textMargin: 2, // gap between bars and text in px
+  textColor: '#1d3557', // defaults to lineColor
+  lineColor: '#1d3557', // bar colour                   default #000000
+  background: '#f1faee', // background colour           default #ffffff
+  margin: 24, // quiet zone in px, or use quietZone
+  marginTop: 10, // per-side overrides
+  quietZone: 10, // quiet zone in modules               default 10
+  rotate: 'N', // N | R | L | I
+});
+```
 
-### Specialized
+**Quiet zone:** when no `margin` is given, the quiet zone is `quietZone` modules
+(10 by default) rather than a fixed pixel count. Most specifications require at
+least 10 narrow modules of clear space, and scanners reject codes with less. Pass
+`margin` in pixels when you need an exact figure, or `margin: 0` for none.
 
-**Code 32** (Italian Pharmacode) • **PharmaCode** • **PharmaCodeTwoTracks** • **Code 16K** • **Code 49**
+**2D symbologies** keep their own aspect ratio: `height` does not apply, and
+`size` is honoured by scaling the module size to the nearest whole number, so the
+result lands close to - not exactly on - the requested pixel size.
 
----
+PDF-only options: `pageWidth`, `pageHeight`, `pageSize` (for example `'A4'`),
+`fitToBarcode` (size the page to the barcode plus its margins) and `title`.
 
-## 💻 Usage Examples
+HTML-only options: `id`, `className`, `includeStyles`.
 
-### Basic Generation
+Anything the encoder itself understands can be passed straight through:
 
 ```javascript
-const BarcodeGenerator = require('isahaq-barcode');
-
-// PNG with custom options
-const barcode = BarcodeGenerator.png('1234567890', 'code128', {
-  width: 3,
-  height: 150,
-  displayValue: true,
-  foregroundColor: '#000000',
-  backgroundColor: '#FFFFFF',
-  margin: 10,
+await BarcodeGenerator.png('1234567890', 'code128', {
+  bwipOptions: { alttext: 'custom caption' },
 });
-
-// Convert to Base64 for web display
-const base64Image = barcode.toString('base64');
-console.log(`<img src="data:image/png;base64,${base64Image}" alt="Barcode" />`);
 ```
 
-### Advanced QR Code with Logo
-
-```javascript
-const qrCode = BarcodeGenerator.modernQr({
-  data: 'https://example.com',
-  size: 300,
-  margin: 10,
+## QR codes with logos, labels and watermarks
 
-  // Logo configuration
-  logoPath: 'path/to/logo.png',
-  logoSize: 60, // Percentage
+`qrCode()` / `modernQr()` return a chainable builder. Plain codes need no extra
+dependencies; a logo, label or watermark requires the optional `canvas` package.
 
-  // Text elements
-  label: 'Scan me!',
-  watermark: 'Company Name',
-  watermarkPosition: 'bottom-center',
-
-  // Colors
-  foregroundColor: [0, 0, 0],
-  backgroundColor: [255, 255, 255],
-
-  // Error correction (H recommended for logos)
+```javascript
+const buffer = await BarcodeGenerator.qrCode('https://example.com', {
+  size: 400,
   errorCorrectionLevel: 'H',
-});
+}).generate();
 
-// Save to file
-await qrCode.saveToFile('qr-code.png');
+// Or with the builder API
+const QrCodeBuilder = BarcodeGenerator.QrCodeBuilder;
 
-// Get as data URI
-const dataUri = await qrCode.getDataUri();
+await QrCodeBuilder.create()
+  .data('https://example.com')
+  .size(400)
+  .margin(12)
+  .errorCorrectionLevel('H')
+  .foregroundColor([29, 53, 87]) // RGB array or '#1d3557'
+  .backgroundColor('#ffffff')
+  .logoPath('./logo.png') // path, URL or data URI
+  .logoSize(20) // percent of the QR code
+  .label('Scan me!')
+  .watermark('DRAFT', 'center')
+  .saveToFile('qr.png');
+
+// Other outputs
+const svg = await BarcodeGenerator.modernQr({
+  data: 'x',
+  format: 'svg',
+}).generate();
+const uri = await BarcodeGenerator.modernQr({ data: 'x' }).getDataUri();
 ```
 
-### QR Code Builder Pattern
+Watermark positions: `top-left`, `top-center`, `top-right`, `left-center`,
+`center`, `right-center`, `bottom-left`, `bottom-center`, `bottom-right`
+(`getWatermarkPositions()`).
 
-```javascript
-const { QrCodeBuilder } = require('isahaq-barcode');
+Keep `logoSize` at or below roughly 25%. A larger logo covers too many modules
+for the error correction to recover, and the code stops scanning.
 
-const qrCode = QrCodeBuilder.create()
-  .data('https://example.com')
-  .size(300)
-  .margin(10)
-  .foregroundColor([0, 0, 0])
-  .backgroundColor([255, 255, 255])
-  .logoPath('path/to/logo.png')
-  .logoSize(60)
-  .label('Scan me!')
-  .watermark('Watermark Text', 'center')
-  .format('png')
-  .build();
+## Validation
 
-await qrCode.saveToFile('qr-code.png');
-```
-
-### Batch Generation
+Validation runs automatically before generation, and is also available directly:
 
 ```javascript
-const items = [
-  { data: '1234567890', type: 'code128', format: 'png' },
-  { data: '9876543210', type: 'code39', format: 'svg' },
-  { data: 'https://example.com', type: 'qrcode', format: 'png' },
-];
+BarcodeGenerator.validate('5901234123457', 'ean13');
+// { valid: true, data: '5901234123457', type: 'ean13', length: 13, charset: 'Numeric' }
 
-const results = BarcodeGenerator.batch(items);
+BarcodeGenerator.validate('1234567890123', 'ean13');
+// { valid: false, error: 'Invalid EAN-13 check digit (expected 8)' }
 
-results.forEach((result, index) => {
-  if (result.success) {
-    console.log(`✓ Barcode ${index} generated`);
-    // result.data contains the generated barcode
-  } else {
-    console.error(`✗ Barcode ${index} failed: ${result.error}`);
-  }
-});
+BarcodeGenerator.validate('123', 'ean13');
+// { valid: false, error: 'Data too short. Minimum length: 12' }
 ```
 
-### Data Validation
+EAN-13, EAN-8, UPC-A and ITF-14 accept the code with or without its trailing
+check digit; when one is supplied it is verified.
 
-```javascript
-const validation = BarcodeGenerator.validate('1234567890', 'code128');
-
-if (validation.valid) {
-  console.log('✓ Valid data');
-  console.log(`  Length: ${validation.length}`);
-  console.log(`  Charset: ${validation.charset}`);
-} else {
-  console.error(`✗ Invalid: ${validation.error}`);
-}
-```
+## Batch generation
 
----
+Per-item failures are reported in the result rather than rejecting the batch:
 
-## 🌐 Express.js Integration
+```javascript
+const results = await BarcodeGenerator.batch([
+  { data: '1234567890', type: 'code128', format: 'png' },
+  {
+    data: '5901234123457',
+    type: 'ean13',
+    format: 'svg',
+    options: { width: 3 },
+  },
+  { data: 'nope', type: 'ean13', format: 'png' },
+]);
+
+// [
+//   { index: 0, success: true,  result: <Buffer ...>, data: '1234567890', type: 'code128', format: 'png' },
+//   { index: 1, success: true,  result: '<svg ...',   data: '5901234123457', type: 'ean13', format: 'svg' },
+//   { index: 2, success: false, error: 'Invalid data for ean13: Data too short. Minimum length: 12', ... }
+// ]
+```
 
-### Basic Route Implementation
+## Express.js integration
 
 ```javascript
 const express = require('express');
@@ -304,361 +283,182 @@ const BarcodeGenerator = require('isahaq-barcode');
 
 const app = express();
 
-// Barcode endpoint
-app.get('/barcode/:data', (req, res) => {
-  const { data } = req.params;
+app.get('/barcode/:data', async (req, res) => {
   const { type = 'code128', format = 'png' } = req.query;
 
   try {
-    let result, contentType;
-
-    switch (format) {
-      case 'png':
-        result = BarcodeGenerator.png(data, type);
-        contentType = 'image/png';
-        break;
-      case 'svg':
-        result = BarcodeGenerator.svg(data, type);
-        contentType = 'image/svg+xml';
-        break;
-      case 'html':
-        result = BarcodeGenerator.html(data, type);
-        contentType = 'text/html';
-        break;
-      default:
-        return res.status(400).json({ error: 'Invalid format' });
-    }
-
-    res.set('Content-Type', contentType);
+    const result = await BarcodeGenerator.generate(
+      req.params.data,
+      type,
+      format
+    );
+    res.set(
+      'Content-Type',
+      BarcodeGenerator.getRenderFormatInfo(format).mimeType
+    );
     res.send(result);
   } catch (error) {
     res.status(400).json({ error: error.message });
   }
 });
 
-// QR code endpoint
-app.get('/qr/:data', async (req, res) => {
-  const { data } = req.params;
-  const { size = 300, logo, label } = req.query;
-
-  try {
-    const qrCode = BarcodeGenerator.modernQr({
-      data: decodeURIComponent(data),
-      size: parseInt(size),
-      logoPath: logo,
-      label: label,
-    });
-
-    const result = await qrCode.generate();
-    res.set('Content-Type', 'image/png');
-    res.send(result);
-  } catch (error) {
-    res.status(400).json({ error: error.message });
-  }
-});
-
-app.listen(3000, () => {
-  console.log('🚀 Barcode server running on port 3000');
+// Inline SVG needs no await
+app.get('/inline/:data', (req, res) => {
+  res.type('svg').send(BarcodeGenerator.svgSync(req.params.data, 'code128'));
 });
 ```
 
-### Middleware Pattern
+A complete server, including QR and batch endpoints, is in
+[examples/express-server.js](examples/express-server.js).
 
-```javascript
-const express = require('express');
-const BarcodeGenerator = require('isahaq-barcode');
+## Browser usage
 
-const app = express();
+Bundlers resolve the package to the browser build automatically through the
+`browser` field. It shares the encoder and type registry with the Node build, so
+output is identical; PDF generation and file writing are Node-only.
 
-// Barcode middleware
-app.use('/api/barcode', (req, res, next) => {
-  req.generateBarcode = (
-    data,
-    type = 'code128',
-    format = 'png',
-    options = {}
-  ) => {
-    try {
-      switch (format) {
-        case 'png':
-          return BarcodeGenerator.png(data, type, options);
-        case 'svg':
-          return BarcodeGenerator.svg(data, type, options);
-        case 'html':
-          return BarcodeGenerator.html(data, type, options);
-        default:
-          throw new Error(`Unsupported format: ${format}`);
-      }
-    } catch (error) {
-      throw new Error(`Generation failed: ${error.message}`);
-    }
-  };
-  next();
-});
+```javascript
+import BarcodeGenerator from 'isahaq-barcode';
 
-// Route using middleware
-app.get('/api/barcode/:data', (req, res) => {
-  const { data } = req.params;
-  const { type, format = 'png', width, height } = req.query;
+// Synchronous SVG - no DOM required
+element.innerHTML = BarcodeGenerator.svg('1234567890', 'code128');
 
-  const options = {};
-  if (width) options.width = parseInt(width);
-  if (height) options.height = parseInt(height);
+// Canvas rendering
+BarcodeGenerator.toCanvas(
+  document.querySelector('canvas'),
+  '1234567890',
+  'code128'
+);
 
-  try {
-    const result = req.generateBarcode(data, type, format, options);
-    const mimeTypes = {
-      png: 'image/png',
-      svg: 'image/svg+xml',
-      html: 'text/html',
-    };
-
-    res.set('Content-Type', mimeTypes[format] || 'image/png');
-    res.send(result);
-  } catch (error) {
-    res.status(400).json({ error: error.message });
-  }
+const dataUrl = BarcodeGenerator.dataUrl('1234567890', 'code128');
+const blob = await BarcodeGenerator.png('1234567890', 'code128'); // Blob, not Buffer
+const qrDataUrl = await BarcodeGenerator.qrCode('https://example.com', {
+  size: 300,
 });
 ```
 
----
-
-## 🖥️ CLI Usage
-
-### Generate Barcodes
+## CLI
 
 ```bash
-# Basic PNG barcode
-barcode-generate barcode -d "1234567890" -t code128 -f png -o barcode.png
-
-# SVG with custom dimensions
-barcode-generate barcode -d "1234567890" -t ean13 -f svg -w 3 -h 150 -o barcode.svg
-
-# Custom colors
-barcode-generate barcode -d "1234567890" -t code128 \
-  --foreground "#FF0000" --background "#FFFFFF" -o red-barcode.png
+npx barcode-generate --help
 ```
 
-### Generate QR Codes
-
 ```bash
-# Basic QR code
-barcode-generate qr -d "https://example.com" -s 300 -o qr.png
+# Barcodes
+barcode-generate barcode -d 1234567890 -t code128 -f png -o barcode.png
+barcode-generate barcode -d 5901234123457 -t ean13 -f pdf -o label.pdf
+barcode-generate barcode -d "https://example.com" -t qrcode -s 400 -o qr.png
+barcode-generate barcode -d 1234567890 -f svg              # writes SVG to stdout
+barcode-generate barcode -d 1234567890 --no-text --width 3 --height 140 -o bars.png
 
-# QR code with logo
-barcode-generate qr -d "https://example.com" -s 300 \
-  --logo "path/to/logo.png" --logo-size 60 -o qr-logo.png
-
-# QR code with watermark
-barcode-generate qr -d "https://example.com" -s 300 \
-  --watermark "Company Name" --watermark-position bottom-center -o qr-watermark.png
-```
-
-### Batch Operations
-
-```bash
-# Create batch configuration file
-cat > batch.json << EOF
-[
-  {"data": "1234567890", "type": "code128", "format": "png"},
-  {"data": "9876543210", "type": "code39", "format": "svg"},
-  {"data": "https://example.com", "type": "qrcode", "format": "png"}
-]
-EOF
-
-# Generate batch
-barcode-generate batch -i batch.json -o ./output
-```
+# QR codes with extras
+barcode-generate qr -d "https://example.com" -s 400 -e H --label "Scan me" -o qr.png
 
-### Utility Commands
+# Batch generation from a JSON file
+barcode-generate batch -i examples/batch-example.json -o ./output
 
-```bash
-# List supported barcode types
+# Discovery and validation
 barcode-generate types
-
-# List output formats
+barcode-generate types -c matrix_2d
 barcode-generate formats
-
-# Validate data for specific type
-barcode-generate validate -d "1234567890" -t code128
+barcode-generate validate -d 5901234123457 -t ean13
 ```
 
----
+Data goes to stdout and diagnostics to stderr, so the CLI pipes cleanly. Without
+`-o`, binary formats are printed as base64. Colour output honours `NO_COLOR`.
 
-## 📚 API Reference
+Sizing flags mirror the render options: `-w/--width` (module width in px),
+`-h/--height` (bar height in px), `-s/--size` (2D target size in px),
+`-q/--quiet-zone` (quiet zone in modules, default 10) and `-m/--margin` (quiet
+zone in px, overrides `--quiet-zone`).
 
-### BarcodeGenerator (Static Methods)
+Install globally with `npm install -g isahaq-barcode` to drop the `npx` prefix.
 
-#### Generation Methods
+## TypeScript
 
-```javascript
-BarcodeGenerator.png(data, type, options?)
-  // Returns: Buffer
+Type declarations ship with the package - no `@types` install needed.
 
-BarcodeGenerator.svg(data, type, options?)
-  // Returns: String
+```typescript
+import BarcodeGenerator = require('isahaq-barcode');
+// or, with esModuleInterop: import BarcodeGenerator from 'isahaq-barcode';
 
-BarcodeGenerator.html(data, type, options?)
-  // Returns: String
+const options: BarcodeGenerator.RenderOptions = { width: 3, height: 140 };
+const png: Buffer = await BarcodeGenerator.png(
+  '1234567890',
+  'code128',
+  options
+);
 
-BarcodeGenerator.pdf(data, type, options?)
-  // Returns: Promise<Buffer>
-
-BarcodeGenerator.modernQr(options)
-  // Returns: QrCodeInstance
+const result = BarcodeGenerator.validate('5901234123457', 'ean13');
+if (result.valid) {
+  console.log(result.charset); // narrowed to the success shape
+}
 ```
 
-#### Utility Methods
+## API reference
 
-```javascript
-BarcodeGenerator.validate(data, type);
-// Returns: { valid: boolean, error?: string, length?: number, charset?: string }
+### Generation
 
-BarcodeGenerator.batch(items);
-// Returns: Array<{ success: boolean, data?: Buffer|String, error?: string }>
+| Method                                  | Returns                     |
+| --------------------------------------- | --------------------------- |
+| `generate(data, type?, format?, opts?)` | `Promise<Buffer \| string>` |
+| `png(data, type?, opts?)`               | `Promise<Buffer>`           |
+| `svg(data, type?, opts?)`               | `Promise<string>`           |
+| `svgSync(data, type?, opts?)`           | `string`                    |
+| `html(data, type?, opts?)`              | `Promise<string>`           |
+| `htmlSync(data, type?, opts?)`          | `string`                    |
+| `pdf(data, type?, opts?)`               | `Promise<Buffer>`           |
+| `batch(items)`                          | `Promise<BatchResult[]>`    |
+| `qrCode(data, opts?)`                   | `QrCodeBuilder`             |
+| `modernQr(opts?)`                       | `QrCodeBuilder`             |
 
-BarcodeGenerator.getBarcodeTypes();
-// Returns: Array<string>
+`type` defaults to `code128`, `format` to `png`.
 
-BarcodeGenerator.getRenderFormats();
-// Returns: Array<string>
+### Metadata
 
-BarcodeGenerator.getWatermarkPositions();
-// Returns: Array<string>
-```
+| Method                           | Returns                    |
+| -------------------------------- | -------------------------- |
+| `validate(data, type)`           | `ValidationResult`         |
+| `getBarcodeTypes()`              | `string[]`                 |
+| `getBarcodeCategories()`         | `string[]`                 |
+| `getBarcodeTypesByCategory(cat)` | `string[]`                 |
+| `getBarcodeTypeInfo(type)`       | `BarcodeTypeInfo \| null`  |
+| `getRenderFormats()`             | `string[]`                 |
+| `getRenderFormatInfo(format)`    | `RenderFormatInfo \| null` |
+| `getWatermarkPositions()`        | `string[]`                 |
+| `getDefaultOptions()`            | `RenderOptions`            |
 
-### Options Object
+### Building blocks
 
-```javascript
-{
-  // Dimensions
-  width: 3,                    // Bar width
-  height: 150,                 // Bar height
-
-  // Display
-  displayValue: true,          // Show text below barcode
-  fontSize: 20,                // Text font size
-  textAlign: 'center',         // 'left' | 'center' | 'right'
-  textPosition: 'bottom',      // 'top' | 'bottom'
-  textMargin: 2,               // Space between bars and text
-
-  // Colors
-  background: '#ffffff',       // Background color
-  lineColor: '#000000',        // Bar color (alias: foregroundColor)
-
-  // Margins
-  margin: 10,                  // All sides
-  marginTop: 10,               // Individual sides
-  marginBottom: 10,
-  marginLeft: 10,
-  marginRight: 10
-}
-```
-
-### QrCodeBuilder Methods
+Attached to the default export for advanced use: `QrCodeBuilder`,
+`BarcodeService`, `BarcodeEncoder`, `BarcodeTypes`, `RenderFormats`, `Validator`.
 
 ```javascript
-QrCodeBuilder.create(options?)
-  .data(string)                // Set data to encode
-  .size(number)                // QR code size in pixels
-  .margin(number)              // Margin size
-  .errorCorrectionLevel(level) // 'L' | 'M' | 'Q' | 'H'
-  .foregroundColor(rgb)        // [R, G, B]
-  .backgroundColor(rgb)        // [R, G, B]
-  .logoPath(string)            // Path to logo image
-  .logoSize(number)            // Logo size percentage
-  .label(string)               // Label text
-  .watermark(text, position)   // Watermark text and position
-  .format(format)              // 'png' | 'svg'
-  .build()                     // Build QR code instance
-
-// QR Code Instance Methods
-qrCode.generate()              // Returns: Promise<Buffer>
-qrCode.saveToFile(path)        // Returns: Promise<void>
-qrCode.getDataUri()            // Returns: Promise<string>
-qrCode.getString()             // Returns: Promise<string>
-```
+const { BarcodeEncoder, BarcodeTypes } = require('isahaq-barcode');
 
-### Watermark Positions
+BarcodeEncoder.getDimensions('1234567890', 'code128', {
+  width: 2,
+  height: 100,
+});
+// { width: 220, height: 153 }  bars + human readable text + quiet zone
 
-```javascript
-('top-left',
-  'top-center',
-  'top-right',
-  'left-center',
-  'center',
-  'right-center',
-  'bottom-left',
-  'bottom-center',
-  'bottom-right');
+BarcodeTypes.getSymbology('aztec'); // 'azteccode'
 ```
 
----
-
-## 🧪 Testing
+## Development
 
 ```bash
-# Run all tests
-npm test
-
-# Run with coverage report
-npm run test:coverage
-
-# Watch mode for development
-npm run test:watch
+npm install
+npm test              # jest
+npm run lint          # eslint
+npm run format        # prettier --write
+npm run typecheck     # tsc against index.d.ts
+npm run verify:scan   # generate barcodes and decode them with ZXing
+npm run build         # lint + format:check + typecheck + test
+node examples/basic-usage.js
+npm run dev           # express example on :3000
 ```
 
----
-
-## 🤝 Contributing
-
-We welcome contributions! Please follow these steps:
-
-1. **Fork** the repository
-2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
-3. **Commit** your changes: `git commit -m 'Add amazing feature'`
-4. **Push** to the branch: `git push origin feature/amazing-feature`
-5. **Open** a Pull Request
-
-Please ensure your code:
-
-- Follows the existing code style
-- Includes tests for new features
-- Updates documentation as needed
-
----
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
----
-
-## 🙏 Acknowledgments
-
-Built with these excellent libraries:
-
-- [JsBarcode](https://github.com/lindell/JsBarcode) - Barcode generation
-- [node-qrcode](https://github.com/soldair/node-qrcode) - QR code generation
-- [node-canvas](https://github.com/Automattic/node-canvas) - Canvas implementation
-- [PDFKit](https://github.com/foliojs/pdfkit) - PDF generation
-
----
-
-## 📞 Support
-
-Need help? Here's how to get support:
-
-1. 📖 Check the [documentation](README.md)
-2. 🔍 Search [existing issues](https://github.com/isahaq1//npm-barcodegeneratop/issues)
-3. 💬 Create a [new issue](https://github.com/isahaq1//npm-barcodegeneratop/issues/new)
-
----
-
-<div align="center">
-
-**Made with ❤️ by [Isahaq](https://github.com/isahaq1)**
-
-[⭐ Star this repo](https://github.com/isahaq1//npm-barcodegeneratop) • [🐛 Report Bug](https://github.com/isahaq1//npm-barcodegeneratop/issues) • [✨ Request Feature](https://github.com/isahaq1//npm-barcodegeneratop/issues)
+## License
 
-</div>
+MIT - see [LICENSE](LICENSE).