@playfast/reform-db-sqlite 0.0.1

package/README.md

@@ -0,0 +1,76 @@
+<div align="center">
+
+# `@playfast/reform-db-sqlite`
+
+**The [`bun:sqlite`](https://bun.sh/docs/api/sqlite) engine for [`@playfast/reform-db`](../reform-db).**
+
+</div>
+
+---
+
+Backs the engine-neutral `Db` driver from [`@playfast/reform-db`](../reform-db) with
+Bun's built-in SQLite. Zero native dependencies (it's part of the Bun runtime),
+`serialize()`/`deserialize()` snapshots, and **emulated reactivity** — SQLite has no
+native live queries, so a live `DbQuery` re-runs after every write. Your tables,
+queries, and migrations stay defined in the engine-neutral core.
+
+> **Bun only.** `bun:sqlite` exists only under the Bun runtime. Import this package
+> from code that runs on Bun; on Node the module import fails (surfaced as a `DbError`).
+
+## Install
+
+```sh
+bun add @playfast/reform-db-sqlite @playfast/reform-db kysely
+```
+
+`effect`, `kysely`, `@playfast/reform`, and `@playfast/reform-db` are peer
+dependencies.
+
+## Quick Start
+
+```ts
+import { DbSchema, DbTable, DbColumn, Migration } from '@playfast/reform-db'
+import { Sqlite } from '@playfast/reform-db-sqlite'
+import { Layer } from 'effect'
+
+const AppDb = DbSchema.make('app', { tables: [/* … */] })
+
+// IMPORTANT: render migrations for the SQLite dialect.
+const migrations = Migration.fromSchema(AppDb, Migration.sqlite)
+
+// Persistent (a file on disk):
+const DataLayer = QueriesAndProcedures.pipe(
+  Layer.provideMerge(Sqlite.layer({ filename: 'app.db', migrations })),
+)
+
+// Ephemeral in-memory — the default for tests / proofs:
+const TestLayer = QueriesAndProcedures.pipe(
+  Layer.provideMerge(Sqlite.memory({ migrations })),
+)
+```
+
+Both layers build the `Db` service **synchronously** (bun:sqlite opens on a background
+fiber inside `makeDriver`), so they slot straight under reform's `runSync` scene /
+proof mount.
+
+### Type storage
+
+SQLite has no native `boolean` or `json` types, so the engine stores them as `integer`
+(`0`/`1`) and `text` (JSON) respectively. The column `Schema`s in `@playfast/reform-db`
+are engine-tolerant, so `DbColumn.boolean()` / `DbColumn.json(schema)` decode back to a
+real `boolean` / object on read — the same table definition works on both engines.
+
+## API
+
+- `Sqlite.layer(options?)` — persistent (or in-memory, if `filename` is omitted) `Db`.
+  Options: `filename?`, `migrations?`, `loadDataDir?` (seed from a prior `dump` `Blob`).
+- `Sqlite.memory(options?)` — ephemeral in-memory `Db`. Options: `migrations?`,
+  `loadDataDir?`.
+- `makeSqliteEngine(options)` — the raw `DbEngine`, for wiring `makeDriver` yourself.
+
+Snapshotting: `driver.dump()` returns a `Blob` of `Database.serialize()` bytes; feed it
+back via `loadDataDir` to boot a database already populated (`Database.deserialize`).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@playfast/reform-db-sqlite",
+  "playbook": "./playbook",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "bun:sqlite engine for @playfast/reform-db — a Db driver backed by Bun's built-in SQLite, with emulated reactivity and serialize()/deserialize() snapshots.",
+  "keywords": [
+    "reform",
+    "effect",
+    "sqlite",
+    "bun",
+    "sql",
+    "reactive",
+    "local-first"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/playfast/reform.git",
+    "directory": "packages/reform-db-sqlite"
+  },
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist .tsbuildinfo",
+    "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "lint": "oxlint src",
+    "lint:fix": "oxlint --fix src"
+  },
+  "peerDependencies": {
+    "effect": "*",
+    "kysely": "*",
+    "@playfast/reform": "*",
+    "@playfast/reform-db": "*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,130 @@
+import { type DbEngine, DbError, type EngineBackend, type Migration } from '@playfast/reform-db'
+import { Effect, Option } from 'effect'
+import { createQueryId, type RootOperationNode, SqliteQueryCompiler } from 'kysely'
+// Type-only: erased at build, so this package imports cleanly on Node (where the
+// `bun:sqlite` module does not exist); the real module is imported lazily at open time.
+import type { Database } from 'bun:sqlite'
+
+// The bun:sqlite engine: Bun's built-in SQLite. It compiles operation nodes to SQLite
+// SQL, opens a `Database` lazily (so importing this package never touches the
+// Bun-only `bun:sqlite` module on Node), and runs migrations. SQLite has NO native
+// live queries, so `live` is `Option.none` — `makeDriver` emulates reactivity by
+// re-running reads after each write. `dump` uses `Database.serialize()` (a full
+// on-the-wire snapshot Buffer), restored via `Database.deserialize` on the next open.
+
+// A value SQLite can bind (bun:sqlite's `SQLQueryBindings`). Booleans ride as `0`/`1`,
+// JSON columns as text — matching the engine-tolerant column `Schema`s in
+// `@playfast/reform-db` that decode either shape. `ExternalApi`-named: it mirrors the
+// driver's own binding shape, which admits a raw `null`.
+type BindingExternalApi = string | number | bigint | boolean | Uint8Array | null
+
+export interface SqliteOptionsExternalApi {
+  /** Database file path; omit for an ephemeral in-memory (`:memory:`) database. */
+  readonly filename?: string
+  /**
+   * DDL/seed migrations to run on open. Use `Migration.fromSchema(AppDb, Migration.sqlite)`
+   * so column types render for SQLite; `Sqlite.layer`/`Sqlite.memory` do NOT pick the
+   * dialect for you.
+   */
+  readonly migrations?: ReadonlyArray<Migration.Migration>
+  /**
+   * Seed the database from a previous `dump` snapshot (`Database.serialize()` bytes,
+   * wrapped in a `Blob`). When present the database is opened via `Database.deserialize`
+   * — an in-memory database restored from the snapshot — before migrations run
+   * (`CREATE TABLE IF NOT EXISTS` then no-ops). `filename` is ignored in this case.
+   */
+  readonly loadDataDir?: Blob
+}
+
+export type SqliteOptions = SqliteOptionsExternalApi
+
+const compiler = new SqliteQueryCompiler()
+
+const compile = (node: RootOperationNode) => {
+  const compiled = compiler.compileQuery(node, createQueryId())
+  return { sql: compiled.sql, parameters: compiled.parameters }
+}
+
+const bindable = (candidate: unknown): candidate is BindingExternalApi =>
+  candidate instanceof Uint8Array ||
+  typeof candidate === 'string' ||
+  typeof candidate === 'number' ||
+  typeof candidate === 'bigint' ||
+  typeof candidate === 'boolean'
+
+// SQLite binds strings/numbers/bigints/booleans/blobs/null directly and throws on any
+// other object — so a json-column value (an object/array) is serialized to JSON text.
+const coerceParam = (param: unknown): BindingExternalApi => {
+  if (param === undefined || param === null) {
+    return null
+  }
+  // oxlint-disable-next-line reform-rules/no-json-parse-stringify -- encodes an already-decoded json-column value for SQLite's text storage; the column's own Schema round-trips it on read
+  return bindable(param) ? param : JSON.stringify(param)
+}
+
+// Open the database (loading the Bun-only module lazily) and run migrations. Though
+// bun:sqlite is synchronous, this is the ASYNC-shaped work `makeDriver` defers to a
+// background fiber so the `Db` service can be acquired SYNCHRONOUSLY.
+const openSqlite = Effect.fn('openSqlite')(function* (
+  options: SqliteOptions,
+): Effect.fn.Return<Database, DbError> {
+  const { Database } = yield* Effect.tryPromise({
+    try: () => import('bun:sqlite'),
+    catch: (cause) => new DbError({ reason: 'bun:sqlite unavailable (Bun runtime required)', cause }),
+  })
+  // `Database.deserialize` wants the snapshot bytes synchronously; the `Blob` is already
+  // fully in memory (it came from a `dump`), so read it async here, then open sync below.
+  const seed = yield* Option.match(Option.fromNullable(options.loadDataDir), {
+    onNone: () => Effect.succeed(Option.none<Uint8Array>()),
+    onSome: (blob) =>
+      Effect.tryPromise({
+        try: () => blob.arrayBuffer(),
+        catch: (cause) => new DbError({ reason: 'loadDataDir read failed', cause }),
+      }).pipe(Effect.map((buffer) => Option.some(new Uint8Array(buffer)))),
+  })
+  const db = yield* Effect.try({
+    try: () =>
+      Option.match(seed, {
+        onNone: () => new Database(options.filename ?? ':memory:'),
+        // A snapshot restore is an in-memory database seeded from the serialized bytes.
+        onSome: (bytes) => Database.deserialize(bytes),
+      }),
+    catch: (cause) => new DbError({ reason: 'open failed', cause }),
+  })
+  yield* Option.match(Option.fromNullable(options.migrations), {
+    onNone: () => Effect.void,
+    onSome: (migrations) =>
+      Effect.forEach(migrations, (migration) =>
+        Effect.forEach(migration.statements, (statement) =>
+          Effect.try({
+            try: () => db.run(statement),
+            catch: (cause) => new DbError({ reason: 'migration failed', sql: statement, cause }),
+          }),
+        ),
+      ),
+  })
+  return db
+})
+
+const backendOf = (db: Database): EngineBackend => ({
+  query: (sql, parameters) =>
+    Effect.try({
+      try: () => db.query(sql).all(...parameters.map(coerceParam)),
+      catch: (cause) => new DbError({ reason: 'query failed', sql, cause }),
+    }),
+  // No native reactivity: `makeDriver` re-runs live queries after each write.
+  live: Option.none(),
+  // `serialize()` returns the full database as a Buffer; wrap it as a portable Blob so
+  // it round-trips through the same dump→save→reload contract as PGlite's tarball.
+  dump: Effect.try({
+    try: () => new Blob([new Uint8Array(db.serialize())]),
+    catch: (cause) => new DbError({ reason: 'dump failed', cause }),
+  }),
+  close: Effect.sync(() => db.close()),
+})
+
+/** The bun:sqlite `DbEngine`. Feed to `makeDriver` (see `Sqlite.layer`/`Sqlite.memory`). */
+export const make = (options: SqliteOptions): DbEngine => ({
+  compile,
+  open: () => openSqlite(options).pipe(Effect.map(backendOf)),
+})

package/src/index.ts

@@ -0,0 +1,21 @@
+// @playfast/reform-db-sqlite — the bun:sqlite engine for @playfast/reform-db.
+//
+// Provides the `Db` driver layer backed by Bun's built-in SQLite (`bun:sqlite`):
+// synchronous, dependency-free, with emulated reactivity (live `DbQuery`s re-run
+// after each write) and `serialize()`/`deserialize()` snapshots. Pair it with the
+// engine-neutral primitives (`DbColumn`/`DbTable`/`DbSchema`/`DbQuery`/`Migration`)
+// from `@playfast/reform-db` — remember the SQLite dialect for migrations:
+//
+//   import { Sqlite } from '@playfast/reform-db-sqlite'
+//   import { Migration } from '@playfast/reform-db'
+//   const DataLayer = QLive.pipe(
+//     Layer.provideMerge(
+//       Sqlite.layer({ filename: 'app.db', migrations: Migration.fromSchema(AppDb, Migration.sqlite) }),
+//     ),
+//   )
+
+export * as Sqlite from './sqlite'
+export type { MemoryOptions } from './sqlite'
+export type { SqliteOptions } from './engine'
+// The engine itself, for advanced callers wiring `makeDriver` directly.
+export { make as makeSqliteEngine } from './engine'

package/src/sqlite.bun.spec.ts

@@ -0,0 +1,137 @@
+// Bun-runtime integration test for the bun:sqlite engine. It uses Bun's own test
+// runner (`bun:test`) because `bun:sqlite` only exists under Bun — and vitest runs its
+// workers in Node, where that module is absent. Run it with `bun test` (the package's
+// `test` script); vitest's `*.test.ts` glob does not match `.spec.ts`, so the
+// workspace `vitest run` ignores it.
+import {
+  Db,
+  DbColumn,
+  DbQuery,
+  DbSchema,
+  DbTable,
+  Migration,
+  type QueryData,
+} from '@playfast/reform-db'
+import { expect, test } from 'bun:test'
+import { Context, Effect, Exit, Layer, Schedule, Schema, Scope } from 'effect'
+import { Sqlite } from './index'
+
+const Meta = Schema.Struct({ note: Schema.String })
+
+// A table covering the type shapes SQLite stores differently from Postgres: a boolean
+// (stored 0/1) and a json column (stored as text). The engine-tolerant column Schemas
+// in @playfast/reform-db must still decode them back to `boolean` / object.
+const Items = DbTable.make('items', {
+  columns: {
+    id: DbColumn.text({ primaryKey: true }),
+    label: DbColumn.text(),
+    rank: DbColumn.integer(),
+    done: DbColumn.boolean(),
+    meta: DbColumn.json(Meta),
+  },
+  primaryKey: 'id',
+})
+
+const AppDb = DbSchema.make('app', { tables: [Items] })
+const migrations = Migration.fromSchema(AppDb, Migration.sqlite)
+
+const ItemsQuery = DbQuery.make('items', { output: Items.Row })
+
+type Item = {
+  readonly id: string
+  readonly label: string
+  readonly rank: number
+  readonly done: boolean
+  readonly meta: { readonly note: string }
+}
+
+const rowsOf = (data: QueryData<Item>): ReadonlyArray<Item> =>
+  data._tag === 'Success' ? data.value : []
+
+const waitUntil = (predicate: () => boolean) =>
+  Effect.sync(predicate).pipe(
+    Effect.repeat({ until: (ready) => ready, schedule: Schedule.spaced('20 millis') }),
+    Effect.timeout('5 seconds'),
+  )
+
+const liveLayer = (dataLayer: Layer.Layer<Db>) =>
+  DbQuery.live(ItemsQuery, {
+    schema: AppDb,
+    inputs: [],
+    build: (_inputs, db) => db.selectFrom('items').selectAll().orderBy('rank'),
+  }).pipe(Layer.provideMerge(dataLayer))
+
+test('DbQuery reflects writes (emulated reactivity), decoding boolean + json columns', async () => {
+  const program = Effect.gen(function* () {
+    const store = yield* ItemsQuery.store
+
+    // The table exists but is empty; the emulated live query resolves to empty Success.
+    yield* waitUntil(() => store.getSnapshot()._tag === 'Success')
+    expect(rowsOf(store.getSnapshot())).toEqual([])
+
+    const insert = (id: string, label: string, rank: number, done: boolean, note: string) =>
+      Db.exec(AppDb.kysely.insertInto('items').values({ id, label, rank, done, meta: { note } }))
+
+    yield* insert('b', 'second', 2, false, 'two')
+    yield* insert('a', 'first', 1, true, 'one')
+
+    // Each `exec` re-fires the emulated live query.
+    yield* waitUntil(() => rowsOf(store.getSnapshot()).length === 2)
+    const rows = rowsOf(store.getSnapshot())
+    expect(rows.map((row) => row.label)).toEqual(['first', 'second'])
+    // boolean decoded from SQLite's 0/1, json decoded from stored text.
+    expect(rows.map((row) => row.done)).toEqual([true, false])
+    expect(rows.map((row) => row.meta.note)).toEqual(['one', 'two'])
+  }).pipe(Effect.provide(liveLayer(Sqlite.memory({ migrations }))))
+
+  await Effect.runPromise(program)
+})
+
+test('dump() → loadDataDir round-trips rows into a fresh in-memory db', async () => {
+  const dump = await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const context = yield* Layer.build(Sqlite.memory({ migrations }))
+        const driver = Context.get(context, Db)
+        yield* Db.exec(
+          AppDb.kysely
+            .insertInto('items')
+            .values({ id: 'a', label: 'first', rank: 1, done: true, meta: { note: 'one' } }),
+        ).pipe(Effect.provideService(Db, driver))
+        return yield* driver.dump()
+      }),
+    ),
+  )
+
+  await Effect.runPromise(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const store = yield* ItemsQuery.store
+        yield* waitUntil(() => rowsOf(store.getSnapshot()).length === 1)
+        const row = rowsOf(store.getSnapshot())[0]
+        expect(row?.label).toBe('first')
+        expect(row?.done).toBe(true)
+        expect(row?.meta.note).toBe('one')
+      }).pipe(Effect.provide(liveLayer(Sqlite.memory({ migrations, loadDataDir: dump })))),
+    ),
+  )
+})
+
+test('Sqlite.memory layer is sync-providable: store starts loading, then resolves to Success', async () => {
+  const layer = liveLayer(Sqlite.memory({ migrations }))
+
+  // Build the layer SYNCHRONOUSLY (bun:sqlite opens on a background fiber). This is the
+  // path reform's `runSync` renderer/proof mount takes; it must not throw "Fiber cannot
+  // be resolved synchronously".
+  const scope = Effect.runSync(Scope.make())
+  const context = Effect.runSync(Layer.buildWithScope(layer, scope))
+  const store = Context.get(context, ItemsQuery.store)
+
+  try {
+    expect(store.getSnapshot()._tag).toBe('Loading')
+    await Effect.runPromise(waitUntil(() => store.getSnapshot()._tag === 'Success'))
+    expect(rowsOf(store.getSnapshot())).toEqual([])
+  } finally {
+    await Effect.runPromise(Scope.close(scope, Exit.void))
+  }
+})

