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 Set
• Plain objects or Map
• Uint8Array
• Simple objects
• Values replaceable by the optional replacer

If a value is not primitive and possesses a toCBOR property that is a function, that function will be prioritized.

options

Encoding options.

replacer?: Replacer | Replacer[]

The encoder encodes most values to CBOR by default, but it may be necessary to replace special values not directly encodable. This option allows implementing replacement logic by specifying a function or an array of functions. If a function returns the CONTINUE symbol obtained with Symbol.for("@tai-kun/surrealdb/cbor/continue"), subsequent functions in the array will be called. A SurrealTypeError is thrown if no replacement is found.

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

This option is a function to validate the safety of keys in Map objects. The function receives two arguments: key, the value of the key, 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 to the default validation, you should also consider "__proto__" or "constructor" as unsafe keys.

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

This option is a function to validate the safety of keys in plain objects. The function receives two arguments: key, the value of the key, 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 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. Although the encoding does not use recursion, there is no upper limit on the depth, but it is recommended not to make it too 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