{"id":17877,"library":"popsicle-content-encoding","title":"Popsicle Content Encoding Middleware","description":"This package, `popsicle-content-encoding`, provides a specialized middleware for the `Popsicle` HTTP client library, designed to transparently manage HTTP `Content-Encoding` compression and decompression. Currently at its initial stable release, version `1.0.0`, it emerged from the core `popsicle` project to offer a modular solution for handling content negotiation. The middleware automatically detects and adds appropriate `Accept-Encoding` headers to outgoing requests based on the Node.js runtime's supported compression algorithms (e.g., gzip, deflate, brotli). Upon receiving a response, it automatically decodes the body if a matching `Content-Encoding` header is present, simplifying client-side data handling. A key differentiator is its seamless integration within the `servie` and `popsicle` middleware composition pattern, abstracting away the complexities of manual compression negotiation and decompression. It operates passively if `Accept-Encoding` is already defined, allowing for manual override when necessary. Its release cadence is currently tied to user feedback and the broader `serviejs` ecosystem, with `1.0.0` marking its first standalone stable version.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/serviejs/popsicle-content-encoding","tags":["javascript","popsicle","encoding","compression","zip","brotli","gzip","typescript"],"install":[{"cmd":"npm install popsicle-content-encoding","lang":"bash","label":"npm"},{"cmd":"yarn add popsicle-content-encoding","lang":"bash","label":"yarn"},{"cmd":"pnpm add popsicle-content-encoding","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for middleware composition and core HTTP utilities, defining the `Middleware` type.","package":"servie","optional":false}],"imports":[{"note":"The primary factory function for the middleware is a named export. While ESM is preferred, CommonJS users should destructure the export.","wrong":"const { contentEncoding } = require('popsicle-content-encoding');","symbol":"contentEncoding","correct":"import { contentEncoding } from 'popsicle-content-encoding';"},{"note":"The TypeScript interface for configuring the `contentEncoding` middleware, allowing control over supported compression types (gzip, brotli, deflate).","symbol":"Options","correct":"import type { Options } from 'popsicle-content-encoding';"},{"note":"The `contentEncoding` function returns a `Middleware` instance, whose type is defined by the `servie` peer dependency, not `popsicle-content-encoding` itself.","wrong":"import type { Middleware } from 'popsicle-content-encoding';","symbol":"Middleware","correct":"import type { Middleware } from 'servie';"}],"quickstart":{"code":"import { compose } from 'servie';\nimport popsicle from 'popsicle'; // popsicle is typically a default export\nimport { transport } from 'servie-http'; // Common transport for servie/popsicle\nimport { contentEncoding, Options } from 'popsicle-content-encoding'; // Import Options\n\nasync function fetchDataWithCompression() {\n  const API_URL = 'https://jsonplaceholder.typicode.com/posts/1'; // A public API for demonstration\n\n  // Configure contentEncoding middleware with specific options\n  // For example, to explicitly enable gzip and brotli, or disable certain types.\n  const encodingOptions: Options = {\n    gzip: true,\n    brotli: true,\n    deflate: false, // Explicitly disable deflate for this request\n  };\n\n  // Compose the middleware pipeline: contentEncoding first to handle headers, then transport\n  const requestMiddleware = compose([\n    contentEncoding(encodingOptions), // Pass the configuration options\n    transport()\n  ]);\n\n  const request = popsicle(API_URL, {\n    method: 'GET',\n    middleware: requestMiddleware, // Apply the composed middleware\n  });\n\n  try {\n    const response = await request.send();\n    console.log(`Status: ${response.status}`);\n    const contentEncodingHeader = response.headers.get('Content-Encoding');\n    console.log(`Content-Encoding Header (from response): ${contentEncodingHeader || 'N/A'}`);\n    console.log(`Response URL: ${response.url}`);\n\n    const data = await response.json(); // Body is automatically decoded by the middleware\n    console.log('Decoded data snippet (first 100 chars):', JSON.stringify(data).substring(0, 100) + '...');\n\n    if (typeof data === 'object' && data !== null) {\n      console.log('Successfully decoded JSON response and processed.');\n    } else {\n      console.warn('Response body might not be JSON or was not correctly decoded by the middleware.');\n    }\n  } catch (error: any) {\n    console.error('Error fetching data:', error.message);\n  }\n}\n\nfetchDataWithCompression();","lang":"typescript","description":"This quickstart demonstrates how to integrate `popsicle-content-encoding` into a Popsicle request pipeline, showing how to configure its `Options` to control `Content-Encoding` negotiation and decompression for HTTP requests."},"warnings":[{"fix":"Install `popsicle-content-encoding` via `npm install popsicle-content-encoding` and add `contentEncoding()` to your Popsicle middleware chain (e.g., `compose([contentEncoding(), transport()])`).","message":"The `popsicle-content-encoding` functionality, previously integrated directly into `popsicle` core, has been extracted into this standalone package. Applications upgrading from older `popsicle` versions that relied on implicit content encoding will need to explicitly install and include this middleware in their request pipelines.","severity":"breaking","affected_versions":"<1.0.0 (of this package)"},{"fix":"Ensure `servie` is installed alongside this package: `npm install servie@^4.0.0` or `yarn add servie@^4.0.0`.","message":"This package has a peer dependency on `servie` (version `^4.0.0`), which is not automatically installed by npm or yarn. Failure to install `servie` will result in runtime errors due to missing modules or type definitions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If automatic `Accept-Encoding` population is desired, ensure the header is not manually set *before* the `contentEncoding` middleware runs. To override the automatic behavior, explicitly set `Accept-Encoding` in your request headers.","message":"The `contentEncoding` middleware will not modify the `Accept-Encoding` header or perform decoding if an `Accept-Encoding` header is already present in the request. This behavior allows for manual control but can be a source of confusion if automatic handling is expected.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Install `servie` using your package manager: `npm install servie@^4.0.0` or `yarn add servie@^4.0.0`.","cause":"The required peer dependency `servie` is not installed in the project.","error":"Error: Cannot find module 'servie'"},{"fix":"Ensure you are using `const { contentEncoding } = require('popsicle-content-encoding');` for CommonJS. For ESM, use `import { contentEncoding } from 'popsicle-content-encoding';`.","cause":"Attempting to `require` a named export from `popsicle-content-encoding` in a CommonJS context without proper destructuring, or when the module itself might not be correctly interpreted as CommonJS.","error":"TypeError: Cannot destructure property 'contentEncoding' of 'undefined' or 'null'."},{"fix":"Ensure `servie-http` (or another `servie`-compatible transport) is installed and included at the end of your middleware `compose` array, e.g., `compose([contentEncoding(), transport()])`.","cause":"The `popsicle` request object does not have a `.send()` method because the necessary transport middleware (e.g., `servie-http`) was not included or correctly composed in the middleware chain.","error":"TypeError: request.send is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}