\n\n# @stricahq/cbors\n\n[](https://www.npmjs.com/package/@stricahq/cbors)\n[](https://www.npmjs.com/package/@stricahq/cbors)\n[](https://nodejs.org)\n[](https://github.com/StricaHQ/cbors/blob/master/package.json)\n[](./LICENSE)\n\nCBOR ([RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)) encoder and decoder for JavaScript, with no dependencies.\n\nThe thing that makes it different is what it remembers. Most decoders hand you a value and throw the encoding away. cbors can hand you an annotation tree instead: every item, primitives included, still knows which bytes it came from. That matters on Cardano, where a transaction is hashed and signed over its exact bytes and re-encoding a decoded value is not guaranteed to give you those bytes back.\n\n## v2 is a breaking change\n\nv2 is not a drop-in upgrade. It is ESM-only and needs Node >= 22.12, and the API, the number type, and the byte type all changed, so v1 code will not run unchanged against it. [Migrating from v1](#migrating-from-v1) lists every change and its replacement.\n\nMoving to v2 is the recommended path: it is faster than v1 (see [Benchmarks](#benchmarks)), carries no dependencies and no Node.js builtins, and it will get new features and fixes from here on.\n\n### Staying on v1\n\nv1 remains on npm and keeps working. Pin the major version to stay there:\n\n```sh\nyarn add @stricahq/cbors@1\n```\n\n```html\n\n```\n\nv1 is a CJS + ESM dual package, runs on older Node, and uses `bignumber.js` and `Buffer`. Everything below documents v2.\n\n## Installation\n\n### yarn/npm\n\n```sh\nyarn add @stricahq/cbors\n```\n\n### Browser\n\n```html\n\n\n// access the cbors global variable\n```\n\ncbors has no dependencies and uses no Node.js builtins, so bundlers need no polyfills or aliases for it.\n\n## Quick start\n\n```js\nimport { encode, decode } from \"@stricahq/cbors\";\n\nconst bytes = encode(new Map().set(0, [1, 2])); // Uint8Array a1 00 82 01 02\nconst value = decode(bytes); // Map(1) { 0 => [ 1, 2 ] }\n```\n\n`decode` returns the value directly, and throws if the input holds anything other than exactly one complete CBOR item.\n\nThat is the whole surface for simple work. Everything else the package exports:\n\n```js\nimport {\n encode, // value -> Uint8Array\n decode, // bytes -> value\n decodeAnnotated, // bytes -> CborNode tree, keeps the original bytes of every item\n IncrementalDecoder, // push chunks, get items as they complete\n CborTag, // a tagged value\n SimpleValue, // a simple value other than true/false/null/undefined\n EncodedCbor, // pre-encoded bytes to splice into the output as-is\n IndefiniteArray, // Array subclass that encodes in indefinite form\n IndefiniteMap, // Map subclass that encodes in indefinite form\n} from \"@stricahq/cbors\";\n```\n\nFor more examples, the [tests](https://github.com/StricaHQ/cbors/tree/master/tests) cover every supported data type.\n\n## What decodes to what\n\n```js\ndecode(bytes);\n```\n\n| CBOR | you get |\n|---|---|\n| integer within ±2^53 | `number` |\n| integer beyond ±2^53 | `bigint` |\n| bignum (tags 2 and 3) | `bigint` |\n| float16 / float32 / float64 | `number` |\n| byte string | `Uint8Array` |\n| text string | `string` |\n| array | `Array`, or `IndefiniteArray` if it was indefinite |\n| map | `Map`, or `IndefiniteMap` if it was indefinite |\n| any other tag | `CborTag { tag, value }` |\n| `true` / `false` / `null` / `undefined` | the same, unwrapped |\n| any other simple value | `SimpleValue { value }` |\n\nMaps always come back as a `Map`, never a plain object, because CBOR keys are not limited to strings. A decoded byte string is a zero-copy view into the buffer you passed in, so it stays valid as long as that buffer does.\n\n```js\nencode(value);\n```\n\n| you pass | you get |\n|---|---|\n| `number`, integral | integer, in the smallest head that fits |\n| `number`, fractional | float64 |\n| `NaN`, `±Infinity`, `-0` | the two-byte float16 forms |\n| `bigint` | integer if it fits in 64 bits, else a bignum tag |\n| `string` | text string |\n| `Uint8Array`, `Buffer`, `ArrayBuffer`, `Uint8ClampedArray` | byte string |\n| `Array` / `IndefiniteArray` | definite / indefinite array |\n| `Map` / `IndefiniteMap` | definite / indefinite map |\n| plain object | map with text keys |\n| `CborTag` | tagged item |\n| `SimpleValue` | simple value |\n| `EncodedCbor` | its bytes, spliced in untouched |\n| any other object (a class instance, `Date`, `Set`, `RegExp`, other typed arrays), functions, symbols | throws |\n\nAnything the encoder cannot represent faithfully throws rather than being silently mangled into a map of its fields. Note that an integral `number` always encodes as an integer, so `1.0` goes out as `01`, and floats are never shrunk to half or single precision. If you need a specific float encoding on the wire, splice it in with `EncodedCbor`.\n\nIndefinite-length arrays and maps survive a full round trip: they decode to `IndefiniteArray` / `IndefiniteMap`, which encode back to indefinite form.\n\n```js\nimport { IndefiniteArray } from \"@stricahq/cbors\";\n\nconst list = new IndefiniteArray();\nlist.push(1, 2);\nencode(list); // 9f 01 02 ff\nencode(decode(encode(list))); // 9f 01 02 ff, still indefinite\n```\n\nIndefinite byte and text strings are the exception: they decode to a single joined `Uint8Array` / `string`, so a re-encode produces the definite form. If you need those bytes back exactly, use the annotation tree below.\n\n## Cardano\n\nEverything on Cardano is hashed and signed over exact CBOR bytes, and a value has more than one valid encoding. The integer 23 can be written as `17` or as `1817`. An array can be definite or indefinite. Both are legal, both decode to the same thing, and they hash to different values. So decoding a transaction and encoding it again is not a safe way to move it around: you may get different bytes, and different bytes mean a different transaction id or a broken signature.\n\ncbors handles both directions of this problem: `decodeAnnotated` on the way in, `EncodedCbor` on the way out.\n\n### The annotation tree\n\n`decodeAnnotated` returns a `CborNode` tree instead of a plain value. Every item carries its `kind`, its byte `span` in the source buffer, and the head-byte `encoding` info. `node.bytes` is a zero-copy slice of the original bytes of that item, header included.\n\nSo a transaction id is the hash of the body node's bytes:\n\n```js\nimport { decodeAnnotated } from \"@stricahq/cbors\";\n\n// tx = [body, witnessSet, isValid, auxiliaryData]\nconst tx = decodeAnnotated(txBytes);\nconst txId = blake2b256(tx.at(0).bytes); // any hash function\n```\n\n`tx.at(0).bytes` is the same stretch of memory as in `txBytes`, so the hash matches the on-chain id. The same trick covers datum hashes, script integrity hashes and anything else hashed over original bytes.\n\nWalking a node:\n\n- `node.at(k)` — array index, or the value of the first map entry whose key matches `k`. Keys can be a number/bigint (they cross-match), a string, a bool, or a `Uint8Array` matched by content. Returns a `CborNode` or `undefined`.\n- `node.bytes` — the exact source bytes for this item, header included.\n- `node.toJS()` — the plain `decode()` value for this subtree (joins indefinite chunks, collapses bignum tags, last-wins for duplicate keys).\n- `node.kind` — `uint`, `nint`, `bytes`, `text`, `array`, `map`, `tag`, `simple`, `float`, `bool`, `null` or `undefined`.\n- `node.value` — the payload of a leaf. For a byte string that is the bytes *without* the header, unlike `node.bytes`.\n- `node.items` — array children. `node.entries` — map entries, keeping order **and** duplicate keys. `node.chunks` — the pieces of an indefinite byte/text string. `node.child` — a tag's payload.\n- `node.span` — `[start, end)` offsets into the input. `node.encoding` — `{ ai, indefinite }`, the head byte's additional info and whether the item was indefinite.\n\nReading a couple of fields out of a transaction body:\n\n```js\nconst body = tx.at(0);\nconst fee = body.at(2).toJS(); // body key 2 is the fee\n\nconst inputs = body.at(0); // body key 0 is the inputs\n// since Conway, sets arrive wrapped in tag 258\nconst inputItems = inputs.kind === \"tag\" ? inputs.child.items : inputs.items;\n```\n\n`decodeAnnotated` is one-shot: spans are offsets into a single contiguous buffer. For a stream, `IncrementalDecoder.annotated()` gives you the same tree per item as they complete.\n\n### Splicing pre-encoded bytes with EncodedCbor\n\n`EncodedCbor` wraps a buffer that already holds one encoded CBOR item, and the encoder writes those bytes into the output untouched instead of re-encoding them. Any bytes, from anywhere, at any position in the value you are encoding.\n\n```js\nimport { encode, EncodedCbor } from \"@stricahq/cbors\";\n\nconst raw = encode(new Map().set(1, 2).set(3, 4)); // a2 01 02 03 04, from wherever\n\nencode(new EncodedCbor(raw)); // a2 01 02 03 04, spliced in as-is\nencode(raw); // 45 a2 01 02 03 04, a Uint8Array is a byte string\nencode([1, new EncodedCbor(raw)]); // 82 01 a2 01 02 03 04, nests like any other value\n```\n\nPair it with `node.bytes` from the annotation tree and you can rebuild a transaction with one subtree replaced, while every untouched subtree keeps its original bytes. Attaching a witness set from a CIP-30 wallet is exactly that:\n\n```js\nimport { decodeAnnotated, encode, EncodedCbor } from \"@stricahq/cbors\";\n\nconst tx = decodeAnnotated(txBytes);\nconst witnessSet = await api.signTx(txHex, true); // CIP-30, hex string\n\nconst signedTx = encode([\n new EncodedCbor(tx.at(0).bytes), // body, spliced verbatim, its hash unchanged\n new EncodedCbor(toBytes(witnessSet)), // fresh witness set from the wallet\n true, // isValid\n null, // auxiliaryData\n]);\n```\n\nThe buffer can come from anywhere: a wallet, a node, a cache, a slice of an annotation tree. It is spliced as given and never re-parsed or validated, so it has to be exactly one well-formed item.\n\ncbors ships no hex helper of its own. Anything that produces a `Uint8Array` works: `Buffer.from(hex, \"hex\")` on Node, `Uint8Array.fromHex(hex)` on runtimes that have it, or whichever hex utility your project already uses.\n\n## Tags\n\nTags are first class in both directions. Anything cbors does not fold into a native value decodes to a `CborTag`, and a `CborTag` encodes back to the same tag number and payload.\n\n```js\nimport { encode, decode, CborTag } from \"@stricahq/cbors\";\n\nconst bytes = encode(new CborTag([1, 2, 3], 258)); // d9 0102 83 01 02 03\n\nconst tagged = decode(bytes);\ntagged.tag; // 258\ntagged.value; // [1, 2, 3], the payload decoded normally\nencode(tagged); // the same bytes back\n```\n\nThere is no tag registry and no way to register a decoder for a tag: cbors gives you the number and the payload, and your code decides what it means. The one exception is bignums, tags 2 and 3, which decode straight to `bigint` because there is no lossless way to hand them back otherwise.\n\nTag numbers are supported over the full CBOR range, up to 2^64 - 1. Numbers beyond 2^53 come back as a `bigint` and can be passed back to `encode` the same way.\n\nTags you will meet on Cardano:\n\n| Tag | Used for | In cbors |\n|---|---|---|\n| 2, 3 | bignums | decode to `bigint`; `encode` emits them when a `bigint` exceeds 64 bits |\n| 24 | a byte string that holds another CBOR item | `new CborTag(bytes, 24)`; the payload stays a `Uint8Array`, run `decode` on it yourself if you want the value |\n| 30 | rational numbers, e.g. protocol parameters | `new CborTag([numerator, denominator], 30)` |\n| 258 | sets, since Conway | `new CborTag(items, 258)` |\n| 121-127, 1280-1400, 102 | Plutus data constructors | plain `CborTag`, the alternative is in the tag number |\n\nDecimal fractions (tag 4) work the same way, built explicitly:\n\n```js\nencode(new CborTag([-1, 15], 4)); // c4 82 20 0f, i.e. 15 * 10^-1\n```\n\n## Streaming\n\n`IncrementalDecoder` is a dependency-free push decoder for a stream of concatenated CBOR items, a chain-sync feed or a file of blocks. Feed it chunks as they arrive; each `push` returns the top-level items that completed in that chunk, as `{ value, bytes }`. Chunk boundaries can fall anywhere, including in the middle of an item. Call `end()` when the input is done, and it throws if the stream stopped mid-item.\n\n```js\nimport { IncrementalDecoder } from \"@stricahq/cbors\";\n\nconst decoder = new IncrementalDecoder();\nsocket.on(\"data\", (chunk) => {\n for (const { value, bytes } of decoder.push(chunk)) {\n // one entry per completed top-level item\n }\n});\nsocket.on(\"end\", () => decoder.end());\n```\n\n`IncrementalDecoder.annotated()` decodes the same stream into [annotation trees](#the-annotation-tree): `value` is a `CborNode` instead of a plain value, so a streamed block or transaction still knows the bytes of every item inside it. Each item is framed into its own buffer, spans are offsets into that item, not into the stream.\n\n```js\nconst decoder = IncrementalDecoder.annotated();\nsocket.on(\"data\", (chunk) => {\n for (const { value } of decoder.push(chunk)) {\n const txId = blake2b256(value.at(0).bytes);\n }\n});\n```\n\nTo `.pipe()` it into a Node.js stream, wrap it in a `Transform`: `push` each chunk on `transform`, and `end` on `flush`. The decoder stays dependency-free; you bring the stream glue.\n\n```js\nimport { createReadStream } from \"node:fs\";\nimport { Transform } from \"node:stream\";\nimport { IncrementalDecoder } from \"@stricahq/cbors\";\n\nconst decoder = new IncrementalDecoder();\nconst decodeStream = new Transform({\n readableObjectMode: true,\n transform(chunk, _enc, cb) {\n try {\n for (const item of decoder.push(chunk)) this.push(item);\n cb();\n } catch (err) {\n cb(err);\n }\n },\n flush(cb) {\n try {\n decoder.end();\n cb();\n } catch (err) {\n cb(err);\n }\n },\n});\n\ncreateReadStream(\"stream.cbor\")\n .pipe(decodeStream)\n .on(\"data\", ({ value, bytes }) => {\n // one entry per completed top-level item\n });\n```\n\n## Options\n\nOptions are plain objects and always optional.\n\n`decode(bytes, options)`, `decodeAnnotated(bytes, options)`, `new IncrementalDecoder(options)` and `IncrementalDecoder.annotated(options)` take the same decoder options:\n\n| Option | Default | What it does |\n|---|---|---|\n| `maxDepth` | `1024` | Rejects items nested deeper than this. cbors itself handles any depth without running out of stack (`decode`, `toJS()` and `encode` alike), so the limit is there for code that walks decoded values recursively. |\n| `maxStringLength` | `4294967295` | Rejects a byte or text string, or an indefinite chunk, that declares a length above this. Stops a two-byte header from asking for a gigabyte allocation. This is also the ceiling: a larger value is clamped to it. |\n\n```js\ndecode(bytes, { maxDepth: 32, maxStringLength: 1 << 20 });\n```\n\nBoth limits take a non-negative integer. `Infinity` turns `maxDepth` off, and leaves `maxStringLength` at its ceiling.\n\n`encode(value, options)`:\n\n| Option | Default | What it does |\n|---|---|---|\n| `collapseBigInt` | `true` | Writes a `bigint` as a plain integer when it fits in 64 bits. Set it to `false` to always emit a bignum tag. |\n\n```js\nencode(10n); // 0a\nencode(10n, { collapseBigInt: false }); // c2 41 0a\n```\n\n### What the decoder rejects\n\nThe decoder is strict about well-formedness, and throws a plain `Error` rather than guessing:\n\n- trailing bytes after the item, or an item that ends early\n- reserved additional info 28-30\n- indefinite length on a major type that has no indefinite form\n- indefinite string chunks of the wrong major type, or themselves indefinite\n- text strings that are not valid UTF-8\n- two-byte simple values below 32, which RFC 8949 forbids\n- anything past `maxDepth` or `maxStringLength`\n\n## Benchmarks\n\nReal Cardano CBOR data, single threaded.\n\n| Workload | Size | `decode` | `decodeAnnotated` | `encode` | `IncrementalDecoder` |\n|---|---|---|---|---|---|\n| Smallest tx | 193 B | 351 MB/s | 274 MB/s | 246 MB/s | 159 MB/s |\n| Median tx | 576 B | 558 MB/s | 439 MB/s | 314 MB/s | 312 MB/s |\n| Largest tx | 16.0 kB | 452 MB/s | 867 MB/s | 696 MB/s | 433 MB/s |\n| Full block (1 item, 15 txs) | 86.9 kB | 419 MB/s | 699 MB/s | 679 MB/s | 334 MB/s |\n\nA median 576 B transaction decodes in about 1.0 µs, a full 87 kB block in about 0.20 ms. `decodeAnnotated` tracks plain `decode` closely, and runs ahead of it on large map-heavy items.\n\nMeasured on an Apple M1 Pro, Node 24.13.0.\n\n## Migrating from v1\n\n| v1 | v2 |\n|---|---|\n| `Encoder.encode(x)` | `encode(x)` |\n| `Decoder.decode(x).value` | `decode(x)` (returns the value directly) |\n| `getCborBytes(buf, item)` / byte spans | `decodeAnnotated(buf)` → `node.at(...).bytes` |\n| `hasByteSpan` / `Spanned` guards | annotation tree carries spans for every item |\n| `new Decoder()` Transform stream | `new IncrementalDecoder()` (`push` / `end`) |\n| BigNumber (via `bignumber.js`) | native `bigint` (BigNumber inputs now throw) |\n| `collapseBigNumber` encode option | `collapseBigInt` |\n| decimal fractions via BigNumber | `new CborTag([exponent, mantissa], 4)` |\n| `Buffer` in and out | `Uint8Array` out; `Buffer` still accepted as input |\n| `buffer` polyfill for browsers | no dependencies, no Node.js builtins |\n| CJS + ESM dual package | ESM only, `require(esm)` on Node >= 22.12 |\n\n## API Doc\n\nFind the API documentation [here](https://docs.strica.io/lib/cbors).\n\n# License\nCopyright 2022 Strica\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","readmeFilename":"README.md"}
![](\"https://docs.strica.io/images/logo.png\"){kind=logo}
\n \n