接続

インポート

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

.constructor()

new Surreal();

引数

なし。

返値

new を通じて呼び出された場合、Surreal はそのインスタンスを返します。

.connect() インスタンス メソッド

SurrealDB エンドポイントに接続します。このメソッドは非同期で実行されますが、同じインスタンス内であれば他の .connect() や .disconnect() と重複して実行されることはありません。

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

引数

endpoint

SurrealDB のエンドポイントを URL で指定します。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

登録解除するイベントリスナーです。

返値

なし。