{"id":16480,"library":"parse-prefer-header","title":"HTTP Prefer Header Parser","description":"The `parse-prefer-header` library provides a lightweight utility for parsing the HTTP `Prefer` header, as defined in RFC7240. Currently at version 1.0.0, this package focuses on accurately transforming the header's comma-separated tokens and their optional parameters into a user-friendly JavaScript object. It handles various intricacies like token normalization (e.g., `respond-async` to `respondAsync`) and correctly interprets quoted values. Its core functionality is to map preference tokens to either `true` (for preferences without explicit values) or their parsed string value. Given its stable 1.0.0 version and specific parsing scope, its release cadence is effectively stable with no new major versions anticipated for such a focused utility. Key differentiators include its strict adherence to RFC7240 and its minimal API surface for a common, yet often complex, HTTP header.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/ppaskaris/node-parse-prefer-header","tags":["javascript","prefer","rfc7240","7240"],"install":[{"cmd":"npm install parse-prefer-header","lang":"bash","label":"npm"},{"cmd":"yarn add parse-prefer-header","lang":"bash","label":"yarn"},{"cmd":"pnpm add parse-prefer-header","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package (v1.0.0, published 2016) is CommonJS-only. Direct ESM imports will fail unless transpiled or using Node.js's CJS interop for default exports. For Node.js ESM, `import parsePreferHeader from 'parse-prefer-header';` would typically work due to interop, but `require` is the canonical CJS usage.","wrong":"import parsePreferHeader from 'parse-prefer-header';","symbol":"parsePreferHeader","correct":"const parsePreferHeader = require('parse-prefer-header');"},{"note":"While Node.js ESM interop allows `import parsePreferHeader from 'parse-prefer-header';` for a CJS default export, a named import like `import { parsePreferHeader } from 'parse-prefer-header';` will result in `undefined` for `parsePreferHeader` as the package does not export it by name.","wrong":"import { parsePreferHeader } from 'parse-prefer-header';","symbol":"parsePreferHeader","correct":"import parsePreferHeader from 'parse-prefer-header';"}],"quickstart":{"code":"import parsePreferHeader from 'parse-prefer-header';\n\n// Example 1: Basic preferences\nlet preferences = parsePreferHeader('respond-async, wait=300');\nconsole.log('Example 1:', preferences);\n// Expected: { respondAsync: true, wait: '300' }\n\n// Example 2: Preferences with quoted values and parameters\npreferences = parsePreferHeader('foo=\"key=value;other\", bar;baz=123');\nconsole.log('Example 2:', preferences);\n// Expected: { foo: 'key=value;other', bar: true, baz: '123' }\n\n// Example 3: Handling an array of header values (RFC allows multiple Prefer headers)\nconst multipleHeaders = [\n  'respond-async, wait=500',\n  'handling=lenient;max-age=3600'\n];\npreferences = parsePreferHeader(multipleHeaders);\nconsole.log('Example 3:', preferences);\n// Expected: { respondAsync: true, wait: '500', handling: 'lenient', 'max-age': '3600' }\n\n// Example 4: Empty or invalid input\npreferences = parsePreferHeader('');\nconsole.log('Example 4 (empty):', preferences);\n// Expected: {}\npreferences = parsePreferHeader(null);\nconsole.log('Example 4 (null):', preferences);\n// Expected: {} (or throws, depending on internal implementation for null/undefined - testing shows it handles it gracefully)\n","lang":"typescript","description":"This quickstart demonstrates parsing various HTTP Prefer header string formats, including single strings, arrays, values with parameters, and quoted values, and shows how the output is structured as a JavaScript object."},"warnings":[{"fix":"For CommonJS, use `const parsePreferHeader = require('parse-prefer-header');`. For ESM, ensure your build setup correctly handles CJS module interoperability, or consider a tool like Rollup/Webpack to bundle. In Node.js ESM, `import parsePreferHeader from 'parse-prefer-header';` generally works for CJS default exports.","message":"The package is CommonJS-only (published 2016, v1.0.0). Attempting to use `import` syntax directly in pure ESM environments without proper Node.js CJS interop or a bundler might lead to import errors or unexpected behavior (e.g., `require is not defined`).","severity":"gotcha","affected_versions":"1.0.0"},{"fix":"Always access preferences using their camelCase equivalent. For example, `parsed.respondAsync` instead of `parsed['respond-async']`. If a preference has parameters, the parameters themselves are treated as properties of the main preference object.","message":"This library normalizes preference tokens into camelCase JavaScript properties (e.g., `respond-async` becomes `respondAsync`, `max-age` becomes `maxAge`). Be aware of this transformation when accessing properties on the parsed object.","severity":"gotcha","affected_versions":"1.0.0"},{"fix":"If your environment provides `Prefer` headers as an array (e.g., from `req.headers['prefer']` which often consolidates multiple identical headers into an array), pass the array directly. Otherwise, pass the single header string.","message":"The RFC7240 Prefer header allows for multiple `Prefer` headers or a single header with comma-separated values, which are equivalent. This library accepts either a single string or an array of strings. Ensure you pass your headers correctly to avoid parsing issues.","severity":"gotcha","affected_versions":"1.0.0"},{"fix":"No direct fix, but users should be aware of the package's age. For critical applications, consider vendoring the code or evaluating if a more actively maintained HTTP header parsing utility could be adapted.","message":"This package has not been updated since 2016. While its functionality is simple and specific, relying on a package with no recent maintenance might pose risks for future JavaScript ecosystem changes or if RFC7240 were ever updated.","severity":"gotcha","affected_versions":"1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const parsePreferHeader = require('parse-prefer-header');`. For ESM in Node.js, use `import parsePreferHeader from 'parse-prefer-header';` which leverages Node's CJS default export interop. Do not use named imports from this package.","cause":"Attempting to use `parsePreferHeader` as a named import (e.g., `import { parsePreferHeader } from 'parse-prefer-header';`) when the CommonJS package exports it as a default.","error":"TypeError: parsePreferHeader is not a function"},{"fix":"If in a Node.js ESM file, use `import parsePreferHeader from 'parse-prefer-header';`. If in a browser, ensure your bundler correctly handles CommonJS modules. If you need a direct CJS `require` in Node.js ESM, you can explicitly create a `require` function using `import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);`.","cause":"Using `require('parse-prefer-header')` in an ECMAScript Module (ESM) context in Node.js without specific configuration, or in a browser environment.","error":"ReferenceError: require is not defined"},{"fix":"Verify that `parsePreferHeader` is correctly imported and is indeed a function. Check the input string for valid RFC7240 syntax. Always check for the existence of properties on the returned object before accessing them, e.g., `if (preferences.respondAsync) { ... }`.","cause":"This typically happens if the `parsePreferHeader` function was not imported correctly, resulting in `parsePreferHeader` being `undefined`, or if the input to the function was malformed, causing an empty object to be returned, and you're trying to access a non-existent property.","error":"TypeError: Cannot read properties of undefined (reading 'foo')"}],"ecosystem":"npm"}