@playfast/reform-db-sqlite 1.0.1 → 1.1.0

package/README.md

@@ -44,9 +44,7 @@ const DataLayer = QueriesAndProcedures.pipe(
 )
 
 // Ephemeral in-memory — the default for tests / proofs:
-const TestLayer = QueriesAndProcedures.pipe(
-  Layer.provideMerge(Sqlite.memory({ migrations })),
-)
+const TestLayer = QueriesAndProcedures.pipe(Layer.provideMerge(Sqlite.memory({ migrations })))
 ```
 
 Both layers build the `Db` service **synchronously** (bun:sqlite opens on a background

package/package.json

@@ -1,55 +1,55 @@
 {
   "name": "@playfast/reform-db-sqlite",
-  "playbook": "./playbook",
-  "version": "1.0.1",
-  "type": "module",
+  "version": "1.1.0",
   "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",
+    "effect",
+    "local-first",
     "reactive",
-    "local-first"
+    "reform",
+    "sql",
+    "sqlite"
   ],
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
   "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"
-  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "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"
   },
-  "peerDependencies": {
-    "effect": "*",
-    "kysely": "*",
-    "@playfast/reform": "*",
-    "@playfast/reform-db": "*"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.14"
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "peerDependencies": {
+    "@playfast/reform": "*",
+    "@playfast/reform-db": "*",
+    "effect": "*",
+    "kysely": "*"
+  },
+  "playbook": "./playbook"
 }

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,18 +38,16 @@ 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> {
   const { Database } = yield* Effect.tryPromise({
     try: () => import('bun:sqlite'),
-    catch: (cause) => new DbError({ reason: 'bun:sqlite unavailable (Bun runtime required)', cause }),
+    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 +60,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 +85,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 +94,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,
@@ -12,15 +8,12 @@ import {
   Migration,
   type QueryData,
 } from '@playfast/reform-db'
-import { expect, test } from 'bun:test'
+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 })
 
-// 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 }),
@@ -50,7 +43,10 @@ const rowsOf = (data: QueryData<Item>): ReadonlyArray<Item> =>
 
 const waitUntil = (predicate: () => boolean) =>
   Effect.sync(predicate).pipe(
-    Effect.repeat({ until: (ready) => ready, schedule: Schedule.spaced('20 millis') }),
+    Effect.repeat({
+      until: (ready) => ready,
+      schedule: Schedule.spaced('20 millis'),
+    }),
     Effect.timeout('5 seconds'),
   )
 
@@ -61,11 +57,10 @@ const liveLayer = (dataLayer: Layer.Layer<Db>) =>
     build: (_inputs, db) => db.selectFrom('items').selectAll().orderBy('rank'),
   }).pipe(Layer.provideMerge(dataLayer))
 
-test('DbQuery reflects writes (emulated reactivity), decoding boolean + json columns', async () => {
+it.live('DbQuery reflects writes (emulated reactivity), decoding boolean + json columns', () => {
   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([])
 
@@ -75,36 +70,36 @@ test('DbQuery reflects writes (emulated reactivity), decoding boolean + json col
     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)
+  return program
 })
 
-test('dump() → loadDataDir round-trips rows into a fresh in-memory db', async () => {
-  const dump = await Effect.runPromise(
-    Effect.scoped(
+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' } }),
+          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(
+    yield* Effect.scoped(
       Effect.gen(function* () {
         const store = yield* ItemsQuery.store
         yield* waitUntil(() => rowsOf(store.getSnapshot()).length === 1)
@@ -113,25 +108,23 @@ test('dump() → loadDataDir round-trips rows into a fresh in-memory db', async
         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))
-  }
-})
+    )
+  }),
+)
+
+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 } : {}),