@firtoz/drizzle-sqlite-wasm 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @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

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.2",
+	"version": "0.2.3",
 	"description": "Drizzle SQLite WASM bindings",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -71,17 +71,17 @@
 	"dependencies": {
 		"@firtoz/drizzle-utils": "^0.3.1",
 		"@firtoz/maybe-error": "^1.5.2",
-		"@firtoz/worker-helper": "^1.0.0",
-		"@sqlite.org/sqlite-wasm": "^3.51.1-build2",
-		"@tanstack/db": "^0.5.15",
+		"@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.3",
 		"valibot": "^1.2.0",
-		"zod": "^4.2.1"
+		"zod": "^4.3.5"
 	},
 	"devDependencies": {
 		"@standard-schema/spec": "^1.1.0",
-		"@types/react": "^19.2.7"
+		"@types/react": "^19.2.8"
 	}
 }

package/src/collections/sqlite-collection.ts

@@ -323,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>>[];
@@ -352,12 +352,10 @@ export function sqliteCollectionOptions<
 				});
 			}
 
-			for (const item of items) {
-				write(item);
-			}
+			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
 		},
 
-		loadSubset: async (options, write) => {
+		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();
@@ -476,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`,

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/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;
 			},