HTTP Content Encoding Handler

Common errors

• Error: The encoding 'brotli' cannot be handled synchronously.

  cause Attempting to use `decodeBufferSync` or `encodeBufferSync` with encodings like Brotli or Zstandard that require asynchronous processing.
  fix Replace calls to `decodeBufferSync` or `encodeBufferSync` with their asynchronous counterparts, `decodeBuffer` or `encodeBuffer` respectively.

• TypeError: http_encoding_1.decodeBuffer is not a function

  cause Incorrect module import syntax, typically occurring when attempting to `require()` a named ESM export as a default, or incorrectly destructuring CommonJS exports.
  fix Ensure you are using the correct ESM import syntax: `import { decodeBuffer } from 'http-encoding';`.

Warnings

• gotcha The `decodeBufferSync` method is less performant and has limited codec support, specifically excluding Brotli and Zstandard. It is generally not recommended for production use cases involving these encodings or high-performance scenarios.
  Fix: Always prefer the asynchronous `decodeBuffer` method for robust and performant decoding across all supported encodings.
• gotcha The library heavily leverages native `CompressionStream` and `DecompressionStream` APIs for its streaming functionality in Node.js 18+ and modern browsers. While it aims for broad compatibility, older Node.js versions or non-standard environments might exhibit limited functionality or require polyfills for these web-standard streams.
  Fix: Ensure your Node.js environment is at least v18.0.0 for optimal streaming performance and full compatibility with the web-standard `TransformStream` implementations.
• gotcha This package adopts an ESM-first development approach, especially given its Node.js >=v18.0.0 engine requirement. While CommonJS `require()` might offer partial interoperability, it is strongly advised to use ESM `import` statements for full type safety, consistent behavior, and future compatibility.
  Fix: Migrate to `import { ... } from 'http-encoding'` for all module imports to ensure proper integration and benefit from TypeScript typings.

Install

• npm install http-encoding npm
• yarn add http-encoding yarn
• pnpm add http-encoding pnpm

Imports

• decodeBuffer
  wrong:

  const { decodeBuffer } = require('http-encoding')

  correct:

  import { decodeBuffer } from 'http-encoding'

  The package is primarily ESM-first, aligning with Node.js >=v18.0.0. Prefer ESM imports for type safety and future compatibility.
• createEncodeStream
  wrong:

  import createEncodeStream from 'http-encoding'

  correct:

  import { createEncodeStream } from 'http-encoding'

  All main utilities, including streaming factory functions, are named exports, not default exports.
• gzip
  wrong:

  import * as encoding from 'http-encoding'; encoding.gzip(...)

  correct:

  import { gzip, brotliDecompress } from 'http-encoding'

  Specific codec methods (compress/decompress) are also provided as direct named exports for granular control.

Quickstart

This example demonstrates how to compress and decompress data using `http-encoding`'s buffer-based API for Gzip and its streaming API for Brotli. It covers encoding and decoding a string, verifying the output, and handling asynchronous stream operations in a Node.js environment.

import { decodeBuffer, encodeBuffer, createDecodeStream, createEncodeStream } from 'http-encoding';
import { Readable, Transform } from 'stream'; // For Node.js streaming example

async function handleContentEncoding() {
    const originalText = "Hello, world! This is a test of HTTP content encoding.";
    const originalBuffer = Buffer.from(originalText, 'utf-8');

    // --- Buffer API Example (Gzip) ---
    console.log("-- Buffer API (Gzip) --");
    const gzippedBuffer = await encodeBuffer(originalBuffer, 'gzip', { level: 9 });
    console.log(`Original size: ${originalBuffer.length} bytes, Gzipped size: ${gzippedBuffer.length} bytes`);

    const decodedGzipBuffer = await decodeBuffer(gzippedBuffer, 'gzip');
    console.log(`Decoded Gzip matches original: ${decodedGzipBuffer.toString('utf-8') === originalText}`);

    // --- Streaming API Example (Brotli in Node.js) ---
    console.log("\n-- Streaming API (Brotli) --");

    // createEncodeStream and createDecodeStream return web-standard TransformStream instances.
    // In Node.js, these are compatible with native streams but might need casting for TypeScript
    // if not specifically targeting 'dom' or 'webworker' lib types in tsconfig.
    const encoderStream = createEncodeStream('brotli');
    const decoderStream = createDecodeStream('brotli');

    if (!encoderStream || !decoderStream) {
        console.error("Brotli streaming not available or identity encoding used. Ensure Node.js >= 18.");
        return;
    }

    const inputReadable = Readable.from([originalBuffer]);
    let encodedChunks: Buffer[] = [];
    let decodedChunks: Buffer[] = [];

    // Pipe the original content through the encoder stream
    await new Promise<void>((resolve, reject) => {
        inputReadable
            .pipe(encoderStream as any) // Cast for Node.js Stream compatibility
            .on('data', (chunk) => encodedChunks.push(chunk))
            .on('end', resolve)
            .on('error', reject);
    });

    const encodedTotal = Buffer.concat(encodedChunks);
    console.log(`Original size: ${originalBuffer.length} bytes, Brotli encoded size: ${encodedTotal.length} bytes`);

    // Pipe the encoded content through the decoder stream
    await new Promise<void>((resolve, reject) => {
        Readable.from([encodedTotal])
            .pipe(decoderStream as any) // Cast for Node.js Stream compatibility
            .on('data', (chunk) => decodedChunks.push(chunk))
            .on('end', resolve)
            .on('error', reject);
    });

    const decodedTotal = Buffer.concat(decodedChunks);
    console.log(`Decoded Brotli matches original: ${decodedTotal.toString('utf-8') === originalText}`);
}

handleContentEncoding().catch(console.error);