Skip to content

Conversation

@rvagg
Copy link
Owner

@rvagg rvagg commented Jan 21, 2026

BREAKING CHANGE: 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).


Migration for custom tag decoders:

Before:

function myTagDecoder(value) {
  return transform(value)
}

After:

function myTagDecoder(decode) {
  const value = decode()
  return transform(value)
}

For tags wrapping CBOR maps that need non-string key preservation:

function mapDecoder(decode) {
  return new Map(decode.entries())
}

TypeScript users will see compile errors guiding the fix. JavaScript
users will see runtime errors if not updated (calling methods on a function).

…fidelity

BREAKING CHANGE: 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).

---

Migration for custom tag decoders:

Before:
```js
function myTagDecoder(value) {
  return transform(value)
}
```

After:
```js
function myTagDecoder(decode) {
  const value = decode()
  return transform(value)
}
```

For tags wrapping CBOR maps that need non-string key preservation:
```js
function mapDecoder(decode) {
  return new Map(decode.entries())
}
```

TypeScript users will see compile errors guiding the fix. JavaScript
users will see runtime errors if not updated (calling methods on a function).

Ref: #68
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants