@effect/sql-sqlite-wasm 4.0.0-beta.7 → 4.0.0-beta.71

package/dist/SqliteMigrator.d.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * Utilities for applying Effect SQL migrations to SQLite WASM databases.
+ *
+ * This module re-exports the shared `Migrator` loaders and error types, then
+ * provides `run` and `layer` helpers that execute ordered migrations through the
+ * current SQLite WASM `SqlClient`. Use it when a browser, worker, or test
+ * runtime needs to create or upgrade a local SQLite schema before repositories,
+ * caches, sync services, or other database-backed services start.
+ *
+ * The migrator operates on whichever WASM client is in the environment. With
+ * `SqliteClient.makeMemory`, migrations update an in-memory database, so the
+ * resulting schema is transient unless you persist it with the client's
+ * `export` and `import` operations. With worker-backed OPFS databases, run the
+ * migrator against the same worker configuration and OPFS database name used by
+ * the rest of the application, and coordinate startup across tabs or workers so
+ * only one migrator upgrades a given database at a time. OPFS availability is
+ * browser- and origin-dependent, and this adapter does not currently write
+ * SQLite schema dumps for `schemaDirectory`.
+ *
+ * @since 4.0.0
  */
 import type * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -7,17 +25,21 @@ import * as Migrator from "effect/unstable/sql/Migrator";
 import type * as Client from "effect/unstable/sql/SqlClient";
 import type { SqlError } from "effect/unstable/sql/SqlError";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "effect/unstable/sql/Migrator";
 /**
- * @category constructor
- * @since 1.0.0
+ * Runs SQL migrations for a SQLite WASM database using the shared `Migrator` implementation and the current `SqlClient`.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export declare const run: <R>(options: Migrator.MigratorOptions<R>) => Effect.Effect<ReadonlyArray<readonly [id: number, name: string]>, SqlError | Migrator.MigrationError, Client.SqlClient | R>;
 /**
- * @category constructor
- * @since 1.0.0
+ * Creates a layer that runs the configured SQLite WASM migrations during layer construction and provides no services.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export declare const layer: <R>(options: Migrator.MigratorOptions<R>) => Layer.Layer<never, SqlError | Migrator.MigrationError, R | Client.SqlClient>;
 //# sourceMappingURL=SqliteMigrator.d.ts.map

package/dist/SqliteMigrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SqliteMigrator.d.ts","sourceRoot":"","sources":["../src/SqliteMigrator.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,8BAA8B,CAAA;AACxD,OAAO,KAAK,KAAK,MAAM,MAAM,+BAA+B,CAAA;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAE5D;;GAEG;AACH,cAAc,8BAA8B,CAAA;AAE5C;;;GAGG;AACH,eAAO,MAAM,GAAG,EAAE,CAAC,CAAC,EAClB,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,KACjC,MAAM,CAAC,MAAM,CAChB,aAAa,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,EAClD,QAAQ,GAAG,QAAQ,CAAC,cAAc,EAClC,MAAM,CAAC,SAAS,GAAG,CAAC,CACD,CAAA;AAErB;;;GAGG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EACrB,SAAS,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,KACnC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAsC,CAAA"}
+{"version":3,"file":"SqliteMigrator.d.ts","sourceRoot":"","sources":["../src/SqliteMigrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,8BAA8B,CAAA;AACxD,OAAO,KAAK,KAAK,MAAM,MAAM,+BAA+B,CAAA;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAE5D;;GAEG;AACH,cAAc,8BAA8B,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,GAAG,EAAE,CAAC,CAAC,EAClB,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,KACjC,MAAM,CAAC,MAAM,CAChB,aAAa,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,EAClD,QAAQ,GAAG,QAAQ,CAAC,cAAc,EAClC,MAAM,CAAC,SAAS,GAAG,CAAC,CACD,CAAA;AAErB;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EACrB,SAAS,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,KACnC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAsC,CAAA"}

package/dist/SqliteMigrator.js

@@ -1,17 +1,21 @@
 import * as Layer from "effect/Layer";
 import * as Migrator from "effect/unstable/sql/Migrator";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "effect/unstable/sql/Migrator";
 /**
- * @category constructor
- * @since 1.0.0
+ * Runs SQL migrations for a SQLite WASM database using the shared `Migrator` implementation and the current `SqlClient`.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const run = /*#__PURE__*/Migrator.make({});
 /**
- * @category constructor
- * @since 1.0.0
+ * Creates a layer that runs the configured SQLite WASM migrations during layer construction and provides no services.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const layer = options => Layer.effectDiscard(run(options));
 //# sourceMappingURL=SqliteMigrator.js.map

package/dist/SqliteMigrator.js.map

@@ -1 +1 @@
-{"version":3,"file":"SqliteMigrator.js","names":["Layer","Migrator","run","make","layer","options","effectDiscard"],"sources":["../src/SqliteMigrator.ts"],"sourcesContent":[null],"mappings":"AAIA,OAAO,KAAKA,KAAK,MAAM,cAAc;AACrC,OAAO,KAAKC,QAAQ,MAAM,8BAA8B;AAIxD;;;AAGA,cAAc,8BAA8B;AAE5C;;;;AAIA,OAAO,MAAMC,GAAG,gBAMZD,QAAQ,CAACE,IAAI,CAAC,EAAE,CAAC;AAErB;;;;AAIA,OAAO,MAAMC,KAAK,GAChBC,OAAoC,IAC6CL,KAAK,CAACM,aAAa,CAACJ,GAAG,CAACG,OAAO,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"SqliteMigrator.js","names":["Layer","Migrator","run","make","layer","options","effectDiscard"],"sources":["../src/SqliteMigrator.ts"],"sourcesContent":[null],"mappings":"AAsBA,OAAO,KAAKA,KAAK,MAAM,cAAc;AACrC,OAAO,KAAKC,QAAQ,MAAM,8BAA8B;AAIxD;;;AAGA,cAAc,8BAA8B;AAE5C;;;;;;AAMA,OAAO,MAAMC,GAAG,gBAMZD,QAAQ,CAACE,IAAI,CAAC,EAAE,CAAC;AAErB;;;;;;AAMA,OAAO,MAAMC,KAAK,GAChBC,OAAoC,IAC6CL,KAAK,CAACM,aAAa,CAACJ,GAAG,CAACG,OAAO,CAAC,CAAC","ignoreList":[]}

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpfsWorker from "./OpfsWorker.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as SqliteClient from "./SqliteClient.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as SqliteMigrator from "./SqliteMigrator.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,13 +1,13 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpfsWorker from "./OpfsWorker.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as SqliteClient from "./SqliteClient.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as SqliteMigrator from "./SqliteMigrator.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/sql-sqlite-wasm",
-  "version": "4.0.0-beta.7",
+  "version": "4.0.0-beta.71",
   "type": "module",
   "license": "MIT",
   "description": "A SQLite toolkit for Effect",
@@ -44,11 +44,11 @@
   },
   "devDependencies": {
     "@effect/wa-sqlite": "^0.2.1",
-    "effect": "^4.0.0-beta.7"
+    "effect": "^4.0.0-beta.71"
   },
   "peerDependencies": {
     "@effect/wa-sqlite": "^0.1.2",
-    "effect": "^4.0.0-beta.7"
+    "effect": "^4.0.0-beta.71"
   },
   "scripts": {
     "codegen": "effect-utils codegen",

package/src/OpfsWorker.ts

@@ -1,5 +1,44 @@
 /**
- * @since 1.0.0
+ * Worker-side entry point for SQLite WASM databases stored in the browser's
+ * Origin Private File System (OPFS).
+ *
+ * This module opens `@effect/wa-sqlite` with the OPFS access-handle VFS and
+ * serves the message protocol used by the worker-backed SQLite WASM client.
+ * Run it from a dedicated worker, or from a `SharedWorker` connection port, to
+ * keep durable local SQLite storage off the main thread while preserving the
+ * database in OPFS.
+ *
+ * **Mental model**
+ *
+ * - {@link run} owns one SQLite connection for one OPFS database name.
+ * - The worker posts `ready` after opening the database and then handles the
+ *   client protocol for SQL statements, import, export, update hooks, and
+ *   close.
+ * - The port in {@link OpfsWorkerConfig} is the only communication channel
+ *   between the client and the worker loop.
+ * - Closing the port, sending `close`, or interrupting the surrounding scope
+ *   releases the SQLite database handle.
+ *
+ * **Common tasks**
+ *
+ * Use this module for local-first browser data, offline caches,
+ * client-side migrations, and import/export workflows that need OPFS
+ * durability. Start {@link run} in the worker script, then connect the
+ * application through the worker-backed `SqliteClient` constructor.
+ *
+ * **Gotchas**
+ *
+ * OPFS requires browser support and a secure origin. Coordinate multiple tabs
+ * or workers before opening or migrating the same database, because this module
+ * owns a single connection and does not provide cross-tab locking. Close unused
+ * ports so access handles are released promptly.
+ *
+ * **See also**
+ *
+ * - {@link OpfsWorkerConfig} for the required worker port and database name.
+ * - {@link run} for starting the worker message loop.
+ *
+ * @since 4.0.0
  */
 /// <reference lib="webworker" />
 // oxlint-disable-next-line effect/no-import-from-barrel-package