package/src/sqlite.ts

@@ -0,0 +1,38 @@
+import { Db, makeDriver } from '@playfast/reform-db'
+import { Layer } from 'effect'
+import { make, type SqliteOptions } from './engine'
+
+// The bun:sqlite `Db` layers, built on `@playfast/reform-db`'s engine-neutral
+// `makeDriver` and the SQLite engine here. Both build the `Db` service synchronously
+// (bun:sqlite opens on a background fiber inside `makeDriver`), so they are providable
+// under reform's `runSync` scene/proof mount. Reactivity is emulated by the core:
+// SQLite has no native live queries, so live `DbQuery`s re-run after each write.
+//
+// NOTE: migrations must be rendered for SQLite — pass
+// `Migration.fromSchema(AppDb, Migration.sqlite)`.
+
+// Options for `Sqlite.memory` — an in-memory database can still be migrated and seeded
+// from a `dump` snapshot, so it accepts everything but `filename`.
+export interface MemoryOptionsExternalApi {
+  readonly migrations?: SqliteOptions['migrations']
+  readonly loadDataDir?: SqliteOptions['loadDataDir']
+}
+
+export type MemoryOptions = MemoryOptionsExternalApi
+
+/** A persistent (or in-memory, if `filename` is omitted) bun:sqlite-backed `Db` driver. */
+export const layer = (options: SqliteOptions = {}): Layer.Layer<Db> =>
+  Layer.scoped(Db, makeDriver(make(options)))
+
+/** An ephemeral in-memory bun:sqlite-backed `Db` driver — the default for tests/proofs. */
+export const memory = (options: MemoryOptions = {}): Layer.Layer<Db> =>
+  Layer.scoped(
+    Db,
+    // Spread each option only when set so the bare `Sqlite.memory()` open stays unchanged.
+    makeDriver(
+      make({
+        ...(options.migrations !== undefined ? { migrations: options.migrations } : {}),
+        ...(options.loadDataDir !== undefined ? { loadDataDir: options.loadDataDir } : {}),
+      }),
+    ),
+  )