Read and write binary formats in TypeScript, with the types checking how the fields fit together.
npm install binopsy
Describe a format field by field: binopsy infers the values it reads and writes, and compiles each codec to JavaScript specialized to its format.
import { array, bin, string, u16le, u8 } from "binopsy";const Player = bin() .u32le("id") .field("name", string(u8)) // A length byte, then the string .u8("count") .field("ratings", array(u16le, "count"));const player
Numbers are named by type, size in bits and byte order: u8 is an unsigned 8-bit integer (one byte), u16le an unsigned 16-bit integer stored little-endian, i32be a signed 32-bit integer stored big-endian, and f64le a 64-bit float. .u8("count") adds a u8 field named count.
Lengths, counts and tags name fields before them, and TypeScript checks the names where they are written:
// Error: there is no field `cuont`bin().u8("count").field("ratings", array(u16le, "cuont"));// Error: `name` is not a numberbin().field("name", string(u8)).field("ratings", array(u16le, "name"));
Why binopsy
Formats as they are. Fields depend on earlier ones: a count sizes an array, a tag selects a message (and narrows its type), a version or a flag adds fields. Bit fields, 24-bit integers, padding and alignment cover the layouts of C structs and devices.
One definition for every use. A parser decodes, encodes (writing length prefixes, and fields such as checksums that you compute from the others), measures values, decodes streams whose values span chunks, and decodes only the fields you pick (and those they depend on).
Fast. In a benchmark against eight libraries, binopsy had the highest throughput decoding and encoding each of seven formats, at 1.5 to 12 times that of the next fastest library supporting the format. Compiling costs a millisecond or two for each codec, the first time it is used.
Errors that point at the byte. A decoding error names the field that failed, with its path and byte offset; trace maps every field to its bytes.
binopsy is an ES module without dependencies, with TypeScript types. It works on Uint8Arrays (Node.js Buffers are ones), in Node.js, Deno and browsers.
literal(codec, value) is a fixed value: decoding fails on any other, and encoding writes it, so it may be omitted. Values are numbers, strings, bigints or booleans that the codec stores exactly (not 0.1 in an f32le).
64-bit integers (u64be, i64le, …) are bigints. Each number codec has a parser method: .u32be("length") is .field("length", u32be).
A length is a number, the name of an earlier field (bytes("length")), a function of the earlier fields, or a codec of a count read just before the value (string(u8)). See lengths.
array(item, { until }) reads up to the first item for which until is true, and includes it.
bytes values view the input: new Uint8Array(bytes) copies one. From a Buffer they are Buffers, except in streams, where a value across chunks views a copy of them.
.skip(n) steps over n reserved bytes, and .align(n) over those up to a multiple of n bytes from the start of the parser: a RIFF chunk, bin().field("id", string(4)).u32le("size").field("data", bytes("size")).align(2), takes an even number of bytes. Encoding writes zeros.
decode(bytes, offset) decodes a value at an offset, such as an index whose offset the header gives. Bytes after the value are ignored.
Optional and versioned parts
Later versions of a format add fields, and some fields are only there if a flag says so:
import { bin, literal, optional, string, u32le, u8, when } from "binopsy";const Header = bin() .field("magic", literal(string(4), "DATA")) .u8("version") .u32le("count") .field( "checksum", // Since version 2 when((header) => header.version >= 2, u32le), ) .field("comment", optional(u8, string(u8))); // A flag byte; if not 0, a length byte and the text// { magic: "DATA"; version: number; count: number; checksum: number | null; comment: string | null }
Absent values are null. When encoding, a value must be null exactly when it is absent: { version: 1, checksum: 5, … } throws an EncodeError.
when(condition, codec) reads the value if condition holds: the name of an earlier field that is truthy, or a function of the earlier fields that returns true.
optional(flag, codec) reads a flag with the codec flag, then the value if the flag is not zero. Encoding writes 0 or 1.
Parts laid out differently in each version are a match on the version. fail(message) is a part you do not support: match("compression").case(0, bytes(u32le)).case(1, fail("compressed data is not supported")).
Messages with a type tag
Each message of a protocol starts with its type, and the type decides what follows:
match(tag) picks a codec by the value of the earlier field tag. .merge adds the fields of the case's parser to the message.
.field(name, match(…)) puts the case's value in a field instead: bin().u8("type").field("value", match("type").case(1, i32le).case(2, string(u32le))) decodes { type: 1; value: number } | { type: 2; value: string }.
A tag without a case fails, with a DecodeError of code "no-match". .otherwise(codec) takes all other values. Its tag keeps its whole type (TypeScript has no "a number but 1 or 2"), so comparing the tag does not rule it out: tell it apart by a field of the cases, as in "name" in message.
Case values are numbers, strings, bigints or booleans (1 and "1" are different), each with one case.
The tag may be computed from the earlier fields, with their type annotated: match((o: { kind: number }) => o.kind & 0xf).
A match is a codec: define it once, and use it in several parsers.
Bit-packed fields
Fields smaller than a byte, such as versions and flags, share bytes. An IPv4 header:
.field(name, bits(width)) adds a number of 1 to 53 bits. Bit fields that follow each other share their bytes; other fields start at the next byte. A run of bit fields is padded to whole bytes, with zeros when encoding.
The first bit field takes the most significant bits of its byte, as in network protocols. bin({ bitOrder: "lsb" }) starts with the least significant ones.
map(codec, { decode, encode }) converts values both ways. Without encode, it only decodes.
Enums and named values
enumOf gives raw values names, or checks membership in a TypeScript enum or a const object. Inline tables keep their literal types:
import { bits, enumOf, string, u8 } from "binopsy";enumOf(bits(2), ["low", "normal", "high", "reserved"]); // All four values namedenumOf(bits(2), ["low", "normal", "high"], enumOf.reject); // Raw 3 failsenumOf(bits(2), ["low", "normal", "high"], "high"); // Raw 3 becomes "high"enumOf(bits(1), [false, true]); // booleanenumOf(u8, { 1: "data", 2: "ack", 0x3f: "error" }, enumOf.keep);// "data" | "ack" | "error" | numberenum Kind { Unknown = 0, Data = 1, Ack = 2,}enumOf(u8, Kind, enumOf.reject); // Kind, with membership checkedenumOf(u8, Kind, Kind.Unknown); // Unknown raw values become Kind.Unknownconst Tag = { Data: "DATA", Ack: "ACK!" } as const;enumOf(string(4), Tag, enumOf.keep); // "DATA" | "ACK!" | string
The third argument is required unless every raw value is named. TypeScript proves coverage only for domains of at most 32 values: bits(1) through bits(5). A tuple filling the domain, a numeric-key object with every key, or a TypeScript enum or const object whose member values cover the domain can omit the policy. For example, enumOf(bits(1), { No: 0, Yes: 1 }) and enumOf(bits(1), { 0: "off", 1: "on" }) are complete, as is a 32-value enum covering 0–31 for bits(5). bits(6) and wider codecs, u8, i8, strings, and tables with dynamic types need an explicit policy in TypeScript. enumOf.reject fails on unknown raw values, enumOf.keep keeps them, and a declared name or member is a fallback. A fallback is lossy: decoding an unknown byte as Kind.Unknown and encoding it again writes 0.
Enums of bit fields share bytes with adjacent bit fields. Their decoded names can select a match:
Numeric enum members work as case values too: match("kind").case(Kind.Data, …). keep leaves an open raw-value arm; with a numeric enum, that arm can overlap a named numeric case, so an otherwise branch cannot be narrowed away by that tag alone.
Decode a stream
Messages arrive from a socket, or records from a file, in chunks that do not line up with them. decodeStream decodes the values as the chunks arrive. With the Message above, and a size before each:
import { connect } from "node:net";import { decodeStream, sized, u16be } from "binopsy";const Frame = sized(u16be, Message); // A 16-bit size, then the messageconst socket = connect(9000, "localhost");for await (const message of decodeStream(Frame, socket)) { handle(message);}
The source is any iterable or async iterable of Uint8Arrays: a Node.js stream (a socket, fs.createReadStream), a web ReadableStream (such as response.body), or an array of chunks.
Values may span any number of chunks: decoding continues as more input arrives, without starting over. If the input ends inside a value, the loop throws a DecodeError of code "end-of-input".
Leaving the loop (with break, or by an error) closes the source. For a Node.js stream of the values, use Readable.from(decodeStream(codec, source)).
sized(length, codec) is a value in a region of length bytes: it may not read past them, and bytes it leaves are skipped. A case .otherwise(bin().field("payload", bytes(Infinity))) in a region keeps messages of unknown types as their bytes.
For bytes in memory, new Reader(bytes) reads values one after the other: reader.read(codec) returns the next one, and reader.done tells whether all bytes were read.
Fields stepped over are not decoded: no strings, no objects, no conversions of map. Their literals and refinements are still checked.
Fields that a later length or tag names are read too (here coverSize). A length or condition given as a function may read any earlier field, so all the fields before it are decoded: name a field where you can.
pick() without names steps over whole values, e.g. to count them.
A picked parser only decodes (also in streams); it does not encode.
Records of a fixed size can be decoded one at a time where they are needed, rather than as an array of all of them. With const Score = bin().u32le("id").f64le("value"), whose size is 12, Score.decode(file, i * Score.size) decodes the i-th.
Write messages and files
Every codec encodes what it decodes, except picked parsers and codecs without encode. Counts and sizes read before a value are written from the value:
Frame.encode({ type: 2, room: 7, text: "hi" });// Uint8Array [0, 9, 2, 0, 0, 0, 7, 0, 2, 104, 105]: the size, the type, the room, the length of the text, and the text
A field that a later length names is given with the value, or computed from it. For the PNG Chunk above, the length and the CRC:
The type of the values to encode, Input<typeof WritableChunk>, is that of decoded values, Output<typeof WritableChunk>, except that computed fields and literals may be omitted. A value given for a computed field must be the computed one.
.computed(name, f) computes one field; .computed({ … }) several, each from the value without the computed fields. Like every method, it returns a new parser (to which no fields can be added); Chunk is unchanged.
Values are checked: numbers must fit, arrays and bytes must have their length, and text must fit its string. Failures throw an EncodeError with the path of the field: a name of 300 bytes gives expected u8, got 300 in `name`.
encodeInto(value, bytes, offset?) writes to a buffer you have, and returns the offset after the value. If it fails, it may have written part of the value.
sizeOf(value) is the number of bytes of value, without encoding it (custom codecs are encoded, unless they have a size). It skips the checks of encoding, which may still fail.
Recursive structures
A format contains itself: a tree of nodes, or containers in containers.
lazy(() => codec) is a codec defined later, or the one being defined. It sees no fields around it: functions in it get only the fields of its own parsers.
TypeScript cannot infer the type of a value that refers to itself: annotate it, as Codec<Tree>, and lazy's function needs no type of its own. A format that only decodes (through a map or custom without encode) is a Decoder<Tree>.
Custom encodings, such as varints
Some encodings are not fields of a fixed layout, such as variable-length integers. custom takes functions of your own:
import { custom } from "binopsy";// Variable-length integers (LEB128) of up to 32 bits.const varint = custom({ decode(input, final) { let value = 0; for (let i = 0; i < input.length && i < 5; i++) { if (i === 4 && input[i] > 0x0f) throw new Error("varint exceeds u32"); value += (input[i] & 0x7f) * 2 ** (7 * i); if (input[i] < 0x80) return { value, bytesRead: i + 1 }; } if (!final && input.length < 5) return undefined; throw new Error("invalid varint"); }, encode(value: number) { if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) { throw new Error("expected an unsigned 32-bit integer"); } const digits = []; let rest = value; do { digits.push((rest % 128) | (rest >= 128 ? 0x80 : 0)); rest = Math.floor(rest / 128); } while (rest); return Uint8Array.from(digits); },});
It works wherever a codec does, also as a length:
import { array, bin, string } from "binopsy";const Entry = bin() .field("key", string(varint)) // A varint length, then the text .field("values", array(varint, varint)); // A varint count, then varintsEntry.encode({ key: "id", values: [1, 300] }); // Uint8Array [2, 105, 100, 2, 1, 172, 2]
decode(bytes, final) gets the bytes from the value on. It returns { value, bytesRead }, or undefined if it needs more bytes and final is false (in a stream, more may follow).
It is then called again with all the bytes so far, so it must have no side effects, and should look at a bounded number of them: the varint looks at 5 at most. A search for a delimiter through a long value would start over with each chunk; string({ terminator, max }) finds one in a single pass.
A DecodeError that decode throws keeps its code: throw new DecodeError("invalid", "varint exceeds u32", 4) reports invalid bytes, at an offset in the bytes it got. Other errors become DecodeErrors of code "error".
Given a number as size, decode gets exactly that many bytes, and final is true. A function of a value as size is only for sizeOf, which calls it rather than encoding the value. Without encode, the codec only decodes.
For a conversion of bytes that other codecs read, map is enough: examples/tar.ts reads octal numbers with a map of bytes.
Malformed input
Input from outside may be truncated or corrupt. Decoding then throws a DecodeError that tells what failed, and where (it never returns part of a value). With the Png above, and an image cut off in its second chunk:
import { DecodeError } from "binopsy";try { Png.decode(truncated);} catch (e) { if (!(e instanceof DecodeError)) throw e; console.log(e.code, e.path, e.offset); // "end-of-input" ["chunks", 1, "data"] 41 console.log(e.message); // "unexpected end of input (10 bytes needed, 4 left) in `chunks[1].data` at offset 41"}
code is "end-of-input" (the input ends inside a value), "invalid" (a value failed a check, e.g. of a literal, or reached past the end of its sized region), "no-match" (a tag without a case), or "error" (a function of yours threw; its error is the cause).
refine(codec, test, message?) adds a check of your own, when decoding and when encoding: refine(u32be, (width) => width > 0, "width must be positive"). A type guard as test narrows the type.
Arrays of items that can take no bytes, such as bytes("size") with a size of 0, decode as many items as their count says, whatever the size of the input: a count of 2^32 − 1 exhausts memory. Cap such counts with refine: array(bytes("size"), refine(u32be, (n) => n <= 1024)).
An EncodeError has the path too, but no offset.
Parts shared by formats
Parsers are codecs, so they nest: .field("header", Header). .merge(Header) adds the fields of Header instead. A parser can also read fields of the parser it is merged into, which it declares:
A group of fields used in several parsers is a function of parsers, added with .pipe:
import { bin, bytes, type Bin } from "binopsy";const withValues = <T extends { count: number }, I extends { count: number }>( b: Bin<T, I>,) => b.field( "values", bytes((o) => o.count * 2), );const Record = bin().u8("count").pipe(withValues);
.merge(cond ? A : B) adds the fields of one of several parsers, as a union.
Codecs defined outside a parser, such as match cases, do not know its fields: annotate the argument of their functions, e.g. (o: Output<typeof Prefix>) => ….
In generic functions, give lengths as functions (as above), or define the codecs that read fields outside them: names of fields cannot be checked against a type parameter.
Performance
A codec compiles to JavaScript functions for its format, each when it is first needed: a decoder, an encoder, a resumable decoder for streams, and a decoder for each pick. Fixed-size fields are read and written at constant offsets, and a run of them shares one bounds check.
Compiling takes a millisecond or two for each codec and each way it is used (decoding, encoding, streaming, …), the first time: processes that decode only a few values pay more for it than they save.
Compiling uses new Function: binopsy does not work where generating code is forbidden, such as under a Content Security Policy that blocks eval. Cloudflare Workers (from the compatibility date 2025-06-01) allow it only while a Worker starts: use each codec there once at startup, in each way you need it.
Streams decode a value with the plain decoder when its chunk holds all of it, and resume decoding only for values that span chunks.
bench/compare compares binopsy with eight libraries on seven formats, and bench/parse.ts measures decoding and encoding of a database-like format. Throughput depends on the format: measure yours, on your runtime and hardware.
Reference
Parsers
bin() is an empty parser; each method returns a new parser with a field added, typed from the fields before it.
.u8(name), .i16le(name), … add a number field (a method for each number codec).
.field(name, codec) adds a field of any codec, including parsers and matches.
.merge(parser) adds the fields of another parser, of one of several (cond ? A : B), or of the cases of a match of parsers.
.skip(size) skips bytes, and .align(size) skips to a multiple of size bytes from the start of the parser (a merged parser aligns from its own start); encoding writes zeros.
.pipe(f) applies a function adding fields.
.computed(name, f) and .computed({ … }) compute fields when encoding; they end the parser.
.pick(...names) is a decoder of only the named fields.
.fields lists the names of the fields it decodes, in order, with those of every case of merged matches: P.pick(...P.fields.filter((name) => wanted.has(name))) picks those of some names that P has.
bin({ bitOrder: "lsb" }) takes the bits of bit fields from the least significant one. bin<{ length: number }>() reads the field length of the parser it is merged into, or is a match case of.
Field names are unique: adding a name twice throws when the parser is defined (TypeScript does not check it). Only the cases of one match may have fields of the same names; two matches may not, even on the same tag.
Codecs
Codec
Values
u8, i8, u16le, i32be, f32le, f64be, …
Unsigned (u) and signed (i) integers of 8, 16, 24 and 32 bits and floats (f), little (le) or big (be) endian (f32 rounds numbers to 32 bits)
u64le, i64be, …
64-bit integers, as bigint
bits(width)
Numbers of 1 to 53 bits, as direct parser fields (consecutive bit fields share bytes)
enumOf(codec, table, policy?)
Named raw values or enum members, with rejection, preservation, or a declared fallback for unknown values
bytes(length)
Uint8Arrays, viewing the input (new Uint8Array(b) copies them)
Strings ending with a terminator, of at most max bytes
array(item, length)
Arrays of length items
array(item, { until })
Arrays up to the first item for which until(item) is true (included)
sized(length, codec)
A value in a region of length bytes: it may not read past them, and they are padded with zeros
literal(codec, value)
A fixed value (a number, string, bigint or boolean), checked when decoding and written when encoding
refine(codec, test, message?)
Values passing test, when decoding and encoding (a type guard narrows their type)
map(codec, { decode, encode? })
Values converted both ways; without encode, only when decoding
optional(flag, codec)
null, or a value after a non-zero flag (e.g. u8; encoding writes 0 or 1)
when(condition, codec)
null, or a value if condition holds: an earlier field is truthy, or a function of the earlier fields returns true
match(tag).case(value, codec)…
One of several codecs, picked by a tag (.otherwise(codec) for other values)
lazy(() => codec)
A codec defined later, for formats that contain themselves
custom({ decode, encode?, size? })
A codec of functions of your own
fail(message), fail(error)
Nothing: decoding and encoding fail (e.g. for parts that are not supported), with an error of yours as if a function threw it (Errors)
Every codec has decode, encode, encodeInto and sizeOf, and size: the size of every value in bytes, or NaN if it varies (and always for lazy).
Lengths
A length is
a number; Infinity means up to the end of the input (or of the enclosing sized region),
a codec of the count read before the value (string(u32le): a 32-bit length, then the bytes; sized(u32le, Chunk): a size, then a chunk),
the name of an earlier number field (bytes("size")),
or a function of the earlier fields (bytes((o) => o.size * 2)).
Lengths are non-negative safe integers (Infinity only as a number given to the codec, not from a field or a function). When encoding, a count read before a value is written from the value, and fields and functions giving a length must agree with it. A size read before a region is written after the region's value, so its codec must have a fixed size (e.g. u32le, or a map of it).
To be encoded, an array with until needs a last item for which until is true, and no other. Arrays read without a count (with until, or up to the end) fail on an item that takes no bytes, which would be read forever.
Strings
string(16); // Exactly 16 bytes of textstring(16, { terminator: 0 }); // 16 bytes, the text ending with a zero (C's char[16])string(16, { padRight: 0x20 }); // 16 bytes, the text padded with spacesstring(u8); // A length byte, then the textstring({ terminator: 0 }); // The text, then a zerostring({ terminator: 0, max: 16 }); // The same, of at most 16 bytes (a string of 16 bytes has no zero)
A string of a length (a number, a field or a function) takes all of it: without options, the text must fill it exactly. A terminator or padding allows shorter text: decoding stops at the terminator, or else removes the trailing padding. Text filling the whole length needs no terminator. Encoding pads with padRight (zeros by default), and rejects text that contains the terminator, or (with padding alone) ends with the padding, as it would decode to other text.
A count read before the string (string(u8)) counts the bytes of the text and of its terminator, if it has one. string(Infinity, options) takes the rest of the input. string({ terminator, max }) takes the bytes up to and including its terminator, or max bytes; max is a number, an earlier field or a function.
The encodings are "utf8" (the default), "latin1", "ascii" and "utf16le": string(8, { encoding: "utf16le", terminator: 0 }). Lengths are in bytes (even ones in UTF-16); terminators and padding are bytes, or 16-bit units in UTF-16. Decoding keeps byte order marks; malformed UTF-8 becomes U+FFFD, UTF-16 keeps unpaired surrogates, and ASCII ignores the high bit. Encoding rejects characters that latin1 or ASCII do not have.
For other representations of bytes, such as hex, use map(bytes(length), …).
Bit fields
Use .field("flags", bits(3)). enumOf, map, literal, and refine can wrap bit fields and retain their packing. These codecs require a direct parser field: standalone use and arrays such as array(bits(4), 2) are type errors (and throw when compiled from JavaScript). For arrays of packed records, use array(bin().field("a", bits(4)).field("b", bits(4)), 2). A bit codec's size is NaN; the parser computes the size of each whole-byte run.
The bit fields of a merged parser continue the run (if they have the same bit order: adjoining runs of different orders throw); those of nested parsers, of merged matches, and of merged parsers that compute or pick fields, or align after fields of varying sizes, start at a byte.
Enums
enumOf(codec, table, policy?) takes one of three table forms:
An array of string or boolean names: its index is the raw value. Empty arrays, holes and duplicate names are errors.
An object with only canonical numeric keys (String(Number(key)) === key): keys are safe integers, including negative ones, and values are unique string or boolean names.
A named object, including a TypeScript enum: homogeneous number, string, or bigint values are both the decoded and encoded members. Aliases are allowed. Numeric keys must be the reverse entries of a numeric enum. Enums mixing numbers and strings are type errors; erased const enums cannot be passed as objects.
The table is read when the codec is defined: later changes to it have no effect. Invalid tables and fallback values throw a TypeError, and raw values that an integer codec (bits(n), u8 to i32be) cannot hold throw a RangeError. Raw values of other codecs are checked by them when encoding.
The third argument is enumOf.reject, enumOf.keep, or a name/member declared in the table. The two policy constants are unique symbol sentinels, so they cannot be mistaken for a fallback. The types allow an omitted policy only when a table provably covers bits(1) through bits(5); an explicit policy is always allowed. Runtime coverage checks still accept complete domains through eight bits, including u8 and i8, from JavaScript. Definition-time bounds checks remain in force for all supported integer domains, including when a policy is explicit. keep adds the raw type to the decoded and encoded type. Known names encode to their raw values; raw values pass through the inner encoder's checks. Keeping a raw value preserves its decoded value, not necessarily its original bytes (for example, a padded string is re-encoded with its canonical padding).
Unknown values rejected while decoding produce DecodeError with code "invalid", the field's path, and the byte where the field starts. Checks still run under pick. Encoding unknown names or members throws EncodeError. literal(enumOf(…), name) supplies omitted inputs, and later fields and computed fields see the names or members.
Fields that functions see
Lengths, tags and functions see the fields before them. Functions get the decoded fields, or, when encoding, the values being encoded (so a field mapped from another representation has the type of both). When encoding, they see the fields before them (never later ones), with omitted literals and computed fields filled in. A parser's own fields hide those of the same names around it.
Functions must have no side effects, as they may be called again for the same value: a stream decodes a value again if it did not fit in its chunk, and calls custom decoders again with more bytes.
A literal keeps its default (and may be omitted) through sized and lazy, but not through map, arrays, optional or when.
Decoding and encoding
codec.decode(bytes, offset?) decodes a value at offset, ignoring the bytes after it. codec.decodeExact(bytes, offset?) decodes one that must end the bytes, as a file or message holding one value does: bytes after it fail with a DecodeError of code "invalid" at the first of them. new Reader(bytes, offset?) reads consecutive values: reader.read(codec) returns one and moves reader.offset past it (if it fails, the offset stays), and reader.done tells whether all bytes were read. Setting reader.offset moves the reader, to decode values in any order.
trace(codec, bytes, offset?) decodes a value and returns where each field of its parsers is, to annotate or compare bytes: { path, start, end, value } for every field, after the fields inside it (["items", 0, "name"], then ["items"]). Bit fields have the bytes of their run. With pick, fields stepped over have value: undefined, and arrays stepped over without visiting their items have no spans for them.
codec.encode(value) returns a view of the bytes. Small results share a buffer with other results (as Node.js does for small Buffers), but are never overwritten. Results are views of ArrayBuffers (never of shared memory), so they work with Blob, Response and Web Crypto. codec.encodeInto(value, bytes, offset?) writes to bytes instead, and returns the offset after the value. Inputs and the bytes of encodeInto may be shared memory, but values must not be views of the bytes it writes to. Values being encoded are never changed.
Computed fields: with an object of functions, .computed({ size: …, count: … }), each function gets the value without the computed fields (and without filled-in literals), so they do not see each other's results. Results must not be undefined, and a value given for a computed field must be the computed one (as by Object.is). Merged into another parser, a parser computing fields still computes them from its own fields.
Streams
decodeStream(codec, source) returns an async iterator of the values. Calls of next run one after the other. return() ends the iteration at once (a pending next gives no value), and resolves once the source is closed (async generators close after their pending read). Errors of the source are thrown as they are.
Every value must take at least one byte. A value that reads up to the end of the input, such as bytes(Infinity), ends with the stream. bytes values stay valid as long as the source does not reuse its chunks. A value spanning chunks is collected in a buffer of its own (holding the rest of the input, for a value that reads up to its end). Functions in a value may run twice, as it is first decoded as if its chunk held all of it.
Errors
DecodeError
Holds
code
"end-of-input", "invalid", "no-match", or "error" (an exception in a function)
path
The field names and array indexes of the value that failed, e.g. ["items", 3, "name"]
offset
The offset of the value that failed
detail
The failure, without its location; message adds them: … in `items[3].name` at offset 12
cause
The exception, for "error"
An EncodeError has a path, a detail and a cause, but no code or offset. Offsets of DecodeErrors that custom decoders throw are in the bytes they got; binopsy moves them to the input's.
An error that a function of yours throws, or that you give to fail, is the cause of the DecodeError or EncodeError, except a DecodeError thrown when decoding, which keeps its code, offset and cause, and an EncodeError thrown when encoding, which keeps its detail and cause.
Types
Output<typeof codec> is the type of decoded values, Input<typeof codec> that of encoded ones.
Codec<O, I> is the type of codecs; Bin<T, I> that of parsers, and Struct<T, I> that of parsers adding no more fields (computing some, or picking some).
Context<typeof codec> is the type of the fields a codec reads around it. A codec reading such fields (e.g. bytes("length")) only decodes and encodes in a parser that has them: decode, encode, sizeOf, trace, Reader and streams take codecs that read none.
AnyCodec and AnyBin accept any codec and any parser, in generic functions.
Decoder<O> is Codec<O, never>: a codec that may only decode, which every codec of O that decodes on its own is (Decoder<O, Ctx> also takes those reading the fields Ctx around them). It types tables of parsers of different fields (Record<number, Decoder<object>>), and choices of codecs: functions that take a codec need it to have one type, so annotate cond ? A : B as Decoder<Output<typeof A> | Output<typeof B>> (.merge takes such choices as they are).
Options and parts: BinOptions, BitWidth, StringOptions, TerminatedStringOptions, Encoding, Length, CustomOptions, DecodeResult and Path.
TypeScript may miss a misspelled option in a union of option objects (cond ? { terminator: 0 } : { padRight: 0 }); options are also checked when a codec is defined.