@@ -7,12 +46,17 @@ import * as WaSqlite from "@effect/wa-sqlite"
 import SQLiteESMFactory from "@effect/wa-sqlite/dist/wa-sqlite.mjs"
 import { AccessHandlePoolVFS } from "@effect/wa-sqlite/src/examples/AccessHandlePoolVFS.js"
 import * as Effect from "effect/Effect"
-import { SqlError } from "effect/unstable/sql/SqlError"
+import { classifySqliteError, SqlError } from "effect/unstable/sql/SqlError"
 import type { OpfsWorkerMessage } from "./internal/opfsWorker.ts"
 
+const classifyError = (cause: unknown, message: string, operation: string) =>
+  classifySqliteError(cause, { message, operation })
+
 /**
+ * Configuration for the SQLite OPFS worker, including the message port used for the client protocol and the OPFS database name to open.
+ *
  * @category models
- * @since 1.0.0
+ * @since 4.0.0
  */
 export interface OpfsWorkerConfig {
   readonly port: EventTarget & Pick<MessagePort, "postMessage" | "close">
@@ -20,8 +64,10 @@ export interface OpfsWorkerConfig {
 }
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Runs the SQLite OPFS worker loop, opening the configured database, posting a ready message, handling query/import/export/update-hook messages, and closing when a close message is received.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const run = (
   options: OpfsWorkerConfig
@@ -34,7 +80,7 @@ export const run = (
     const db = yield* Effect.acquireRelease(
       Effect.try({
         try: () => sqlite3.open_v2(options.dbName, undefined, "opfs"),
-        catch: (cause) => new SqlError({ cause, message: "Failed to open database" })
+        catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to open database", "openDatabase") })
       }),
       (db) => Effect.sync(() => sqlite3.close(db))
     )

package/src/SqliteClient.ts

@@ -1,11 +1,38 @@
 /**
- * @since 1.0.0
+ * SQLite WASM client implementation for Effect SQL, backed by `@effect/wa-sqlite`.
+ *
+ * This module exposes constructors and layers for providing both the
+ * SQLite-specific `SqliteClient` service and the generic Effect `SqlClient`
+ * service in browser, worker, and test runtimes. Use it for local-first
+ * browser storage, offline caches, client-side migrations, sandboxed test
+ * databases, and import/export workflows that snapshot a SQLite database as a
+ * `Uint8Array`.
+ *
+ * `makeMemory` opens an in-memory database through the WASM memory VFS, so data
+ * is transient unless the client `export` result is persisted and later passed
+ * back to `import`. `make` talks to a scoped `Worker`, `SharedWorker`, or
+ * `MessagePort`, which is the path used by the OPFS worker helper for persistent
+ * browser storage. Worker-backed queries cross a message boundary, transferable
+ * buffers can be supplied with `withTransferables`, and imports transfer the
+ * supplied `Uint8Array` buffer to the worker.
+ *
+ * Both client variants serialize access through a single connection. A
+ * transaction holds that connection for the lifetime of its scope, so keep
+ * transactions short and use them for multi-statement writes that must commit
+ * atomically. OPFS availability depends on the browser and origin, and multiple
+ * tabs or workers opening the same OPFS database should coordinate migrations
+ * and writes outside this module. Worker-backed clients restart their scoped
+ * connection on worker errors, `executeStream` is not implemented there, and
+ * SQLite does not support `updateValues`.
+ *
+ * @since 4.0.0
  */
 // oxlint-disable-next-line effect/no-import-from-barrel-package
 import * as WaSqlite from "@effect/wa-sqlite"
 import SQLiteESMFactory from "@effect/wa-sqlite/dist/wa-sqlite.mjs"
 import { MemoryVFS } from "@effect/wa-sqlite/src/examples/MemoryVFS.js"
 import * as Config from "effect/Config"
+import * as Context from "effect/Context"
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
@@ -15,32 +42,40 @@ import * as Layer from "effect/Layer"
 import * as Scope from "effect/Scope"
 import * as ScopedRef from "effect/ScopedRef"
 import * as Semaphore from "effect/Semaphore"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import * as Reactivity from "effect/unstable/reactivity/Reactivity"
 import * as Client from "effect/unstable/sql/SqlClient"
 import type { Connection } from "effect/unstable/sql/SqlConnection"
-import { SqlError } from "effect/unstable/sql/SqlError"
+import { classifySqliteError, SqlError } from "effect/unstable/sql/SqlError"
 import * as Statement from "effect/unstable/sql/Statement"
 import type { OpfsWorkerMessage } from "./internal/opfsWorker.ts"
 
 const ATTR_DB_SYSTEM_NAME = "db.system.name"
 
+const classifyError = (cause: unknown, message: string, operation: string) =>
+  classifySqliteError(cause, { message, operation })
+
 /**
- * @category type ids
- * @since 1.0.0
+ * Runtime identifier attached to SQLite WASM client values.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~@effect/sql-sqlite-wasm/SqliteClient"
 
 /**
- * @category type ids
- * @since 1.0.0
+ * Type-level identifier for SQLite WASM client values.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~@effect/sql-sqlite-wasm/SqliteClient"
 
 /**
+ * SQLite WASM client service interface, extending `SqlClient` with database `export` and `import` operations and marking `updateValues` as unsupported for SQLite.
+ *
  * @category models
- * @since 1.0.0
+ * @since 4.0.0
  */
 export interface SqliteClient extends Client.SqlClient {
   readonly [TypeId]: TypeId
@@ -53,14 +88,18 @@ export interface SqliteClient extends Client.SqlClient {
 }
 
 /**
+ * Context service tag for the SQLite WASM client.
+ *
  * @category tags
- * @since 1.0.0
+ * @since 4.0.0
  */
-export const SqliteClient = ServiceMap.Service<SqliteClient>("@effect/sql-sqlite-wasm/SqliteClient")
+export const SqliteClient = Context.Service<SqliteClient>("@effect/sql-sqlite-wasm/SqliteClient")
 
 /**
+ * Configuration for an in-memory SQLite WASM client, including optional reactivity hooks, span attributes, and query/result name transforms.
+ *
  * @category models
- * @since 1.0.0
+ * @since 4.0.0
  */
 export interface SqliteClientMemoryConfig {
   readonly installReactivityHooks?: boolean
@@ -70,8 +109,10 @@ export interface SqliteClientMemoryConfig {
 }
 
 /**
+ * Configuration for a worker-backed SQLite WASM client, including the scoped worker or message port, optional reactivity hooks, span attributes, and query/result name transforms.
+ *
  * @category models
- * @since 1.0.0
+ * @since 4.0.0
  */
 export interface SqliteClientConfig {
   readonly worker: Effect.Effect<Worker | SharedWorker | MessagePort, never, Scope.Scope>
@@ -97,8 +138,10 @@ const initEffect = Effect.runSync(
 const registered = new Set<string>()
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Creates a scoped in-memory SQLite WASM client using the memory VFS, serializing access through a semaphore and exposing database `export` and `import` operations.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const makeMemory = (
   options: SqliteClientMemoryConfig
@@ -125,7 +168,7 @@ export const makeMemory = (
       const db = yield* Effect.acquireRelease(
         Effect.try({
           try: () => sqlite3.open_v2(":memory:", undefined, "memory-vfs"),
-          catch: (cause) => new SqlError({ cause, message: "Failed to open database" })
+          catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to open database", "openDatabase") })
         }),
         (db) => Effect.sync(() => sqlite3.close(db))
       )
@@ -165,7 +208,7 @@ export const makeMemory = (
             }
             return results
           },
-          catch: (cause) => new SqlError({ cause, message: "Failed to execute statement" })
+          catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
         })
 
       return identity<SqliteConnection>({
@@ -203,17 +246,19 @@ export const makeMemory = (
             transformRows
               ? Stream.mapArray((chunk) => transformRows(chunk) as any)
               : identity,
-            Stream.mapError((cause) => new SqlError({ cause, message: "Failed to execute statement" }))
+            Stream.mapError((cause) =>
+              new SqlError({ reason: classifyError(cause, "Failed to execute statement", "stream") })
+            )
           )
         },
         export: Effect.try({
           try: () => sqlite3.serialize(db, "main"),
-          catch: (cause) => new SqlError({ cause, message: "Failed to export database" })
+          catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to export database", "export") })
         }),
         import(data) {
           return Effect.try({
             try: () => sqlite3.deserialize(db, "main", data, data.length, data.length, 1 | 2),
-            catch: (cause) => new SqlError({ cause, message: "Failed to import database" })
+            catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to import database", "import") })
           })
         }
       })
@@ -225,7 +270,7 @@ export const makeMemory = (
     const acquirer = semaphore.withPermits(1)(Effect.succeed(connection))
     const transactionAcquirer = Effect.uninterruptibleMask((restore) => {
       const fiber = Fiber.getCurrent()!
-      const scope = ServiceMap.getUnsafe(fiber.services, Scope.Scope)
+      const scope = Context.getUnsafe(fiber.context, Scope.Scope)
       return Effect.as(
         Effect.tap(
           restore(semaphore.take(1)),
@@ -258,8 +303,10 @@ export const makeMemory = (
   })
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Creates a scoped worker-backed SQLite WASM client, communicating with the configured worker or message port, restarting the scoped connection on worker errors, and exposing database `export` and `import` operations.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = (
   options: SqliteClientConfig
@@ -297,7 +344,11 @@ export const make = (
           if (!resume) return
           pending.delete(id)
           if (error) {
-            resume(Exit.fail(new SqlError({ cause: error as string, message: "Failed to execute statement" })))
+            resume(
+              Exit.fail(
+                new SqlError({ reason: classifyError(error as string, "Failed to execute statement", "execute") })
+              )
+            )
           } else {
             resume(Exit.succeed(results))
           }
@@ -383,7 +434,7 @@ export const make = (
     const acquirer = semaphore.withPermits(1)(ScopedRef.get(connectionRef))
     const transactionAcquirer = Effect.uninterruptibleMask(Effect.fnUntraced(function*(restore) {
       const fiber = Fiber.getCurrent()!
-      const scope = ServiceMap.getUnsafe(fiber.services, Scope.Scope)
+      const scope = Context.getUnsafe(fiber.context, Scope.Scope)
       yield* restore(semaphore.take(1))
       yield* Scope.addFinalizer(scope, semaphore.release(1))
       return yield* ScopedRef.get(connectionRef)
@@ -422,81 +473,93 @@ const extractObject = (rows: [Array<string>, Array<any>]) => rows[1].map((row) =
 const extractRows = (rows: [Array<string>, Array<any>]) => rows[1]
 
 /**
+ * Fiber-local list of transferables to include with worker-backed SQLite WASM query messages.
+ *
  * @category tranferables
- * @since 1.0.0
+ * @since 4.0.0
  */
-export const Transferables = ServiceMap.Reference<ReadonlyArray<Transferable>>(
+export const Transferables = Context.Reference<ReadonlyArray<Transferable>>(
   "@effect/sql-sqlite-wasm/currentTransferables",
   { defaultValue: () => [] }
 )
 
 /**
+ * Runs an effect with the supplied transferables attached to worker-backed SQLite WASM query messages.
+ *
  * @category tranferables
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const withTransferables =
   (transferables: ReadonlyArray<Transferable>) => <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
     Effect.provideService(effect, Transferables, transferables)
 
 /**
+ * Builds a layer from an Effect `Config` value, providing both the in-memory SQLite WASM `SqliteClient` service and the generic `SqlClient` service.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layerMemoryConfig = (
   config: Config.Wrap<SqliteClientMemoryConfig>
 ): Layer.Layer<SqliteClient | Client.SqlClient, Config.ConfigError | SqlError> =>
-  Layer.effectServices(
-    Config.unwrap(config).asEffect().pipe(
+  Layer.effectContext(
+    Config.unwrap(config).pipe(
       Effect.flatMap(makeMemory),
       Effect.map((client) =>
-        ServiceMap.make(SqliteClient, client).pipe(
-          ServiceMap.add(Client.SqlClient, client)
+        Context.make(SqliteClient, client).pipe(
+          Context.add(Client.SqlClient, client)
         )
       )
     )
   ).pipe(Layer.provide(Reactivity.layer))
 
 /**
+ * Builds a layer from an in-memory SQLite WASM client configuration, providing both `SqliteClient` and the generic `SqlClient` service.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layerMemory = (
   config: SqliteClientMemoryConfig
 ): Layer.Layer<SqliteClient | Client.SqlClient, SqlError> =>
-  Layer.effectServices(
+  Layer.effectContext(
     Effect.map(makeMemory(config), (client) =>
-      ServiceMap.make(SqliteClient, client).pipe(
-        ServiceMap.add(Client.SqlClient, client)
+      Context.make(SqliteClient, client).pipe(
+        Context.add(Client.SqlClient, client)
       ))
   ).pipe(Layer.provide(Reactivity.layer))
 
 /**
+ * Builds a layer from a worker-backed SQLite WASM client configuration, providing both `SqliteClient` and the generic `SqlClient` service.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layer = (
   config: SqliteClientConfig
 ): Layer.Layer<SqliteClient | Client.SqlClient, SqlError> =>
-  Layer.effectServices(
+  Layer.effectContext(
     Effect.map(make(config), (client) =>
-      ServiceMap.make(SqliteClient, client).pipe(
-        ServiceMap.add(Client.SqlClient, client)
+      Context.make(SqliteClient, client).pipe(
+        Context.add(Client.SqlClient, client)
       ))
   ).pipe(Layer.provide(Reactivity.layer))
 
 /**
+ * Builds a layer from an Effect `Config` value, providing both the worker-backed SQLite WASM `SqliteClient` service and the generic `SqlClient` service.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layerConfig = (
   config: Config.Wrap<SqliteClientConfig>
 ): Layer.Layer<SqliteClient | Client.SqlClient, Config.ConfigError | SqlError> =>
-  Layer.effectServices(
-    Config.unwrap(config).asEffect().pipe(
+  Layer.effectContext(
+    Config.unwrap(config).pipe(
       Effect.flatMap(make),
       Effect.map((client) =>
-        ServiceMap.make(SqliteClient, client).pipe(
-          ServiceMap.add(Client.SqlClient, client)
+        Context.make(SqliteClient, client).pipe(
+          Context.add(Client.SqlClient, client)
         )
       )
     )

package/src/SqliteMigrator.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * Utilities for applying Effect SQL migrations to SQLite WASM databases.
+ *
+ * This module re-exports the shared `Migrator` loaders and error types, then
+ * provides `run` and `layer` helpers that execute ordered migrations through the
+ * current SQLite WASM `SqlClient`. Use it when a browser, worker, or test
+ * runtime needs to create or upgrade a local SQLite schema before repositories,
+ * caches, sync services, or other database-backed services start.
+ *
+ * The migrator operates on whichever WASM client is in the environment. With
+ * `SqliteClient.makeMemory`, migrations update an in-memory database, so the
+ * resulting schema is transient unless you persist it with the client's
+ * `export` and `import` operations. With worker-backed OPFS databases, run the
+ * migrator against the same worker configuration and OPFS database name used by
+ * the rest of the application, and coordinate startup across tabs or workers so
+ * only one migrator upgrades a given database at a time. OPFS availability is
+ * browser- and origin-dependent, and this adapter does not currently write
+ * SQLite schema dumps for `schemaDirectory`.
+ *
+ * @since 4.0.0
  */
 import type * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -8,13 +26,15 @@ import type * as Client from "effect/unstable/sql/SqlClient"
 import type { SqlError } from "effect/unstable/sql/SqlError"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "effect/unstable/sql/Migrator"
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Runs SQL migrations for a SQLite WASM database using the shared `Migrator` implementation and the current `SqlClient`.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const run: <R>(
   options: Migrator.MigratorOptions<R>
@@ -25,8 +45,10 @@ export const run: <R>(
 > = Migrator.make({})
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Creates a layer that runs the configured SQLite WASM migrations during layer construction and provides no services.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const layer = <R>(
   options: Migrator.MigratorOptions<R>

package/src/index.ts

@@ -1,14 +1,14 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpfsWorker from "./OpfsWorker.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as SqliteClient from "./SqliteClient.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as SqliteMigrator from "./SqliteMigrator.ts"