@firtoz/drizzle-indexeddb 0.3.0 → 0.4.0

package/src/proxy/idb-proxy-server.ts

@@ -0,0 +1,313 @@
+import type { IDBDatabaseLike, IDBCreator } from "../idb-types";
+import { defaultIDBCreator } from "../native-idb-database";
+import type { IDBProxyServerTransport } from "./idb-proxy-transport";
+import type { IDBProxyRequest, IDBProxyResponse } from "./idb-proxy-types";
+
+/**
+ * Options for creating an IDB proxy server
+ */
+export interface IDBProxyServerOptions {
+	/**
+	 * Transport to receive requests from clients
+	 */
+	transport: IDBProxyServerTransport;
+
+	/**
+	 * Optional custom IDB creator (uses native IndexedDB by default)
+	 */
+	dbCreator?: IDBCreator;
+
+	/**
+	 * Called when a database needs to be initialized (first client connects).
+	 * Use this to run migrations before the database is used.
+	 */
+	onDatabaseInit?: (dbName: string, db: IDBDatabaseLike) => Promise<void>;
+
+	/**
+	 * Enable debug logging
+	 */
+	debug?: boolean;
+}
+
+/**
+ * IDB Proxy Server - Handles requests from proxy clients and performs
+ * actual IndexedDB operations.
+ *
+ * The server manages database lifecycle:
+ * - Databases are opened on first client connection
+ * - Databases stay open for all clients to share
+ * - Databases are only closed when the server stops
+ *
+ * When data is mutated, the server broadcasts sync messages to all other
+ * clients so they can update their local state.
+ *
+ * @example
+ * const server = new IDBProxyServer({
+ *   transport: createChromeExtensionServerTransport(),
+ *   onDatabaseInit: async (dbName) => {
+ *     await migrateIndexedDBWithFunctions(dbName, migrations);
+ *   }
+ * });
+ * server.start();
+ */
+export class IDBProxyServer {
+	private databases: Map<string, IDBDatabaseLike> = new Map();
+	private pendingDatabases: Map<string, Promise<void>> = new Map();
+	private dbCreator: IDBCreator;
+	private debug: boolean;
+
+	constructor(private options: IDBProxyServerOptions) {
+		this.dbCreator = options.dbCreator ?? defaultIDBCreator;
+		this.debug = options.debug ?? false;
+	}
+
+	/**
+	 * Start listening for requests from clients
+	 */
+	start(): void {
+		this.options.transport.onRequest(async (request) => {
+			return this.handleRequest(request);
+		});
+
+		if (this.debug) {
+			console.log("[IDBProxyServer] Started");
+		}
+	}
+
+	/**
+	 * Stop the server and close all databases
+	 */
+	stop(): void {
+		for (const [name, db] of this.databases.entries()) {
+			db.close();
+			if (this.debug) {
+				console.log(`[IDBProxyServer] Closed database "${name}"`);
+			}
+		}
+		this.databases.clear();
+		this.options.transport.dispose?.();
+
+		if (this.debug) {
+			console.log("[IDBProxyServer] Stopped");
+		}
+	}
+
+	/**
+	 * Handle an incoming request from a client
+	 */
+	private async handleRequest(
+		request: IDBProxyRequest,
+	): Promise<IDBProxyResponse> {
+		if (this.debug) {
+			console.log(
+				"[IDBProxyServer] Request:",
+				request.type,
+				request.dbName,
+				"from",
+				request.clientId,
+			);
+		}
+
+		try {
+			const result = await this.processRequest(request);
+			return { id: request.id, type: "success", data: result };
+		} catch (error) {
+			let errorMessage: string;
+			if (error instanceof Error) {
+				errorMessage = error.message || error.name || "Unknown error";
+				console.error("[IDBProxyServer] Error:", error.stack || error);
+			} else {
+				errorMessage = String(error) || "Unknown error";
+				console.error("[IDBProxyServer] Error:", error);
+			}
+			return { id: request.id, type: "error", error: errorMessage };
+		}
+	}
+
+	/**
+	 * Process a request and return the result
+	 */
+	private async processRequest(request: IDBProxyRequest): Promise<unknown> {
+		switch (request.type) {
+			case "connect":
+				await this.ensureDatabase(request.dbName);
+				return { connected: true };
+
+			case "disconnect":
+				return { disconnected: true };
+
+			case "getVersion":
+				return (await this.getDatabase(request.dbName)).version;
+
+			case "hasStore":
+				return (await this.getDatabase(request.dbName)).hasStore(
+					request.storeName,
+				);
+
+			case "getStoreNames":
+				return (await this.getDatabase(request.dbName)).getStoreNames();
+
+			case "getStoreIndexes":
+				return (await this.getDatabase(request.dbName)).getStoreIndexes(
+					request.storeName,
+				);
+
+			case "getAll":
+				return (await this.getDatabase(request.dbName)).getAll(
+					request.storeName,
+				);
+
+			case "getAllByIndex":
+				return (await this.getDatabase(request.dbName)).getAllByIndex(
+					request.storeName,
+					request.indexName,
+					request.keyRange,
+				);
+
+			case "get":
+				return (await this.getDatabase(request.dbName)).get(
+					request.storeName,
+					request.key,
+				);
+
+			case "add": {
+				const db = await this.getDatabase(request.dbName);
+				await db.add(request.storeName, request.items);
+				// Broadcast to other clients
+				this.options.transport.broadcast(
+					{
+						type: "sync:add",
+						dbName: request.dbName,
+						storeName: request.storeName,
+						items: request.items,
+					},
+					request.clientId,
+				);
+				return undefined;
+			}
+
+			case "put": {
+				const db = await this.getDatabase(request.dbName);
+				await db.put(request.storeName, request.items);
+				// Broadcast to other clients
+				this.options.transport.broadcast(
+					{
+						type: "sync:put",
+						dbName: request.dbName,
+						storeName: request.storeName,
+						items: request.items,
+					},
+					request.clientId,
+				);
+				return undefined;
+			}
+
+			case "delete": {
+				const db = await this.getDatabase(request.dbName);
+				await db.delete(request.storeName, request.keys);
+				// Broadcast to other clients
+				this.options.transport.broadcast(
+					{
+						type: "sync:delete",
+						dbName: request.dbName,
+						storeName: request.storeName,
+						keys: request.keys,
+					},
+					request.clientId,
+				);
+				return undefined;
+			}
+
+			case "clear": {
+				const db = await this.getDatabase(request.dbName);
+				await db.clear(request.storeName);
+				// Broadcast to other clients
+				this.options.transport.broadcast(
+					{
+						type: "sync:clear",
+						dbName: request.dbName,
+						storeName: request.storeName,
+					},
+					request.clientId,
+				);
+				return undefined;
+			}
+
+			default:
+				throw new Error(
+					`Unknown request type: ${(request as { type: string }).type}`,
+				);
+		}
+	}
+
+	/**
+	 * Get a database, opening it if needed
+	 */
+	private async getDatabase(dbName: string): Promise<IDBDatabaseLike> {
+		await this.ensureDatabase(dbName);
+		// biome-ignore lint/style/noNonNullAssertion: ensureDatabase guarantees it exists
+		return this.databases.get(dbName)!;
+	}
+
+	/**
+	 * Ensure a database is open and initialized.
+	 * Handles concurrent connection requests by having them wait for the same promise.
+	 */
+	private async ensureDatabase(dbName: string): Promise<void> {
+		// Already open
+		if (this.databases.has(dbName)) {
+			return;
+		}
+
+		// Currently being opened - wait for it
+		const pending = this.pendingDatabases.get(dbName);
+		if (pending) {
+			await pending;
+			return;
+		}
+
+		// Start opening
+		if (this.debug) {
+			console.log(`[IDBProxyServer] Opening database "${dbName}"`);
+		}
+
+		const openPromise = (async () => {
+			const db = await this.dbCreator(dbName);
+
+			if (!db) {
+				throw new Error(
+					`dbCreator returned null/undefined for database "${dbName}"`,
+				);
+			}
+
+			this.databases.set(dbName, db);
+
+			if (this.options.onDatabaseInit) {
+				await this.options.onDatabaseInit(dbName, db);
+			}
+
+			if (this.debug) {
+				console.log(`[IDBProxyServer] Database "${dbName}" ready`);
+			}
+		})();
+
+		this.pendingDatabases.set(dbName, openPromise);
+
+		try {
+			await openPromise;
+		} finally {
+			this.pendingDatabases.delete(dbName);
+		}
+	}
+}
+
+/**
+ * Convenience function to create and start a proxy server
+ */
+export function createProxyServer(
+	options: IDBProxyServerOptions,
+): IDBProxyServer {
+	const server = new IDBProxyServer(options);
+	server.start();
+	return server;
+}

