에러

SurrealError

SurrealError는 이 SDK가 명시적으로 던지는 에러 객체의 대부분이 상속하는 기본 클래스입니다. 이 클래스는 JavaScript의 Error 클래스를 상속합니다. 이 에러 객체가 단독으로 던져지는 경우는 거의 없으며, 기본적으로 상속 클래스의 특별한 의미를 가진 에러 객체가 던져집니다. try-catch 구문 등으로 에러를 포착했을 때, 이 SDK가 명시적으로 던진 에러인지 쉽게 분류하기 위해 사용하는 것을 권장합니다.

.name: "SurrealError"

에러 이름입니다.

.message

에러 메시지입니다.

.stack

스택 트레이스가 기록되어 있을 수 있습니다.

.cause

에러가 발생한 원인이나 컨텍스트가 설정되어 있을 수 있습니다.

SurrealTypeError

상속원: SurrealError

입력 값이나 기타 검증에 실패했을 때 던져지는 에러입니다.

.name: "SurrealTypeError"

에러 이름입니다.

.expected

예상하는 데이터 형식입니다.

.actual

실제 값의 문자열 표현입니다.

SurrealAggregateError

상속원: SurrealError

여러 에러 또는 에러 메시지가 결합된 에러입니다.

.name: "SurrealAggregateError"

에러 이름입니다.

.cause: unknown[]

배열의 각 요소에 에러 또는 에러 메시지 등이 포함되어 있습니다.

CircularReferenceError

상속원: SurrealError

순환 참조를 감지했을 때 던져지는 에러입니다. 주로 JavaScript 값을 다른 형식으로 변환하는 과정에서 부모 객체와 동일한 객체가 감지되었을 때 던져집니다.

.name: "CircularReferenceError"

에러 이름입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

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

const a = {};
a.a = a;

console.log(a); // <ref *1> { a: [Circular *1] }

toSurql(a); // throws CircularReferenceError

NumberRangeError

상속원: SurrealError

숫자가 범위를 벗어난 값을 가졌을 때 던져지는 에러입니다.

.name: "NumberRangeError"

에러 이름입니다.

.range

예상 범위입니다.

.actual

실제 값입니다.

.integer

true인 경우, 정수를 예상합니다.

UnsupportedRuntimeError

상속원: SurrealError

지원되지 않는 런타임을 사용하고 있다고 판단될 때 던져지는 에러입니다.

.name: "UnsupportedRuntimeError"

에러 이름입니다.

UnreachableError

상속원: SurrealError

도달할 수 없는 코드에 도달했을 때 던져지는 에러입니다. 이 에러가 던져졌다면, 아마도 이 SDK의 버그를 만난 것으로 생각됩니다.

.name: "UnreachableError"

에러 이름입니다.

CircularEngineReferenceError

상속원: CircularReferenceError

데이터베이스에 연결할 때 엔진 간에 순환 참조가 발생했을 때 던져지는 에러입니다.

.name: "CircularEngineReferenceError"

에러 이름입니다.

.seen: string[]

순환 참조가 발생할 때까지 거친 프로토콜 이름 목록입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

const { Surreal } = initSurreal({
  engines: {
    http: "https",
    https: "http",
  },
  // ...
});

await using db = new Surreal();
await db.connect("https://localhost:8000"); // throws CircularEngineReferenceError: Circular engine reference: http,https

위의 예에서는 https 프로토콜 엔진이 http에 설정된 엔진을 사용하려고 하는데, http 프로토콜 엔진은 https에 설정된 엔진을 사용하려고 하기 때문에 순환 참조 에러가 던져집니다.

EngineNotFoundError

상속원: SurrealError

엔진이 설정되지 않은 프로토콜로 연결하려고 할 때 던져지는 에러입니다.

.name: "EngineNotFoundError"

에러 이름입니다.

.protocol: string

연결할 프로토콜 이름입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

const { Surreal } = initSurreal({
  engines: {
    http: config => new HttpEngine(config),
  },
  // ...
});

await using db = new Surreal();
await db.connect("https://localhost:8000"); // throws EngineNotFoundError: No https protocol engine found.

ConnectionConflictError

상속원: SurrealError

클라이언트가 여러 엔드포인트에 동시에 연결하려고 할 때 던져지는 에러입니다.

.name: "ConnectionConflictError"

에러 이름입니다.

.endpoint1: string

한쪽 엔드포인트입니다.

.endpoint2: string

다른 쪽 엔드포인트입니다.

await using db = new Surreal();

await db.connect("http://localhost:8000");
await db.connect("http://localhost:11298"); // throws ConnectionConflictError: Connection conflict between http://localhost:8000/rpc and http://localhost:11298/rpc.

.connect 메서드는 전달된 URL의 경로가 /rpc로 끝나지 않는 경우, 그것을 끝에 추가합니다. 따라서 한쪽 엔드포인트의 URL 경로가 /rpc로 끝나는 경우, 외관상으로는 에러가 발생하지 않을 수 있습니다.

await using db = new Surreal();

