# 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.