@firtoz/drizzle-sqlite-wasm 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @firtoz/drizzle-sqlite-wasm
 
+## 0.2.3
+
+### Patch Changes
+
+- [`d97681f`](https://github.com/firtoz/fullstack-toolkit/commit/d97681f56e103d033292005d31f298b03b4fa7ca) Thanks [@firtoz](https://github.com/firtoz)! - Add comprehensive Vite configuration documentation for OPFS support. Includes required COOP/COEP headers and a custom plugin to fix the sqlite-wasm 3.51.x OPFS proxy worker module format issue ("Unexpected token 'export'" error).
+
+- Updated dependencies [[`b0f7893`](https://github.com/firtoz/fullstack-toolkit/commit/b0f789314c4ee85d8c08466b968baad2977a2581)]:
+  - @firtoz/worker-helper@1.1.0
+
+## 0.2.2
+
+### Patch Changes
+
+- [`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0) Thanks [@firtoz](https://github.com/firtoz)! - Fix critical bug where debug mode prevented database operations from executing. Debug handlers now properly wrap and call the actual backend handlers instead of replacing them.
+
+  Add cursor-based and offset-based pagination support to `loadSubset` operations, enabling efficient navigation through large datasets.
+
+  Add `SQLInterceptor` support to log all SQL queries, including direct Drizzle queries, with the new `createInstrumentedDrizzle` function. This provides comprehensive query visibility for debugging and monitoring.
+
+  Add explicit return type `SqliteCollectionConfig<TTable>` to `sqliteCollectionOptions` function, improving type safety and eliminating the `any` cast at the return statement.
+
+- Updated dependencies [[`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0), [`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0)]:
+  - @firtoz/maybe-error@1.5.2
+  - @firtoz/drizzle-utils@0.3.1
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -111,6 +111,79 @@ import SqliteWorker from "@firtoz/drizzle-sqlite-wasm/worker/sqlite.worker?worke
 const { drizzle } = useDrizzleSqliteDb(SqliteWorker, "mydb", schema, migrations);
 ```
 
+#### Required Vite Configuration for OPFS Support
+
+To enable OPFS (Origin Private File System) persistence with SQLite WASM, you need to configure Vite properly. Add the following to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    // Required: Set COOP/COEP headers for SharedArrayBuffer support
+    {
+      name: "configure-response-headers",
+      configureServer: (server) => {
+        server.middlewares.use((_req, res, next) => {
+          res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+          res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+          next();
+        });
+      },
+    },
+    // Required: Fix for sqlite-wasm OPFS proxy worker module format
+    {
+      name: "sqlite-wasm-opfs-fix",
+      enforce: "pre",
+      transform(code, id) {
+        // Transform worker creation calls to use module type
+        if (
+          id.includes("@sqlite.org/sqlite-wasm") &&
+          code.includes("new Worker")
+        ) {
+          // This fixes the "Unexpected token 'export'" error in OPFS proxy worker
+          let transformed = code;
+          const workerRegex =
+            /new\s+Worker\s*\(\s*(new\s+URL\s*\([^)]+,[^)]+\))\s*\)/g;
+          transformed = transformed.replace(
+            workerRegex,
+            "new Worker($1, { type: 'module' })",
+          );
+
+          if (transformed !== code) {
+            return {
+              code: transformed,
+              map: null,
+            };
+          }
+        }
+      },
+    },
+  ],
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
+  optimizeDeps: {
+    exclude: ["@sqlite.org/sqlite-wasm"],
+  },
+  worker: {
+    format: "es",
+  },
+});
+```
+
+**Why is this needed?**
+
+1. **COOP/COEP Headers**: Required for `SharedArrayBuffer` support, which OPFS needs for synchronous file operations
+2. **Worker Module Fix**: sqlite-wasm 3.51.x creates workers without specifying `{ type: 'module' }`, causing syntax errors when the OPFS proxy worker (which uses ES module syntax) is loaded
+3. **Worker Format**: Ensures all workers are treated as ES modules
+4. **Exclude from Optimization**: Prevents Vite from pre-bundling sqlite-wasm, which can break worker creation
+
+For a complete example, see [`tests/test-playground/vite.config.ts`](../../tests/test-playground/vite.config.ts) in the repository.
+
 ### Webpack 5+
 
 Use `new URL()` with `import.meta.url`:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-sqlite-wasm",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"description": "Drizzle SQLite WASM bindings",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -43,9 +43,7 @@
 		"typecheck": "tsc --noEmit -p ./tsconfig.json",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
-		"format": "biome format src --write",
-		"test": "bun test --pass-with-no-tests",
-		"test:watch": "bun test --watch"
+		"format": "biome format src --write"
 	},
 	"keywords": [
 		"typescript",
@@ -71,19 +69,19 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@firtoz/drizzle-utils": "^0.3.0",
-		"@firtoz/maybe-error": "^1.5.1",
-		"@firtoz/worker-helper": "^1.0.0",
-		"@sqlite.org/sqlite-wasm": "^3.51.1-build2",
-		"@tanstack/db": "^0.5.10",
-		"drizzle-orm": "^0.44.7",
+		"@firtoz/drizzle-utils": "^0.3.1",
+		"@firtoz/maybe-error": "^1.5.2",
+		"@firtoz/worker-helper": "^1.1.0",
+		"@sqlite.org/sqlite-wasm": "^3.51.2-build3",
+		"@tanstack/db": "^0.5.20",
+		"drizzle-orm": "^0.45.1",
 		"drizzle-valibot": "^0.4.2",
-		"react": "^19.2.0",
+		"react": "^19.2.3",
 		"valibot": "^1.2.0",
-		"zod": "^4.1.13"
+		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@standard-schema/spec": "^1.0.0",
-		"@types/react": "^19.2.7"
+		"@standard-schema/spec": "^1.1.0",
+		"@types/react": "^19.2.8"
 	}
 }

package/src/collections/sqlite-collection.ts

@@ -1,4 +1,8 @@
-import type { InferSchemaOutput, SyncMode } from "@tanstack/db";
+import type {
+	InferSchemaOutput,
+	SyncMode,
+	CollectionConfig,
+} from "@tanstack/db";
 import type { IR } from "@tanstack/db";
 import {
 	eq,
@@ -31,6 +35,7 @@ import type {
 	TableWithRequiredFields,
 	BaseSyncConfig,
 	SyncBackend,
+	CollectionUtils,
 } from "@firtoz/drizzle-utils";
 import {
 	createSyncFunction,
@@ -38,6 +43,7 @@ import {
 	createGetKeyFunction,
 	createCollectionConfig,
 } from "@firtoz/drizzle-utils";
+import type * as v from "valibot";
 
 export type AnyDrizzleDatabase = BaseSQLiteDatabase<
 	"async",
@@ -102,6 +108,16 @@ export type SQLOperation =
 			tableName: string;
 			sql?: string;
 			timestamp: number;
+	  }
+	| {
+			/** Raw SQL query executed directly via Drizzle (not through collection) */
+			type: "raw-query";
+			sql: string;
+			params?: unknown[];
+			method: string;
+			rowCount: number;
+			context: string;
+			timestamp: number;
 	  };
 
 /**
@@ -144,6 +160,25 @@ export type ValidTableNames<TSchema extends Record<string, unknown>> = {
 	[K in keyof TSchema]: TSchema[K] extends TableWithRequiredFields ? K : never;
 }[keyof TSchema];
 
+/**
+ * Return type for sqliteCollectionOptions - configuration object for creating SQLite collections
+ *
+ * Note: The third type parameter of CollectionConfig uses `any` to maintain compatibility with
+ * TanStack DB's type system, which expects different schema types in different contexts.
+ */
+export type SqliteCollectionConfig<TTable extends Table> = Omit<
+	CollectionConfig<
+		InferSchemaOutput<SelectSchema<TTable>>,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Required for TanStack DB type compatibility
+		any
+	>,
+	"utils"
+> & {
+	schema: v.GenericSchema<unknown>;
+	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
+};
+
 /**
  * Converts TanStack DB IR BasicExpression to Drizzle SQL expression
  *
@@ -262,7 +297,9 @@ export function sqliteCollectionOptions<
 	const TDrizzle extends AnyDrizzleDatabase,
 	const TTableName extends string & ValidTableNames<DrizzleSchema<TDrizzle>>,
 	TTable extends DrizzleSchema<TDrizzle>[TTableName] & TableWithRequiredFields,
->(config: DrizzleCollectionConfig<TDrizzle, TTableName>) {
+>(
+	config: DrizzleCollectionConfig<TDrizzle, TTableName>,
+): SqliteCollectionConfig<TTable> {
 	const tableName = config.tableName as string &
 		ValidTableNames<DrizzleSchema<TDrizzle>>;
 
@@ -286,7 +323,7 @@ export function sqliteCollectionOptions<
 
 	// Create backend-specific implementation
 	const backend: SyncBackend<TTable> = {
-		initialLoad: async (write) => {
+		initialLoad: async () => {
 			const items = (await config.drizzle
 				.select()
 				.from(table)) as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
@@ -315,25 +352,44 @@ export function sqliteCollectionOptions<
 				});
 			}
 
-			for (const item of items) {
-				write(item);
-			}
+			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
 		},
 
-		loadSubset: async (options, write) => {
-			// Build the query with optional where, orderBy, and limit
+		loadSubset: async (options) => {
+			// Build the query with optional where, orderBy, limit, and offset
 			// Use $dynamic() to enable dynamic query building
 			let query = config.drizzle.select().from(table).$dynamic();
 
-			// Convert TanStack DB IR expressions to Drizzle expressions
+			// Combine where with cursor expressions if present
+			// The cursor.whereFrom gives us rows after the cursor position
 			let hasWhere = false;
-			if (options.where) {
-				const drizzleWhere = convertBasicExpressionToDrizzle(
-					options.where,
-					table,
-				);
-				query = query.where(drizzleWhere);
-				hasWhere = true;
+			if (options.where || options.cursor?.whereFrom) {
+				let drizzleWhere: SQL | undefined;
+
+				if (options.where && options.cursor?.whereFrom) {
+					// Combine main where with cursor expression using AND
+					const mainWhere = convertBasicExpressionToDrizzle(
+						options.where,
+						table,
+					);
+					const cursorWhere = convertBasicExpressionToDrizzle(
+						options.cursor.whereFrom,
+						table,
+					);
+					drizzleWhere = and(mainWhere, cursorWhere);
+				} else if (options.where) {
+					drizzleWhere = convertBasicExpressionToDrizzle(options.where, table);
+				} else if (options.cursor?.whereFrom) {
+					drizzleWhere = convertBasicExpressionToDrizzle(
+						options.cursor.whereFrom,
+						table,
+					);
+				}
+
+				if (drizzleWhere) {
+					query = query.where(drizzleWhere);
+					hasWhere = true;
+				}
 			}
 
 			if (options.orderBy) {
@@ -345,6 +401,11 @@ export function sqliteCollectionOptions<
 				query = query.limit(options.limit);
 			}
 
+			// Apply offset for offset-based pagination
+			if (options.offset !== undefined && options.offset > 0) {
+				query = query.offset(options.offset);
+			}
+
 			const items = (await query) as unknown as InferSchemaOutput<
 				SelectSchema<TTable>
 			>[];
@@ -358,6 +419,12 @@ export function sqliteCollectionOptions<
 				if (options.limit !== undefined) {
 					contextParts.push(`limit ${options.limit}`);
 				}
+				if (options.offset !== undefined && options.offset > 0) {
+					contextParts.push(`offset ${options.offset}`);
+				}
+				if (options.cursor) {
+					contextParts.push("with cursor pagination");
+				}
 
 				if (hasWhere) {
 					config.interceptor.onOperation({
@@ -393,6 +460,9 @@ export function sqliteCollectionOptions<
 				if (options.limit !== undefined) {
 					contextParts.push(`limit ${options.limit}`);
 				}
+				if (options.offset !== undefined && options.offset > 0) {
+					contextParts.push(`offset ${options.offset}`);
+				}
 
 				config.interceptor.onOperation({
 					type: "write",
@@ -404,22 +474,16 @@ export function sqliteCollectionOptions<
 				});
 			}
 
-			for (const item of items) {
-				write(item);
-			}
+			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
 		},
 
-		handleInsert: async (mutations) => {
+		handleInsert: async (items) => {
 			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
 
 			// Queue the transaction to serialize SQLite operations
 			await queueTransaction(async () => {
 				await config.drizzle.transaction(async (tx) => {
-					for (const mutation of mutations) {
-						// TanStack DB applies schema transform (including ID default) before calling this listener
-						// So mutation.modified already has the ID from insertSchemaWithIdDefault
-						const itemToInsert = mutation.modified;
-
+					for (const itemToInsert of items) {
 						if (config.debug) {
 							console.log(
 								`[${new Date().toISOString()}] insertListener inserting`,
@@ -544,21 +608,29 @@ export function sqliteCollectionOptions<
 		onInsert: config.debug
 			? async (params) => {
 					console.log("onInsert", params);
+					// Call the actual handler from syncResult (always defined in createSyncFunction)
+					// biome-ignore lint/style/noNonNullAssertion: onInsert is always defined in SyncFunctionResult
+					await syncResult.onInsert!(params);
 				}
 			: undefined,
 		onUpdate: config.debug
 			? async (params) => {
 					console.log("onUpdate", params);
+					// Call the actual handler from syncResult (always defined in createSyncFunction)
+					// biome-ignore lint/style/noNonNullAssertion: onUpdate is always defined in SyncFunctionResult
+					await syncResult.onUpdate!(params);
 				}
 			: undefined,
 		onDelete: config.debug
 			? async (params) => {
 					console.log("onDelete", params);
+					// Call the actual handler from syncResult (always defined in createSyncFunction)
+					// biome-ignore lint/style/noNonNullAssertion: onDelete is always defined in SyncFunctionResult
+					await syncResult.onDelete!(params);
 				}
 			: undefined,
 		syncMode: config.syncMode,
 	});
 
-	// biome-ignore lint/suspicious/noExplicitAny: Collection schema type needs to be flexible
-	return collectionConfig as any;
+	return collectionConfig;
 }

package/src/drizzle/direct.ts

@@ -1,4 +1,4 @@
-import type { Database } from "@sqlite.org/sqlite-wasm";
+import type { Database } from "../types";
 import type { DrizzleConfig } from "drizzle-orm";
 import { drizzle as drizzleSqliteProxy } from "drizzle-orm/sqlite-proxy";
 import { handleRemoteCallback } from "./handle-callback";

package/src/drizzle/handle-callback.ts

@@ -4,7 +4,7 @@ import {
 	success,
 	type MaybeError,
 } from "@firtoz/maybe-error";
-import type { Database } from "@sqlite.org/sqlite-wasm";
+import type { Database } from "../types";
 
 export const handleRemoteCallback = async ({
 	sqliteDb,

package/src/drizzle/worker.ts

@@ -1,6 +1,10 @@
 import type { DrizzleConfig } from "drizzle-orm";
 import { drizzle as drizzleSqliteProxy } from "drizzle-orm/sqlite-proxy";
 import type { ISqliteWorkerClient } from "../worker/client";
+import type {
+	SQLInterceptor,
+	SQLOperation,
+} from "../collections/sqlite-collection";
 
 export const drizzleSqliteWasmWorker = <
 	TSchema extends Record<string, unknown> = Record<string, never>,
@@ -22,3 +26,139 @@ export const drizzleSqliteWasmWorker = <
 		});
 	}, config);
 };
+
+/**
+ * Creates an instrumented Drizzle instance that logs all SQL queries.
+ * This wraps the standard drizzleSqliteWasmWorker to intercept every query.
+ */
+export const createInstrumentedDrizzle = <
+	TSchema extends Record<string, unknown> = Record<string, never>,
+>(
+	client: ISqliteWorkerClient,
+	config: DrizzleConfig<TSchema> = {},
+	interceptor?: SQLInterceptor,
+) => {
+	return drizzleSqliteProxy<TSchema>(async (sql, params, method) => {
+		const startTime = Date.now();
+
+		const result = await new Promise<{ rows: unknown[] }>((resolve, reject) => {
+			client.performRemoteCallback(
+				{
+					sql,
+					params,
+					method,
+				},
+				resolve,
+				reject,
+			);
+		});
+
+		// Log the operation if interceptor is provided
+		if (interceptor?.onOperation) {
+			// Parse SQL to determine context
+			const sqlLower = sql.toLowerCase().trim();
+			let context = "Direct Drizzle query";
+
+			if (sqlLower.startsWith("select")) {
+				// Extract table name from SELECT query
+				const fromMatch = sql.match(/from\s+["']?(\w+)["']?/i);
+				const tableName = fromMatch?.[1] || "unknown";
+
+				// Check for LIMIT/OFFSET - handle both literal values and ? placeholders
+				// Drizzle uses parameterized queries, so we need to check for `limit ?` style
+				const hasLimit = /limit\s+(\d+|\?|\$\d+)/i.test(sql);
+				const hasOffset = /offset\s+(\d+|\?|\$\d+)/i.test(sql);
+				const hasOrderBy = /order\s+by/i.test(sql);
+
+				if (hasLimit || hasOffset) {
+					// Extract actual values from params if using placeholders
+					// Drizzle typically puts LIMIT as second-to-last param, OFFSET as last
+					let limitVal = "?";
+					let offsetVal = "0";
+
+					// Try to extract literal values first
+					const literalLimit = sql.match(/limit\s+(\d+)/i);
+					const literalOffset = sql.match(/offset\s+(\d+)/i);
+
+					if (literalLimit) {
+						limitVal = literalLimit[1];
+					} else if (params && params.length > 0) {
+						// For parameterized queries, try to infer from params
+						// LIMIT/OFFSET are usually at the end
+						if (hasLimit && hasOffset && params.length >= 2) {
+							limitVal = String(params[params.length - 2]);
+							offsetVal = String(params[params.length - 1]);
+						} else if (hasLimit && params.length >= 1) {
+							limitVal = String(params[params.length - 1]);
+						}
+					}
+
+					if (literalOffset) {
+						offsetVal = literalOffset[1];
+					}
+
+					context = `SELECT with LIMIT ${limitVal} OFFSET ${offsetVal}`;
+				} else if (hasOrderBy) {
+					context = `SELECT all from ${tableName} (ordered)`;
+				} else {
+					context = `SELECT all from ${tableName}`;
+				}
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: result.rows?.length ?? 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			} else if (sqlLower.startsWith("insert")) {
+				const intoMatch = sql.match(/into\s+["']?(\w+)["']?/i);
+				context = `INSERT into ${intoMatch?.[1] || "unknown"}`;
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			} else if (sqlLower.startsWith("update")) {
+				const tableMatch = sql.match(/update\s+["']?(\w+)["']?/i);
+				context = `UPDATE ${tableMatch?.[1] || "unknown"}`;
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			} else if (sqlLower.startsWith("delete")) {
+				const fromMatch = sql.match(/from\s+["']?(\w+)["']?/i);
+				context = `DELETE from ${fromMatch?.[1] || "unknown"}`;
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			}
+		}
+
+		return result;
+	}, config);
+};

package/src/hooks/useDrizzleSqliteDb.ts

@@ -3,12 +3,16 @@ import {
 	customSqliteMigrate,
 	type DurableSqliteMigrationConfig,
 } from "@firtoz/drizzle-sqlite-wasm/sqlite-wasm-migrator";
-import { drizzleSqliteWasmWorker } from "@firtoz/drizzle-sqlite-wasm/drizzle-sqlite-wasm-worker";
+import {
+	drizzleSqliteWasmWorker,
+	createInstrumentedDrizzle,
+} from "@firtoz/drizzle-sqlite-wasm/drizzle-sqlite-wasm-worker";
 import type { ISqliteWorkerClient } from "../worker/manager";
 import {
 	initializeSqliteWorker,
 	isSqliteWorkerInitialized,
 } from "../worker/global-manager";
+import type { SQLInterceptor } from "../collections/sqlite-collection";
 
 export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 	WorkerConstructor: new () => Worker,
@@ -16,6 +20,8 @@ export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 	schema: TSchema,
 	migrations: DurableSqliteMigrationConfig,
 	debug?: boolean,
+	/** Optional interceptor to log ALL SQL queries (including direct Drizzle queries) */
+	interceptor?: SQLInterceptor,
 ) => {
 	const resolveRef = useRef<null | (() => void)>(null);
 	const rejectRef = useRef<null | ((error: unknown) => void)>(null);
@@ -72,45 +78,66 @@ export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 		};
 	}, [dbName, WorkerConstructor]);
 
+	// Store interceptor in a ref to avoid recreating drizzle on interceptor changes
+	const interceptorRef = useRef(interceptor);
+	interceptorRef.current = interceptor;
+
 	// Create drizzle instance with a callback-based approach that waits for the client
+	// Use instrumented version if interceptor is provided to log ALL queries
 	const drizzle = useMemo(() => {
 		if (debug) {
 			console.log(`[DEBUG] ${dbName} - creating drizzle proxy wrapper`);
 		}
-		return drizzleSqliteWasmWorker<TSchema>(
-			{
-				performRemoteCallback: (data, resolve, reject) => {
-					const client = sqliteClientRef.current;
-					if (!client) {
-						console.error(
-							`[DEBUG] ${dbName} - performRemoteCallback called but no sqliteClient yet`,
-						);
-						reject(
-							new Error(
-								`Database ${dbName} not ready yet - still initializing`,
-							),
-						);
-						return;
-					}
-					client.performRemoteCallback(data, resolve, reject);
-				},
-				onStarted: (callback) => {
-					const client = sqliteClientRef.current;
-					if (!client) {
-						console.warn(
-							`[DEBUG] ${dbName} - onStarted called but no sqliteClient yet`,
-						);
-						return;
-					}
-					client.onStarted(callback);
-				},
-				terminate: () => {
-					sqliteClientRef.current?.terminate();
-				},
+
+		const client: ISqliteWorkerClient = {
+			performRemoteCallback: (data, resolve, reject) => {
+				const actualClient = sqliteClientRef.current;
+				if (!actualClient) {
+					console.error(
+						`[DEBUG] ${dbName} - performRemoteCallback called but no sqliteClient yet`,
+					);
+					reject(
+						new Error(`Database ${dbName} not ready yet - still initializing`),
+					);
+					return;
+				}
+				actualClient.performRemoteCallback(data, resolve, reject);
+			},
+			onStarted: (callback) => {
+				const actualClient = sqliteClientRef.current;
+				if (!actualClient) {
+					console.warn(
+						`[DEBUG] ${dbName} - onStarted called but no sqliteClient yet`,
+					);
+					return;
+				}
+				actualClient.onStarted(callback);
 			},
-			{ schema },
-		);
-	}, [schema, dbName]); // Using ref for sqliteClient to avoid recreating drizzle
+			terminate: () => {
+				sqliteClientRef.current?.terminate();
+			},
+			checkpoint: () => {
+				return sqliteClientRef.current?.checkpoint() ?? Promise.resolve();
+			},
+		};
+
+		// Use instrumented version if interceptor is provided
+		// Use a wrapper that accesses the ref so interceptor changes don't recreate drizzle
+		const interceptorWrapper: SQLInterceptor = {
+			onOperation: (op) => interceptorRef.current?.onOperation?.(op),
+		};
+
+		// Always use instrumented if initial interceptor was provided
+		if (interceptor) {
+			return createInstrumentedDrizzle<TSchema>(
+				client,
+				{ schema },
+				interceptorWrapper,
+			);
+		}
+
+		return drizzleSqliteWasmWorker<TSchema>(client, { schema });
+	}, [schema, dbName, !!interceptor]); // Only recreate if interceptor presence changes, not on every render
 
 	useEffect(() => {
 		if (!sqliteClient) {

package/src/types.ts

@@ -0,0 +1,4 @@
+import type init from "@sqlite.org/sqlite-wasm";
+
+export type Sqlite3Static = Awaited<ReturnType<typeof init>>;
+export type Database = InstanceType<Sqlite3Static["oo1"]["DB"]>;

package/src/worker/sqlite.worker.ts

@@ -1,9 +1,3 @@
-import type {
-	// type BindingSpec,
-	Database,
-	Sqlite3Static,
-} from "@sqlite.org/sqlite-wasm";
-
 import { WorkerHelper } from "@firtoz/worker-helper";
 import {
 	SqliteWorkerClientMessageSchema,
@@ -18,6 +12,7 @@ import {
 } from "./schema";
 import { handleRemoteCallback } from "../drizzle/handle-callback";
 import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { Sqlite3Static, Database } from "../types";
 
 // Declare self as DedicatedWorkerGlobalScope for TypeScript
 declare var self: DedicatedWorkerGlobalScope;
@@ -27,7 +22,13 @@ class SqliteWorkerHelper extends WorkerHelper<
 	SqliteWorkerServerMessage
 > {
 	private initPromise: Promise<Sqlite3Static>;
-	private databases = new Map<DbId, { db: Database; initialized: boolean }>();
+	private databases = new Map<
+		DbId,
+		{
+			db: Database;
+			initialized: boolean;
+		}
+	>();
 
 	constructor() {
 		super(self, SqliteWorkerClientMessageSchema, sqliteWorkerServerMessage, {
@@ -50,10 +51,7 @@ class SqliteWorkerHelper extends WorkerHelper<
 
 		this.initPromise = import("@sqlite.org/sqlite-wasm").then(
 			async ({ default: sqlite3InitModule }) => {
-				const result = await sqlite3InitModule({
-					print: this.log.bind(this),
-					printErr: this.error.bind(this),
-				});
+				const result = await sqlite3InitModule();
 
 				return result;
 			},