Connecting

Importing

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

.constructor()

new Surreal();

Arguments

None.

Return Value

When called with new, Surreal returns its instance.

.connect() instance method

Connects to the SurrealDB endpoint. This method is asynchronous but will not run concurrently with other .connect() or .disconnect() calls within the same instance.

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

Arguments

endpoint

Specifies the SurrealDB endpoint as a URL. If the URL path does not end with /rpc, it will be automatically appended. Therefore, passing http://localhost:8000 will connect to http://localhost:8000/rpc.

options

Connection options.

signal?: AbortSignal

An abort signal to interrupt the connection. By default, an abort signal with a 15-second timeout is set.

Return Value

Returns a Promise object that resolves to undefined.

Example

The following example connects to SurrealDB using the WebSocket protocol:

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

const db = new Surreal();

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

Connecting to a different endpoint without disconnecting using .disconnect() is not permitted. The connection to the previously established endpoint will be maintained:

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.

Because .connect() will not run concurrently in an asynchronous context, the following example will also fail to connect. The error message may vary because it is generally unpredictable which endpoint establishes the connection first:

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() instance method

Disconnects from SurrealDB. It will not throw an error if not yet connected or already disconnected. This method is asynchronous but will not run concurrently with .connect() or other .disconnect() calls within the same instance.

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

Arguments

options

Disconnection options.

force?: boolean

If true, sends an abort signal to the abort signal passed to the Surreal object’s event listeners. Event listeners are expected to immediately interrupt even if processing is incomplete.

signal?: AbortSignal

An abort signal to interrupt the connection. By default, an abort signal with a 15-second timeout is set.

Return Value

Returns a Promise object that resolves to undefined.

Example

The following example connects to SurrealDB using the WebSocket protocol and then disconnects:

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

const db = new Surreal();

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

.getConnectionInfo() instance method

Retrieves connection information. The connection information always holds a copied value of the internal information. Therefore, although the connection information includes a URL object, modifying it directly will not change the endpoint information held internally by the Surreal object. It is undefined if a connection has not yet been requested.

getConnectionInfo(): ConnectionInfo | undefined;

Arguments

None.

Return Value

Returns connection information if a connection is established; otherwise, it returns undefined. The connection information includes the following items:

state: 0 | 1 | 2 | 3

A numerical value indicating the current connection state. Each number represents the following:

• 0 … Connecting.
• 1 … Connected.
• 2 … Disconnecting.
• 3 … Disconnected.

endpoint: URL | null

The connected endpoint. null only in the disconnected state.

namespace: string | null

The currently selected namespace. null if no namespace is selected.

database: string | null

The currently selected database name. null if no database is selected.

token: string | null

The currently authenticated token. null if not signed up or signed in.

The possible values of the connection information for each connection state are shown in the following table:

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 instance property readonly

A numerical value indicating the current connection state.

state: 0 | 1 | 2 | 3

Each number represents the following:

• 0 … Connecting.
• 1 … Connected.
• 2 … Disconnecting.
• 3 … Disconnected.

For convenience, it will be 3 even if no connection is established (undefined is not used).

Related: See also .getConnectionInfo().

.endpoint instance property readonly

The connected endpoint. null only in the disconnected state. undefined if no connection is established.

endpoint: string | null | undefined

Related: See also .getConnectionInfo().

.namespace instance property

The currently selected namespace. null if no namespace is selected. undefined if no connection is established.

namespace: string | null | undefined

Related: See also .getConnectionInfo().

.database instance property

The currently selected database name. null if no database is selected. undefined if no connection is established.

database: string | null | undefined

Related: See also .getConnectionInfo().

.token instance property

The currently authenticated token. null if not signed up or signed in. undefined if no connection is established.

token: string | null | undefined

Related: See also .getConnectionInfo().

.on() instance method

Registers an event listener.

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

Arguments

event

The name of the event to monitor.

0 | 1 | 2 | 3

Events that occur when connection information transitions or when a transition fails.

rpc_${RpcMethod}_${number}

Event that occurs when an RPC response occurs in two-way communication. Currently used only with the WebSocket protocol and not used with the HTTP protocol. RpcMethod is the name of the PRC method, such as ping or use. number is an identifier for associating requests/responses in two-way communication and takes an integer from 1 to 2^53-1.

live_${string}

Event that occurs when receiving an event from a live query. Currently used only with the WebSocket protocol and not used with the HTTP protocol. string is the UUID of the live query.

error

Error event. Currently used only with the WebSocket protocol and not used with the HTTP protocol.

listener

The function to execute when the event occurs. See also Task Emitter. The value passed to eventArgs varies depending on the event.

0 | 1 | 2 | 3

One of the following:

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

rpc_${RpcMethod}_${number}

One of the following:

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

live_${string}

Normal mode live query:

• { action: "CREATE" | "UPDATE" | "DELETE", result: object } Difference acquisition mode live query:
• { action: "CREATE" | "UPDATE", result: object[] }
• { action: "DELETE", result: object }

error

One of the following:

• HttpEngineError
• WebSocketEngineError

Return Value

None.

.once() instance method

Similar to .on(), but captures the event only once.

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

Arguments

event

Same as event in .on().

options

Task listener options. See Task Emitter.

Return Value

Returns a StatefulPromise that resolves with the eventArgs of the .on() task listener.

.off() instance method

Removes an event listener registered with .on().

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

Arguments

event

The name of the event to remove the listener from.

listener

The event listener to remove.

Return Value

None.