Skip to content
surrealdb.js

Synchronous and Asynchronous CBOR Decoding

Synchronous Decoding

The decode function decodes a CBOR-formatted Uint8Array into a JavaScript value.

Import

import { decode } from "@tai-kun/surrealdb/cbor";

Syntax

function decode(input: Uint8Array, options?: DecodeOptions): unknown;

Arguments

input

A CBOR-formatted Uint8Array to be decoded into a JavaScript value.

options

Decoding options.

mapType?: "Object" | "Map"
This option allows you to choose whether to decode key-value objects as JavaScript plain objects or Map objects. "Object" results in plain objects; "Map" results in Map instances. The default is "Object". Plain object keys can only accept strings or numbers (string | number), while decoding with this option set to "Map" allows keys to accept any decoded value.
reviver?: Reviver | ReviverObject | (Reviver | ReviverObject)[]
This option is used to transform simple or tagged CBOR data items into JavaScript values. Simple data items are limited to values from 0 to 19 and 32 to 255. Tagged data items have tags that are number or bigint values ranging from 0 to 2^64-1. If the function returns the CONTINUE symbol obtained from Symbol.for("@tai-kun/surrealdb/cbor/continue"), subsequent functions will be called. If no conversion can be performed, a SurrealTypeError is thrown.
isSafeMapKey?: (key: unknown, map: Map<unknown, unknown>) => boolean
This option is a function to validate whether a key in a Map object is safe. The function receives two arguments: key, the key’s value, and map, the Map object being validated. If this function returns false, a CborUnsafeMapKeyError is thrown. By default, it considers "__proto__" or "constructor" as unsafe keys. Note that specifying this option completely overrides the default validation. If you want to add your own validation to the default, you should also consider "__proto__" or "constructor" unsafe keys.
isSafeObjectKey?: (key: unknown, obj: Record<string | number, unknown>) => boolean
This option is a function to validate whether a key in a plain object is safe. The function receives two arguments: key, the key’s value, and obj, the plain object being validated. If this function returns false, a CborUnsafeMapKeyError is thrown. By default, it considers "__proto__" or "constructor" as unsafe keys. Note that specifying this option completely overrides the default validation. If you want to add your own validation to the default, you should also consider "__proto__" or "constructor" unsafe keys.
maxDepth?: number
Specifies the maximum depth of objects. The depth increases by 1 each time an object or array is entered. The default value is 64. While the decoding does not use recursion and therefore has no upper limit on depth, it is recommended to not set this value too high.

Return Value

The JavaScript value decoded from the CBOR-formatted Uint8Array.

Example

Decoding with a Map object

import { decode } from "@tai-kun/surrealdb/cbor";


const cbor = new Uint8Array([
  0xa1, // mt: 5, ai: 1
  // key
  0x00, // mt: 0, ai: 0
  // value
  0x00, // mt: 0, ai: 0
]);


const value = decode(cbor, { mapType: "Map" });


console.log(value); // Map(1) { [ 0 ] => 0 }

Asynchronous Decoding

The decodeStream function decodes a CBOR-formatted Uint8Array stream into a JavaScript value.

Import

import { decodeStream } from "@tai-kun/surrealdb/cbor";

Syntax

function decodeStream(
  input: ReadableStream<Uint8Array>,
  options?: DecodeStreamOptions,
): unknown;

Arguments

input

A readable stream of Uint8Arrays. The Fetch API may provide this stream in the body property of a Response object for requests.

options

In addition to the synchronous decoding options, you can specify the following:

signal?: AbortSignal
An abort signal to interrupt the stream.

Return Value

A StatefulPromise that resolves to the JavaScript value.

Example

Fetch API

import { decodeStream } from "@tai-kun/surrealdb/cbor";


const response = await fetch("http://localhost:8000/rpc", {
  method: "POST",
  headers: {
    Accept: "application/cbor",
    // ... more headers
  },
  // ... more properties
});


const result = await decodeStream(response.body);