Initial Commit

packages/persistence/database/surrealdb/src/connection/connection.md

@@ -0,0 +1,84 @@
+# connection
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Manages the lifecycle of SurrealDB driver connections: creating new connections via a `SurrealClientFactory`, signing in, selecting namespace and database, and maintaining a module-level singleton registry. The singleton pattern is essential for long-lived server processes that should reuse a single authenticated connection across requests rather than reconnecting on every operation.
+
+The factory injection point (`SurrealClientFactory`) decouples this module from the `surrealdb` npm package, allowing the connection logic to be tested end-to-end without a running SurrealDB instance.
+
+## Features
+
+- `getDefaultConfig()` — returns development-friendly defaults (localhost, root/root)
+- `createConnection()` — connects, signs in, and selects namespace/database in one call
+- `connectWith()` — returns a cached singleton or creates one
+- `hasSurreal()` — inspects the singleton registry
+- `closeSurreal()` — disconnects and removes a named singleton
+- `closeAllSurreal()` — disconnects all registered singletons
+- AbortSignal support for early cancellation
+- Optional `LoggerLike` for structured connection lifecycle logs
+
+## Usage: Basic Example
+
+```ts
+import { createConnection, getDefaultConfig } from "@suaveplan/surrealdb/connection/connection";
+import { Surreal } from "surrealdb";
+
+const db = await createConnection(getDefaultConfig(), () => new Surreal());
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+  closeSurreal,
+  connectWith,
+  hasSurreal,
+} from "@suaveplan/surrealdb/connection/connection";
+import { Surreal } from "surrealdb";
+
+const KEY = "primary";
+
+async function getDb() {
+  return connectWith(KEY, { url: "wss://db.prod.example.com", namespace: "app", database: "main", auth: { username: "app", password: process.env.DB_PASS! } }, () => new Surreal());
+}
+
+// Later, on graceful shutdown:
+if (hasSurreal(KEY)) {
+  await closeSurreal(KEY);
+}
+```
+
+## API Reference
+
+### `getDefaultConfig(): SurrealDBConfig`
+
+Returns `{ url: "ws://localhost:8000", namespace: "test", database: "test", auth: { username: "root", password: "root" } }`.
+
+### `createConnection(config, factory, opts?): Promise<SurrealClientLike>`
+
+Merges config with defaults, validates via Zod, connects, signs in, and selects namespace/database.
+
+**Throws:** `SurrealError(CONNECTION_FAILED)` | `SurrealError(AUTH_FAILED)`.
+
+### `connectWith(key, config, factory, opts?): Promise<SurrealClientLike>`
+
+Returns cached singleton or creates via `createConnection`.
+
+### `hasSurreal(key: string): boolean`
+
+Returns `true` if a singleton is registered under `key`.
+
+### `closeSurreal(key: string): Promise<void>`
+
+Disconnects and removes the named singleton.
+
+### `closeAllSurreal(): Promise<void>`
+
+Disconnects all singletons. Aggregates errors.
+
+## Implementation Notes
+
+The module-level `singletonRegistry` Map is safe in Bun's single-threaded model. The `connectWith` function checks for an existing entry before calling `createConnection`, which prevents duplicate connections when called concurrently from different async call stacks in the same tick.