跳转到内容
surrealdb.js

encode

encode 函数用于将 JavaScript 值编码为 CBOR 格式的 Uint8Array。

导入

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

语法

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

参数

value

要编码为 CBOR 格式 Uint8Array 的 JavaScript 值。value 可以是以下 JavaScript 值：

  • 原生值
    • number
    • bigint
    • string
    • boolean
    • null
    • undefined
  • 拥有 .toCBOR() 方法的对象
  • 数组或 Set
  • 普通对象或 Map
  • Uint8Array
  • Simple 对象
  • 可由可选的 replacer 替换的值

如果值不是原生值，并且具有 toCBOR 属性且该属性为函数，则优先调用该函数。

options

编码选项。

replacer?: Replacer | Replacer[]
编码器默认情况下可以将大多数值编码为 CBOR，但对于不符合此条件的特殊值，可以通过将它们替换为可编码的值来处理。此选项允许通过指定函数或函数数组来实现替换处理。如果函数返回 Symbol.for("@tai-kun/surrealdb/cbor/continue") 获得的 CONTINUE 符号，则将调用后续函数。如果无法替换任何值，则会抛出 SurrealTypeError。
isSafeMapKey?: (key: unknown, map: ReadonlyMap<unknown, unknown>) => boolean
此选项是一个函数，用于验证 Map 对象的键是否安全。该函数接收两个参数：key（键的值）和 map（正在验证的 Map 对象）。如果此函数返回 false，则会抛出 CborUnsafeMapKeyError。默认情况下，它将 "__proto__" 或 "constructor" 视为不安全的键。请注意，指定此选项将完全覆盖默认验证。如果您想在默认验证的基础上添加自定义验证，则应仍然将 "__proto__" 或 "constructor" 视为不安全的键。
isSafeObjectKey?: (key: unknown, obj: { readonly [p: string]: unknown }) => boolean
此选项是一个函数，用于验证普通对象的键是否安全。该函数接收两个参数：key（键的值）和 obj（正在验证的普通对象）。如果此函数返回 false，则会抛出 CborUnsafeMapKeyError。默认情况下，它将 "__proto__" 或 "constructor" 视为不安全的键。请注意，指定此选项将完全覆盖默认验证。如果您想在默认验证的基础上添加自定义验证，则应仍然将 "__proto__" 或 "constructor" 视为不安全的键。
maxDepth?: number
指定对象的最大深度。每次进入对象或数组时，深度都会增加 1。默认值为 64。虽然编码没有使用递归，因此深度没有上限，但建议不要设置过大的值。

返回值

将 JavaScript 值编码为 CBOR 格式的 Uint8Array。

例子

使用 isSafeObjectKey 保护对象键

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


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

使用 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 ]

使用 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