@playfast/reform-db-sqlite 0.1.0 → 1.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-db-sqlite",
   "playbook": "./playbook",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "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": [
@@ -36,7 +36,7 @@
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
-    "test": "bun test",
+    "test": "bun --bun run vitest run --config vitest.config.ts",
     "lint": "oxlint src",
     "lint:fix": "oxlint --fix src"
   },

package/src/engine.ts

@@ -1,38 +1,15 @@
 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.
+// Type-only: erased at build so package imports cleanly on Node (bun:sqlite absent).
 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.
-   */
+  // Use Migration.fromSchema(AppDb, Migration.sqlite) — layer does not pick dialect.
   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
 }
 
@@ -52,8 +29,7 @@ const bindable = (candidate: unknown): candidate is BindingExternalApi =>
   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.
+// SQLite throws on object binds — serialize json-column objects/arrays to text.
 const coerceParam = (param: unknown): BindingExternalApi => {
   if (param === undefined || param === null) {
     return null
@@ -62,9 +38,7 @@ const coerceParam = (param: unknown): BindingExternalApi => {
   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.
+// Lazy bun:sqlite import + migrations: async-shaped so makeDriver acquires Db sync.
 const openSqlite = Effect.fn('openSqlite')(function* (
   options: SqliteOptions,
 ): Effect.fn.Return<Database, DbError> {
@@ -72,8 +46,7 @@ const openSqlite = Effect.fn('openSqlite')(function* (
     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.
+  // deserialize wants bytes sync; Blob is already in memory — read async then open sync.
   const seed = yield* Option.match(Option.fromNullable(options.loadDataDir), {
     onNone: () => Effect.succeed(Option.none<Uint8Array>()),
     onSome: (blob) =>
@@ -86,7 +59,6 @@ const openSqlite = Effect.fn('openSqlite')(function* (
     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 }),
@@ -112,10 +84,8 @@ const backendOf = (db: Database): EngineBackend => ({
       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.
+  // No native live — makeDriver emulates by re-running after 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 }),
@@ -123,7 +93,6 @@ const backendOf = (db: Database): EngineBackend => ({
   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

@@ -1,21 +1,4 @@
-// @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

@@ -1,8 +1,4 @@
-// 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.
+// Bun-only: bun:sqlite is absent under Node. Run with Vitest on Bun.
 import {
   Db,
   DbColumn,
@@ -11,17 +7,14 @@ import {
   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'
+} from "@playfast/reform-db";
+import { expect, it } from "@effect/vitest";
+import { Context, Effect, Exit, Layer, Schedule, Schema, Scope } from "effect";
+import { Sqlite } from "./index";
 
-const Meta = Schema.Struct({ note: Schema.String })
+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', {
+const Items = DbTable.make("items", {
   columns: {
     id: DbColumn.text({ primaryKey: true }),
     label: DbColumn.text(),
@@ -29,109 +22,130 @@ const Items = DbTable.make('items', {
     done: DbColumn.boolean(),
     meta: DbColumn.json(Meta),
   },
-  primaryKey: 'id',
-})
+  primaryKey: "id",
+});
 
-const AppDb = DbSchema.make('app', { tables: [Items] })
-const migrations = Migration.fromSchema(AppDb, Migration.sqlite)
+const AppDb = DbSchema.make("app", { tables: [Items] });
+const migrations = Migration.fromSchema(AppDb, Migration.sqlite);
 
-const ItemsQuery = DbQuery.make('items', { output: Items.Row })
+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 }
-}
+  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 : []
+  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'),
-  )
+    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(
+    build: (_inputs, db) => db.selectFrom("items").selectAll().orderBy("rank"),
+  }).pipe(Layer.provideMerge(dataLayer));
+
+it.live(
+  "DbQuery reflects writes (emulated reactivity), decoding boolean + json columns",
+  () => {
+    const program = Effect.gen(function* () {
+      const store = yield* ItemsQuery.store;
+
+      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: '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))
-  }
-})
+            .insertInto("items")
+            .values({ id, label, rank, done, meta: { note } }),
+        );
+
+      yield* insert("b", "second", 2, false, "two");
+      yield* insert("a", "first", 1, true, "one");
+
+      yield* waitUntil(() => rowsOf(store.getSnapshot()).length === 2);
+      const rows = rowsOf(store.getSnapshot());
+      expect(rows.map((row) => row.label)).toEqual(["first", "second"]);
+      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 }))));
+
+    return program;
+  },
+);
+
+it.scopedLive(
+  "dump() → loadDataDir round-trips rows into a fresh in-memory db",
+  () =>
+    Effect.gen(function* () {
+      const dump = yield* 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();
+        }),
+      );
+
+      yield* 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 })),
+          ),
+        ),
+      );
+    }),
+);
+
+it.scopedLive(
+  "Sqlite.memory layer is sync-providable: store starts loading, then resolves to Success",
+  () =>
+    Effect.gen(function* () {
+      const layer = liveLayer(Sqlite.memory({ migrations }));
+
+      // Sync build (opens on background fiber) — must not throw "Fiber cannot be resolved synchronously".
+      const scope = Effect.runSync(Scope.make());
+      const context = Effect.runSync(Layer.buildWithScope(layer, scope));
+      yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
+      const store = Context.get(context, ItemsQuery.store);
+      expect(store.getSnapshot()._tag).toBe("Loading");
+      yield* waitUntil(() => store.getSnapshot()._tag === "Success");
+      expect(rowsOf(store.getSnapshot())).toEqual([]);
+    }),
+);

package/src/sqlite.ts

@@ -2,17 +2,6 @@ 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']
@@ -20,15 +9,13 @@ export interface MemoryOptionsExternalApi {
 
 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.
+    // Spread only when set so bare `Sqlite.memory()` open stays unchanged.
     makeDriver(
       make({
         ...(options.migrations !== undefined ? { migrations: options.migrations } : {}),