cborg 4.2.18 → 4.3.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [4.3.0](https://github.com/rvagg/cborg/compare/v4.2.18...v4.3.0) (2025-11-05)
+
+### Features
+
+* support RFC8949 deterministic encoding ([#150](https://github.com/rvagg/cborg/issues/150)) ([6d44cc0](https://github.com/rvagg/cborg/commit/6d44cc0778b81bdfac6d654ab1893ac25b08eba3))
+
 ## [4.2.18](https://github.com/rvagg/cborg/compare/v4.2.17...v4.2.18) (2025-10-16)
 
 ### Trivial Changes

package/README.md

@@ -33,6 +33,7 @@
   * [Tag decoders](#tag-decoders)
 * [Decoding with a custom tokeniser](#decoding-with-a-custom-tokeniser)
 * [Deterministic encoding recommendations](#deterministic-encoding-recommendations)
+  * [RFC 8949 deterministic mode](#rfc-8949-deterministic-mode)
   * [Round-trip consistency](#round-trip-consistency)
 * [JSON mode](#json-mode)
   * [Example](#example-1)
@@ -209,7 +210,7 @@ Encode a JavaScript object and return a `Uint8Array` with the CBOR byte represen
 * Integers larger than `Number.MAX_SAFE_INTEGER` or less than `Number.MIN_SAFE_INTEGER` will be encoded as floats. There is no way to safely determine whether a number has a fractional part outside of this range.
 * `BigInt`s are supported by default within the 64-bit unsigned range but will be also be encoded to their smallest possible representation (so will not round-trip as a `BigInt` if they are smaller than `Number.MAX_SAFE_INTEGER`). Larger `BigInt`s require a tag (officially tags 2 and 3).
 * Floats will be encoded in their smallest possible representations: 16-bit, 32-bit or 64-bit. Unless the `float64` option is supplied.
-* Object properties are sorted according to the original [RFC 7049](https://tools.ietf.org/html/rfc7049) canonical representation recommended method: length-first and then bytewise. Note that this recommendation has changed in [RFC 8949](https://tools.ietf.org/html/rfc8949) to be plain bytewise (this is not currently supported but pull requests are welcome to add it as an option).
+* Object properties are sorted according to the original [RFC 7049](https://tools.ietf.org/html/rfc7049) canonical representation recommended method: length-first and then bytewise. Note that this recommendation has changed in [RFC 8949](https://tools.ietf.org/html/rfc8949) to be plain bytewise, use the `rfc8949EncodeOptions` to apply this rule.
 * The only CBOR major 7 "simple values" supported are `true`, `false`, `undefined` and `null`. "Simple values" outside of this range are intentionally not supported (pull requests welcome to enable them with an option).
 * Objects, arrays, strings and bytes are encoded as fixed-length, encoding as indefinite length is intentionally not supported.
 
@@ -439,7 +440,7 @@ cborg is designed with deterministic encoding forms as a primary feature. It is
 By default, cborg will always **encode** objects to the same bytes by applying some strictness rules:
 
 * Using smallest-possible representations for ints, negative ints, floats and lengthed object lengths.
-* Always sorting maps using the _original_ recommended [RFC 7049](https://tools.ietf.org/html/rfc7049) map key ordering rules.
+* Always sorting maps using the _original_ recommended [RFC 7049](https://tools.ietf.org/html/rfc7049) map key ordering rules. (Note that this has changed in [RFC 8949](https://tools.ietf.org/html/rfc8949) to be plain bytewise sorting, use the `rfc8949EncodeOptions` to apply this rule).
 * Omitting support for tags (therefore omitting support for exotic object types).
 * Applying deterministic rules to `number` differentiation - if a fractional part is missing and it's within the safe integer boundary, it's encoded as an integer, otherwise it's encoded as a float.
 
@@ -451,6 +452,24 @@ By default, cborg allows for some flexibility on **decode** of objects, which wi
 * Not providing any tag decoders, or ensuring that tag decoders are strict about their forms (e.g. a bigint decoder could reject bigints that could have fit into a standard major 0 64-bit integer).
 * Overriding type decoders where they may introduce undesired flexibility.
 
+### RFC 8949 deterministic mode
+
+RFC 8949 updates the canonical map ordering recommendation to plain bytewise comparisons. The `rfc8949EncodeOptions` export configures cborg to follow this rule and can be passed directly to `encode`:
+
+```js
+import { encode, rfc8949EncodeOptions } from 'cborg'
+
+const bytes = encode(obj, rfc8949EncodeOptions)
+```
+
+You can also merge these defaults with your own preferences:
+
+```js
+import { encode, rfc8949EncodeOptions } from 'cborg'
+
+const bytes = encode(obj, { ...rfc8949EncodeOptions, typeEncoders: YOUR_TYPE_ENCODERS })
+```
+
 Currently, there are two areas that cborg cannot impose strictness requirements (pull requests welcome!):
 
 * Smallest-possible floats, or always-float64 cannot be enforced on decode.

package/cborg.js

@@ -1,4 +1,4 @@
-import { encode } from './lib/encode.js'
+import { encode, rfc8949EncodeOptions } from './lib/encode.js'
 import { decode, decodeFirst, Tokeniser, tokensToObject } from './lib/decode.js'
 import { Token, Type } from './lib/token.js'
 
@@ -17,6 +17,7 @@ export {
   Tokeniser as Tokenizer,
   tokensToObject,
   encode,
+  rfc8949EncodeOptions,
   Token,
   Type
 }

package/lib/encode.js

@@ -3,7 +3,7 @@ import { Token, Type } from './token.js'
 import { Bl } from './bl.js'
 import { encodeErrPrefix } from './common.js'
 import { quickEncodeToken } from './jump.js'
-import { asU8A } from './byte-utils.js'
+import { asU8A, compare } from './byte-utils.js'
 
 import { encodeUint } from './0uint.js'
 import { encodeNegint } from './1negint.js'
@@ -30,6 +30,13 @@ const defaultEncodeOptions = {
   quickEncodeToken
 }
 
+/** @type {EncodeOptions} */
+export const rfc8949EncodeOptions = Object.freeze({
+  float64: true,
+  mapSorter: rfc8949MapSorter,
+  quickEncodeToken
+})
+
 /** @returns {TokenTypeEncoder[]} */
 export function makeCborEncoders () {
   const encoders = []
@@ -352,19 +359,6 @@ Recommendation: stick to single key types or you'll get into trouble, and prefer
 string keys because it's much simpler that way.
 */
 
-/*
-(UPDATE, Dec 2020)
-https://tools.ietf.org/html/rfc8949 is the updated CBOR spec and clarifies some
-of the questions above with a new recommendation for sorting order being much
-closer to what would be expected in other environments (i.e. no length-first
-weirdness).
-This new sorting order is not yet implemented here but could be added as an
-option. "Determinism" (canonicity) is system dependent and it's difficult to
-change existing systems that are built with existing expectations. So if a new
-ordering is introduced here, the old needs to be kept as well with the user
-having the option.
-*/
-
 /**
  * @param {TokenOrNestedTokens[]} entries
  * @param {EncodeOptions} options
@@ -404,6 +398,40 @@ function mapSorter (e1, e2) {
   return tcmp
 }
 
+/**
+ * @typedef {Token & { _keyBytes?: Uint8Array }} TokenEx
+ *
+ * @param {(Token|Token[])[]} e1
+ * @param {(Token|Token[])[]} e2
+ * @returns {number}
+ */
+function rfc8949MapSorter (e1, e2) {
+  if (e1[0] instanceof Token && e2[0] instanceof Token) {
+    const t1 = /** @type {TokenEx} */ (e1[0])
+    const t2 = /** @type {TokenEx} */ (e2[0])
+
+    if (!t1._keyBytes) {
+      t1._keyBytes = encodeRfc8949(t1.value)
+    }
+
+    if (!t2._keyBytes) {
+      t2._keyBytes = encodeRfc8949(t2.value)
+    }
+
+    return compare(t1._keyBytes, t2._keyBytes)
+  }
+
+  throw new Error('rfc8949MapSorter: complex key types are not supported yet')
+}
+
+/**
+ * @param {any} data
+ * @returns {Uint8Array}
+ */
+function encodeRfc8949 (data) {
+  return encodeCustom(data, cborEncoders, rfc8949EncodeOptions)
+}
+
 /**
  * @param {Bl} buf
  * @param {TokenOrNestedTokens} tokens

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cborg",
-  "version": "4.2.18",
+  "version": "4.3.0",
   "description": "Fast CBOR with a focus on strictness",
   "main": "cborg.js",
   "type": "module",

package/test/test-encode-rfc8949.js

@@ -0,0 +1,46 @@
+/* eslint-env mocha */
+
+import * as chai from 'chai'
+import { encode, rfc8949EncodeOptions } from '../cborg.js'
+import { toHex } from '../lib/byte-utils.js'
+
+const { assert } = chai
+
+describe('RFC8949 deterministic encoding', () => {
+  it('should encode', () => {
+    const value = new Map()
+    // https://datatracker.ietf.org/doc/html/rfc8949#section-4.2.1
+    value.set(false, false)
+    // value.set([-1], [-1])
+    // value.set([100], [100])
+    value.set('aa', 'aa')
+    value.set('z', 'z')
+    value.set(-1, -1)
+    value.set(10, 10)
+    value.set(100, 100)
+
+    const data = encode(value, rfc8949EncodeOptions)
+    assert.deepEqual(
+      toHex(data),
+      'a60a0a186418642020617a617a626161626161f4f4'
+    )
+    // {10: 10, 100: 100, -1: -1, "z": "z", "aa": "aa", false: false}
+  })
+
+  it('will throw on complex key types', () => {
+    const value = new Map()
+    // https://datatracker.ietf.org/doc/html/rfc8949#section-4.2.1
+    value.set(false, false)
+    value.set([-1], [-1])
+    value.set([100], [100])
+    value.set('aa', 'aa')
+    value.set('z', 'z')
+    value.set(-1, -1)
+    value.set(10, 10)
+    value.set(100, 100)
+
+    assert.throws(() => {
+      encode(value, rfc8949EncodeOptions)
+    })
+  })
+})

package/types/cborg.d.ts

@@ -19,7 +19,8 @@ import { decodeFirst } from './lib/decode.js';
 import { Tokeniser } from './lib/decode.js';
 import { tokensToObject } from './lib/decode.js';
 import { encode } from './lib/encode.js';
+import { rfc8949EncodeOptions } from './lib/encode.js';
 import { Token } from './lib/token.js';
 import { Type } from './lib/token.js';
-export { decode, decodeFirst, Tokeniser as Tokenizer, tokensToObject, encode, Token, Type };
+export { decode, decodeFirst, Tokeniser as Tokenizer, tokensToObject, encode, rfc8949EncodeOptions, Token, Type };
 //# sourceMappingURL=cborg.d.ts.map

package/types/cborg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cborg.d.ts","sourceRoot":"","sources":["../cborg.js"],"names":[],"mappings":";;;yBAMa,OAAO,aAAa,EAAE,UAAU;;;;0BAEhC,OAAO,aAAa,EAAE,mBAAmB;;;;4BACzC,OAAO,aAAa,EAAE,aAAa;;;;4BACnC,OAAO,aAAa,EAAE,aAAa;uBATe,iBAAiB;4BAAjB,iBAAiB;0BAAjB,iBAAiB;+BAAjB,iBAAiB;uBADzD,iBAAiB;sBAEZ,gBAAgB;qBAAhB,gBAAgB"}
+{"version":3,"file":"cborg.d.ts","sourceRoot":"","sources":["../cborg.js"],"names":[],"mappings":";;;yBAMa,OAAO,aAAa,EAAE,UAAU;;;;0BAEhC,OAAO,aAAa,EAAE,mBAAmB;;;;4BACzC,OAAO,aAAa,EAAE,aAAa;;;;4BACnC,OAAO,aAAa,EAAE,aAAa;uBATe,iBAAiB;4BAAjB,iBAAiB;0BAAjB,iBAAiB;+BAAjB,iBAAiB;uBADnC,iBAAiB;qCAAjB,iBAAiB;sBAElC,gBAAgB;qBAAhB,gBAAgB"}

package/types/lib/encode.d.ts

@@ -1,5 +1,10 @@
 /** @returns {TokenTypeEncoder[]} */
 export function makeCborEncoders(): TokenTypeEncoder[];
+/** @type {EncodeOptions} */
+export const rfc8949EncodeOptions: EncodeOptions;
+export type TokenEx = Token & {
+    _keyBytes?: Uint8Array;
+};
 export type EncodeOptions = import("../interface").EncodeOptions;
 export type OptionalTypeEncoder = import("../interface").OptionalTypeEncoder;
 export type Reference = import("../interface").Reference;
@@ -47,4 +52,5 @@ export class Ref implements Reference {
      */
     includes(obj: object | any[]): boolean;
 }
+import { Token } from './token.js';
 //# sourceMappingURL=encode.d.ts.map

package/types/lib/encode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../lib/encode.js"],"names":[],"mappings":"AAgCA,oCAAoC;AACpC,oCADc,gBAAgB,EAAE,CAY/B;4BA3BY,OAAO,cAAc,EAAE,aAAa;kCACpC,OAAO,cAAc,EAAE,mBAAmB;wBAC1C,OAAO,cAAc,EAAE,SAAS;gCAChC,OAAO,cAAc,EAAE,iBAAiB;+BACxC,OAAO,cAAc,EAAE,gBAAgB;kCACvC,OAAO,cAAc,EAAE,mBAAmB;AAgQvD;;;;;GAKG;AACH,oCALW,GAAG,YACH,aAAa,aACb,SAAS,GACP,mBAAmB,CAgB/B;AA2JD;;;;GAIG;AACH,6BAJW,GAAG,YACH,aAAa,GACX,UAAU,CAKtB;AAvCD;;;;;GAKG;AACH,mCALW,GAAG,YACH,gBAAgB,EAAE,WAClB,aAAa,GACX,UAAU,CAyBtB;AAjZD,8BAA8B;AAC9B,4BADiB,SAAS;IA0BxB;;;;OAIG;IACH,0BAJW,SAAS,GAAC,SAAS,OACnB,MAAM,GAAC,GAAG,EAAE,GACV,SAAS,CAOrB;IAlCD;;;OAGG;IACH,iBAHW,MAAM,GAAC,GAAG,EAAE,UACZ,SAAS,GAAC,SAAS,EAK7B;IAFC,oBAAc;IACd,qDAAoB;IAGtB;;;OAGG;IACH,cAHW,MAAM,GAAC,GAAG,EAAE,GACV,OAAO,CAWnB;CAaF"}
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../lib/encode.js"],"names":[],"mappings":"AAuCA,oCAAoC;AACpC,oCADc,gBAAgB,EAAE,CAY/B;AAnBD,4BAA4B;AAC5B,mCADW,aAAa,CAKtB;sBA4WW,KAAK,GAAG;IAAE,SAAS,CAAC,EAAE,UAAU,CAAA;CAAE;4BAhYlC,OAAO,cAAc,EAAE,aAAa;kCACpC,OAAO,cAAc,EAAE,mBAAmB;wBAC1C,OAAO,cAAc,EAAE,SAAS;gCAChC,OAAO,cAAc,EAAE,iBAAiB;+BACxC,OAAO,cAAc,EAAE,gBAAgB;kCACvC,OAAO,cAAc,EAAE,mBAAmB;AAuQvD;;;;;GAKG;AACH,oCALW,GAAG,YACH,aAAa,aACb,SAAS,GACP,mBAAmB,CAgB/B;AAgLD;;;;GAIG;AACH,6BAJW,GAAG,YACH,aAAa,GACX,UAAU,CAKtB;AAvCD;;;;;GAKG;AACH,mCALW,GAAG,YACH,gBAAgB,EAAE,WAClB,aAAa,GACX,UAAU,CAyBtB;AAtaD,8BAA8B;AAC9B,4BADiB,SAAS;IA0BxB;;;;OAIG;IACH,0BAJW,SAAS,GAAC,SAAS,OACnB,MAAM,GAAC,GAAG,EAAE,GACV,SAAS,CAOrB;IAlCD;;;OAGG;IACH,iBAHW,MAAM,GAAC,GAAG,EAAE,UACZ,SAAS,GAAC,SAAS,EAK7B;IAFC,oBAAc;IACd,qDAAoB;IAGtB;;;OAGG;IACH,cAHW,MAAM,GAAC,GAAG,EAAE,GACV,OAAO,CAWnB;CAaF;sBA7F2B,YAAY"}