연결

가져오기

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

.constructor()

new Surreal();

매개변수

없음.

반환값

new 키워드를 통해 호출될 경우, Surreal 인스턴스를 반환합니다.

.connect() 인스턴스 메서드

SurrealDB 엔드포인트에 연결합니다. 이 메서드는 비동기적으로 실행되지만, 동일한 인스턴스 내에서 다른 .connect() 또는 .close() 메서드와 중복 실행되지 않습니다.

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

.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

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

반환값

없음.