first commit

docs/persistence/database/surrealdb/src/errors/error.md

@@ -0,0 +1,73 @@
+# 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.