error

(no submodules)

Purpose

Defines the SurrealError class and the SURREAL_CODES registry for all structured errors emitted by @suaveplan/surrealdb. Every throw site in the package uses one of these stable codes so callers can distinguish failure modes without fragile string matching against error messages. Extending SuaveplanError ensures compatibility with cause-chain traversal, wire serialisation, and OTel span-event adapters provided by @suaveplan/error.

The mapSurrealCode helper normalises raw driver exceptions into the stable code set, enabling a consistent error surface even when the underlying surrealdb driver changes its error messages between releases.

Features

Ten stable SURREAL.* codes covering connection, authentication, query, transaction, timeout, version, schema, init, and record-not-found failure modes
SurrealError extends SuaveplanError<SurrealCode> with a public constructor
mapSurrealCode(err) heuristically maps raw errors by message substring to the closest stable code

Usage: Basic Example

import { SurrealError, SURREAL_CODES } from "@suaveplan/surrealdb/errors/error";

throw new SurrealError(SURREAL_CODES.NOT_CONNECTED, "adapter is not connected");

Usage: Advanced Example

import { mapSurrealCode, SurrealError, SURREAL_CODES } from "@suaveplan/surrealdb/errors/error";

try {
  await db.query("SELECT * FROM missing");
} catch (raw) {
  const code = mapSurrealCode(raw);
  throw new SurrealError(code, `query failed: ${raw instanceof Error ? raw.message : String(raw)}`, {
    cause: raw instanceof Error ? raw : undefined,
  });
}

API Reference

`SURREAL_CODES`

Record<string, SurrealCode> — stable code dictionary produced by defineCodes("SURREAL", [...]).

Key	Value
`CONNECTION_FAILED`	`"SURREAL.CONNECTION_FAILED"`
`NOT_CONNECTED`	`"SURREAL.NOT_CONNECTED"`
`QUERY_FAILED`	`"SURREAL.QUERY_FAILED"`
`AUTH_FAILED`	`"SURREAL.AUTH_FAILED"`
`TIMEOUT`	`"SURREAL.TIMEOUT"`
`VERSION_UNSUPPORTED`	`"SURREAL.VERSION_UNSUPPORTED"`
`SCHEMA_LOAD_FAILED`	`"SURREAL.SCHEMA_LOAD_FAILED"`
`INIT_FAILED`	`"SURREAL.INIT_FAILED"`
`TRANSACTION_FAILED`	`"SURREAL.TRANSACTION_FAILED"`
`RECORD_NOT_FOUND`	`"SURREAL.RECORD_NOT_FOUND"`

`SurrealError`

class SurrealError extends SuaveplanError<SurrealCode>
constructor(code: SurrealCode, message: string, options?: SuaveplanErrorOptions)

`mapSurrealCode(err: unknown): SurrealCode`

Maps an unknown thrown value to the closest SurrealCode by heuristic substring match. Falls back to SURREAL.QUERY_FAILED.

Implementation Notes

Codes are registered at import time via defineCodes, which stamps them into the global @suaveplan/error code registry. The SurrealError public constructor widens SuaveplanError's protected constructor and normalises empty/whitespace messages to SurrealError(<code>) so log surfaces never render an empty Error: line — the body does real work, so no static-analysis suppression is needed.

3.1 KiB Raw Blame History