Initial Commit

packages/persistence/database/db-sqlite/src/schemas/schemas.md

@@ -0,0 +1,71 @@
+# schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Zod schemas and inferred TypeScript types for all `@suaveplan/db-sqlite` configuration objects. Centralising validation in one module ensures that every entry point — `createBunDriver`, `createWasmDriver`, `SqliteAdapter`, `MigrationRunner` — applies the same rules with the same error messages, rather than duplicating ad-hoc checks across modules.
+
+All schemas use `.strict()` where applicable so extra unknown properties are rejected at runtime, preventing silent misconfiguration from typos in option objects.
+
+## Features
+
+- `BunDriverOptionsSchema` — validates `filename` (optional string) and `readonly` (optional boolean, default `false`)
+- `WasmDriverOptionsSchema` — validates `filename` (optional string) for OPFS persistence
+- `SqliteAdapterOptionsSchema` — alias for `BunDriverOptionsSchema`; adapter and driver share the same shape
+- `MigrationRunnerOptionsSchema` — validates `migrationsFolder` (default `"./migrations"`), `migrationsTable` (default `"__sqlite_migrations"`), `dryRun` (default `false`)
+- Inferred TypeScript types exported for all four schemas
+
+## Usage: Basic Example
+
+```ts
+import { BunDriverOptionsSchema } from "@suaveplan/db-sqlite/schemas";
+
+const opts = BunDriverOptionsSchema.parse({ filename: ":memory:" });
+// opts.readonly === false  (default applied)
+```
+
+## Usage: Advanced Example
+
+```ts
+import { MigrationRunnerOptionsSchema } from "@suaveplan/db-sqlite/schemas";
+
+const opts = MigrationRunnerOptionsSchema.parse({
+  migrationsFolder: "./db/migrations",
+  dryRun: true,
+});
+// opts.migrationsTable === "__sqlite_migrations"  (default applied)
+// opts.dryRun === true
+```
+
+## API Reference
+
+### `BunDriverOptionsSchema`
+
+`z.object({ filename?: string, readonly?: boolean }).strict()` — `readonly` defaults to `false`.
+
+### `WasmDriverOptionsSchema`
+
+`z.object({ filename?: string }).strict()` — no defaults; absence means in-memory.
+
+### `SqliteAdapterOptionsSchema`
+
+Alias for `BunDriverOptionsSchema`. Both driver and adapter accept the same option shape.
+
+### `MigrationRunnerOptionsSchema`
+
+`z.object({ migrationsFolder?: string, migrationsTable?: string, dryRun?: boolean }).strict()`.
+
+Defaults: `migrationsFolder = "./migrations"`, `migrationsTable = "__sqlite_migrations"`, `dryRun = false`.
+
+### Type aliases
+
+- `BunDriverOptions = z.infer<typeof BunDriverOptionsSchema>`
+- `WasmDriverOptions = z.infer<typeof WasmDriverOptionsSchema>`
+- `SqliteAdapterOptions = BunDriverOptions`
+- `MigrationRunnerOptions = z.infer<typeof MigrationRunnerOptionsSchema>`
+
+## Implementation Notes
+
+`SqliteAdapterOptions` is deliberately an alias for `BunDriverOptions` rather than a separate schema so that passing an `SqliteAdapterOptions` object to `createBunDriver` is type-safe without casting. If the WASM adapter ever gains `readonly` support the alias can be split without a breaking change to the option names callers already use.