await db.connect("http://localhost:8000");
await db.connect("http://localhost:8000/rpc"); // OK!

await using db = new Surreal();

await db.connect("http://localhost:8000/rpc");
await db.connect("http://localhost:8000"); // OK!

NamespaceConflictError

상속원: SurrealError

SDK가 동시에 여러 다른 네임스페이스로 전환하려고 할 때 던져지는 에러입니다.

.name: "NamespaceConflictError"

에러 이름입니다.

.namespace1: string

한쪽 네임스페이스입니다.

.namespace2: string

다른 쪽 네임스페이스입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

await using db = new Surreal();

await db.connect("http://localhost:8000");
await db.signin({ user: "root", pass: "root" });
await Promise.all([
  db.use({ namespace: "foo" }),
  db.use({ namespace: "bar" }),
]);

DatabaseConflictError

상속원: SurrealError

SDK가 동시에 여러 다른 데이터베이스로 전환하려고 할 때 던져지는 에러입니다.

.name: "DatabaseConflictError"

에러 이름입니다.

.database1: string

한쪽 데이터베이스입니다.

.database2: string

다른 쪽 데이터베이스입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

await using db = new Surreal();

await db.connect("http://localhost:8000");
await db.signin({ user: "root", pass: "root" });
await Promise.all([
  db.use({ namespace: "baz" database: "foo" }),
  db.use({ namespace: "baz" database: "bar" }),
]);

MissingNamespaceError

상속원: SurrealError

데이터베이스를 선택하기 전에 네임스페이스가 선택되지 않았을 때 던져지는 에러입니다. 또는 데이터베이스를 선택한 상태에서 네임스페이스를 선택하지 않은 상태로 만들려고 할 때도 던져집니다.

.name: "MissingNamespaceError"

에러 이름입니다.

.database: string

데이터베이스 이름입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

await using db = new Surreal();
await db.connect("http://localhost:8000");

await db.use({ database: "example" }); // throws MissingNamespaceError: The namespace must be specified before the database.

RpcResponseError

상속원: SurrealError

RPC 응답이 에러를 나타낼 때 던져지는 에러입니다. 연결된 프로토콜에 의한 통신이나 응답 바디의 디코딩에는 문제가 없지만, SurrealDB가 RPC 요청을 처리할 수 없음을 의미합니다.

.name: "RpcResponseError"

에러 이름입니다.

.id?: string

RPC 요청을 식별하는 ID입니다. ID는 항상 <메서드 이름>_으로 시작합니다.

.code: number

SurrealDB 문서에 명시되어 있지 않지만, 아마도 JSON-RPC의 에러 코드일 것입니다.

QueryFailedError

상속원: SurrealAggregateError

쿼리에 실패했을 때 던져지는 에러입니다.

.name: "QueryFailedError"

에러 이름입니다.

.cause: string[]

에러 목록입니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

await using db = new Surreal();
await db.connect("http://localhost:8000");

await db.query("OUTPUT 'Hello'"); // throws QueryFailedError: Query failed with 1 error(s)

Disconnected

상속원: SurrealError

연결이 강제로 종료되었음을 나타내는 에러입니다.

.name: "Disconnected"

에러 이름입니다.

예를 들어 다음과 같은 경우에 이 에러를 얻습니다.

const db = new Surreal();

db.on("<event_name>", ({ signal }) => {
  return new Promise((resolve, reject) => {
    signal.addEventListener("abort", function() {
      console.error(this.reason); // Disconnected
      reject();
    })

    // ...
  });
});

await db.disconnect({ force: true });

EngineError

상속원: SurrealError

엔진에 기인하는 에러임을 나타냅니다. 이벤트 리스너를 통해 전송됩니다.

.name: "EngineError"

에러 이름입니다.

.fatal: boolean | undefined

이 에러가 치명적인지 여부를 나타냅니다.

HttpEngineError

상속원: EngineError

HTTP 엔진에 기인하는 에러임을 나타냅니다. 현재는 정의만 되어 있고 사용되지 않습니다.

.name: "HttpEngineError"

에러 이름입니다.

WebSocketEngineError

상속원: EngineError

WebSocket 엔진에 기인하는 에러임을 나타냅니다. RPC 요청을 식별하는 ID를 찾기 전에 응답 바디의 분석에 실패했거나, WebSocket 객체에서 에러 이벤트를 받았을 때, WebSocket 연결을 끊었을 때 등 사용됩니다.

.name: "WebSocketEngineError"

에러 이름입니다.

.code: number

다음 상태 코드 중 하나입니다.

