encode

The encode function encodes a JavaScript value into a CBOR-formatted Uint8Array.

Import

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

Syntax

function encode(value: unknown, options?: EncodeOptions): Uint8Array;

Arguments

value

The JavaScript value to encode into a CBOR-formatted Uint8Array. Acceptable JavaScript values for value include:

• Primitive values:
  • number
  • bigint
  • string
  • boolean
  • null
  • undefined
• Objects with a .toCBOR() method
• Arrays or Sets
• Plain objects or Maps
• Uint8Array
• Simple objects
• Values replaceable with the optional replacer

If a value is not primitive and has a toCBOR property that is a function, that function will be called preferentially.

options

Encoding options.

replacer?: Replacer | Replacer[]

While the encoder handles most values to CBOR by default, special values that don’t fit this category can be replaced with encodable ones. This option allows implementing replacement logic by providing a function or an array of functions. If a function returns the CONTINUE symbol obtained via Symbol.for("@tai-kun/surrealdb/cbor/continue"), subsequent functions are called. If no replacement is possible, a SurrealTypeError is thrown.

isSafeMapKey?: (key: unknown, map: ReadonlyMap<unknown, unknown>) => boolean

This option is a function that validates whether a key in a Map object is safe. The function accepts two arguments: key (the key value) and map (the Map object being validated). If this function returns false, a CborUnsafeMapKeyError is thrown. By default, it considers keys "__proto__" or "constructor" as unsafe. Note that specifying this option completely overrides the default validation. If you want to add your own validation to the default, you should still consider "__proto__" or "constructor" unsafe.

isSafeObjectKey?: (key: unknown, obj: { readonly [p: string]: unknown }) => boolean

This option is a function that validates whether a key in a plain object is safe. The function accepts two arguments: key (the key value) and obj (the plain object being validated). If this function returns false, a CborUnsafeMapKeyError is thrown. By default, it considers keys "__proto__" or "constructor" as unsafe. Note that specifying this option completely overrides the default validation. If you want to add your own validation to the default, you should still consider "__proto__" or "constructor" unsafe.

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 encoding doesn’t use recursion, there’s no hard limit on depth, but it’s recommended not to make it excessively large.

Return Value

A Uint8Array containing the CBOR-encoded JavaScript value.

Examples

Protecting Object Keys with isSafeObjectKey

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

encode(
  {
    "API_KEY": "***"
  },
  {
    isSafeObjectKey: k => !["constructor", "__proto__", "API_KEY"].includes(k),
  }
); // throws CborUnsafeMapKeyError

Replacing Symbols with replacer

import { CONTINUE, encode } from "@tai-kun/surrealdb/cbor";

const bytes = encode(Symbol.for("ID"), {
  replacer(o) {
    switch (o) {
      case Symbol.for("ID"):
        return "ID";

      default:
        return CONTINUE;
    }
  },
});

console.log(bytes); // Uint8Array(3) [ 98, 73, 68 ]

Limiting Maximum Depth with maxDepth

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

encode(
  {
    // depth: 1
    a: new Map([
      // depth: 2
      ["b", [
        // depth: 3
        new Set([
          // depth: 4
        ]),
      ]],
    ]),
  },
  {
    maxDepth: 3,
  },
); // throws CborMaxDepthReachedError