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:
@@ -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.
|
||||
Reference in New Issue
Block a user