Move docs/ package mirror into document-navigator plugin

Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-30 01:10:00 +01:00
parent fe3fedf42e
commit 9bf56a806b
6022 changed files with 12437 additions and 0 deletions

View File

@@ -0,0 +1,83 @@
# connection
<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose
Provides thin singleton-management wrappers for `SqliteAdapter`, built on top of the `@suaveplan/db` singleton helpers. These functions let callers share a single connected `SqliteAdapter` instance across an application without manually tracking the singleton lifecycle or passing the adapter through every layer of the call stack.
The helpers default the singleton name to `"default"` so simple applications need only call `getDefaultSqlite()` with no arguments. More complex applications with multiple databases use explicit names.
## Features
- `getDefaultSqlite(options?, config?, name?)` — creates-or-returns a connected `SqliteAdapter` singleton
- `closeSqlite(name?)` — disconnects and removes the named singleton
- `closeAllSqlite()` — disconnects and removes all `SqliteAdapter` singletons
- `hasSqlite(name?)` — returns `true` if the named singleton exists and is connected
- Default name: `"default"` — single-database apps never need to supply a name
## Usage: Basic Example
```ts
import { getDefaultSqlite } from "@suaveplan/db-sqlite/connection/connection";
const adapter = await getDefaultSqlite();
const rows = await adapter.query("SELECT * FROM users");
```
## Usage: Advanced Example
```ts
import {
closeAllSqlite,
closeSqlite,
getDefaultSqlite,
hasSqlite,
} from "@suaveplan/db-sqlite/connection/connection";
// Primary database
const primary = await getDefaultSqlite(
{ filename: "/data/app.db" },
undefined,
"primary"
);
// Analytics read-only shard
const analytics = await getDefaultSqlite(
{ filename: "/data/analytics.db", readonly: true },
undefined,
"analytics"
);
console.log(hasSqlite("primary")); // true
console.log(hasSqlite("analytics")); // true
await closeSqlite("analytics");
console.log(hasSqlite("analytics")); // false
// Shutdown — closes all remaining singletons
await closeAllSqlite();
```
## API Reference
### `getDefaultSqlite(options?, config?, name?): Promise<SqliteAdapter>`
Creates a new `SqliteAdapter` using the given `options`, calls `connect(config)` on it, caches it under `name`, and returns it. Subsequent calls with the same `name` return the cached instance without reconnecting.
### `closeSqlite(name?): Promise<void>`
Disconnects and removes the singleton named `name`. No-op if no singleton by that name exists.
### `closeAllSqlite(): Promise<void>`
Disconnects and removes all singletons. Throws `AggregateError` if any disconnect fails.
### `hasSqlite(name?): boolean`
Returns `true` if a singleton exists under `name`.
## Implementation Notes
These functions delegate entirely to `@suaveplan/db`'s `getSingleton`, `closeSingleton`, `closeAllSingletons`, and `hasSingleton`. The `SqliteAdapter`-specific names (`getDefaultSqlite`, `closeSqlite`, etc.) exist for discoverability — callers working with SQLite need not know the generic singleton API. The return type is narrowed from `DatabaseAdapter` to `SqliteAdapter` via a cast so callers have access to SQLite-specific properties.