@firtoz/drizzle-sqlite-wasm 0.1.0

package/src/migration/migrator.ts

@@ -0,0 +1,148 @@
+// Adapted from https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-orm/src/durable-sqlite/migrator.ts
+// Adaptation date: 26/10/2025 20:28 commit 9cf0ed2
+
+import { sql } from "drizzle-orm";
+import type { MigrationMeta } from "drizzle-orm/migrator";
+import type { SqliteRemoteDatabase } from "drizzle-orm/sqlite-proxy";
+import type { migrate as durableSqliteMigrate } from "drizzle-orm/durable-sqlite/migrator";
+
+export type DurableSqliteMigrationConfig = Parameters<
+	typeof durableSqliteMigrate
+>[1];
+
+function readMigrationFiles({
+	journal,
+	migrations,
+}: DurableSqliteMigrationConfig): MigrationMeta[] {
+	const migrationQueries: MigrationMeta[] = [];
+
+	for (const journalEntry of journal.entries) {
+		const query =
+			migrations[`m${journalEntry.idx.toString().padStart(4, "0")}`];
+
+		if (!query) {
+			throw new Error(`Missing migration: ${journalEntry.tag}`);
+		}
+
+		try {
+			const result = query.split("--> statement-breakpoint").map((it) => {
+				return it;
+			});
+
+			migrationQueries.push({
+				sql: result,
+				bps: journalEntry.breakpoints,
+				folderMillis: journalEntry.when,
+				hash: "",
+			});
+		} catch {
+			throw new Error(`Failed to parse migration: ${journalEntry.tag}`);
+		}
+	}
+
+	return migrationQueries;
+}
+
+export async function customSqliteMigrate<
+	TSchema extends Record<string, unknown>,
+>(
+	db: SqliteRemoteDatabase<TSchema>,
+	config: DurableSqliteMigrationConfig,
+	debug: boolean = false,
+): Promise<void> {
+	if (debug) {
+		console.log(
+			`[${new Date().toISOString()}] [SqliteWasmMigrator] migrating database`,
+			config,
+		);
+	}
+
+	const migrations = readMigrationFiles(config);
+	let currentStatement: string | null = null;
+
+	let migrationCount = 0;
+	let success = true;
+
+	await db.transaction(async (tx) => {
+		try {
+			const migrationsTable = "__drizzle_migrations";
+
+			await tx.run(sql`
+				CREATE TABLE IF NOT EXISTS ${sql.identifier(migrationsTable)} (
+					id SERIAL PRIMARY KEY,
+					hash text NOT NULL,
+					created_at numeric
+				)
+			`);
+
+			const dbMigrations = await tx.values<[number, string, string]>(
+				sql`SELECT id, hash, created_at FROM ${sql.identifier(migrationsTable)} ORDER BY created_at DESC LIMIT 1`,
+			);
+
+			const lastDbMigration = dbMigrations[0] ?? undefined;
+
+			if (debug) {
+				console.log(
+					`[${new Date().toISOString()}] [SqliteWasmMigrator] last db migration`,
+					lastDbMigration,
+				);
+			}
+
+			for (const migration of migrations) {
+				if (
+					!lastDbMigration ||
+					Number(lastDbMigration[2]) < migration.folderMillis
+				) {
+					for (const stmt of migration.sql) {
+						currentStatement = stmt;
+						if (debug) {
+							console.log(
+								`[${new Date().toISOString()}] [SqliteWasmMigrator] running migration`,
+								stmt,
+							);
+						}
+						await tx.run(sql.raw(stmt));
+						currentStatement = null;
+					}
+					await tx.run(
+						sql`INSERT INTO ${sql.identifier(
+							migrationsTable,
+						)} ("hash", "created_at") VALUES(${migration.hash}, ${migration.folderMillis})`,
+					);
+					migrationCount++;
+				}
+			}
+		} catch (error: unknown) {
+			const e = error instanceof Error ? error : new Error(String(error));
+			console.error("[Sqlite WASM Migrator] Database migration failed:", {
+				error: e,
+				errorMessage: e.message,
+				errorStack: e.stack,
+				migrations: Object.keys(migrations),
+				...(currentStatement && { failedStatement: currentStatement }),
+			});
+			tx.rollback();
+			success = false;
+			throw e;
+		}
+	});
+
+	if (debug) {
+		if (!success) {
+			console.log(
+				`[${new Date().toISOString()}] [SqliteWasmMigrator] migration failed.`,
+			);
+			return;
+		}
+
+		if (migrationCount > 0) {
+			console.log(
+				`[${new Date().toISOString()}] [SqliteWasmMigrator] migration completed. migrations count: ${migrationCount} migrations applied.`,
+			);
+		} else {
+			console.log(
+				`[${new Date().toISOString()}] [SqliteWasmMigrator] no migrations applied.`,
+			);
+		}
+	}
+}