package/src/proxy/idb-proxy-transport.ts

@@ -0,0 +1,174 @@
+import type {
+	IDBProxyRequest,
+	IDBProxyResponse,
+	IDBProxySyncMessage,
+} from "./idb-proxy-types";
+
+/**
+ * Client-side transport interface.
+ * Implement this to connect to an IDB proxy server via any messaging system.
+ *
+ * Examples of transports:
+ * - Chrome extension: chrome.runtime.sendMessage
+ * - WebSocket: ws.send + onmessage
+ * - MessageChannel: port.postMessage
+ * - In-memory (for testing): direct function call
+ */
+export interface IDBProxyClientTransport {
+	/**
+	 * Send a request to the server and wait for a response.
+	 * The transport is responsible for correlating request/response by ID.
+	 */
+	sendRequest(request: IDBProxyRequest): Promise<IDBProxyResponse>;
+
+	/**
+	 * Register a handler for sync messages from the server.
+	 * These are broadcasts when other clients modify data.
+	 */
+	onSync(handler: (message: IDBProxySyncMessage) => void): void;
+
+	/**
+	 * Optional: Clean up resources when the client is done.
+	 */
+	dispose?(): void;
+}
+
+/**
+ * Server-side transport interface.
+ * Implement this to receive requests from IDB proxy clients.
+ */
+export interface IDBProxyServerTransport {
+	/**
+	 * Register a handler for incoming requests.
+	 * The handler should process the request and return a response.
+	 * The transport is responsible for sending the response back to the client.
+	 */
+	onRequest(
+		handler: (request: IDBProxyRequest) => Promise<IDBProxyResponse>,
+	): void;
+
+	/**
+	 * Broadcast a sync message to all clients except the one specified.
+	 * @param message The sync message to broadcast
+	 * @param excludeClientId Client ID to exclude from the broadcast (the initiator)
+	 */
+	broadcast(message: IDBProxySyncMessage, excludeClientId: string): void;
+
+	/**
+	 * Optional: Clean up resources when the server is done.
+	 */
+	dispose?(): void;
+}
+
+/**
+ * A simple in-memory transport for testing.
+ * Connects a client and server directly without any actual messaging.
+ */
+export function createInMemoryTransport(): {
+	clientTransport: IDBProxyClientTransport;
+	serverTransport: IDBProxyServerTransport;
+} {
+	let requestHandler:
+		| ((request: IDBProxyRequest) => Promise<IDBProxyResponse>)
+		| null = null;
+	let syncHandler: ((message: IDBProxySyncMessage) => void) | null = null;
+	const clientId = `single-client-${Date.now()}`;
+
+	const clientTransport: IDBProxyClientTransport = {
+		async sendRequest(request): Promise<IDBProxyResponse> {
+			if (!requestHandler) {
+				return {
+					id: request.id,
+					type: "error",
+					error: "No server handler registered",
+				};
+			}
+			return requestHandler(request);
+		},
+		onSync(handler): void {
+			syncHandler = handler;
+		},
+	};
+
+	const serverTransport: IDBProxyServerTransport = {
+		onRequest(handler): void {
+			requestHandler = handler;
+		},
+		broadcast(message, excludeClientId): void {
+			// In single-client transport, only send if the client isn't excluded
+			if (syncHandler && excludeClientId !== clientId) {
+				syncHandler(message);
+			}
+		},
+	};
+
+	return { clientTransport, serverTransport };
+}
+
+/**
+ * A broadcast transport that supports multiple clients connecting to one server.
+ * Useful for testing N-client scenarios.
+ */
+export function createMultiClientTransport(): {
+	createClientTransport: () => IDBProxyClientTransport;
+	serverTransport: IDBProxyServerTransport;
+} {
+	let requestHandler:
+		| ((request: IDBProxyRequest) => Promise<IDBProxyResponse>)
+		| null = null;
+
+	// Track all connected clients and their sync handlers
+	const clients = new Map<
+		string,
+		{ syncHandler: ((message: IDBProxySyncMessage) => void) | null }
+	>();
+
+	const createClientTransport = (): IDBProxyClientTransport => {
+		const clientId = `client-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+		clients.set(clientId, { syncHandler: null });
+
+		return {
+			async sendRequest(request: IDBProxyRequest): Promise<IDBProxyResponse> {
+				if (!requestHandler) {
+					return {
+						id: request.id,
+						type: "error",
+						error: "No server handler registered",
+					};
+				}
+				// Inject clientId into request
+				return requestHandler({ ...request, clientId });
+			},
+			onSync(handler: (message: IDBProxySyncMessage) => void): void {
+				const client = clients.get(clientId);
+				if (client) {
+					client.syncHandler = handler;
+				}
+			},
+			dispose(): void {
+				clients.delete(clientId);
+			},
+		};
+	};
+
+	const serverTransport: IDBProxyServerTransport = {
+		onRequest(
+			handler: (request: IDBProxyRequest) => Promise<IDBProxyResponse>,
+		): void {
+			requestHandler = handler;
+		},
+		broadcast(message: IDBProxySyncMessage, excludeClientId: string): void {
+			// Send to all clients except the one that initiated the change
+			for (const [clientId, client] of clients) {
+				if (clientId !== excludeClientId && client.syncHandler) {
+					client.syncHandler(message);
+				}
+			}
+		},
+		dispose(): void {
+			clients.clear();
+		},
+	};
+
+	return { createClientTransport, serverTransport };
+}

package/src/proxy/idb-proxy-types.ts

@@ -0,0 +1,77 @@
+import type { KeyRangeSpec } from "../idb-types";
+
+/**
+ * Request body types (without the common fields)
+ */
+export type IDBProxyRequestBody =
+	// Connection (client session, not database lifecycle)
+	| { type: "connect" }
+	| { type: "disconnect" }
+	// Read operations
+	| { type: "getAll"; storeName: string }
+	| {
+			type: "getAllByIndex";
+			storeName: string;
+			indexName: string;
+			keyRange?: KeyRangeSpec;
+	  }
+	| { type: "get"; storeName: string; key: IDBValidKey }
+	// Write operations
+	| { type: "add"; storeName: string; items: unknown[] }
+	| { type: "put"; storeName: string; items: unknown[] }
+	| { type: "delete"; storeName: string; keys: IDBValidKey[] }
+	| { type: "clear"; storeName: string }
+	// Metadata (read-only)
+	| { type: "getVersion" }
+	| { type: "hasStore"; storeName: string }
+	| { type: "getStoreNames" }
+	| { type: "getStoreIndexes"; storeName: string };
+
+/**
+ * Full request type with all required fields
+ */
+export type IDBProxyRequest = {
+	/** Unique request ID for correlating responses */
+	id: string;
+	/** Unique client ID for tracking who sent the request */
+	clientId: string;
+	/** Database name */
+	dbName: string;
+} & IDBProxyRequestBody;
+
+/**
+ * Response types for IDB proxy operations
+ */
+export type IDBProxyResponse =
+	| { id: string; type: "success"; data?: unknown }
+	| { id: string; type: "error"; error: string };
+
+/**
+ * Sync messages broadcast to clients when data changes.
+ * These are sent from server to clients to keep them in sync.
+ */
+export type IDBProxySyncMessage = {
+	/** Database that was modified */
+	dbName: string;
+	/** Store that was modified */
+	storeName: string;
+} & (
+	| { type: "sync:add"; items: unknown[] }
+	| { type: "sync:put"; items: unknown[] }
+	| { type: "sync:delete"; keys: IDBValidKey[] }
+	| { type: "sync:clear" }
+);
+
+/**
+ * Generate a unique request ID
+ */
+export function generateRequestId(): string {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Generate a unique client ID
+ */
+export function generateClientId(): string {
+	return `client-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}

package/src/proxy/idb-sync-adapter.ts

@@ -0,0 +1,95 @@
+import type { ExternalSyncHandler } from "@firtoz/drizzle-utils";
+import type { IDBProxySyncMessage } from "./idb-proxy-types";
+
+/**
+ * Creates a sync message handler that translates proxy sync messages
+ * into collection external sync events.
+ *
+ * @param storeName The store name to handle sync for
+ * @param pushExternalSync The collection's external sync handler (from syncResult)
+ * @param options Optional configuration
+ *
+ * @example
+ * // Get the sync handler from the collection
+ * const { pushExternalSync } = syncResult;
+ *
+ * // Create the adapter
+ * const handleSync = createCollectionSyncHandler(
+ *   'todo',
+ *   pushExternalSync,
+ *   { debug: true }
+ * );
+ *
+ * // Connect to proxy client
+ * proxyClient.onSync(handleSync);
+ */
+export function createCollectionSyncHandler<T = unknown>(
+	storeName: string,
+	pushExternalSync: ExternalSyncHandler<T>,
+	options?: { debug?: boolean },
+): (message: IDBProxySyncMessage) => void {
+	const debug = options?.debug ?? false;
+
+	return (message: IDBProxySyncMessage) => {
+		// Ignore messages for other stores
+		if (message.storeName !== storeName) {
+			return;
+		}
+
+		if (debug) {
+			console.log(`[SyncAdapter:${storeName}]`, message.type, message);
+		}
+
+		switch (message.type) {
+			case "sync:add":
+				pushExternalSync({
+					type: "insert",
+					items: message.items as T[],
+				});
+				break;
+
+			case "sync:put":
+				pushExternalSync({
+					type: "update",
+					items: message.items as T[],
+				});
+				break;
+
+			case "sync:delete":
+				// For delete, we need the full items, but we only have keys
+				// The collection will handle this via the key
+				// We'll need to construct minimal items with just the id
+				pushExternalSync({
+					type: "delete",
+					items: message.keys.map((key) => ({ id: key })) as T[],
+				});
+				break;
+
+			case "sync:clear":
+				pushExternalSync({
+					type: "truncate",
+				});
+				break;
+		}
+	};
+}
+
+/**
+ * Combines multiple sync handlers into one.
+ * Use when you have multiple stores to sync from the same proxy client.
+ *
+ * @example
+ * const todoHandler = createCollectionSyncHandler('todo', todoSync);
+ * const userHandler = createCollectionSyncHandler('user', userSync);
+ *
+ * proxyClient.onSync(combineSyncHandlers([todoHandler, userHandler]));
+ */
+export function combineSyncHandlers(
+	handlers: Array<(message: IDBProxySyncMessage) => void>,
+): (message: IDBProxySyncMessage) => void {
+	return (message: IDBProxySyncMessage) => {
+		for (const handler of handlers) {
+			handler(message);
+		}
+	};
+}

package/src/proxy/index.ts

@@ -0,0 +1,37 @@
+// Proxy types
+export {
+	type IDBProxyRequest,
+	type IDBProxyRequestBody,
+	type IDBProxyResponse,
+	type IDBProxySyncMessage,
+	generateRequestId,
+	generateClientId,
+} from "./idb-proxy-types";
+
+// Transport interfaces
+export {
+	type IDBProxyClientTransport,
+	type IDBProxyServerTransport,
+	createInMemoryTransport,
+	createMultiClientTransport,
+} from "./idb-proxy-transport";
+
+// Proxy client
+export {
+	IDBProxyClient,
+	createProxyDbCreator,
+	type SyncHandler,
+} from "./idb-proxy-client";
+
+// Proxy server
+export {
+	IDBProxyServer,
+	createProxyServer,
+	type IDBProxyServerOptions,
+} from "./idb-proxy-server";
+
+// Sync adapter (connects proxy sync to collection)
+export {
+	createCollectionSyncHandler,
+	combineSyncHandlers,
+} from "./idb-sync-adapter";