{"id":16062,"library":"http-encoding","title":"HTTP Content Encoding Handler","description":"The `http-encoding` package provides a robust and consistent API for handling HTTP message body `Content-Encoding` headers. It supports a comprehensive set of common encodings, including Gzip, raw Deflate (with or without zlib wrappers), Brotli, Zstandard (Zstd), and Base64. The library is compatible with Node.js environments (specifically `>=v18.0.0`) and modern browsers, offering both promise-based buffer APIs (`decodeBuffer`, `encodeBuffer`) and web-standard `TransformStream` streaming APIs (`createDecodeStream`, `createEncodeStream`). It intelligently leverages native `CompressionStream` and `DecompressionStream` APIs for performance where available. All encoding names are handled case-insensitively, and various no-op encodings like 'identity' are explicitly supported. Currently at version 2.2.0, it is actively maintained as part of the broader HTTP Toolkit ecosystem. Its primary differentiator is its unified API for multiple complex encoding schemes, making it ideal for tasks involving HTTP proxying, inspection, or manipulation.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/httptoolkit/http-encoding","tags":["javascript","http","encoding","content-encoding","encoder","decoder","brotli","zstandard","zstd","typescript"],"install":[{"cmd":"npm install http-encoding","lang":"bash","label":"npm"},{"cmd":"yarn add http-encoding","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-encoding","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is primarily ESM-first, aligning with Node.js >=v18.0.0. Prefer ESM imports for type safety and future compatibility.","wrong":"const { decodeBuffer } = require('http-encoding')","symbol":"decodeBuffer","correct":"import { decodeBuffer } from 'http-encoding'"},{"note":"All main utilities, including streaming factory functions, are named exports, not default exports.","wrong":"import createEncodeStream from 'http-encoding'","symbol":"createEncodeStream","correct":"import { createEncodeStream } from 'http-encoding'"},{"note":"Specific codec methods (compress/decompress) are also provided as direct named exports for granular control.","wrong":"import * as encoding from 'http-encoding'; encoding.gzip(...)","symbol":"gzip","correct":"import { gzip, brotliDecompress } from 'http-encoding'"}],"quickstart":{"code":"import { decodeBuffer, encodeBuffer, createDecodeStream, createEncodeStream } from 'http-encoding';\nimport { Readable, Transform } from 'stream'; // For Node.js streaming example\n\nasync function handleContentEncoding() {\n    const originalText = \"Hello, world! This is a test of HTTP content encoding.\";\n    const originalBuffer = Buffer.from(originalText, 'utf-8');\n\n    // --- Buffer API Example (Gzip) ---\n    console.log(\"-- Buffer API (Gzip) --\");\n    const gzippedBuffer = await encodeBuffer(originalBuffer, 'gzip', { level: 9 });\n    console.log(`Original size: ${originalBuffer.length} bytes, Gzipped size: ${gzippedBuffer.length} bytes`);\n\n    const decodedGzipBuffer = await decodeBuffer(gzippedBuffer, 'gzip');\n    console.log(`Decoded Gzip matches original: ${decodedGzipBuffer.toString('utf-8') === originalText}`);\n\n    // --- Streaming API Example (Brotli in Node.js) ---\n    console.log(\"\\n-- Streaming API (Brotli) --\");\n\n    // createEncodeStream and createDecodeStream return web-standard TransformStream instances.\n    // In Node.js, these are compatible with native streams but might need casting for TypeScript\n    // if not specifically targeting 'dom' or 'webworker' lib types in tsconfig.\n    const encoderStream = createEncodeStream('brotli');\n    const decoderStream = createDecodeStream('brotli');\n\n    if (!encoderStream || !decoderStream) {\n        console.error(\"Brotli streaming not available or identity encoding used. Ensure Node.js >= 18.\");\n        return;\n    }\n\n    const inputReadable = Readable.from([originalBuffer]);\n    let encodedChunks: Buffer[] = [];\n    let decodedChunks: Buffer[] = [];\n\n    // Pipe the original content through the encoder stream\n    await new Promise<void>((resolve, reject) => {\n        inputReadable\n            .pipe(encoderStream as any) // Cast for Node.js Stream compatibility\n            .on('data', (chunk) => encodedChunks.push(chunk))\n            .on('end', resolve)\n            .on('error', reject);\n    });\n\n    const encodedTotal = Buffer.concat(encodedChunks);\n    console.log(`Original size: ${originalBuffer.length} bytes, Brotli encoded size: ${encodedTotal.length} bytes`);\n\n    // Pipe the encoded content through the decoder stream\n    await new Promise<void>((resolve, reject) => {\n        Readable.from([encodedTotal])\n            .pipe(decoderStream as any) // Cast for Node.js Stream compatibility\n            .on('data', (chunk) => decodedChunks.push(chunk))\n            .on('end', resolve)\n            .on('error', reject);\n    });\n\n    const decodedTotal = Buffer.concat(decodedChunks);\n    console.log(`Decoded Brotli matches original: ${decodedTotal.toString('utf-8') === originalText}`);\n}\n\nhandleContentEncoding().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Always prefer the asynchronous `decodeBuffer` method for robust and performant decoding across all supported encodings.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<18.0.0"},{"fix":"Migrate to `import { ... } from 'http-encoding'` for all module imports to ensure proper integration and benefit from TypeScript typings.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Replace calls to `decodeBufferSync` or `encodeBufferSync` with their asynchronous counterparts, `decodeBuffer` or `encodeBuffer` respectively.","cause":"Attempting to use `decodeBufferSync` or `encodeBufferSync` with encodings like Brotli or Zstandard that require asynchronous processing.","error":"Error: The encoding 'brotli' cannot be handled synchronously."},{"fix":"Ensure you are using the correct ESM import syntax: `import { decodeBuffer } from 'http-encoding';`.","cause":"Incorrect module import syntax, typically occurring when attempting to `require()` a named ESM export as a default, or incorrectly destructuring CommonJS exports.","error":"TypeError: http_encoding_1.decodeBuffer is not a function"}],"ecosystem":"npm"}