{"id":16232,"library":"structured-headers","title":"Structured Headers","description":"structured-headers is a JavaScript/TypeScript library providing a robust parser and serializer for HTTP Structured Field Values (RFC9651 and RFC8941). This specification standardizes complex HTTP header values, including lists, dictionaries, numbers, booleans, binary data (ByteSequences), timestamps, and Unicode strings (Display Strings). The current stable version is 2.0.2. New major versions are typically released to align with updates to the underlying RFCs, such as v2.0.0 which added support for RFC9651's new `Date` and `Display String` types. Patches address bug fixes and dependency updates. Key differentiators include its TypeScript foundation, shipping both ESM and CommonJS builds (though ESM is primary since v2), zero runtime dependencies, and an extensive test suite comprising 2805 unit tests largely sourced from the official HTTP Working Group. The library prioritizes strict RFC compliance, returning data structures that precisely mirror the specification, which can sometimes result in more complex types than developers might initially expect.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/evert/structured-header","tags":["javascript","http","structured-header","structured-fields","structured fields","RFC9651","RFC8941","headers"],"install":[{"cmd":"npm install structured-headers","lang":"bash","label":"npm"},{"cmd":"yarn add structured-headers","lang":"bash","label":"yarn"},{"cmd":"pnpm add structured-headers","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library converted to ESM in v2.0.0. CommonJS `require()` is not supported for modern versions.","wrong":"const parseItem = require('structured-headers');","symbol":"parseItem","correct":"import { parseItem } from 'structured-headers';"},{"note":"Use named imports for all parsing functions. Default imports are not provided.","wrong":"const parseList = require('structured-headers');","symbol":"parseList","correct":"import { parseList } from 'structured-headers';"},{"note":"Similar to `parseItem` and `parseList`, `parseDictionary` is also a named export for parsing dictionary-type structured headers.","symbol":"parseDictionary","correct":"import { parseDictionary } from 'structured-headers';"}],"quickstart":{"code":"import { parseItem, parseList, parseDictionary } from 'structured-headers';\n\n// Parsing an 'Item' header\nconst itemHeader = '\"Hello world\"; a=\"5\", @1686634251, :RE0gbWUgZm9yIGEgZnJlZSBjb29raWU=:';\nconsole.log('Parsed Item:', parseItem('\"Hello world\"; a=\"5\"'));\nconsole.log('Parsed Date Item:', parseItem('@1686634251'));\nconsole.log('Parsed Binary Item:', parseItem(':RE0gbWUgZm9yIGEgZnJlZSBjb29raWU=:'));\n\n// Parsing a 'List' header\nconst listHeader = 'sometoken; param1; param2=hi, 42, (innerlistitem1 innerlistitem2)';\nconsole.log('Parsed List:', JSON.stringify(parseList(listHeader), null, 2));\n\n// Parsing a 'Dictionary' header\nconst dictHeader = 'fn=\"evert\", ln=\"pot\", coffee=?1, foo=(1 2 3)';\nconsole.log('Parsed Dictionary:', JSON.stringify(Object.fromEntries(parseDictionary(dictHeader)), null, 2));\n","lang":"typescript","description":"Demonstrates parsing various HTTP Structured Field Values: single items with parameters, lists including inner lists, and dictionaries with diverse member types."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your code to directly use `ArrayBuffer` instances when dealing with binary structured field values, both for parsing output and serializing input.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"fix":"Acknowledge this minor discrepancy in floating-point serialization. The library plans to implement a custom rounding algorithm in the future to address this.","message":"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`).","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `structured-headers` using `require()` in a CommonJS module after upgrading to v2.0.0 or later.","error":"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:"},{"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`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'buffer') when processing binary data."}],"ecosystem":"npm"}