# error

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

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

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

## Usage: Advanced Example

```ts
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`

```ts
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.