Releases: rvagg/cborg
v5.1.1
v5.1.0
v5.0.1
v5.0.0
5.0.0 (2026-03-31)
⚠ BREAKING CHANGES
- extended: Tag decoder signature changed from receiving the decoded
value to receiving a decode control object. See migration guide below.
Add new cborg/extended entry point providing encode/decode with built-in
support for Date, RegExp, Set, Map, BigInt, Error, and all TypedArrays using
standard CBOR tags. Type support is similar to the browser's structured
clone algorithm.
Key features:
- Date (Tag 1), RegExp (Tag 21066), Set (Tag 258), Map (Tag 259)
- BigInt always tagged (Tags 2/3) for round-trip fidelity
- All TypedArrays via RFC 8746 tags (64-87)
- Error types via Tag 27 (Error, TypeError, RangeError, etc.)
- Negative zero (-0) round-trips correctly
- Objects round-trip as objects, Maps round-trip as Maps
- Map and object key insertion order preserved (not sorted)
- Mixed structures like { myMap: new Map([[1, 'a']]) } work correctly
The Map/object fidelity is achieved through a new tag decoder API that
gives decoders control over how their content is decoded. Tag 259 (Map)
uses decode.entries() to preserve key types regardless of the useMaps
setting, while plain CBOR maps decode as objects.
Extends cborg/taglib with encoders and decoders for all supported types
(previously only BigInt). Moves taglib.js to lib/taglib.js for consistency
(external API unchanged via package.json exports).
Also fixes a bug in lib/7float.js where -0 lost its sign bit during
half-precision float encoding (bitwise ops on floats convert to int32).
Features
Trivial Changes
- deps-dev: bump typescript from 5.9.3 to 6.0.2 (5382bfa)
- deps: bump actions/setup-node from 6.2.0 to 6.3.0 (#171) (a2525b9)
- update deps and upgrade to typescript 6 (463bdfd)
Migration Guide (v4 to v5)
Tag decoder signature change
Tag decoders no longer receive the decoded value directly. Instead, they receive a TagDecodeControl function that must be called to decode the tagged content.
Before (v4):
function myTagDecoder (value) {
// `value` is already decoded
return processTag(value)
}After (v5):
function myTagDecoder (decode) {
const value = decode() // call to decode the tagged content
return processTag(value)
}The TagDecodeControl object also provides an entries() method for decoding CBOR maps as [key, value] pairs, preserving non-string key types:
function myMapTagDecoder (decode) {
const entries = decode.entries() // Array<[unknown, unknown]>
return new Map(entries)
}The TagDecodeControl type is exported from both cborg and cborg/interface.
Tags option is now an object
The tags decode option changed from an array (indexed by tag number) to an object mapping tag numbers to decoders.
Before (v4):
import { decode } from 'cborg'
const tags = []
tags[42] = myTagDecoder
decode(bytes, { tags })After (v5):
import { decode } from 'cborg'
decode(bytes, { tags: { 42: myTagDecoder } })taglib moved to cborg/taglib
The taglib module has moved from a top-level file to lib/taglib.js, accessible via the cborg/taglib export. The import path remains the same for consumers using the package exports:
import { bigIntEncoder, bigIntDecoder } from 'cborg/taglib'The taglib module now includes encoders and decoders for additional types: Date, RegExp, Set, Map, Error, and TypedArrays. See cborg/extended for a batteries-included configuration.
New cborg/extended module
A new cborg/extended export provides encode/decode options pre-configured with tag handlers for common JavaScript types (Date, RegExp, BigInt, Set, Map, Error, TypedArrays). This is opt-in and not loaded by default.
import { encode, decode } from 'cborg/extended'
const bytes = encode({ timestamp: new Date(), pattern: /foo/i })
const obj = decode(bytes)