연결

import

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

등록 해제할 이벤트 리스너입니다.

반환값

없음.