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 formatted objects as JavaScript plain objects or Map objects. Selecting "Object" will decode to a plain object, while "Map" will decode to a Map instance. The default is "Object". Plain object keys can only accept strings or numbers (i.e., string | number), but when using "Map", keys can 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 between 0 and 19 and 32 and 255. Tagged data item tags are number or bigint from 0 to 2^64-1. If the function returns the CONTINUE symbol obtained with Symbol.for("@tai-kun/surrealdb/cbor/continue"), subsequent functions will be called. A SurrealTypeError will be thrown if no transformation could be performed.
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 and map. key is the value of the key, and map is the Map object being validated. If this function returns false, a CborUnsafeMapKeyError will be thrown. By default, it considers "__proto__" or "constructor" as unsafe keys. Note that specifying this option completely overwrites the default validation. If you want to add your own validation to the default validation, you should also consider "__proto__" or "constructor" as 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 and obj. key is the value of the key, and obj is the plain object being validated. If this function returns false, a CborUnsafeMapKeyError will be thrown. By default, it considers "__proto__" or "constructor" as unsafe keys. Note that specifying this option completely overwrites the default validation. If you want to add your own validation to the default validation, you should also consider "__proto__" or "constructor" as 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 decoding doesn’t use recursion and therefore has no inherent depth limit, it’s recommended to avoid excessively large values.

Return Value

The JavaScript value decoded from the CBOR-formatted Uint8Array.

Example

Decoding to 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 Uint8Array. The Fetch API may provide this stream in the body property of the Response object for a request.

options

In addition to the synchronous decoding options, the following option can be specified:

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);