cborg 4.5.8 → 5.0.0

package/lib/decode.js

@@ -5,8 +5,9 @@ import { asU8A } from './byte-utils.js'
 
 /**
  * @typedef {import('./token.js').Token} Token
- * @typedef {import('../interface').DecodeOptions} DecodeOptions
- * @typedef {import('../interface').DecodeTokenizer} DecodeTokenizer
+ * @typedef {import('../interface.js').DecodeOptions} DecodeOptions
+ * @typedef {import('../interface.js').DecodeTokenizer} DecodeTokenizer
+ * @typedef {import('../interface.js').TagDecodeControl} TagDecodeControl
  */
 
 const defaultDecodeOptions = {
@@ -133,6 +134,91 @@ function tokenToMap (token, tokeniser, options) {
   return useMaps ? m : obj
 }
 
+/**
+ * Generator that yields [key, value] entries from a CBOR map token.
+ * Used by tag decoders that need to preserve key types (e.g., Tag 259 Map).
+ * @param {Token} token - The map token
+ * @param {DecodeTokenizer} tokeniser
+ * @param {DecodeOptions} options
+ * @returns {Generator<[any, any], void, unknown>}
+ */
+function * tokenToMapEntries (token, tokeniser, options) {
+  for (let i = 0; i < token.value; i++) {
+    const key = tokensToObject(tokeniser, options)
+    if (key === BREAK) {
+      if (token.value === Infinity) {
+        // normal end to indefinite length map
+        break
+      }
+      throw new Error(`${decodeErrPrefix} got unexpected break to lengthed map`)
+    }
+    if (key === DONE) {
+      throw new Error(`${decodeErrPrefix} found map but not enough entries (got ${i} [no key], expected ${token.value})`)
+    }
+    const value = tokensToObject(tokeniser, options)
+    if (value === DONE) {
+      throw new Error(`${decodeErrPrefix} found map but not enough entries (got ${i} [no value], expected ${token.value})`)
+    }
+    yield [key, value]
+  }
+}
+
+/**
+ * Creates a TagDecodeControl object for tag decoders.
+ * @param {DecodeTokenizer} tokeniser
+ * @param {DecodeOptions} options
+ * @returns {TagDecodeControl}
+ */
+function createTagDecodeControl (tokeniser, options) {
+  let called = false
+
+  /**
+   * @type {TagDecodeControl}
+   */
+  const decode = function () {
+    if (called) {
+      throw new Error(`${decodeErrPrefix} tag decode() may only be called once`)
+    }
+    called = true
+    const value = tokensToObject(tokeniser, options)
+    if (value === DONE) {
+      throw new Error(`${decodeErrPrefix} tag content missing`)
+    }
+    if (value === BREAK) {
+      throw new Error(`${decodeErrPrefix} got unexpected break in tag content`)
+    }
+    return value
+  }
+
+  decode.entries = function () {
+    if (called) {
+      throw new Error(`${decodeErrPrefix} tag decode() may only be called once`)
+    }
+    called = true
+
+    // Get the next token and ensure it's a map
+    const token = tokeniser.next()
+    if (!Type.equals(token.type, Type.map)) {
+      throw new Error(`${decodeErrPrefix} entries() requires map content, got ${token.type.name}`)
+    }
+
+    // Collect all entries into an array (ensures full content consumption)
+    const entries = []
+    for (const entry of tokenToMapEntries(token, tokeniser, options)) {
+      entries.push(entry)
+    }
+    return entries
+  }
+
+  // For internal tracking
+  Object.defineProperty(decode, '_called', {
+    get () { return called },
+    enumerable: false
+  })
+
+  return decode
+}
+
 /**
  * @param {DecodeTokenizer} tokeniser
  * @param {DecodeOptions} options
@@ -165,8 +251,12 @@ function tokensToObject (tokeniser, options) {
 
   if (Type.equals(token.type, Type.tag)) {
     if (options.tags && typeof options.tags[token.value] === 'function') {
-      const tagged = tokensToObject(tokeniser, options)
-      return options.tags[token.value](tagged)
+      const decodeControl = createTagDecodeControl(tokeniser, options)
+      const result = options.tags[token.value](decodeControl)
+      if (!decodeControl._called) {
+        throw new Error(`${decodeErrPrefix} tag decoder must call decode() or entries()`)
+      }
+      return result
     }
     throw new Error(`${decodeErrPrefix} tag not supported (${token.value})`)
   }

package/lib/encode.js

@@ -15,13 +15,13 @@ import { encodeTag } from './6tag.js'
 import { encodeFloat, MINOR_FALSE, MINOR_TRUE, MINOR_NULL, MINOR_UNDEFINED } from './7float.js'
 
 /**
- * @typedef {import('../interface').EncodeOptions} EncodeOptions
- * @typedef {import('../interface').OptionalTypeEncoder} OptionalTypeEncoder
- * @typedef {import('../interface').Reference} Reference
- * @typedef {import('../interface').StrictTypeEncoder} StrictTypeEncoder
- * @typedef {import('../interface').TokenTypeEncoder} TokenTypeEncoder
- * @typedef {import('../interface').TokenOrNestedTokens} TokenOrNestedTokens
- * @typedef {import('../interface').ByteWriter} ByteWriter
+ * @typedef {import('../interface.js').EncodeOptions} EncodeOptions
+ * @typedef {import('../interface.js').OptionalTypeEncoder} OptionalTypeEncoder
+ * @typedef {import('../interface.js').Reference} Reference
+ * @typedef {import('../interface.js').StrictTypeEncoder} StrictTypeEncoder
+ * @typedef {import('../interface.js').TokenTypeEncoder} TokenTypeEncoder
+ * @typedef {import('../interface.js').TokenOrNestedTokens} TokenOrNestedTokens
+ * @typedef {import('../interface.js').ByteWriter} ByteWriter
  */
 
 /** @type {EncodeOptions} */

package/lib/extended/extended.js

@@ -0,0 +1,250 @@
+/**
+ * cborg/extended - Extended JavaScript type support for CBOR
+ *
+ * This module provides encode/decode functions that support extended JavaScript
+ * types: Date, RegExp, Map, Set, BigInt, and all TypedArray types.
+ *
+ * Similar to the browser's structured clone algorithm, this module prioritises
+ * JavaScript type preservation using standard CBOR tags. Unlike base cborg
+ * (designed for IPLD/content-addressed data), types round-trip with full fidelity.
+ */
+
+import { encode as _encode, decode as _decode } from '../../cborg.js'
+import {
+  // BigInt
+  structBigIntEncoder,
+  bigIntDecoder,
+  bigNegIntDecoder,
+
+  // Date
+  dateEncoder,
+  dateDecoder,
+
+  // RegExp
+  regExpEncoder,
+  regExpDecoder,
+
+  // Set
+  setEncoder,
+  setDecoder,
+
+  // Map
+  mapEncoder,
+  mapDecoder,
+
+  // Error
+  errorEncoder,
+  errorDecoder,
+
+  // Negative zero
+  negativeZeroEncoder,
+
+  // TypedArrays
+  uint8ArrayEncoder,
+  uint8ArrayDecoder,
+  uint8ClampedArrayEncoder,
+  uint8ClampedArrayDecoder,
+  int8ArrayEncoder,
+  int8ArrayDecoder,
+  uint16ArrayEncoder,
+  uint16ArrayDecoder,
+  uint32ArrayEncoder,
+  uint32ArrayDecoder,
+  int16ArrayEncoder,
+  int16ArrayDecoder,
+  int32ArrayEncoder,
+  int32ArrayDecoder,
+  float32ArrayEncoder,
+  float32ArrayDecoder,
+  float64ArrayEncoder,
+  float64ArrayDecoder,
+  bigUint64ArrayEncoder,
+  bigUint64ArrayDecoder,
+  bigInt64ArrayEncoder,
+  bigInt64ArrayDecoder,
+
+  // Tag constants
+  TAG_DATE_EPOCH,
+  TAG_BIGINT_POS,
+  TAG_BIGINT_NEG,
+  TAG_OBJECT_CLASS,
+  TAG_UINT8_ARRAY,
+  TAG_UINT8_CLAMPED_ARRAY,
+  TAG_INT8_ARRAY,
+  TAG_UINT16_ARRAY_LE,
+  TAG_UINT32_ARRAY_LE,
+  TAG_BIGUINT64_ARRAY_LE,
+  TAG_INT16_ARRAY_LE,
+  TAG_INT32_ARRAY_LE,
+  TAG_BIGINT64_ARRAY_LE,
+  TAG_FLOAT32_ARRAY_LE,
+  TAG_FLOAT64_ARRAY_LE,
+  TAG_SET,
+  TAG_MAP,
+  TAG_REGEXP
+} from '../taglib.js'
+
+/**
+ * @typedef {import('../../interface.js').EncodeOptions} EncodeOptions
+ * @typedef {import('../../interface.js').DecodeOptions} DecodeOptions
+ */
+
+/**
+ * Type encoders for all supported types
+ */
+const typeEncoders = {
+  number: negativeZeroEncoder,
+  bigint: structBigIntEncoder,
+  Date: dateEncoder,
+  RegExp: regExpEncoder,
+  Set: setEncoder,
+  Map: mapEncoder,
+  Error: errorEncoder,
+  EvalError: errorEncoder,
+  RangeError: errorEncoder,
+  ReferenceError: errorEncoder,
+  SyntaxError: errorEncoder,
+  TypeError: errorEncoder,
+  URIError: errorEncoder,
+  Uint8Array: uint8ArrayEncoder,
+  Uint8ClampedArray: uint8ClampedArrayEncoder,
+  Int8Array: int8ArrayEncoder,
+  Uint16Array: uint16ArrayEncoder,
+  Uint32Array: uint32ArrayEncoder,
+  Int16Array: int16ArrayEncoder,
+  Int32Array: int32ArrayEncoder,
+  Float32Array: float32ArrayEncoder,
+  Float64Array: float64ArrayEncoder,
+  BigUint64Array: bigUint64ArrayEncoder,
+  BigInt64Array: bigInt64ArrayEncoder
+}
+
+/**
+ * Tag decoders for all supported tags
+ */
+const tags = {
+  [TAG_DATE_EPOCH]: dateDecoder,
+  [TAG_BIGINT_POS]: bigIntDecoder,
+  [TAG_BIGINT_NEG]: bigNegIntDecoder,
+  [TAG_OBJECT_CLASS]: errorDecoder,
+  [TAG_REGEXP]: regExpDecoder,
+  [TAG_SET]: setDecoder,
+  [TAG_MAP]: mapDecoder,
+  [TAG_UINT8_ARRAY]: uint8ArrayDecoder,
+  [TAG_UINT8_CLAMPED_ARRAY]: uint8ClampedArrayDecoder,
+  [TAG_INT8_ARRAY]: int8ArrayDecoder,
+  [TAG_UINT16_ARRAY_LE]: uint16ArrayDecoder,
+  [TAG_UINT32_ARRAY_LE]: uint32ArrayDecoder,
+  [TAG_INT16_ARRAY_LE]: int16ArrayDecoder,
+  [TAG_INT32_ARRAY_LE]: int32ArrayDecoder,
+  [TAG_FLOAT32_ARRAY_LE]: float32ArrayDecoder,
+  [TAG_FLOAT64_ARRAY_LE]: float64ArrayDecoder,
+  [TAG_BIGUINT64_ARRAY_LE]: bigUint64ArrayDecoder,
+  [TAG_BIGINT64_ARRAY_LE]: bigInt64ArrayDecoder
+}
+
+/**
+ * Encode a value to CBOR with extended JavaScript type support.
+ *
+ * Supported types beyond standard cborg:
+ * - Date (Tag 1)
+ * - RegExp (Tag 21066)
+ * - Map (Tag 259)
+ * - Set (Tag 258)
+ * - BigInt (Tags 2/3, always tagged)
+ * - All TypedArrays (Tags 64-87)
+ *
+ * @param {any} obj - Value to encode
+ * @param {EncodeOptions} [options] - Additional options (merged with extended defaults)
+ * @returns {Uint8Array}
+ */
+export function encode (obj, options = {}) {
+  return _encode(obj, {
+    mapSorter: undefined, // Preserve insertion order for type fidelity (like structured clone)
+    ...options,
+    typeEncoders: { ...typeEncoders, ...options.typeEncoders }
+  })
+}
+
+/**
+ * Decode CBOR to a value with extended JavaScript type support.
+ *
+ * @param {Uint8Array} data - CBOR data to decode
+ * @param {DecodeOptions} [options] - Additional options (merged with extended defaults)
+ * @returns {any}
+ */
+export function decode (data, options = {}) {
+  return _decode(data, {
+    ...options,
+    tags: { ...tags, ...options.tags }
+    // useMaps defaults to false: plain objects decode as objects, Tag 259 Maps decode as Maps.
+    // The mapDecoder uses decode.entries() to preserve key types regardless of useMaps setting.
+  })
+}
+
+// Re-export all taglib components for users who want to customize
+export {
+  // Tag constants
+  TAG_DATE_EPOCH,
+  TAG_BIGINT_POS,
+  TAG_BIGINT_NEG,
+  TAG_UINT8_ARRAY,
+  TAG_UINT8_CLAMPED_ARRAY,
+  TAG_INT8_ARRAY,
+  TAG_UINT16_ARRAY_LE,
+  TAG_UINT32_ARRAY_LE,
+  TAG_BIGUINT64_ARRAY_LE,
+  TAG_INT16_ARRAY_LE,
+  TAG_INT32_ARRAY_LE,
+  TAG_BIGINT64_ARRAY_LE,
+  TAG_FLOAT32_ARRAY_LE,
+  TAG_FLOAT64_ARRAY_LE,
+  TAG_SET,
+  TAG_MAP,
+  TAG_REGEXP,
+
+  // BigInt
+  structBigIntEncoder,
+  bigIntDecoder,
+  bigNegIntDecoder,
+
+  // Date
+  dateEncoder,
+  dateDecoder,
+
+  // RegExp
+  regExpEncoder,
+  regExpDecoder,
+
+  // Set
+  setEncoder,
+  setDecoder,
+
+  // Map
+  mapEncoder,
+  mapDecoder,
+
+  // TypedArrays
+  uint8ArrayEncoder,
+  uint8ArrayDecoder,
+  uint8ClampedArrayEncoder,
+  uint8ClampedArrayDecoder,
+  int8ArrayEncoder,
+  int8ArrayDecoder,
+  uint16ArrayEncoder,
+  uint16ArrayDecoder,
+  uint32ArrayEncoder,
+  uint32ArrayDecoder,
+  int16ArrayEncoder,
+  int16ArrayDecoder,
+  int32ArrayEncoder,
+  int32ArrayDecoder,
+  float32ArrayEncoder,
+  float32ArrayDecoder,
+  float64ArrayEncoder,
+  float64ArrayDecoder,
+  bigUint64ArrayEncoder,
+  bigUint64ArrayDecoder,
+  bigInt64ArrayEncoder,
+  bigInt64ArrayDecoder
+}

package/lib/json/decode.js

@@ -4,8 +4,8 @@ import { decodeCodePointsArray } from '../byte-utils.js'
 import { decodeErrPrefix } from '../common.js'
 
 /**
- * @typedef {import('../../interface').DecodeOptions} DecodeOptions
- * @typedef {import('../../interface').DecodeTokenizer} DecodeTokenizer
+ * @typedef {import('../../interface.js').DecodeOptions} DecodeOptions
+ * @typedef {import('../../interface.js').DecodeTokenizer} DecodeTokenizer
  */
 
 /**

package/lib/json/encode.js

@@ -4,9 +4,9 @@ import { encodeErrPrefix } from '../common.js'
 import { asU8A, fromString } from '../byte-utils.js'
 
 /**
- * @typedef {import('../../interface').EncodeOptions} EncodeOptions
- * @typedef {import('../../interface').ByteWriter} ByteWriter
- * @typedef {import('../token').Token} Token
+ * @typedef {import('../../interface.js').EncodeOptions} EncodeOptions
+ * @typedef {import('../../interface.js').ByteWriter} ByteWriter
+ * @typedef {import('../token.js').Token} Token
  */
 
 class JSONEncoder extends Array {

package/lib/jump.js

@@ -11,7 +11,7 @@ import { decodeErrPrefix } from './common.js'
 import { fromArray } from './byte-utils.js'
 
 /**
- * @typedef {import('../interface').DecodeOptions} DecodeOptions
+ * @typedef {import('../interface.js').DecodeOptions} DecodeOptions
  */
 
 /**

package/lib/length.js

@@ -2,9 +2,9 @@ import { makeCborEncoders, objectToTokens } from './encode.js'
 import { quickEncodeToken } from './jump.js'
 
 /**
- * @typedef {import('../interface').EncodeOptions} EncodeOptions
- * @typedef {import('../interface').TokenTypeEncoder} TokenTypeEncoder
- * @typedef {import('../interface').TokenOrNestedTokens} TokenOrNestedTokens
+ * @typedef {import('../interface.js').EncodeOptions} EncodeOptions
+ * @typedef {import('../interface.js').TokenTypeEncoder} TokenTypeEncoder
+ * @typedef {import('../interface.js').TokenOrNestedTokens} TokenOrNestedTokens
  */
 
 const cborEncoders = makeCborEncoders()