Structured Headers

Common errors

• ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/structured-headers/dist/index.js not supported. Consider one of the following options to enable ESM support:

  cause Attempting to import `structured-headers` using `require()` in a CommonJS module after upgrading to v2.0.0 or later.
  fix Update your import statements to use ES Modules syntax (`import { parseItem } from 'structured-headers';`). If in Node.js, ensure your package.json has `"type": "module"` or your file uses the `.mjs` extension.

• TypeError: Cannot read properties of undefined (reading 'buffer') when processing binary data.

  cause Attempting to use `ByteSequence` objects or an outdated binary data format as input for serialization, or expecting `ByteSequence` output from parsing after upgrading to v2.0.0.
  fix All binary data input for serialization and output from parsing is now `ArrayBuffer`. Ensure your code converts any `ByteSequence` instances to `ArrayBuffer` before passing them to serializer functions, and updates consumption of parsed binary data to handle `ArrayBuffer`.

Warnings

• breaking Since v2.0.0, the library has converted entirely to ES Modules (ESM). Attempts to `require()` the package in a CommonJS context will result in a module resolution error. Additionally, Node.js 18 or higher is now required.
  Fix: Refactor your project to use ES Modules (`import` statements, `"type": "module"` in `package.json` if in Node.js) and ensure your Node.js runtime is version 18 or newer.
• breaking In v2.0.0, the internal representation and API for binary data changed from a custom `ByteSequence` object to the standard `ArrayBuffer`. This affects how binary data is consumed and provided.
  Fix: Update your code to directly use `ArrayBuffer` instances when dealing with binary structured field values, both for parsing output and serializing input.
• gotcha Due to JavaScript's number type behavior, the library cannot differentiate between `1.0` and `1` during serialization. This means that if the specification strictly requires `1.0`, the library will output `1`, which is a known deviation from the official test suite.
  Fix: Be aware of this limitation in serialization output for numbers where trailing `.0` is significant. No direct workaround is available without custom number wrapping, which the library avoids for developer experience.
• gotcha JavaScript's default rounding behavior differs slightly from the Structured Headers specification, specifically for values like `0.0025`. JavaScript typically rounds to `0.003`, while the spec suggests rounding to the nearest even number (`0.002`).
  Fix: Acknowledge this minor discrepancy in floating-point serialization. The library plans to implement a custom rounding algorithm in the future to address this.
• gotcha The library prioritizes strict RFC compliance, returning the _exact_ data structures suggested by the specification. This can result in complex nested types (e.g., `[BareItem, Map<string, BareItem>]` for an Item) which might require careful destructuring or type handling.
  Fix: Familiarize yourself with the library's specific return types for `parseItem`, `parseList`, and `parseDictionary` to correctly destructure and access the parsed values and their parameters.

Install

• npm install structured-headers npm
• yarn add structured-headers yarn
• pnpm add structured-headers pnpm

Imports

• parseItem
  wrong:

  const parseItem = require('structured-headers');

  correct:

  import { parseItem } from 'structured-headers';

  The library converted to ESM in v2.0.0. CommonJS `require()` is not supported for modern versions.
• parseList
  wrong:

  const parseList = require('structured-headers');

  correct:

  import { parseList } from 'structured-headers';

  Use named imports for all parsing functions. Default imports are not provided.
• parseDictionary

  import { parseDictionary } from 'structured-headers';

  Similar to `parseItem` and `parseList`, `parseDictionary` is also a named export for parsing dictionary-type structured headers.

Quickstart

Demonstrates parsing various HTTP Structured Field Values: single items with parameters, lists including inner lists, and dictionaries with diverse member types.

import { parseItem, parseList, parseDictionary } from 'structured-headers';

// Parsing an 'Item' header
const itemHeader = '"Hello world"; a="5", @1686634251, :RE0gbWUgZm9yIGEgZnJlZSBjb29raWU=:';
console.log('Parsed Item:', parseItem('"Hello world"; a="5"'));
console.log('Parsed Date Item:', parseItem('@1686634251'));
console.log('Parsed Binary Item:', parseItem(':RE0gbWUgZm9yIGEgZnJlZSBjb29raWU=:'));

// Parsing a 'List' header
const listHeader = 'sometoken; param1; param2=hi, 42, (innerlistitem1 innerlistitem2)';
console.log('Parsed List:', JSON.stringify(parseList(listHeader), null, 2));

// Parsing a 'Dictionary' header
const dictHeader = 'fn="evert", ln="pot", coffee=?1, foo=(1 2 3)';
console.log('Parsed Dictionary:', JSON.stringify(Object.fromEntries(parseDictionary(dictHeader)), null, 2));