Initial Commit
This commit is contained in:
78
packages/api-stack/api/api-db-sqlite-memory/README.md
Normal file
78
packages/api-stack/api/api-db-sqlite-memory/README.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# @suaveplan/api-db-sqlite-memory — in-memory SQLite database adapter for the @suaveplan/api plugin host testing kit. Wraps bun:sqlite in `:memory:` mode (or an on-disk file for persistent test fixtures) behind the AdminDatabaseLike + TenantScopedDatabaseLike contracts, applies WAL + foreign_keys pragmas by default, ships a lexicographic migration runner with __plugin_migrations bookkeeping, and registers itself in the @suaveplan/api-db-adapter engine registry under the `sqlite-memory` key so `createDbAdapter({ engine: 'sqlite-memory' })` resolves transparently.
|
||||
|
||||
Stage-5 in-memory SQLite database adapter for the `@suaveplan/api` plugin host testing kit. Wraps `bun:sqlite` (in `:memory:` mode by default, or a file path for longer-lived fixtures) behind the `AdminDatabaseLike` + `TenantScopedDatabaseLike` contracts from `@suaveplan/api-types/db`, ships a lexicographic migration runner with `__plugin_migrations` bookkeeping, and self-registers in the `@suaveplan/api-db-adapter` engine registry under the `sqlite-memory` key so `createDbAdapter({ engine: "sqlite-memory" })` resolves transparently.
|
||||
|
||||
The adapter is production-grade — it happens to keep state in process memory. Real SQLite drives every query, transaction semantics match, foreign-key enforcement is on by default, and the migration runner is fully transactional. Tests boot in milliseconds without testcontainers or any other external service.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [engine](./src/engine/register-engine.md) — Registers the in-memory SQLite adapter under `engine: "sqlite-memory"` in the open `@suaveplan/api-db-adapter` engine r…
|
||||
- [register-engine](./src/engine/register-engine.md) — Registers the in-memory SQLite adapter under `engine: "sqlite-memory"` in the open `@suaveplan/api-db-adapter` engine r…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module declares the stable error-code registry for `@suaveplan/api-db-sqlite-memory`. Every error thrown from the…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module declares the stable error-code registry for `@suaveplan/api-db-sqlite-memory`. Every error thrown from the…
|
||||
- [create-sqlite-memory-adapter](./src/factory/create-sqlite-memory-adapter.md) — Opens a real `bun:sqlite` `Database` and wraps it as an `AdminDatabaseLike`. The default zero-argument call yields a `:…
|
||||
- [create-sqlite-memory-db](./src/factory/create-sqlite-memory-db.md) — Stage-5 top-level testing factory. Combines `createSqliteMemoryAdapter` with the tenant-scoping wrapper from this packa…
|
||||
- [migrations](./src/migrations/migrations.md) — Lexicographic forward-only migration runner for the in-memory SQLite adapter. Applies every `*.sql` file in a directory…
|
||||
- [migrations](./src/migrations/migrations.md) — Lexicographic forward-only migration runner for the in-memory SQLite adapter. Applies every `*.sql` file in a directory…
|
||||
- [options](./src/options/sqlite-memory-db-options.md) — Defines the Zod-validated options object accepted by `createSqliteMemoryDb`, `createSqliteMemoryAdapter`, and the engin…
|
||||
- [sqlite-memory-db-options](./src/options/sqlite-memory-db-options.md) — Defines the Zod-validated options object accepted by `createSqliteMemoryDb`, `createSqliteMemoryAdapter`, and the engin…
|
||||
- [tenant-scoping](./src/tenant-scoping/tenant-scoping.md) — Wraps an `AdminDatabaseLike` as a `TenantScopedDatabaseLike` that transparently injects the resolved tenant id into eve…
|
||||
- [tenant-scoping](./src/tenant-scoping/tenant-scoping.md) — Wraps an `AdminDatabaseLike` as a `TenantScopedDatabaseLike` that transparently injects the resolved tenant id into eve…
|
||||
- [testing](./src/testing/harness.md) — Convenience builder for plugin test files. Wraps `createSqliteMemoryDb` with an idempotent `cleanup()` so the canonical…
|
||||
- [harness](./src/testing/harness.md) — Convenience builder for plugin test files. Wraps `createSqliteMemoryDb` with an idempotent `cleanup()` so the canonical…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Connection string
|
||||
|
||||
The canonical connection string is `":memory:"` — the default. Any non-empty string passed as `filename` is forwarded straight to `bun:sqlite`'s `Database` constructor, so an absolute path opens a persistent file-backed fixture:
|
||||
|
||||
```ts
|
||||
import { createSqliteMemoryAdapter } from "@suaveplan/api-db-sqlite-memory";
|
||||
|
||||
const ephemeral = createSqliteMemoryAdapter(); // ":memory:"
|
||||
const persisted = createSqliteMemoryAdapter({ filename: "/tmp/fixture.sqlite" });
|
||||
```
|
||||
|
||||
## Default pragmas
|
||||
|
||||
Every fresh connection has these pragmas applied at open time:
|
||||
|
||||
- `journal_mode = WAL` — write-ahead logging. No-op for `:memory:`, useful for file-backed fixtures.
|
||||
- `foreign_keys = ON` — SQLite ships with FK enforcement disabled by default. The adapter flips it on so referential integrity is honoured.
|
||||
|
||||
Operators that want to override either default supply `pragmas` in the options object:
|
||||
|
||||
```ts
|
||||
const adapter = createSqliteMemoryAdapter({
|
||||
pragmas: { foreign_keys: "OFF", synchronous: "FULL" },
|
||||
});
|
||||
```
|
||||
|
||||
The final merged pragma map is `{ ...DEFAULT_PRAGMAS, ...options.pragmas }`, so any default can be overridden by repeating its key.
|
||||
|
||||
## Subpath exports
|
||||
|
||||
| Subpath | Purpose |
|
||||
| --- | --- |
|
||||
| `.` | Root barrel — re-exports every public symbol. |
|
||||
| `./adapter` | `createSqliteMemoryAdapter` + OTel instrument hooks. |
|
||||
| `./factory` | `createSqliteMemoryDb` returning `{ admin, scoped, close }`. |
|
||||
| `./engine` | `registerSqliteMemoryEngine` for the api-db-adapter registry. |
|
||||
| `./migrations` | `runSqliteMemoryMigrations` + `SqliteMigrationsFsReader`. |
|
||||
| `./options` | Zod schema + `parseSqliteMemoryDbOptions` + `resolvePragmas`. |
|
||||
| `./tenant-scoping` | `createTenantScopedSqliteWrapper` + pure SQL rewriters. |
|
||||
| `./error-codes` | `DB_SQLITE_MEMORY_CODES` + `DbSqliteMemoryError`. |
|
||||
| `./testing` | `createInMemorySqliteHarness` convenience builder. |
|
||||
|
||||
## Error codes
|
||||
|
||||
- `DB_SQLITE_MEMORY.OPEN_FAILED` — `bun:sqlite` constructor threw.
|
||||
- `DB_SQLITE_MEMORY.INVALID_OPTIONS` — Zod validation failed.
|
||||
- `DB_SQLITE_MEMORY.MIGRATION_FAILED` — a migration file threw; transaction rolled back.
|
||||
- `DB_SQLITE_MEMORY.TENANT_SCOPE_VIOLATION` — cross-tenant write or unsupported SQL shape.
|
||||
|
||||
## License
|
||||
|
||||
MIT.
|
||||
|
||||
Reference in New Issue
Block a user