cborg 4.4.1 → 4.5.1

package/lib/7float.js

@@ -6,7 +6,7 @@ import { decodeErrPrefix } from './common.js'
 import { encodeUint } from './0uint.js'
 
 /**
- * @typedef {import('./bl.js').Bl} Bl
+ * @typedef {import('../interface').ByteWriter} ByteWriter
  * @typedef {import('../interface').DecodeOptions} DecodeOptions
  * @typedef {import('../interface').EncodeOptions} EncodeOptions
  */
@@ -98,21 +98,21 @@ export function decodeFloat64 (data, pos, _minor, options) {
 }
 
 /**
- * @param {Bl} buf
+ * @param {ByteWriter} writer
  * @param {Token} token
  * @param {EncodeOptions} options
  */
-export function encodeFloat (buf, token, options) {
+export function encodeFloat (writer, token, options) {
   const float = token.value
 
   if (float === false) {
-    buf.push([Type.float.majorEncoded | MINOR_FALSE])
+    writer.push([Type.float.majorEncoded | MINOR_FALSE])
   } else if (float === true) {
-    buf.push([Type.float.majorEncoded | MINOR_TRUE])
+    writer.push([Type.float.majorEncoded | MINOR_TRUE])
   } else if (float === null) {
-    buf.push([Type.float.majorEncoded | MINOR_NULL])
+    writer.push([Type.float.majorEncoded | MINOR_NULL])
   } else if (float === undefined) {
-    buf.push([Type.float.majorEncoded | MINOR_UNDEFINED])
+    writer.push([Type.float.majorEncoded | MINOR_UNDEFINED])
   } else {
     let decoded
     let success = false
@@ -121,14 +121,14 @@ export function encodeFloat (buf, token, options) {
       decoded = readFloat16(ui8a, 1)
       if (float === decoded || Number.isNaN(float)) {
         ui8a[0] = 0xf9
-        buf.push(ui8a.slice(0, 3))
+        writer.push(ui8a.slice(0, 3))
         success = true
       } else {
         encodeFloat32(float)
         decoded = readFloat32(ui8a, 1)
         if (float === decoded) {
           ui8a[0] = 0xfa
-          buf.push(ui8a.slice(0, 5))
+          writer.push(ui8a.slice(0, 5))
           success = true
         }
       }
@@ -137,7 +137,7 @@ export function encodeFloat (buf, token, options) {
       encodeFloat64(float)
       decoded = readFloat64(ui8a, 1)
       ui8a[0] = 0xfb
-      buf.push(ui8a.slice(0, 9))
+      writer.push(ui8a.slice(0, 9))
     }
   }
 }

package/lib/bl.js

@@ -122,3 +122,49 @@ export class Bl {
     return byts
   }
 }
+
+/**
+ * U8Bl is a buffer list that writes directly to a user-provided Uint8Array.
+ * It provides the same interface as Bl but writes to a fixed destination.
+ */
+export class U8Bl {
+  /**
+   * @param {Uint8Array} dest
+   */
+  constructor (dest) {
+    this.dest = dest
+    /** @type {number} */
+    this.cursor = 0
+    // chunks is for interface compatibility with Bl - encode.js checks chunks.length
+    // as a sanity check for pre-calculated sizes. For U8Bl this is always [dest].
+    /** @type {Uint8Array[]} */
+    this.chunks = [dest]
+  }
+
+  reset () {
+    this.cursor = 0
+  }
+
+  /**
+   * @param {Uint8Array|number[]} bytes
+   */
+  push (bytes) {
+    if (this.cursor + bytes.length > this.dest.length) {
+      throw new Error('write out of bounds, destination buffer is too small')
+    }
+    this.dest.set(bytes, this.cursor)
+    this.cursor += bytes.length
+  }
+
+  /**
+   * @param {boolean} [reset]
+   * @returns {Uint8Array}
+   */
+  toBytes (reset = false) {
+    const byts = this.dest.subarray(0, this.cursor)
+    if (reset) {
+      this.reset()
+    }
+    return byts
+  }
+}

package/lib/encode.js

@@ -1,6 +1,6 @@
 import { is } from './is.js'
 import { Token, Type } from './token.js'
-import { Bl } from './bl.js'
+import { Bl, U8Bl } from './bl.js'
 import { encodeErrPrefix } from './common.js'
 import { quickEncodeToken } from './jump.js'
 import { asU8A, compare } from './byte-utils.js'
@@ -21,6 +21,7 @@ import { encodeFloat } from './7float.js'
  * @typedef {import('../interface').StrictTypeEncoder} StrictTypeEncoder
  * @typedef {import('../interface').TokenTypeEncoder} TokenTypeEncoder
  * @typedef {import('../interface').TokenOrNestedTokens} TokenOrNestedTokens
+ * @typedef {import('../interface').ByteWriter} ByteWriter
  */
 
 /** @type {EncodeOptions} */
@@ -53,7 +54,7 @@ export function makeCborEncoders () {
 
 const cborEncoders = makeCborEncoders()
 
-const buf = new Bl()
+const defaultWriter = new Bl()
 
 /** @implements {Reference} */
 class Ref {
@@ -452,18 +453,18 @@ function encodeRfc8949 (data) {
 }
 
 /**
- * @param {Bl} buf
+ * @param {ByteWriter} writer
  * @param {TokenOrNestedTokens} tokens
  * @param {TokenTypeEncoder[]} encoders
  * @param {EncodeOptions} options
  */
-function tokensToEncoded (buf, tokens, encoders, options) {
+function tokensToEncoded (writer, tokens, encoders, options) {
   if (Array.isArray(tokens)) {
     for (const token of tokens) {
-      tokensToEncoded(buf, token, encoders, options)
+      tokensToEncoded(writer, token, encoders, options)
     }
   } else {
-    encoders[tokens.type.major](buf, tokens, options)
+    encoders[tokens.type.major](writer, tokens, options)
   }
 }
 
@@ -471,31 +472,43 @@ function tokensToEncoded (buf, tokens, encoders, options) {
  * @param {any} data
  * @param {TokenTypeEncoder[]} encoders
  * @param {EncodeOptions} options
+ * @param {Uint8Array} [destination]
  * @returns {Uint8Array}
  */
-function encodeCustom (data, encoders, options) {
+function encodeCustom (data, encoders, options, destination) {
+  // arg ordering is different to encodeInto for backward compatibility
+  const hasDest = destination instanceof Uint8Array
+  let writeTo = hasDest ? new U8Bl(destination) : defaultWriter
+
   const tokens = objectToTokens(data, options)
   if (!Array.isArray(tokens) && options.quickEncodeToken) {
     const quickBytes = options.quickEncodeToken(tokens)
     if (quickBytes) {
+      if (hasDest) {
+        // Copy quick bytes into destination buffer
+        writeTo.push(quickBytes)
+        return writeTo.toBytes()
+      }
       return quickBytes
     }
     const encoder = encoders[tokens.type.major]
     if (encoder.encodedSize) {
       const size = encoder.encodedSize(tokens, options)
-      const buf = new Bl(size)
-      encoder(buf, tokens, options)
+      if (!hasDest) {
+        writeTo = new Bl(size)
+      }
+      encoder(writeTo, tokens, options)
       /* c8 ignore next 4 */
       // this would be a problem with encodedSize() functions
-      if (buf.chunks.length !== 1) {
+      if (writeTo.chunks.length !== 1) {
         throw new Error(`Unexpected error: pre-calculated length for ${tokens} was wrong`)
       }
-      return asU8A(buf.chunks[0])
+      return hasDest ? writeTo.toBytes() : asU8A(writeTo.chunks[0])
     }
   }
-  buf.reset()
-  tokensToEncoded(buf, tokens, encoders, options)
-  return buf.toBytes(true)
+  writeTo.reset()
+  tokensToEncoded(writeTo, tokens, encoders, options)
+  return writeTo.toBytes(true)
 }
 
 /**
@@ -508,4 +521,16 @@ function encode (data, options) {
   return encodeCustom(data, cborEncoders, options)
 }
 
-export { objectToTokens, encode, encodeCustom, Ref }
+/**
+ * @param {any} data
+ * @param {Uint8Array} destination
+ * @param {EncodeOptions} [options]
+ * @returns {{ written: number }}
+ */
+function encodeInto (data, destination, options) {
+  options = Object.assign({}, defaultEncodeOptions, options)
+  const result = encodeCustom(data, cborEncoders, options, destination)
+  return { written: result.length }
+}
+
+export { objectToTokens, encode, encodeCustom, encodeInto, Ref }

package/lib/is.js

@@ -3,24 +3,10 @@
 // check is expensive, and unnecessary for our purposes. The values returned
 // are compatible with @sindresorhus/is, however.
 
-const typeofs = [
-  'string',
-  'number',
-  'bigint',
-  'symbol'
-]
-
+// Types that reach getObjectType() - excludes types with fast-paths above:
+// primitives (typeof), Array (isArray), Uint8Array (instanceof), plain Object (constructor)
 const objectTypeNames = [
-  'Function',
-  'Generator',
-  'AsyncGenerator',
-  'GeneratorFunction',
-  'AsyncGeneratorFunction',
-  'AsyncFunction',
-  'Observable',
-  'Array',
-  'Buffer',
-  'Object',
+  'Object', // for Object.create(null) and other non-plain objects
   'RegExp',
   'Date',
   'Error',
@@ -35,7 +21,6 @@ const objectTypeNames = [
   'URL',
   'HTMLElement',
   'Int8Array',
-  'Uint8Array',
   'Uint8ClampedArray',
   'Int16Array',
   'Uint16Array',
@@ -62,19 +47,23 @@ export function is (value) {
     return 'boolean'
   }
   const typeOf = typeof value
-  if (typeofs.includes(typeOf)) {
+  if (typeOf === 'string' || typeOf === 'number' || typeOf === 'bigint' || typeOf === 'symbol') {
     return typeOf
   }
-  /* c8 ignore next 4 */
-  // not going to bother testing this, it's not going to be valid anyway
+  /* c8 ignore next 3 */
   if (typeOf === 'function') {
     return 'Function'
   }
   if (Array.isArray(value)) {
     return 'Array'
   }
-  if (isBuffer(value)) {
-    return 'Buffer'
+  // Also catches Node.js Buffer which extends Uint8Array
+  if (value instanceof Uint8Array) {
+    return 'Uint8Array'
+  }
+  // Fast path for plain objects (most common case after primitives/arrays/bytes)
+  if (value.constructor === Object) {
+    return 'Object'
   }
   const objectType = getObjectType(value)
   if (objectType) {
@@ -84,14 +73,6 @@ export function is (value) {
   return 'Object'
 }
 
-/**
- * @param {any} value
- * @returns {boolean}
- */
-function isBuffer (value) {
-  return value && value.constructor && value.constructor.isBuffer && value.constructor.isBuffer.call(null, value)
-}
-
 /**
  * @param {any} value
  * @returns {string|undefined}

package/lib/json/encode.js

@@ -5,8 +5,8 @@ import { asU8A, fromString } from '../byte-utils.js'
 
 /**
  * @typedef {import('../../interface').EncodeOptions} EncodeOptions
+ * @typedef {import('../../interface').ByteWriter} ByteWriter
  * @typedef {import('../token').Token} Token
- * @typedef {import('../bl').Bl} Bl
  */
 
 class JSONEncoder extends Array {
@@ -17,7 +17,7 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} buf
+   * @param {ByteWriter} buf
    */
   prefix (buf) {
     const recurs = this.inRecursive[this.inRecursive.length - 1]
@@ -42,7 +42,7 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} buf
+   * @param {ByteWriter} buf
    * @param {Token} token
    */
   [Type.uint.major] (buf, token) {
@@ -56,7 +56,7 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} buf
+   * @param {ByteWriter} buf
    * @param {Token} token
    */
   [Type.negint.major] (buf, token) {
@@ -65,7 +65,7 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} _buf
+   * @param {ByteWriter} _buf
    * @param {Token} _token
    */
   [Type.bytes.major] (_buf, _token) {
@@ -73,7 +73,7 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} buf
+   * @param {ByteWriter} buf
    * @param {Token} token
    */
   [Type.string.major] (buf, token) {
@@ -86,7 +86,7 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} buf
+   * @param {ByteWriter} buf
    * @param {Token} _token
    */
   [Type.array.major] (buf, _token) {
@@ -96,7 +96,7 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} buf
+   * @param {ByteWriter} buf
    * @param {Token} _token
    */
   [Type.map.major] (buf, _token) {
@@ -106,13 +106,13 @@ class JSONEncoder extends Array {
   }
 
   /**
-   * @param {Bl} _buf
+   * @param {ByteWriter} _buf
    * @param {Token} _token
    */
   [Type.tag.major] (_buf, _token) {}
 
   /**
-   * @param {Bl} buf
+   * @param {ByteWriter} buf
    * @param {Token} token
    */
   [Type.float.major] (buf, token) {

package/package.json

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

package/test/test-0uint.js

@@ -2,11 +2,17 @@
 
 import * as chai from 'chai'
 
-import { decode, encode } from '../cborg.js'
+import { decode, encode, encodeInto } from '../cborg.js'
 import { fromHex, toHex } from '../lib/byte-utils.js'
 
 const { assert } = chai
 
+// Helper to get encoded bytes from encodeInto (which returns { written })
+const encodeIntoBytes = (data, dest) => {
+  const { written } = encodeInto(data, dest)
+  return dest.subarray(0, written)
+}
+
 // some from https://github.com/PJK/libcbor
 
 const fixtures = [
@@ -27,6 +33,8 @@ const fixtures = [
   { data: '1bffffffffffffffff', expected: BigInt('18446744073709551615'), type: 'uint64' }
 ]
 
+const fixedDest = new Uint8Array(1024)
+
 describe('uint', () => {
   describe('decode', () => {
     for (const fixture of fixtures) {
@@ -53,8 +61,10 @@ describe('uint', () => {
       it(`should encode ${fixture.type}=${fixture.expected}`, () => {
         if (fixture.strict === false) {
           assert.notStrictEqual(toHex(encode(fixture.expected)), fixture.data, `encode ${fixture.type} !strict`)
+          assert.notStrictEqual(toHex(encodeIntoBytes(fixture.expected, fixedDest)), fixture.data, `encode ${fixture.type} !strict`)
         } else {
           assert.strictEqual(toHex(encode(fixture.expected)), fixture.data, `encode ${fixture.type}`)
+          assert.strictEqual(toHex(encodeIntoBytes(fixture.expected, fixedDest)), fixture.data, `encode ${fixture.type}`)
         }
       })
     }
@@ -66,6 +76,7 @@ describe('uint', () => {
       if (fixture.strict !== false) {
         it(`should roundtrip ${fixture.type}=${fixture.expected}`, () => {
           assert.ok(decode(encode(fixture.expected)) === fixture.expected, `roundtrip ${fixture.type}`)
+          assert.ok(decode(encodeIntoBytes(fixture.expected, fixedDest)) === fixture.expected, `roundtrip ${fixture.type}`)
         })
       }
     }

package/test/test-1negint.js

@@ -2,11 +2,17 @@
 
 import * as chai from 'chai'
 
-import { decode, encode } from '../cborg.js'
+import { decode, encode, encodeInto } from '../cborg.js'
 import { fromHex, toHex } from '../lib/byte-utils.js'
 
 const { assert } = chai
 
+// Helper to get encoded bytes from encodeInto (which returns { written })
+const encodeIntoBytes = (data, dest) => {
+  const { written } = encodeInto(data, dest)
+  return dest.subarray(0, written)
+}
+
 // some from https://github.com/PJK/libcbor
 
 const fixtures = [
@@ -28,6 +34,8 @@ const fixtures = [
   { data: '3bffffffffffffffff', expected: BigInt('-18446744073709551616'), type: 'negint64' }
 ]
 
+const fixedDest = new Uint8Array(1024)
+
 describe('negint', () => {
   describe('decode', () => {
     for (const fixture of fixtures) {
@@ -48,8 +56,10 @@ describe('negint', () => {
       it(`should encode ${fixture.type}=${fixture.expected}`, () => {
         if (fixture.strict === false) {
           assert.notStrictEqual(toHex(encode(fixture.expected)), fixture.data, `encode ${fixture.type} !strict`)
+          assert.notStrictEqual(toHex(encodeIntoBytes(fixture.expected, fixedDest)), fixture.data, `encode ${fixture.type} !strict`)
         } else {
           assert.strictEqual(toHex(encode(fixture.expected)), fixture.data, `encode ${fixture.type}`)
+          assert.strictEqual(toHex(encodeIntoBytes(fixture.expected, fixedDest)), fixture.data, `encode ${fixture.type}`)
         }
       })
     }
@@ -60,6 +70,7 @@ describe('negint', () => {
     for (const fixture of fixtures) {
       it(`should roundtrip ${fixture.type}=${fixture.expected}`, () => {
         assert.ok(decode(encode(fixture.expected)) === fixture.expected, `roundtrip ${fixture.type}`)
+        assert.ok(decode(encodeIntoBytes(fixture.expected, fixedDest)) === fixture.expected, `roundtrip ${fixture.type}`)
       })
     }
   })

package/test/test-2bytes.js

@@ -2,11 +2,17 @@
 
 import * as chai from 'chai'
 
-import { decode, encode } from '../cborg.js'
+import { decode, encode, encodeInto } from '../cborg.js'
 import { useBuffer, fromHex, toHex } from '../lib/byte-utils.js'
 
 const { assert } = chai
 
+// Helper to get encoded bytes from encodeInto (which returns { written })
+const encodeIntoBytes = (data, dest) => {
+  const { written } = encodeInto(data, dest)
+  return dest.subarray(0, written)
+}
+
 // some from https://github.com/PJK/libcbor
 
 const fixtures = [
@@ -42,6 +48,8 @@ const fixtures = [
   }
 ]
 
+const fixedDest = new Uint8Array(65536 + 8)
+
 // fill up byte arrays we can validate in strict mode, the minimal size for each
 // excluding 64-bit because 4G is just too big
 ;(() => {
@@ -111,8 +119,10 @@ describe('bytes', () => {
           assert.throws(() => encode(data), Error, /^CBOR encode error: number too large to encode \(-\d+\)$/)
         } else if (fixture.strict === false) {
           assert.notStrictEqual(toHex(encode(data)), expectedHex, `encode ${fixture.type} !strict`)
+          assert.notStrictEqual(toHex(encodeIntoBytes(data, fixedDest)), expectedHex, `encode ${fixture.type} !strict`)
         } else {
           assert.strictEqual(toHex(encode(data)), expectedHex, `encode ${fixture.type}`)
+          assert.strictEqual(toHex(encodeIntoBytes(data, fixedDest)), expectedHex, `encode ${fixture.type}`)
         }
       })
     }

package/test/test-3string.js

@@ -2,11 +2,17 @@
 
 import * as chai from 'chai'
 
-import { decode, encode } from '../cborg.js'
+import { decode, encode, encodeInto } from '../cborg.js'
 import { fromHex, toHex } from '../lib/byte-utils.js'
 
 const { assert } = chai
 
+// Helper to get encoded bytes from encodeInto (which returns { written })
+const encodeIntoBytes = (data, dest) => {
+  const { written } = encodeInto(data, dest)
+  return dest.subarray(0, written)
+}
+
 // some from https://github.com/PJK/libcbor
 
 const fixtures = [
@@ -52,6 +58,8 @@ const fixtures = [
   }
 ]
 
+const fixedDest = new Uint8Array(65536 + 8)
+
 // fill up byte arrays converted to strings so we can validate in strict mode,
 // the minimal size for each excluding 64-bit because 4G is just too big
 ;(() => {
@@ -131,8 +139,10 @@ describe('string', () => {
           assert.throws(() => encode(data), Error, /^CBOR encode error: number too large to encode \(-\d+\)$/)
         } else if (fixture.strict === false) {
           assert.notStrictEqual(toHex(encode(data)), expectedHex, `encode ${fixture.type} !strict`)
+          assert.notStrictEqual(toHex(encodeIntoBytes(data, fixedDest)), expectedHex, `encode ${fixture.type} !strict`)
         } else {
           assert.strictEqual(toHex(encode(data)), expectedHex, `encode ${fixture.type}`)
+          assert.strictEqual(toHex(encodeIntoBytes(data, fixedDest)), expectedHex, `encode ${fixture.type}`)
         }
       })
 

package/test/test-4array.js

@@ -2,11 +2,17 @@
 
 import * as chai from 'chai'
 
-import { decode, encode } from '../cborg.js'
+import { decode, encode, encodeInto } from '../cborg.js'
 import { fromHex, toHex } from '../lib/byte-utils.js'
 
 const { assert } = chai
 
+// Helper to get encoded bytes from encodeInto (which returns { written })
+const encodeIntoBytes = (data, dest) => {
+  const { written } = encodeInto(data, dest)
+  return dest.subarray(0, written)
+}
+
 const fixtures = [
   { data: '80', expected: [], type: 'array empty' },
   { data: '8102', expected: [2], type: 'array 1 compact uint' },
@@ -35,6 +41,8 @@ const fixtures = [
   { data: '9b000000000000000403040506', expected: [3, 4, 5, 6], type: 'array 4 ints, length64', strict: false }
 ]
 
+const fixedDest = new Uint8Array(1024)
+
 describe('array', () => {
   describe('decode', () => {
     for (const fixture of fixtures) {
@@ -63,8 +71,10 @@ describe('array', () => {
           assert.throws(encode.bind(null, fixture.expected), Error, /^CBOR encode error: number too large to encode \(\d+\)$/)
         } else if (fixture.strict === false) {
           assert.notDeepEqual(toHex(encode(fixture.expected)), fixture.data, `encode ${fixture.type} !strict`)
+          assert.notDeepEqual(toHex(encodeIntoBytes(fixture.expected, fixedDest)), fixture.data, `encode ${fixture.type} !strict`)
         } else {
           assert.strictEqual(toHex(encode(fixture.expected)), fixture.data, `encode ${fixture.type}`)
+          assert.strictEqual(toHex(encodeIntoBytes(fixture.expected, fixedDest)), fixture.data, `encode ${fixture.type}`)
         }
       })
     }

package/test/test-5map.js

@@ -2,11 +2,17 @@
 
 import * as chai from 'chai'
 
-import { decode, encode } from '../cborg.js'
+import { decode, encode, encodeInto } from '../cborg.js'
 import { fromHex, toHex } from '../lib/byte-utils.js'
 
 const { assert } = chai
 
+// Helper to get encoded bytes from encodeInto (which returns { written })
+const encodeIntoBytes = (data, dest) => {
+  const { written } = encodeInto(data, dest)
+  return dest.subarray(0, written)
+}
+
 // TODO: reject duplicate keys from encoded form
 
 const fixtures = [
@@ -133,6 +139,8 @@ const fixtures = [
   { data: 'bb0000000000000001616101', expected: { a: 1 }, type: 'map 1 pair, length64', strict: false }
 ]
 
+const fixedDest = new Uint8Array(1024)
+
 function toMap (arr) {
   const m = new Map()
   for (const [key, value] of arr) {
@@ -205,9 +213,9 @@ describe('map', () => {
         if (fixture.unsafe) {
           assert.throws(encode.bind(null, toEncode), Error, /^CBOR encode error: number too large to encode \(\d+\)$/)
         } else if (fixture.strict === false || fixture.roundtrip === false) {
-          assert.notDeepEqual(toHex(encode(toEncode)), fixture.data, `encode ${fixture.type} !strict`)
+          assert.notDeepEqual(toHex(encodeIntoBytes(toEncode, fixedDest)), fixture.data, `encode ${fixture.type} !strict`)
         } else {
-          assert.strictEqual(toHex(encode(toEncode)), fixture.data, `encode ${fixture.type}`)
+          assert.strictEqual(toHex(encodeIntoBytes(toEncode, fixedDest)), fixture.data, `encode ${fixture.type}`)
         }
       })
     }