连接

导入

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

.constructor()

new Surreal();

参数

无。

返回值

如果通过 new 调用，Surreal 将返回其实例。

.connect() 实例 方法

连接到SurrealDB端点。此方法异步执行，但在同一实例中，它不会与其他.connect()或.disconnect()重复执行。

connect(
  endpoint: string | URL,
  options?: ClientConnectOptions,
): Promise<void>;

参数

endpoint

使用URL指定SurrealDB的端点。如果URL路径末尾不是/rpc，则会自动添加。因此，如果传入http://localhost:8000作为参数，则会连接到http://localhost:8000/rpc。

options

连接选项。

signal?: AbortSignal

连接中断的取消信号。默认情况下，设置15秒超时取消信号。

返回值

返回一个以undefined解析的Promise对象。

例子

以下示例使用WebSocket协议连接到SurrealDB：

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

const db = new Surreal();

await db.connect("ws://localhost:8000");

在不进行.disconnect()断开连接的情况下，无法连接到不同的端点。此外，与先前建立连接的端点的连接将保持不变：

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

const db = new Surreal();

await db.connect("ws://localhost:8000");
await db.connect("ws://localhost:1129"); // throws ConnectionConflictError: Connection conflict between ws://localhost:8000/rpc and ws://localhost:1129/rpc.

.connect()不会同时在异步处理上下文中执行，因此以下示例也会连接失败。通常不知道哪个端点先建立连接，因此错误消息可能会因情况而异：

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

const db = new Surreal();

await Promise.all([
  db.connect("ws://localhost:8000"),
  db.connect("ws://localhost:1129"),
]); // throws ConnectionConflictError

.disconnect() 实例 方法

断开与SurrealDB的连接。如果尚未连接或已断开连接，则不会引发错误。此方法异步执行，但在同一实例中，它不会与.connect()或其他.disconnect()重复执行。

disconnect(options?: ClientDisconnectOptions): Promise<void>

参数

options

断开连接时的选项。

force?: boolean

设置为true时，将中止信号发送到传递给Surreal对象的事件监听器的中止信号。预期事件监听器即使处理不完整也会立即中断。

signal?: AbortSignal

连接中断的取消信号。默认情况下，设置15秒超时取消信号。

返回值

返回一个以undefined解析的Promise对象。

例子

以下示例使用WebSocket协议连接到SurrealDB，然后断开连接：

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

const db = new Surreal();

await db.connect("ws://localhost:8000");
await db.disconnect();

.getConnectionInfo() 实例 方法

获取连接信息。连接信息始终包含内部信息的副本值。因此，连接信息包含URL对象，但是直接修改它不会改变Surreal对象内部的端点信息。如果尚未请求连接，则为undefined。

getConnectionInfo(): ConnectionInfo | undefined;

参数

无。

返回值

如果已建立连接，则返回连接信息；否则返回undefined。连接信息包含以下项目：

state: 0 | 1 | 2 | 3

表示当前连接状态的数字。每个数字表示以下含义：

• 0 … 正在建立连接。
• 1 … 连接已建立。
• 2 … 正在断开连接。
• 3 … 连接已断开。

endpoint: URL | null

连接到的端点。仅在断开连接状态下为null。

namespace: string | null

当前选择的命名空间。如果没有选择命名空间，则为null。

database: string | null

当前选择的数据库名。如果没有选择数据库，则为null。

token: string | null

当前已认证的令牌。如果没有注册或登录，则为null。

在每种连接状态下，连接信息可以取的值如下表所示：

state	endpoint	namespace	database	token
0	URL	null	null	null
1	URL	string|null	string|null	string|null
2	URL	string|null	string|null	string|null
3	null	null	null	null

.state 实例 属性 只读

表示当前连接状态的数字。

state: 0 | 1 | 2 | 3

每个数字表示以下含义：

• 0 … 正在建立连接。
• 1 … 连接已建立。
• 2 … 正在断开连接。
• 3 … 连接已断开。

为方便起见，即使连接未建立，也为3（不是undefined）。

相关：另请参阅.getConnectionInfo()。

.endpoint 实例 属性 只读

连接到的端点。仅在断开连接状态下为null。如果连接未建立，则为undefined。

endpoint: string | null | undefined

相关：另请参阅.getConnectionInfo()。

.namespace 实例 属性

当前选择的命名空间。如果没有选择命名空间，则为null。如果连接未建立，则为undefined。

namespace: string | null | undefined

相关：另请参阅.getConnectionInfo()。

.database 实例 属性

当前选择的数据库名。如果没有选择数据库，则为null。如果连接未建立，则为undefined。

database: string | null | undefined

相关：另请参阅.getConnectionInfo()。

.token 实例 属性

当前已认证的令牌。如果没有注册或登录，则为null。如果连接未建立，则为undefined。

token: string | null | undefined

相关：另请参阅.getConnectionInfo()。

.on() 实例 方法

注册事件监听器。

off(
  event:
    | 0 | 1 | 2 | 3
    | `rpc_${RpcMethod}_${number}`
    | `live_${string}`
    | "error",
  listener: (taskRunnerArgs, ...eventArgs) => void | PromiseLike<void>,
): void

参数

event

要监视的事件名称。

0 | 1 | 2 | 3

连接信息发生转移时或转移失败时发生的事件。

rpc_${RpcMethod}_${number}

双向通信中发生RPC响应时发生的事件。目前仅在WebSocket协议中使用，在HTTP协议中不使用此事件。RpcMethod例如ping或use等PRC方法名。number是双向通信中用于关联请求/响应的标识符，取值为1到2^53-1之间的整数。

live_${string}

收到实时查询事件时发生的事件。目前仅在WebSocket协议中使用，在HTTP协议中不使用此事件。string是实时查询的UUID。

error

错误事件。目前仅在WebSocket协议中使用，在HTTP协议中不使用此事件。

listener

事件发生时执行的函数。另请参阅任务发射器。传递给eventArgs的值因事件而异。

0 | 1 | 2 | 3

以下是其中之一：

• { state: 0 | 1 | 2 | 3 }
• { state: 0 | 1 | 2 | 3, error: unknown }

rpc_${RpcMethod}_${number}

以下是其中之一：

• { id: string, result: unknown }
• { id: string, error: { code: number, message: string } }

live_${string}

普通模式的实时查询：

• { action: "CREATE" | "UPDATE" | "DELETE", result: object }

增量获取模式的实时查询：

• { action: "CREATE" | "UPDATE", result: object[] }
• { action: "DELETE", result: object }

error

以下是其中之一：

• HttpEngineError
• WebSocketEngineError

返回值

无。

.once() 实例 方法

类似于.on()，但只捕获一次事件。

once(
  event:
    | 0 | 1 | 2 | 3
    | `rpc_${RpcMethod}_${number}`
    | `live_${string}`
    | "error",
  options?: TaskListenerOptions,
): StatefulPromise<unknown[]>

参数

event

与.on()中的event相同。

options

任务监听器的选项。请参阅任务发射器。

返回值

返回一个以.on()的任务监听器的eventArgs解析的StatefulPromise。

.off() 实例 方法

取消.on()中注册的事件监听器。

off(
  event:
    | 0 | 1 | 2 | 3
    | `rpc_${RpcMethod}_${number}`
    | `live_${string}`
    | "error",
  listener: (taskRunnerArgs, ...eventArgs) => void | PromiseLike<void>,
): void

参数

event

要取消注册事件监听器的事件名称。

listener

要取消注册的事件监听器。

返回值

无。