cborg 4.4.1 → 4.5.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [4.5.1](https://github.com/rvagg/cborg/compare/v4.5.0...v4.5.1) (2026-01-20)
+
+## [4.5.0](https://github.com/rvagg/cborg/compare/v4.4.1...v4.5.0) (2026-01-20)
+
+### Features
+
+* add encodeInto() for BYO buffer encoding ([a577843](https://github.com/rvagg/cborg/commit/a5778432faa44be491ce2fdd814eceddd1979d77))
+* **bench:** add realistic IPLD workload benchmarks ([07d9618](https://github.com/rvagg/cborg/commit/07d9618f1a86262d59690ff00e268db0ad0c6d4a))
+
 ## [4.4.1](https://github.com/rvagg/cborg/compare/v4.4.0...v4.4.1) (2026-01-19)
 
 ### Trivial Changes

package/README.md

@@ -25,6 +25,7 @@
 * [API](#api)
   * [`encode(object[, options])`](#encodeobject-options)
     * [Options](#options)
+  * [`encodeInto(data, destination[, options])`](#encodeintodata-destination-options)
   * [`decode(data[, options])`](#decodedata-options)
     * [Options](#options-1)
   * [`decodeFirst(data[, options])`](#decodefirstdata-options)
@@ -221,6 +222,26 @@ Encode a JavaScript object and return a `Uint8Array` with the CBOR byte represen
 * `mapSorter` (function): a function taking two arguments, where each argument is a `Token`, or an array of `Token`s representing the keys of a map being encoded. Similar to other JavaScript compare functions, a `-1`, `1` or `0` (which shouldn't be possible) should be returned depending on the sorting order of the keys. See the source code for the default sorting order which uses the length-first rule recommendation from [RFC 7049](https://tools.ietf.org/html/rfc7049).
 * `ignoreUndefinedProperties` (boolean, default `false`): when encoding a plain object, properties with `undefined` values will be omitted. Does not apply to `Map`s or arrays.
 
+### `encodeInto(data, destination[, options])`
+
+```js
+import { encodeInto } from 'cborg'
+```
+
+Encode a JavaScript object directly into a provided `Uint8Array` destination buffer, returning an object with a `written` property indicating the number of bytes written.
+
+This API mirrors [`TextEncoder.encodeInto()`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder/encodeInto) and is useful for performance-critical scenarios where you want to avoid allocations by reusing a buffer.
+
+```js
+const destination = new Uint8Array(1024)
+const { written } = encodeInto({ hello: 'world' }, destination)
+const encoded = destination.subarray(0, written)
+```
+
+If the destination buffer is too small to hold the encoded data, an error will be thrown. Use `encodedLength()` to pre-calculate the required size if needed.
+
+The same encoding rules and options as [`encode()`](#encodeobject-options) apply.
+
 ### `decode(data[, options])`
 
 ```js

package/bench/README.md

@@ -0,0 +1,115 @@
+# cborg Benchmarks
+
+Benchmarks for measuring cborg encode/decode performance with realistic IPLD workloads.
+
+## Quick Start
+
+```bash
+# Run all benchmarks (dag-cbor mode with tag 42 + strict options)
+node bench/bench.js
+
+# Run specific suite
+node bench/bench.js --suite=bsky       # Bluesky (string-heavy)
+node bench/bench.js --suite=filecoin   # Filecoin (bytes-heavy)
+node bench/bench.js --suite=micro      # Micro-benchmarks (maps, strings, integers, etc.)
+
+# Run in raw mode (no tags, minimal options) for baseline comparison
+node bench/bench.js --mode=raw
+
+# Test encodeInto() performance
+node bench/bench.js --encode-into
+
+# Adjust duration per test (default 1000ms)
+node bench/bench.js --duration=2000
+```
+
+## Browser Benchmarks
+
+Open `bench/index.html` in a browser. Select mode, suite, and duration, then click "Run Benchmarks".
+
+## Capturing and Comparing Results
+
+### Save a baseline
+
+```bash
+# Save results to a file
+node bench/bench.js --json > bench/baselines/before-change.json
+
+# Or with a version/date identifier
+node bench/bench.js --json > bench/baselines/v4.4.0.json
+node bench/bench.js --json > bench/baselines/$(date +%Y%m%d).json
+```
+
+### Compare against baseline
+
+```bash
+node bench/bench.js --compare=bench/baselines/before-change.json
+```
+
+This shows percentage differences for each benchmark.
+
+### Typical workflow
+
+1. Capture baseline before making changes:
+   ```bash
+   node bench/bench.js --json > bench/baselines/before.json
+   ```
+
+2. Make your changes to cborg
+
+3. Compare:
+   ```bash
+   node bench/bench.js --compare=bench/baselines/before.json
+   ```
+
+4. Optionally save the new results:
+   ```bash
+   node bench/bench.js --json > bench/baselines/after.json
+   ```
+
+## Benchmark Modes
+
+### dag-cbor mode (default)
+
+Simulates `@ipld/dag-cbor` usage:
+- CID encoding/decoding via CBOR tag 42
+- `float64: true` (always 64-bit floats)
+- `strict: true` on decode
+- `rejectDuplicateMapKeys: true`
+- Bluesky suite uses `ignoreUndefinedProperties: true`
+- Filecoin/micro suites throw on undefined (strict IPLD)
+
+### raw mode (`--mode=raw`)
+
+Minimal cborg options for baseline comparison:
+- No tag encoding/decoding
+- Default encode/decode options
+- Shows overhead of dag-cbor-specific features
+
+## Files
+
+- `bench.js` - Main benchmark runner (Node.js)
+- `index.html` - Browser benchmark UI
+- `fixtures.js` - Deterministic fixture generators (seeded PRNG)
+- `bench-comparative.js` - Historical cborg vs borc comparison
+- `json.js` - JSON encode/decode benchmarks
+
+## Fixture Suites
+
+### Bluesky (string-heavy)
+- Posts, follows, likes, reposts, profiles
+- MST (Merkle Search Tree) nodes
+- Heavy on strings, DIDs, AT-URIs, timestamps
+
+### Filecoin (bytes-heavy)
+- Messages, block headers
+- HAMT and AMT nodes
+- CID arrays
+- Heavy on byte arrays and CIDs
+
+### Micro-benchmarks
+- Maps (small/medium/large key counts)
+- Nesting depth (shallow/deep)
+- Strings (short/medium/long)
+- Integers (small/medium/large)
+- Bytes (small/medium/large)

package/bench/bench-comparative.js

@@ -0,0 +1,133 @@
+// can be run in a browser with `polendina --runner=bare-sync --timeout 6000 --cleanup bench.js`
+// with additional dependencies for cborg installed here
+
+import assert from 'assert'
+import { garbage } from 'ipld-garbage'
+import { decode, encode, encodeInto } from '../cborg.js'
+import borc from 'borc'
+
+const WITH_CBORG_FIXED_DESTINATION = true
+
+let writebuf = ''
+const write = process.stdout
+  ? process.stdout.write.bind(process.stdout)
+  : (str) => {
+      writebuf += str
+      if (str.endsWith('\n')) {
+        console.log(writebuf.replace(/\n$/, ''))
+        writebuf = ''
+      }
+    }
+
+function runWith (description, count, targetTime, size, options) {
+  let borcDecoder = null
+  const borcDecode = (bytes) => {
+    if (!borcDecoder) {
+      // account for initial allocation & setup time in benchmark
+      borcDecoder = new borc.Decoder({ size: 10 * 1024 * 1024 })
+    }
+    return borcDecoder.decodeAll(bytes)[0]
+  }
+
+  let cborgEncoder = WITH_CBORG_FIXED_DESTINATION ? null : encode
+
+  const cborgEncode = (bytes) => {
+    if (!cborgEncoder) {
+      // account for initial allocation & setup time in benchmark
+      const fixedDestination = new Uint8Array(10 * 1024 * 1024)
+      cborgEncoder = (bytes) => {
+        const { written } = encodeInto(bytes, fixedDestination)
+        return fixedDestination.subarray(0, written)
+      }
+    }
+    return cborgEncoder(bytes)
+  }
+
+  const fixtures = []
+
+  console.log(`${description} @ ${count.toLocaleString()}`)
+  for (let i = 0; i < count; i++) {
+    const obj = garbage(size, options)
+    const cbyts = encode(obj)
+    /*
+    const bbyts = borc.encode(obj)
+    if (Buffer.compare(Buffer.from(cbyts), bbyts) !== 0) {
+      console.log(`mismatch for obj: ${JSON.stringify(obj)}`)
+      console.log('\t', Buffer.from(cbyts).toString('hex'))
+      console.log('\t', Buffer.from(bbyts).toString('hex'))
+    }
+    */
+    if (cbyts.length <= size * 2) {
+      fixtures.push([obj, cbyts])
+    }
+  }
+  const avgSize = Math.round(fixtures.reduce((p, c) => p + c[1].length, 0) / fixtures.length)
+
+  const enc = (encoder) => {
+    for (const [obj, byts] of fixtures) {
+      const ebyts = encoder(obj)
+      if (byts.length !== ebyts.length) {
+        throw new Error('bork')
+      }
+    }
+    return fixtures.length
+  }
+
+  const bench = (bfn) => {
+    const start = Date.now()
+    let opcount = 0
+    do {
+      opcount += bfn()
+    } while (Date.now() - start < targetTime)
+    const ops = Math.round(opcount / ((Date.now() - start) / 1000))
+    return ops
+  }
+
+  const dec = (decoder) => {
+    for (const [obj, byts] of fixtures) {
+      const cobj = decoder(byts)
+      if (obj != null && typeof obj === 'object') {
+        assert.deepStrictEqual(Object.keys(cobj).length, Object.keys(obj).length)
+      } else {
+        assert.deepStrictEqual(obj, cobj)
+      }
+    }
+    return fixtures.length
+  }
+
+  const cmp = (desc, cbfn, bofn) => {
+    write(`\t${desc} (avg ${avgSize.toLocaleString()} b):`)
+    const cborgOps = bench(cbfn)
+    write(` cborg @ ${cborgOps.toLocaleString()} op/s`)
+    const borcOps = bench(bofn)
+    write(` / borc @ ${borcOps.toLocaleString()} op/s`)
+    const percent = Math.round((cborgOps / borcOps) * 1000) / 10
+    write(` = ${(percent).toLocaleString()} %\n`)
+    return percent
+  }
+
+  return [
+    cmp('encode', () => enc(cborgEncode), () => enc(borc.encode)),
+    cmp('decode', () => dec(decode), () => dec(borcDecode))
+  ]
+}
+
+const targetTime = 1000
+const accum = []
+accum.push(runWith('rnd-100', 1000, targetTime, 100, { weights: { CID: 0 } }))
+accum.push(runWith('rnd-300', 1000, targetTime, 300, { weights: { CID: 0 } }))
+accum.push(runWith('rnd-nomap-300', 1000, targetTime, 300, { weights: { CID: 0, map: 0 } }))
+accum.push(runWith('rnd-nolist-300', 1000, targetTime, 300, { weights: { CID: 0, list: 0 } }))
+accum.push(runWith('rnd-nofloat-300', 1000, targetTime, 300, { weights: { CID: 0, float: 0 } }))
+accum.push(runWith('rnd-nomaj7-300', 1000, targetTime, 300, { weights: { CID: 0, float: 0, null: 0, boolean: 0 } }))
+accum.push(runWith('rnd-nostr-300', 1000, targetTime, 300, { weights: { CID: 0, string: 0, bytes: 0 } }))
+accum.push(runWith('rnd-nostrbyts-300', 1000, targetTime, 300, { weights: { CID: 0, string: 0 } }))
+accum.push(runWith('rnd-1000', 1000, targetTime, 1000, { weights: { CID: 0 } }))
+accum.push(runWith('rnd-2000', 1000, targetTime, 2000, { weights: { CID: 0 } }))
+accum.push(runWith('rnd-fil-100', 1000, targetTime, 100, { weights: { float: 0, map: 0, CID: 0 } }))
+accum.push(runWith('rnd-fil-300', 1000, targetTime, 300, { weights: { float: 0, map: 0, CID: 0 } }))
+accum.push(runWith('rnd-fil-500', 1000, targetTime, 500, { weights: { float: 0, map: 0, CID: 0 } }))
+accum.push(runWith('rnd-fil-1000', 1000, targetTime, 1000, { weights: { float: 0, map: 0, CID: 0 } }))
+accum.push(runWith('rnd-fil-2000', 1000, targetTime, 2000, { weights: { float: 0, map: 0, CID: 0 } }))
+console.log(`Avg encode: ${Math.round(accum.reduce((p, c) => p + c[0], 0) / accum.length).toLocaleString()} %`)
+console.log(`Avg decode: ${Math.round(accum.reduce((p, c) => p + c[1], 0) / accum.length).toLocaleString()} %`)