컨텐츠로 건너뛰기
surrealdb.js

encode

encode 함수는 JavaScript 값을 CBOR 형식의 Uint8Array로 인코딩하는 함수입니다.

import

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의 두 인수를 받습니다. key는 키 값이고, map은 검증 중인 Map 객체입니다. 이 함수가 false를 반환하면 CborUnsafeMapKeyError가 발생합니다. 기본적으로는 "__proto__" 또는 "constructor"를 안전하지 않은 키로 판단합니다. 이 옵션을 지정하면 기본 검증이 완전히 덮어쓰여짐에 유의하십시오. 기본 검증에 자체 검증을 추가하려면 "__proto__" 또는 "constructor"도 안전하지 않은 키로 판단해야 합니다.
isSafeObjectKey?: (key: unknown, obj: { readonly [p: string]: unknown }) => boolean
이 옵션은 일반 객체의 키가 안전한지 확인하는 함수입니다. 함수는 key와 obj의 두 인수를 받습니다. 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