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

connection

(no submodules)

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

import { createConnection, getDefaultConfig } from "@suaveplan/surrealdb/connection/connection";
import { Surreal } from "surrealdb";

const db = await createConnection(getDefaultConfig(), () => new Surreal());

Usage: Advanced Example

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.