• 1000~1015: MDN Reference
• 3150: WebSocket[^1] 인스턴스에서 “error” 이벤트를 받았음을 나타냅니다.
• 3151: WebSocket 엔진이 등록하는 “open” 이벤트 핸들러에서 에러가 발생했음을 나타냅니다. 연결 중 상태에서 연결 상태로 전이하는 중에 StateTransitionError가 발생한 경우가 대부분입니다.
• 3152: WebSocket 엔진이 등록하는 “message” 이벤트 핸들러에서 에러가 발생했음을 나타냅니다. 다양한 원인이 있을 수 있지만, 이벤트 핸들러에서 ResponseError 또는 RpcResponseError가 던져졌을 가능성이 높습니다. 원인을 추적하면 .query() 메서드에서 잘못된 문법의 SurrealQL 커스텀 쿼리를 요청했거나, 잘못된 RPC 매개변수로 요청했기 때문일 수 있습니다. 그 경우, RPC 호출의 원본 메서드는 (기본적으로) 5초 후에 타임아웃되어 실패합니다.
• 3153: ping 송수신에 실패했음을 나타냅니다. 일시적인 에러일 수도 있지만, 계속해서 받고 있다면 연결을 유지하지 못하고 있을 가능성이 있습니다.
• 3154: WebSocket 엔진이 등록하는 “close” 이벤트 핸들러에서 에러가 발생했음을 나타냅니다. 연결 해제 중 상태에서 연결 해제 상태로 전이하는 중에 StateTransitionError가 발생한 경우가 대부분입니다.

참고로, 위에서 다음 상태 코드를 제외합니다. 이 SDK에서는 에러로 처리하지 않습니다.

• 1000: 정상적으로 연결이 해제되었습니다.
• 1001: 조기 연결 해제는 흔히 발생합니다.
• 1004: 예약됨.
• 1005: 예약됨.
• 1006: 예약됨.
• 1015: 예약됨.

^1: WebSocket은 런타임이 전역 변수에 정의하는 클래스이거나, ws SDK의 클래스일 수 있습니다.

StateTransitionError

상속원: SurrealAggregateError

상태 전이 중에 이벤트 리스너의 실행에 실패했을 때 던져지는 에러입니다.

.name: "StateTransitionError"

에러 이름입니다.

.from: number

상태 전이 시작 시 상태입니다.

.to: number

전이할 상태입니다.

.fallback: number

상태 전이에 실패했을 때 대체 전이할 상태입니다. .to와 같은 값이면, 강제로 전이했음을 의미합니다.

예를 들어 다음과 같은 경우에 이 에러가 던져집니다.

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

await using db = new Surreal();

db.on(CONNECTING, () => {
  throw new Error("Don't let me connect !!!")
});

await db.connect("http://localhost:8000"); // throws ...
// StateTransitionError: The transition from `3` to `0` failed, falling back to `3`.
//     at <stack trace ...> {
//   cause: [
//     Error: Don't let me connect !!!
//         at <stack trace ...>
//   ],
//   from: 3,
//   to: 0,
//   fallback: 3
// }

ConnectionUnavailableError

상속원: SurrealError

연결되지 않은 상태에서 RPC 요청을 보내려고 할 때 던져지는 에러입니다.

.name: "ConnectionUnavailableError"

에러 이름입니다.

ResponseError

상속원: SurrealError

응답을 PRC 응답으로 분석할 수 없을 때 던져지는 에러입니다. RpcResponseError와는 다릅니다.

.name: "ResponseError"

에러 이름입니다.

CborError

상속원: SurrealError

@tai-kun/surrealdb/cbor가 명시적으로 던지는, CBOR 관련 모든 에러가 상속하는 클래스입니다. 이것이 직접 던져지는 경우는 없습니다.

.name: "CborError"

에러 이름입니다.

CborWellFormednessError

상속원: CborError

@tai-kun/surrealdb/cbor가 명시적으로 던지는, CBOR 디코딩 관련 모든 에러가 상속하는 클래스입니다. 이것이 직접 던져지는 경우는 없습니다.

RFC8949 부록 F의 “Well-Formedness Errors and Examples”를 참조하십시오.

.name: "CborWellFormednessError"

에러 이름입니다.

CborTooMuchDataError

상속원: CborWellFormednessError

소비되지 않은 입력 바이트가 남아 있음을 나타냅니다.

RFC8949

.name: "CborTooMuchDataError"

에러 이름입니다.

CborTooLittleDataError

상속원: CborWellFormednessError

입력 바이트가 불완전함을 나타냅니다.

RFC8949

.name: "CborTooLittleDataError"

에러 이름입니다.

CborSyntaxError

상속원: CborWellFormednessError

입력 바이트가 CBOR의 인코딩 형식과 일치하지 않음을 나타냅니다.

RFC8949

.name: "CborSyntaxError"

에러 이름입니다.

CborMaxDepthReachedError

상속원: CborError

CBOR 인코딩 또는 디코딩 시 JavaScript 객체의 깊이가 최대값에 도달했을 때 던져지는 에러입니다. 객체 또는 배열에 들어갈 때마다 깊이가 1 증가합니다.

.name: "CborMaxDepthReachedError"

에러 이름입니다.

.maxDepth: number

최대 깊이입니다.

CborUnsafeMapKeyError

상속원: CborError

CBOR 인코딩 또는 디코딩 시 안전하지 않은 맵 키가 발견되었을 때 던져지는 에러입니다.

.name: "CborUnsafeMapKeyError"

에러 이름입니다.

.key: unknown

안전하지 않다고 판단된 맵 키입니다.