This specification defines a standard serialization for complex HTTP header
values, including lists (arrays), dictionaries (maps) and also numbers,
booleans, binary data, timestamps and Unicode strings.
The library is written in Typescript, and the examples in this document are
too, but plain Javascript is also fully supported. It ships with ESM and
CommonJS builds and has 0 dependencies.
Compatibility
This package has 2805 unittests, the vast majority are supplied from the
official HTTP WG test suite.
However, there are 2 differences in the serializer:
Javascript can't differentiate between 1.0 and 1. As a result we're
skipping the tests that require a serialiation output of 1.0.
Javascript rounds slightly different from the spec. The tests suggest that
0.0025 should round to the nearest event number (0.002), but Javascript
rounds to 0.003.
No fix is planned for #1, because there's no reasonably way to fix this
without wrapping every number in a custom class, and this will negatively
impact the developer experience. We do intend to fix #2 in the future with a
custom rounding algorithm.
This library emits and expects the exact data structures as they are
suggested by the RFC. The result of this is that the returned types can be
a bit complex.
In the future we intend to loosen the required types for the serializer, and
add new helper functions that give you simpler structures if you don't need
certain features for a header (such as Parameters).
Let us know what you would like to see here!
Installation
Using npm:
npm install structured-headers
API
Parsing an item
The following are examples of item headers:
Parsed as string
# Parsed an ASCII stringHeader: "foo"# A simple string, called a 'Token' in the specHeader: foo# A Unicode string, called a 'Display String' in the spec. They use# percent encoding, but encode a different set of characters than# URLs.Header %"Frysl%C3%A2n"# Parsed as numberHeader: 5Header: -10Header: 5.01415# Parsed into booleanHeader: ?1Header: ?0# Binaries are base64 encodedHeader: :RE0gbWUgZm9yIGEgZnJlZSBjb29raWU=:# Items can have parametersHeader: "Hello world"; a="5"# Parsed into a Date objectHeader: @1686634251
To parse these header values, use the parseItem:
import { parseItem } from 'structured-headers';console.log( parseItem(header));
parseItem returns a tuple (array with 2 items), the first item is the value,
the second is a Map object with parameters.
The type is roughly:
// The raw value. A Byte Sequence is parsed as an ArrayBuffer, and may be// serialized from any BufferSource (an ArrayBuffer, a Uint8Array, a Node// Buffer or a DataView).type BareItem = number | string | Token | BufferSource | boolean | Date | DisplayString;// The return type of parseItemtype Item = [ BareItem, Map<string, BareItem>];
Parsing a list
A list is an array of items. Some examples:
# A simple listHeader: 5, "foo", bar, ?1# Each element can have parametersHeader: sometoken; param1; param2=hi, 42# A list can also contain lists itself. These are called 'inner lists' and# use parenthesisHeader: sometoken, (innerlistitem1 innerlistitem2), (anotherlist)
To parse these:
import { parseList } from 'structured-headers';console.log( parseList(header));
parseList returns an array with each member. The return type is:
type InnerList = [Item[], Parameters];type List = (InnerList|Item)[];
Parsing a dictionary
A dictionary is a key->value object. Examples:
# A simple dictionaryHeader: fn="evert", ln="pot", coffee=?1# Each item may have parameters tooHeader: foo=123; q=1, bar=123, q=0.5# A dictionary value may be an inner list againHeader: foo=(1 2 3)
To parse dictionaries:
import { parseDictionary } from 'structured-headers';console.log( parseDictionary(header));
The return type for parseDictionary is a Map.
type Dictionary = Map<string, Item|InnerList>;
Serializing
The serialiser functions work the exact same way, but in opposite direction.
They all return strings.
Currently the serializes expect the exact type that the parsers return, but
the intention is to loosen the types for serialization, so it's a bit more
ergnomic to call. Want this? Let me know by opening an issue.
import { serializeDictionary, serializeList, serializeItem} from 'structured-headers';// Returns "foo", "bar"serializeList([ ['foo', new Map()], ['bar', new Map()],]);// Returns a=1, b=?0sh.serializeDictionary({ a: 1, b: false,});// Returns 42serializeItem(42);48,65,6C,6C,6F,2C,20,57,6F,72
Browser support
There is a minified version of this library in the browser/ directory. This minified
file will expose a global variable called 'structuredHeader' which contains the rest
of the api.
,6C,
64
,
21.
72, 101, 108, 108,
111, 32, 119, 111,
114, 108, 100
// Returns 5.5
serializeItem(5.5);
// Returns "hello world"
serializeItem("hello world");
// Returns %"Frysl%C3%A2n"
serializeItem("Fryslân");
// Returns ?1
serializeItem(true);
// Returns a base-64 representation like: *aGVsbG8=*