Skip to content
surrealdb.js

Other Tools

write

Import

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

Syntax

write is a helper function that writes any JavaScript value encodable in CBOR format to a Writer.

write(writer: Writer, value: unknown, options?: WriteOptions): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

The JavaScript value to encode to a CBOR Uint8Array. The following JavaScript values can be passed to value:

  • 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 it’s not a primitive value and has a toCBOR property that is a function, it will be called preferentially.

options

Write options.

replacer?: Replacer | Replacer[]
The encoder encodes most values to CBOR by default, but you can replace special values that don’t fit into them with encodable values. This option allows implementing replacement processing 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 are called. If nothing can be replaced, a SurrealTypeError is thrown.
isSafeMapKey?: (key: unknown, map: ReadonlyMap<unknown, unknown>) => boolean
This option is a function that verifies whether the key of a Map object is safe. The function takes 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 is thrown. By default, it determines that "__proto__" or "constructor" are 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 determine that "__proto__" or "constructor" are unsafe keys.
isSafeObjectKey?: (key: unknown, obj: { readonly [p: string]: unknown }) => boolean
This option is a function that verifies whether the key of a plain object is safe. The function takes 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 is thrown. By default, it determines that "__proto__" or "constructor" are 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 determine that "__proto__" or "constructor" are unsafe keys.

Return Value

None.

writeNumber

Import

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

Syntax

writeNumber is a helper function that writes a number to a Writer.

writeNumber(writer: Writer, value: number): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

A number. For integers, values between -2^53-1 and 2^53-1 are valid. Since there is no way to determine .0 as a floating-point number in JavaScript, it is encoded as an integer value to CBOR in that case. For example, -1.0 is -1, which is an integer.

Return Value

None.

writeBigInt

Import

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

Syntax

writeBigInt is a helper function that writes a bigint to a Writer. (Note: The import statement uses writeInteger which might be a typo in the original Japanese document. It should likely be writeBigInt for consistency.)

writeBigInt(writer: Writer, value: bigint): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

A bigint. Values between -2^64 and 2^64-1 are valid.

Return Value

None.

writeByteString

Import

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

Syntax

writeByteString is a helper function that writes a Uint8Array to a Writer.

writeByteString(writer: Writer, value: Uint8Array): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

A Uint8Array.

Return Value

None.

writeUtf8String

Import

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

Syntax

writeUtf8String is a helper function that writes a UTF-8 encoded string to a Writer.

writeUtf8String(writer: Writer, value: string): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

A UTF-8 encoded string.

Return Value

None.

writeEncodedUtf8String

Import

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

Syntax

writeEncodedUtf8String is a helper function that writes a UTF-8 encoded string (Uint8Array) to a Writer.

writeEncodedUtf8String(writer: Writer, value: Uint8Array): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

A UTF-8 encoded string (Uint8Array).

Return Value

None.

writeBoolean

Import

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

Syntax

writeBoolean is a helper function that writes a boolean value to a Writer.

writeBoolean(writer: Writer, value: boolean): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

A boolean value.

Return Value

None.

writeNullable

Import

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

Syntax

writeNullable is a helper function that writes null or undefined to a Writer.

writeNullable(writer: Writer, value: null | undefined): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

null or undefined.

Return Value

None.

writeHeader

Import

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

Syntax

writeHeader is a helper function that writes the header of a CBOR data item to a Writer.

writeHeader(writer: Writer, mt: MajorType, length: number | bigint): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

mt

The CBOR major type. Must be an integer value from 0 to 7.

length

The data itself or the byte length of the data.

Return Value

None.

writePayload

Import

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

Syntax

writePayload is a helper function that writes the payload of a CBOR data item to a Writer.

writePayload(writer: Writer, value: Uint8Array): void;

Arguments

writer

A Writer to write the value to a Uint8Array.

value

The payload of the CBOR data item.

Return Value

None.