package/src/worker/client.ts

@@ -0,0 +1,11 @@
+import type { SqliteWorkerRemoteCallbackClientMessage } from "./schema";
+
+export interface ISqliteWorkerClient {
+	performRemoteCallback: (
+		data: Omit<SqliteWorkerRemoteCallbackClientMessage, "type" | "id" | "dbId">,
+		resolve: (value: { rows: unknown[] }) => void,
+		reject: (error: Error) => void,
+	) => void;
+	onStarted: (callback: () => void) => void;
+	terminate: () => void;
+}

package/src/worker/global-manager.ts

@@ -0,0 +1,78 @@
+import { SqliteWorkerManager } from "./manager";
+
+let globalManager: SqliteWorkerManager | null = null;
+let initPromise: Promise<SqliteWorkerManager> | null = null;
+
+/**
+ * Initialize the global SQLite worker manager.
+ * Should be called once, early in your app (e.g., in entry.client.tsx).
+ * Subsequent calls return the same manager instance.
+ *
+ * @example
+ * ```typescript
+ * // In entry.client.tsx
+ * import { initializeSqliteWorker } from "@firtoz/drizzle-sqlite-wasm";
+ * import SqliteWorker from "@firtoz/drizzle-sqlite-wasm/worker/sqlite.worker?worker";
+ *
+ * initializeSqliteWorker(SqliteWorker);
+ * ```
+ */
+export function initializeSqliteWorker(
+	WorkerConstructor: new () => Worker,
+	debug: boolean = false,
+): Promise<SqliteWorkerManager> {
+	// Return existing init promise if initialization is in progress
+	if (initPromise) {
+		return initPromise;
+	}
+
+	// Return resolved promise if already initialized
+	if (globalManager) {
+		return Promise.resolve(globalManager);
+	}
+
+	// Start initialization
+	initPromise = (async () => {
+		const worker = new WorkerConstructor();
+		const manager = new SqliteWorkerManager(worker, debug);
+		globalManager = manager;
+
+		// Wait for the worker to actually send its Ready message
+		await manager.ready;
+
+		return manager;
+	})();
+
+	return initPromise;
+}
+
+/**
+ * Get the global SQLite worker manager.
+ * Throws an error if not initialized.
+ */
+export function getSqliteWorkerManager(): SqliteWorkerManager {
+	if (!globalManager) {
+		throw new Error(
+			"SQLite worker manager not initialized. Call initializeSqliteWorker() first.",
+		);
+	}
+	return globalManager;
+}
+
+/**
+ * Check if the global manager has been initialized
+ */
+export function isSqliteWorkerInitialized(): boolean {
+	return globalManager !== null;
+}
+
+/**
+ * Reset the global manager (mainly for testing)
+ */
+export function resetSqliteWorkerManager() {
+	if (globalManager) {
+		globalManager.terminate();
+	}
+	globalManager = null;
+	initPromise = null;
+}

package/src/worker/manager.ts

