tessl/npm-brotli

A JavaScript port of the Brotli compression algorithm as used in WOFF2

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Brotli

Name: tessl/npm-brotli
Author: tessl

Brotli is a JavaScript port of the Brotli compression algorithm originally developed by Google. It provides both compression and decompression capabilities through a simple API, with the decompressor hand-ported from C++ and the compressor ported using Emscripten. Originally developed for use in the WOFF2 font format, it offers high-performance compression with configurable quality levels and modes.

Package Information

Package Name: brotli
Package Type: npm
Language: JavaScript
Installation: npm install brotli

Core Imports

const brotli = require('brotli');

For individual function imports (useful for bundling):

const compress = require('brotli/compress');
const decompress = require('brotli/decompress');

For accessing internal decompression functions:

const { BrotliDecompressBuffer, BrotliDecompressedSize, BrotliDecompress } = require('brotli/dec/decode');
const { BrotliInput, BrotliOutput } = require('brotli/dec/streams');

Basic Usage

const brotli = require('brotli');
const fs = require('fs');

// Compress binary data
const inputData = fs.readFileSync('input.bin');
const compressed = brotli.compress(inputData);

// Decompress data
const decompressed = brotli.decompress(compressed);

// Compress with options
const compressedText = brotli.compress(inputData, {
  mode: 1,      // text mode
  quality: 11,  // maximum quality
  lgwin: 22     // window size
});

Module Organization

The Brotli package provides multiple ways to access its functionality:

Main module: require('brotli') - Exports compress and decompress functions
Individual modules: require('brotli/compress') and require('brotli/decompress') - For bundling optimization
Internal modules: Access to lower-level decompression functions via brotli/dec/decode and brotli/dec/streams

Capabilities

Compression

Compresses data using the Brotli compression algorithm with configurable quality levels and modes.

/**
 * Compresses the given buffer using Brotli algorithm
 * @param buffer - Input data to compress (Buffer or Uint8Array)
 * @param opts - Compression options (boolean or object, optional)
 * @returns Uint8Array containing compressed data, or null on error
 */
function compress(buffer, opts);

Options parameter:

When boolean: true for text mode (mode=1), false for generic mode (mode=0, default)
When object:
- quality (number, default: 11): Compression quality level (0-11, higher = better compression)
- mode (number, default: 0): Compression mode (0=generic, 1=text, 2=font/WOFF2)
- lgwin (number, default: 22): Window size parameter (10-24, higher = better compression but more memory)

Usage Examples:

const brotli = require('brotli');

// Basic compression (text mode, default when no options)
const compressed = brotli.compress(Buffer.from('Hello World'));

// Generic mode compression
const genericCompressed = brotli.compress(Buffer.from('Hello World'), true);

// Advanced compression with options
const advancedCompressed = brotli.compress(inputBuffer, {
  quality: 9,   // high quality but faster than maximum
  mode: 1,      // text mode for better text compression
  lgwin: 20     // smaller window size for less memory usage
});

Decompression

Decompresses Brotli-compressed data with optional output size specification.

/**
 * Decompresses Brotli-compressed data to buffer
 * @param buffer - Compressed input data (Buffer or Uint8Array)
 * @param outputSize - Expected output size (number, optional - computed if not provided)
 * @returns Uint8Array containing decompressed data
 * @throws Error on decompression failure or invalid data
 */
function decompress(buffer, outputSize);

Usage Examples:

const brotli = require('brotli');

// Basic decompression (output size computed automatically)
const decompressed = brotli.decompress(compressedData);

// Decompression with known output size (more efficient)
const decompressed = brotli.decompress(compressedData, 1024);

// Convert result to string for text data
const text = Buffer.from(decompressed).toString('utf8');

Stream Interface

For advanced use cases, Brotli provides stream classes for lower-level decompression control.

/**
 * Low-level decompression function using stream interfaces
 * @param input - BrotliInput stream containing compressed data
 * @param output - BrotliOutput stream for decompressed data
 * @throws Error on decompression failure
 */
function BrotliDecompress(input, output);

/**
 * Input stream wrapper for decompression
 */
class BrotliInput {
  constructor(buffer);
  read(buf, i, count);
}

/**
 * Output stream wrapper for decompression  
 */
class BrotliOutput {
  constructor(buf);
  write(buf, count);
}

Stream Usage Example:

const decode = require('brotli/dec/decode');
const streams = require('brotli/dec/streams');

// Stream-based decompression
const input = new streams.BrotliInput(compressedBuffer);
const outputBuffer = new Uint8Array(expectedSize);
const output = new streams.BrotliOutput(outputBuffer);

decode.BrotliDecompress(input, output);
// Result available in outputBuffer

Types

/**
 * Input stream for Brotli decompression
 * @constructor
 * @param {Buffer|Uint8Array} buffer - Source buffer
 */
function BrotliInput(buffer);

/**
 * Read data from input buffer
 * @param {Array|Buffer} buf - Destination buffer
 * @param {number} i - Starting index in destination buffer
 * @param {number} count - Number of bytes to read
 * @returns {number} Number of bytes actually read
 */
BrotliInput.prototype.read = function(buf, i, count);

/**
 * Output stream for Brotli decompression
 * @constructor
 * @param {Uint8Array} buf - Target buffer
 */
function BrotliOutput(buf);

/**
 * Write data to output buffer
 * @param {Buffer|Uint8Array} buf - Source buffer
 * @param {number} count - Number of bytes to write
 * @returns {number} Number of bytes written
 * @throws {Error} If output buffer is too small
 */
BrotliOutput.prototype.write = function(buf, count);

/**
 * Compression options object (when using object form)
 * @typedef {Object} CompressionOptions
 * @property {number} [quality=11] - Compression quality level (0-11)
 * @property {number} [mode=0] - Compression mode (0=generic, 1=text, 2=font)
 * @property {number} [lgwin=22] - Window size parameter (10-24)
 */

Error Handling

The Brotli library handles errors in the following ways:

Compression errors: The compress function returns null when compression fails
Decompression errors: Decompression functions throw Error objects with descriptive messages
Stream errors: Stream operations throw errors for buffer overflow or invalid data
Invalid parameters: Functions may throw errors for invalid input parameters

Error Handling Example:

const brotli = require('brotli');

try {
  // Compression error handling
  const compressed = brotli.compress(inputData);
  if (compressed === null) {
    console.error('Compression failed');
    return;
  }
  
  // Decompression error handling
  const decompressed = brotli.decompress(compressed);
  console.log('Success:', decompressed.length, 'bytes decompressed');
  
} catch (error) {
  console.error('Brotli operation failed:', error.message);
}

Browser Compatibility

The Brotli library supports both Node.js and browser environments:

Node.js: Full support for all features
Browser: Requires bundling with Browserify or similar tools
Dictionary loading: Automatically switches between Node.js and browser dictionary implementations
Memory management: Emscripten-compiled encoder handles memory allocation automatically

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/brotli@1.3.x
Publish Source: CLI
Badge