tessl/npm-qrcode

QR code generator for both server-side and client-side applications with multiple output formats including PNG, SVG, Canvas, and Terminal rendering.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core QR Generation

Name: tessl/npm-qrcode
Author: tessl

Core QR code symbol generation functionality that handles automatic mode selection, error correction, and optimization for minimal QR code size.

Capabilities

Create QR Symbol

Creates a QR code symbol object containing all the data needed for rendering.

/**
 * Creates QR Code symbol and returns a qrcode object
 * @param {string|Array} text - Text to encode or array of segments
 * @param {Object} options - Optional configuration
 * @returns {Object} QRCode object with modules, version, errorCorrectionLevel, maskPattern, segments
 */
function create(text, options);

Usage Examples:

const QRCode = require('qrcode');

// Simple text encoding
const qrCode = QRCode.create('Hello World');
console.log(qrCode.version); // QR Code version (1-40)
console.log(qrCode.errorCorrectionLevel); // Error correction level
console.log(qrCode.modules); // BitMatrix with QR code data

// With options
const qrCode = QRCode.create('Hello World', {
  errorCorrectionLevel: 'H',
  version: 5,
  maskPattern: 3
});

// Manual segments
const segments = [
  { data: 'HELLO', mode: 'alphanumeric' },
  { data: '123', mode: 'numeric' }
];
const qrCode = QRCode.create(segments);

Input Data Types

String Input

Simple string input with automatic mode optimization:

const qrCode = QRCode.create('Hello World 123');
// Automatically optimized into mixed segments for minimal size

Segment Array Input

Manual segment specification for precise control:

const segments = [
  { data: 'HELLO WORLD', mode: 'alphanumeric' },  // 0-9, A-Z, space, $%*+-./:
  { data: '12345678', mode: 'numeric' },           // 0-9 only
  { data: 'Hello 世界', mode: 'byte' },             // Any UTF-8 characters
  { data: '漢字', mode: 'kanji' }                   // Kanji characters (requires toSJISFunc)
];

const qrCode = QRCode.create(segments, {
  toSJISFunc: require('qrcode/helper/to-sjis') // For Kanji mode
});

Binary Data Input

Binary data using typed arrays, buffers, or regular arrays:

// Using Uint8ClampedArray
const binarySegments = [
  { data: new Uint8ClampedArray([253, 254, 255]), mode: 'byte' }
];

// Using Node.js Buffer
const bufferSegments = [
  { data: Buffer.from([253, 254, 255]), mode: 'byte' }
];

// Using regular array (values clamped to 0-255)
const arraySegments = [
  { data: [253, 254, 255], mode: 'byte' }
];

Return Object Structure

The create() function returns a QR code object with the following structure:

interface QRCodeObject {
  /** BitMatrix containing the QR code modules (black/white dots) */
  modules: BitMatrix;
  /** Calculated QR code version (1-40) */
  version: number;
  /** Error correction level used */
  errorCorrectionLevel: ErrorCorrectionLevel;
  /** Mask pattern applied to the symbol */
  maskPattern: number;
  /** Generated segments used for encoding */
  segments: Segment[];
}

interface BitMatrix {
  /** Size of the matrix (modules per side) */
  size: number;
  /** Get the value of a module at row, col */
  get(row: number, col: number): boolean;
  /** Set the value of a module at row, col */
  set(row: number, col: number, value: boolean, reserved?: boolean): void;
  /** Check if a module position is reserved for QR code structure */
  isReserved(row: number, col: number): boolean;
}

interface Segment {
  /** Encoding mode used for this segment */
  mode: Mode;
  /** Raw data for this segment */
  data: any;
  /** Get the length of data in this segment */
  getLength(): number;
  /** Write segment data to a bit buffer */
  write(buffer: BitBuffer): void;
}

Encoding Modes

Automatic Mode Selection

By default, QRCode automatically analyzes input text and creates optimized segments:

// This text will be automatically split into optimal segments
const text = 'HELLO123world!@#';
// Result: 
// - 'HELLO' -> alphanumeric mode
// - '123' -> numeric mode  
// - 'world!@#' -> byte mode

Mode Constants

Available encoding modes for manual segment specification:

const Mode = {
  NUMERIC: { id: 'Numeric', bit: 1 },      // 0-9 (3 chars = 10 bits)
  ALPHANUMERIC: { id: 'Alphanumeric', bit: 2 }, // 0-9,A-Z,space,$%*+-./:  (2 chars = 11 bits)
  BYTE: { id: 'Byte', bit: 4 },            // ISO/IEC 8859-1 (1 char = 8 bits)
  KANJI: { id: 'Kanji', bit: 8 }           // Shift JIS (1 kanji = 13 bits)
};

Error Correction Levels

Error correction allows QR codes to be readable even when partially damaged:

const ErrorCorrectionLevel = {
  L: { bit: 1 }, // Low - ~7% error resistance
  M: { bit: 0 }, // Medium - ~15% error resistance (default)
  Q: { bit: 3 }, // Quartile - ~25% error resistance  
  H: { bit: 2 }  // High - ~30% error resistance
};

Usage:

const qrCode = QRCode.create('Important Data', {
  errorCorrectionLevel: 'H' // High error correction for critical data
});

Version Selection

QR code versions (1-40) determine the size and data capacity:

// Automatic version selection (recommended)
const qrCode = QRCode.create('Some text'); // Uses minimum required version

// Manual version specification
const qrCode = QRCode.create('Some text', { version: 10 });

// Version validation - will throw error if text doesn't fit
try {
  const qrCode = QRCode.create('Very long text...', { version: 1 });
} catch (err) {
  console.log('Text too long for version 1');
}

Advanced Options

Mask Pattern Selection

QR codes use mask patterns to avoid problematic visual patterns:

// Automatic mask selection (recommended)
const qrCode = QRCode.create('text');

// Manual mask pattern (0-7)
const qrCode = QRCode.create('text', { maskPattern: 3 });

Kanji Mode Configuration

For Kanji mode support, provide a conversion function:

const toSJIS = require('qrcode/helper/to-sjis');

const qrCode = QRCode.create('漢字テスト', {
  toSJISFunc: toSJIS
});

Browser usage:

<script src="/build/qrcode.js"></script>
<script src="/build/qrcode.tosjis.js"></script>
<script>
const qrCode = QRCode.create('漢字', { toSJISFunc: QRCode.toSJIS });
</script>

Error Handling

The create() function throws errors for:

// Empty or undefined input  
try {
  QRCode.create('');
} catch (err) {
  console.log(err.message); // "No input text"
}

// Data too large for QR code
try {
  QRCode.create('x'.repeat(8000), { errorCorrectionLevel: 'H' });
} catch (err) {
  console.log(err.message); // "The amount of data is too big..."
}

// Version too small for data
try {
  QRCode.create('Long text', { version: 1 });
} catch (err) {
  console.log(err.message); // "The chosen QR Code version cannot contain..."
}

// Invalid segment data
try {
  QRCode.create([{ data: 123, mode: 'invalid' }]);
} catch (err) {
  console.log(err.message); // "Invalid data"
}

Install with Tessl CLI