@@ -0,0 +1,339 @@
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import { WorkerClient } from "@firtoz/worker-helper/WorkerClient";
+import {
+	type SqliteWorkerClientMessage,
+	type SqliteWorkerServerMessage,
+	type RemoteCallbackId,
+	type DbId,
+	type StartRequestId,
+	type CheckpointId,
+	SqliteWorkerClientMessageSchema,
+	sqliteWorkerServerMessage,
+	SqliteWorkerServerMessageType,
+	SqliteWorkerClientMessageType,
+	type SqliteWorkerRemoteCallbackClientMessage,
+	RemoteCallbackIdSchema,
+	StartRequestIdSchema,
+	CheckpointIdSchema,
+} from "./schema";
+
+export interface ISqliteWorkerClient {
+	performRemoteCallback: (
+		data: Omit<SqliteWorkerRemoteCallbackClientMessage, "type" | "id" | "dbId">,
+		resolve: (value: { rows: unknown[] }) => void,
+		reject: (error: Error) => void,
+	) => void;
+	checkpoint: () => Promise<void>;
+	onStarted: (callback: () => void) => void;
+	terminate: () => void;
+}
+
+/**
+ * Per-database instance that can perform operations on a specific database
+ */
+export class DbInstance implements ISqliteWorkerClient {
+	private dbId: DbId | null = null;
+	private startedCallbacks: Array<() => void> = [];
+	private isStarted = false;
+
+	constructor(
+		private readonly manager: SqliteWorkerManager,
+		public readonly dbName: string,
+		private readonly debug: boolean = false,
+	) {}
+
+	/**
+	 * Internal method called by manager when database is started
+	 */
+	_setStarted(dbId: DbId) {
+		this.dbId = dbId;
+		this.isStarted = true;
+
+		// Call all pending callbacks
+		for (const callback of this.startedCallbacks) {
+			callback();
+		}
+		this.startedCallbacks = [];
+	}
+
+	public performRemoteCallback(
+		data: Omit<SqliteWorkerRemoteCallbackClientMessage, "type" | "id" | "dbId">,
+		resolve: (value: { rows: unknown[] }) => void,
+		reject: (error: Error) => void,
+	) {
+		if (!this.dbId) {
+			reject(
+				new Error(`Database not started - dbId is null for ${this.dbName}`),
+			);
+			return;
+		}
+
+		if (this.debug) {
+			console.log(
+				`[${new Date().toISOString()}] [DbInstance:${this.dbName}] performing remote callback`,
+				data,
+			);
+		}
+
+		this.manager.performRemoteCallback(this.dbId, data, resolve, reject);
+	}
+
+	public checkpoint(): Promise<void> {
+		return new Promise((resolve, reject) => {
+			if (!this.dbId) {
+				reject(
+					new Error(`Database not started - dbId is null for ${this.dbName}`),
+				);
+				return;
+			}
+
+			if (this.debug) {
+				console.log(
+					`[${new Date().toISOString()}] [DbInstance:${this.dbName}] checkpointing database`,
+				);
+			}
+
+			this.manager.checkpoint(this.dbId, resolve, reject);
+		});
+	}
+
+	public onStarted(callback: () => void) {
+		if (this.isStarted) {
+			// Already started, call immediately
+			callback();
+		} else {
+			this.startedCallbacks.push(callback);
+		}
+	}
+
+	public terminate() {
+		// Per-db instances don't terminate the worker
+		// That's managed by the SqliteWorkerManager
+	}
+}
+
+/**
+ * Main worker manager that can create multiple database instances
+ */
+export class SqliteWorkerManager extends WorkerClient<
+	SqliteWorkerClientMessage,
+	SqliteWorkerServerMessage
+> {
+	private readonly remoteCallbacks = new Map<
+		RemoteCallbackId,
+		{
+			resolve: (value: { rows: unknown[] }) => void;
+			reject: (error: Error) => void;
+		}
+	>();
+
+	private readonly checkpointCallbacks = new Map<
+		CheckpointId,
+		{
+			resolve: () => void;
+			reject: (error: Error) => void;
+		}
+	>();
+
+	private readyResolve?: () => void;
+	private readyReject?: (error: Error) => void;
+	private readonly readyPromise: Promise<void>;
+	private isReady = false;
+
+	private readonly dbInstances = new Map<string, DbInstance>();
+	private readonly pendingStarts = new Map<
+		StartRequestId,
+		{ dbName: string; instance: DbInstance }
+	>();
+
+	constructor(
+		worker: Worker,
+		private readonly debug: boolean = false,
+	) {
+		super({
+			worker,
+			clientSchema: SqliteWorkerClientMessageSchema,
+			serverSchema: sqliteWorkerServerMessage,
+			onMessage: (message) => {
+				this.onMessage(message);
+			},
+			onValidationError: (error, rawMessage) => {
+				console.error(error, rawMessage);
+				// Reject promises if we get validation errors before being ready
+				if (!this.isReady && this.readyReject) {
+					this.readyReject(new Error(`Validation error: ${error.message}`));
+				}
+			},
+			onError: (event) => {
+				console.error(event);
+				// Reject promises if worker errors before being ready
+				if (!this.isReady && this.readyReject) {
+					this.readyReject(
+						new Error(`Worker error: ${event.message || "Unknown error"}`),
+					);
+				}
+			},
+		});
+
+		this.readyPromise = new Promise((resolve, reject) => {
+			this.readyResolve = resolve;
+			this.readyReject = reject;
+		});
+	}
+
+	/**
+	 * Promise that resolves when the worker sends its first Ready message
+	 */
+	public get ready(): Promise<void> {
+		return this.readyPromise;
+	}
+
+	private onMessage(message: SqliteWorkerServerMessage) {
+		const { type } = message;
+		switch (type) {
+			case SqliteWorkerServerMessageType.Ready:
+				{
+					this.isReady = true;
+					this.readyResolve?.();
+					if (this.debug) {
+						console.log("[SqliteWorkerManager] ready for databases");
+					}
+				}
+				break;
+			case SqliteWorkerServerMessageType.Started:
+				{
+					const pending = this.pendingStarts.get(message.requestId);
+					if (pending) {
+						pending.instance._setStarted(message.dbId);
+						this.pendingStarts.delete(message.requestId);
+					}
+				}
+				break;
+			case SqliteWorkerServerMessageType.RemoteCallbackResponse:
+				{
+					const { id, rows } = message;
+					const remoteCallback = this.remoteCallbacks.get(id);
+					if (remoteCallback) {
+						remoteCallback.resolve({ rows });
+						this.remoteCallbacks.delete(id);
+					}
+				}
+				break;
+			case SqliteWorkerServerMessageType.RemoteCallbackError:
+				{
+					const { id, error } = message;
+					const remoteCallback = this.remoteCallbacks.get(id);
+					if (remoteCallback) {
+						remoteCallback.reject(new Error(error));
+						this.remoteCallbacks.delete(id);
+					}
+				}
+				break;
+			case SqliteWorkerServerMessageType.CheckpointComplete:
+				{
+					const { id } = message;
+					const checkpointCallback = this.checkpointCallbacks.get(id);
+					if (checkpointCallback) {
+						checkpointCallback.resolve();
+						this.checkpointCallbacks.delete(id);
+					}
+				}
+				break;
+			case SqliteWorkerServerMessageType.CheckpointError:
+				{
+					const { id, error } = message;
+					const checkpointCallback = this.checkpointCallbacks.get(id);
+					if (checkpointCallback) {
+						checkpointCallback.reject(new Error(error));
+						this.checkpointCallbacks.delete(id);
+					}
+				}
+				break;
+			default:
+				return exhaustiveGuard(type);
+		}
+	}
+
+	/**
+	 * Get or create a database instance
+	 */
+	public async getDbInstance(dbName: string): Promise<DbInstance> {
+		// Check if instance already exists
+		let instance = this.dbInstances.get(dbName);
+		if (instance) {
+			return instance;
+		}
+
+		// Check again after waiting (another call might have created it)
+		instance = this.dbInstances.get(dbName);
+		if (instance) {
+			return instance;
+		}
+
+		// Create new instance
+		instance = new DbInstance(this, dbName, this.debug);
+		this.dbInstances.set(dbName, instance);
+
+		// Start the database
+
+		const startRequestId = StartRequestIdSchema.parse(crypto.randomUUID());
+		this.pendingStarts.set(startRequestId, { dbName, instance });
+
+		this.send({
+			type: SqliteWorkerClientMessageType.Start,
+			requestId: startRequestId,
+			dbName: dbName,
+		});
+
+		return instance;
+	}
+
+	/**
+	 * Internal method for db instances to perform remote callbacks
+	 */
+	public performRemoteCallback(
+		dbId: DbId,
+		data: Omit<SqliteWorkerRemoteCallbackClientMessage, "type" | "id" | "dbId">,
+		resolve: (value: { rows: unknown[] }) => void,
+		reject: (error: Error) => void,
+	) {
+		if (this.debug) {
+			console.log(
+				`[${new Date().toISOString()}] [SqliteWorkerManager] performing remote callback for dbId: ${dbId}`,
+				data,
+			);
+		}
+		const id = RemoteCallbackIdSchema.parse(crypto.randomUUID());
+		this.remoteCallbacks.set(id, { resolve, reject });
+		this.send({
+			type: SqliteWorkerClientMessageType.RemoteCallbackRequest,
+			id,
+			dbId,
+			sql: data.sql,
+			params: data.params,
+			method: data.method,
+		});
+	}
+
+	/**
+	 * Internal method for db instances to checkpoint the database
+	 */
+	public checkpoint(
+		dbId: DbId,
+		resolve: () => void,
+		reject: (error: Error) => void,
+	) {
+		if (this.debug) {
+			console.log(
+				`[${new Date().toISOString()}] [SqliteWorkerManager] checkpointing database for dbId: ${dbId}`,
+			);
+		}
+		const id = CheckpointIdSchema.parse(crypto.randomUUID());
+		this.checkpointCallbacks.set(id, { resolve, reject });
+		this.send({
+			type: SqliteWorkerClientMessageType.Checkpoint,
+			id,
+			dbId,
+		});
+	}
+}

