HTTP Prefer Header Parser

Common errors

• TypeError: parsePreferHeader is not a function

  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.
  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.

• ReferenceError: require is not defined

  cause Using `require('parse-prefer-header')` in an ECMAScript Module (ESM) context in Node.js without specific configuration, or in a browser environment.
  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);`.

• TypeError: Cannot read properties of undefined (reading 'foo')

  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.
  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) { ... }`.

Warnings

• gotcha 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`).
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install parse-prefer-header npm
• yarn add parse-prefer-header yarn
• pnpm add parse-prefer-header pnpm

Imports

• parsePreferHeader
  wrong:

  import parsePreferHeader from 'parse-prefer-header';

  correct:

  const parsePreferHeader = require('parse-prefer-header');

  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.
• parsePreferHeader
  wrong:

  import { parsePreferHeader } from 'parse-prefer-header';

  correct:

  import parsePreferHeader from 'parse-prefer-header';

  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.

Quickstart

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.

import parsePreferHeader from 'parse-prefer-header';

// Example 1: Basic preferences
let preferences = parsePreferHeader('respond-async, wait=300');
console.log('Example 1:', preferences);
// Expected: { respondAsync: true, wait: '300' }

// Example 2: Preferences with quoted values and parameters
preferences = parsePreferHeader('foo="key=value;other", bar;baz=123');
console.log('Example 2:', preferences);
// Expected: { foo: 'key=value;other', bar: true, baz: '123' }

// Example 3: Handling an array of header values (RFC allows multiple Prefer headers)
const multipleHeaders = [
  'respond-async, wait=500',
  'handling=lenient;max-age=3600'
];
preferences = parsePreferHeader(multipleHeaders);
console.log('Example 3:', preferences);
// Expected: { respondAsync: true, wait: '500', handling: 'lenient', 'max-age': '3600' }

// Example 4: Empty or invalid input
preferences = parsePreferHeader('');
console.log('Example 4 (empty):', preferences);
// Expected: {}
preferences = parsePreferHeader(null);
console.log('Example 4 (null):', preferences);
// Expected: {} (or throws, depending on internal implementation for null/undefined - testing shows it handles it gracefully)