cbor-x

When storing data in databases or files, you can use shared structures to improve efficiency across different encoding sessions. You can provide a structures array to the Encoder constructor, which is automatically updated as new structures are encountered (up to a limit of 64).

To handle persisted data robustly, use the getStructures() and saveStructures(structures) hooks. This allows you to load and save the generated shared structures in a way that is compatible with multiple processes or storage systems. The structures are added incrementally, so an object encoded with an earlier version of the structures can still be decoded with a later version.

import { Encoder, decode, encode } from 'cbor-x';
import { readFileSync, writeFileSync } from 'fs';

let encoder = new Encoder({
	getStructures() {
		// Load structures from a file, DB, or KV store
		return decode(readFileSync('my-shared-structures.cbor')) || [];
	},
	saveStructures(structures) {
		// Persist the updated structures
		writeFileSync('my-shared-structures.cbor', encode(structures))
	},
	structures: []
});

By default, cbor-x can decode CBOR maps into either JavaScript Map objects or plain JavaScript objects. This is controlled by the mapsAsObjects option in the Decoder constructor.

• mapsAsObjects: true (Default): Maps are converted to { key: value } objects. This is often more convenient for standard JSON-like data.
• mapsAsObjects: false: Maps are converted to new Map() instances. This is necessary if your keys are not strings or if you need to preserve the distinction between a key and a property name.

Note: If you use keyMap for decoding, mapsAsObjects is automatically set to true unless explicitly overridden.

// Decodes maps as Map instances
const decoder = new Decoder({ mapsAsObjects: false });
const result = decoder.decode(buffer);
console.log(result instanceof Map); // true

// Decodes maps as plain objects
const decoderObj = new Decoder({ mapsAsObjects: true });
const resultObj = decoderObj.decode(buffer);
console.log(typeof resultObj); // 'object'

When instantiating an Encoder or Decoder, you can pass an options object to customize behavior. Key options include:

• keyMap: An object used to map keys in source Objects/Maps to other keys (including integers) for more efficient encoding or Senml support.
• useRecords: If false, disables the record extension. Objects are stored as CBOR maps (tag 259) and decoded as JS Objects for compatibility.
• structures: An array of structures used for the record extension. This array is modified in place.
• structuredClone: Enables structured cloning extensions for cyclic references and additional built-in types.
• mapsAsObjects: If true, decodes CBOR maps/JS Objects as object properties. If false, decodes as JS Maps. (Note: behavior depends on useRecords).
• useFloat32: Enables 32-bit floating point encoding for non-integers.
• alwaysUseFloat: Forces all numbers (including integers) to be encoded as floats.
• pack: Enables CBOR packing.
• variableMapSize: Uses varying map size definitions for more compact encoding of small objects (slower encoding).
• copyBuffers: If true, copies buffers during decoding instead of providing a slice/view.
• bundleStrings: Uses a custom extension to bundle strings for faster decoding in browsers/Deno.
• useTimestamp32: Encodes JS Dates in 32-bit format (dropping milliseconds).
• sequential: Encodes structures and references them, expecting the decoder to read them in the same order via unpackMultiple.
• largeBigIntToFloat: Encodes bigints larger than 64-bit as float-64 instead of throwing a RangeError.
• useTag259ForMaps: Uses tag 259 for JS Maps. (Note: behavior depends on useRecords).
• tagUint8Array: Uses tag 64 for Uint8Arrays.
• int64AsNumber: Decodes uint64/int64 as standard JS numbers instead of bigint.
• skipFunction: Skips functions during object encoding.