连接

导入

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

.constructor()

new Surreal();

参数

无。

返回值

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

.connect() 实例 方法

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

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");

无需.close()断开连接即可连接到不同的端点。此外，与先前建立连接的端点的连接将保持不变：

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

const db = new Surreal();

await db.connect("ws://localhost:8000");
await db.connect("ws://localhost:1129"); // throws ConnectionConflictError: An attempt was made to connect to ws://localhost:1129/rpc while ws://localhost:8000/rpc was already connected.

.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

.close() 实例 方法

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

close(options?: ClientCloseOptions): 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.close();

.getConnectionInfo() 实例 方法

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

getConnectionInfo(): ConnectionInfo | undefined;

参数

无。

返回值

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

state: "connecting" | "open" | "closing" | "closed"

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

endpoint: URL | null

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

namespace: string | null

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

database: string | null

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

token: string | null

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

各种连接状态下连接信息的可能取值如下表所示：

state	endpoint	namespace	database	token
"connecting"	URL	null	null	null
"open"	URL	string|null	string|null	string|null
"closing"	URL	string|null	string|null	string|null
"closed"	null	null	null	null

.state 实例 属性 只读

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

state: "connecting" | "open" | "closing" | "closed"

为方便起见，即使连接未建立，也为"closed"（而不是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:
    | "connecting" | "open" | "closing" | "closed"
    | `rpc_${RpcMethod}_${number}`
    | `live_${string}`
    | "error",
  listener: (taskRunnerArgs, ...eventArgs) => void | PromiseLike<void>,
): void

参数

event

要监视的事件名称。

"connecting" | "open" | "closing" | "closed"

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

rpc_${RpcMethod}_${number}

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

live_${string}

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

error

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

listener

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

"connecting" | "open" | "closing" | "closed"

以下之一：

• { state: "connecting" | "open" | "closing" | "closed" }
• { state: "connecting" | "open" | "closing" | "closed", error: unknown }

rpc_${RpcMethod}_${number}

以下之一：

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

live_${string}

普通模式的实时查询：

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

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

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

error

以下之一：

• HttpEngineError
• WebSocketEngineError

返回值

无。

.once() 实例 方法

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

once(
  event:
    | "connecting" | "open" | "closing" | "closed"
    | `rpc_${RpcMethod}_${number}`
    | `live_${string}`
    | "error",
  options?: TaskListenerOptions,
): StatefulPromise<unknown[]>

参数

event

与.on()的event相同。

options

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

返回值

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

.off() 实例 方法

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

off(
  event:
    | "connecting" | "open" | "closing" | "closed"
    | `rpc_${RpcMethod}_${number}`
    | `live_${string}`
    | "error",
  listener: (taskRunnerArgs, ...eventArgs) => void | PromiseLike<void>,
): void

参数

event

要注销事件监听器的事件名称。

listener

要注销的事件监听器。

返回值

无。