package/src/worker/schema.ts

@@ -0,0 +1,111 @@
+import z from "zod";
+
+export const RemoteCallbackIdSchema = z.string().brand("remote-callback-id");
+export type RemoteCallbackId = z.infer<typeof RemoteCallbackIdSchema>;
+
+export const DbIdSchema = z.string().brand("db-id");
+export type DbId = z.infer<typeof DbIdSchema>;
+
+export const StartRequestIdSchema = z.string().brand("start-request-id");
+export type StartRequestId = z.infer<typeof StartRequestIdSchema>;
+
+export const CheckpointIdSchema = z.string().brand("checkpoint-id");
+export type CheckpointId = z.infer<typeof CheckpointIdSchema>;
+
+export enum SqliteWorkerClientMessageType {
+	Start = "start",
+	RemoteCallbackRequest = "remote-callback-request",
+	Checkpoint = "checkpoint",
+}
+
+export enum SqliteWorkerServerMessageType {
+	Ready = "ready",
+	Started = "started",
+	RemoteCallbackResponse = "remote-callback-response",
+	RemoteCallbackError = "remote-callback-error",
+	CheckpointComplete = "checkpoint-complete",
+	CheckpointError = "checkpoint-error",
+}
+
+export const RemoteCallbackRequestSchema = z.object({
+	type: z.literal(SqliteWorkerClientMessageType.RemoteCallbackRequest),
+	// AsyncRemoteCallback
+	// sql: string, params: any[], method: 'run' | 'all' | 'values' | 'get'
+	id: RemoteCallbackIdSchema,
+	dbId: DbIdSchema,
+	sql: z.string(),
+	params: z.array(z.any()),
+	method: z.enum(["run", "all", "values", "get"]),
+});
+
+export type SqliteWorkerRemoteCallbackClientMessage = z.infer<
+	typeof RemoteCallbackRequestSchema
+>;
+
+export const CheckpointRequestSchema = z.object({
+	type: z.literal(SqliteWorkerClientMessageType.Checkpoint),
+	id: CheckpointIdSchema,
+	dbId: DbIdSchema,
+});
+
+export type CheckpointRequest = z.infer<typeof CheckpointRequestSchema>;
+
+export const SqliteWorkerClientMessageSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal(SqliteWorkerClientMessageType.Start),
+		requestId: StartRequestIdSchema,
+		dbName: z.string(),
+	}),
+	RemoteCallbackRequestSchema,
+	CheckpointRequestSchema,
+]);
+
+export const RemoteCallbackResponseSchema = z.object({
+	type: z.literal(SqliteWorkerServerMessageType.RemoteCallbackResponse),
+	id: RemoteCallbackIdSchema,
+	rows: z.array(z.any()),
+});
+
+export const RemoteCallbackErrorServerMessageSchema = z.object({
+	type: z.literal(SqliteWorkerServerMessageType.RemoteCallbackError),
+	id: RemoteCallbackIdSchema,
+	error: z.string(),
+});
+
+export const CheckpointCompleteSchema = z.object({
+	type: z.literal(SqliteWorkerServerMessageType.CheckpointComplete),
+	id: CheckpointIdSchema,
+});
+
+export const CheckpointErrorSchema = z.object({
+	type: z.literal(SqliteWorkerServerMessageType.CheckpointError),
+	id: CheckpointIdSchema,
+	error: z.string(),
+});
+
+export const sqliteWorkerServerMessage = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal(SqliteWorkerServerMessageType.Ready),
+	}),
+	z.object({
+		type: z.literal(SqliteWorkerServerMessageType.Started),
+		requestId: StartRequestIdSchema,
+		dbId: DbIdSchema,
+	}),
+	RemoteCallbackResponseSchema,
+	RemoteCallbackErrorServerMessageSchema,
+	CheckpointCompleteSchema,
+	CheckpointErrorSchema,
+]);
+
+export type SqliteWorkerClientMessage = z.infer<
+	typeof SqliteWorkerClientMessageSchema
+>;
+
+export type SqliteWorkerServerMessage = z.infer<
+	typeof sqliteWorkerServerMessage
+>;
+
+export type SqliteClientRemoteCallbackServerMessage = z.infer<
+	typeof RemoteCallbackResponseSchema
+>;