@firtoz/drizzle-indexeddb 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @firtoz/drizzle-indexeddb
 
+## 0.4.1
+
+### Patch Changes
+
+- [`904019f`](https://github.com/firtoz/fullstack-toolkit/commit/904019f4d04bc02521206fbe0feaeecb67e38f87) Thanks [@firtoz](https://github.com/firtoz)! - Fix tsx exporting
+
+## 0.4.0
+
+### Minor Changes
+
+- [`46059a2`](https://github.com/firtoz/fullstack-toolkit/commit/46059a28bd0135414b9ed022ffe162a2292adae3) Thanks [@firtoz](https://github.com/firtoz)! - Add IDB Proxy system for multi-client IndexedDB sync over messaging layers:
+
+  **New Proxy Module** (`@firtoz/drizzle-indexeddb/proxy`):
+
+  - **`IDBProxyServer`** - Server that manages database lifecycle, migrations, and broadcasts mutations to connected clients
+  - **`IDBProxyClient`** - Client implementing `IDBDatabaseLike`, routing operations through a transport layer
+  - **`createMultiClientTransport()`** - In-memory transport for testing N clients connected to one server
+  - **`createProxyDbCreator()`** - Factory to create `dbCreator` for `DrizzleIndexedDBProvider`
+  - **`createCollectionSyncHandler()`** - Adapter connecting proxy sync messages to collection's external sync
+
+  **Real-time Multi-Client Sync**:
+
+  - Server broadcasts `sync:add`, `sync:put`, `sync:delete`, `sync:clear` messages to all clients (excluding initiator)
+  - All mutations automatically sync across connected clients
+
+  **Provider Enhancements**:
+
+  - New `onSyncReady` prop for wiring up external sync handlers
+  - `handleProxySync` method routes sync messages to the appropriate collection
+
+  **Collection Truncate**:
+
+  - `collection.utils.truncate()` clears all data and syncs to other clients
+  - `handleTruncate` implemented in IndexedDB backend
+
+  **Bug Fixes**:
+
+  - Server handles concurrent database initialization requests (race condition fix)
+
+### Patch Changes
+
+- Updated dependencies [[`46059a2`](https://github.com/firtoz/fullstack-toolkit/commit/46059a28bd0135414b9ed022ffe162a2292adae3)]:
+  - @firtoz/drizzle-utils@0.3.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -20,6 +20,7 @@ npm install @firtoz/drizzle-indexeddb @firtoz/drizzle-utils drizzle-orm @tanstac
 - 📦 **Soft deletes** - Built-in support for `deletedAt` column
 - ⚛️ **React hooks** - Provider and hooks for easy React integration
 - 📝 **Function-based migrations** - Generated migration functions from Drizzle schema changes
+- 🔄 **Multi-client sync** - IDB Proxy system for real-time sync across multiple clients (Chrome extensions, etc.)
 
 ## Quick Start
 
@@ -416,6 +417,167 @@ const collection = createCollection(
 );
 ```
 
+### Collection Truncate
+
+Clear all data from a collection:
+
+```typescript
+// Clear all todos
+await todoCollection.utils.truncate();
+```
+
+This clears the IndexedDB store and updates the local reactive store.
+
+## IDB Proxy System
+
+For scenarios where IndexedDB needs to be accessed over a messaging layer (e.g., Chrome extensions, WebSockets), the proxy system enables multi-client sync:
+
+### Overview
+
+```
+┌─────────┐     ┌─────────┐     ┌─────────┐
+│ Client 1│     │ Client 2│     │ Client N│
+└────┬────┘     └────┬────┘     └────┬────┘
+     │               │               │
+     └───────────────┼───────────────┘
+                     │
+              ┌──────▼──────┐
+              │   Server    │
+              │  (manages   │
+              │  IndexedDB) │
+              └─────────────┘
+```
+
+- **Server** manages database lifecycle, migrations, and broadcasts mutations
+- **Clients** connect via a transport layer and receive real-time sync updates
+- All insert/update/delete/truncate operations sync to all connected clients
+
+### Basic Setup
+
+```typescript
+import {
+  createMultiClientTransport,
+  createProxyServer,
+  createProxyDbCreator,
+  migrateIndexedDBWithFunctions,
+  DrizzleIndexedDBProvider,
+} from "@firtoz/drizzle-indexeddb";
+
+// Create transport (in-memory for testing, or custom for production)
+const { createClientTransport, serverTransport } = createMultiClientTransport();
+
+// Create server with migrations
+const server = createProxyServer({
+  transport: serverTransport,
+  dbCreator: async (dbName) => {
+    return await migrateIndexedDBWithFunctions(dbName, migrations);
+  },
+});
+
+// Create client
+const clientTransport = createClientTransport();
+const dbCreator = createProxyDbCreator(clientTransport);
+
+// Use with React provider
+function App() {
+  const handleSyncReady = useCallback((handleSync) => {
+    clientTransport.onSync(handleSync);
+  }, []);
+
+  return (
+    <DrizzleIndexedDBProvider
+      dbName="my-app.db"
+      schema={schema}
+      dbCreator={dbCreator}
+      onSyncReady={handleSyncReady}
+    >
+      <YourApp />
+    </DrizzleIndexedDBProvider>
+  );
+}
+```
+
+### Multiple Clients
+
+```typescript
+// Server setup (once)
+const { createClientTransport, serverTransport } = createMultiClientTransport();
+const server = createProxyServer({ transport: serverTransport, ... });
+
+// Each client gets its own transport
+const client1Transport = createClientTransport();
+const client2Transport = createClientTransport();
+const client3Transport = createClientTransport();
+
+// All clients share the same data and receive real-time sync
+```
+
+### Sync Operations
+
+All standard collection operations automatically sync:
+
+```typescript
+// Client 1 inserts
+await todoCollection.insert({ title: "Buy milk", completed: false });
+// → Client 2, 3, N receive the new todo instantly
+
+// Client 2 updates
+await todoCollection.update(todoId, (draft) => {
+  draft.completed = true;
+});
+// → Client 1, 3, N see the update instantly
+
+// Client 3 deletes
+await todoCollection.delete(todoId);
+// → Client 1, 2, N see the deletion instantly
+
+// Client N truncates
+await todoCollection.utils.truncate();
+// → All clients are cleared instantly
+```
+
+### Custom Transport
+
+For production use (Chrome extension, WebSocket, etc.), implement the transport interface:
+
+```typescript
+import type { IDBProxyClientTransport, IDBProxyServerTransport } from "@firtoz/drizzle-indexeddb";
+
+// Client transport (e.g., in content script)
+const clientTransport: IDBProxyClientTransport = {
+  sendRequest: async (request) => {
+    // Send to background script and wait for response
+    return await chrome.runtime.sendMessage(request);
+  },
+  onSync: (handler) => {
+    // Listen for sync broadcasts
+    chrome.runtime.onMessage.addListener((msg) => {
+      if (msg.type?.startsWith("sync:")) handler(msg);
+    });
+  },
+};
+
+// Server transport (e.g., in background script)
+const serverTransport: IDBProxyServerTransport = {
+  onRequest: (handler) => {
+    chrome.runtime.onMessage.addListener(async (msg, sender, sendResponse) => {
+      const response = await handler(msg);
+      sendResponse(response);
+    });
+  },
+  broadcast: (message, excludeClientId) => {
+    // Broadcast to all connected tabs except sender
+    chrome.tabs.query({}, (tabs) => {
+      for (const tab of tabs) {
+        if (tab.id !== excludeClientId) {
+          chrome.tabs.sendMessage(tab.id, message);
+        }
+      }
+    });
+  },
+};
+```
+
 ### Handling Migration Errors
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-indexeddb",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"description": "IndexedDB migrations powered by Drizzle ORM",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -24,10 +24,16 @@
 			"types": "./src/*.ts",
 			"import": "./src/*.ts",
 			"require": "./src/*.ts"
+		},
+		"./*.tsx": {
+			"types": "./src/*.tsx",
+			"import": "./src/*.tsx",
+			"require": "./src/*.tsx"
 		}
 	},
 	"files": [
 		"src/**/*.ts",
+		"src/**/*.tsx",
 		"!src/**/*.test.ts",
 		"README.md",
 		"CHANGELOG.md"
@@ -64,14 +70,14 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@firtoz/drizzle-utils": "^0.2.0",
-		"@tanstack/db": "^0.5.10",
-		"drizzle-orm": "^0.44.7",
+		"@firtoz/drizzle-utils": "^0.3.0",
+		"@tanstack/db": "^0.5.11",
+		"drizzle-orm": "^0.45.0",
 		"drizzle-valibot": "^0.4.2",
 		"valibot": "^1.2.0"
 	},
 	"peerDependencies": {
-		"react": "^19.2.0"
+		"react": "^19.2.1"
 	},
 	"devDependencies": {
 		"@types/react": "^19.2.7"

package/src/collections/indexeddb-collection.ts

@@ -14,7 +14,7 @@ import {
 	createCollectionConfig,
 } from "@firtoz/drizzle-utils";
 
-import type { IDBDatabaseLike, KeyRangeSpec } from "../utils";
+import type { IDBDatabaseLike, KeyRangeSpec } from "../idb-types";
 
 // biome-ignore lint/suspicious/noExplicitAny: intentional
 type AnyId = IdOf<any>;
@@ -30,73 +30,6 @@ export type IndexedDBSyncItem = {
 	[key: string]: unknown;
 };
 
-/**
- * Operation tracking for IndexedDB queries
- * Useful for testing and debugging to verify what operations are actually performed
- *
- * Uses discriminated unions for type safety - TypeScript can narrow the type based on the 'type' field
- */
-export type IDBOperation =
-	| {
-			type: "getAll";
-			storeName: string;
-			itemsReturned: unknown[];
-			itemCount: number;
-			context: string;
-			timestamp: number;
-	  }
-	| {
-			type: "index-getAll";
-			storeName: string;
-			indexName: string;
-			keyRange?: IDBKeyRange;
-			itemsReturned: unknown[];
-			itemCount: number;
-			context: string;
-			timestamp: number;
-	  }
-	| {
-			type: "write";
-			storeName: string;
-			itemsWritten: unknown[];
-			writeCount: number;
-			context: string;
-			timestamp: number;
-	  }
-	| {
-			type: "get";
-			storeName: string;
-			key: IDBValidKey;
-			itemReturned?: unknown;
-			timestamp: number;
-	  }
-	| {
-			type: "put";
-			storeName: string;
-			item: unknown;
-			timestamp: number;
-	  }
-	| {
-			type: "delete";
-			storeName: string;
-			key: IDBValidKey;
-			timestamp: number;
-	  }
-	| {
-			type: "clear";
-			storeName: string;
-			timestamp: number;
-	  };
-
-/**
- * Interceptor interface for tracking IndexedDB operations
- * Allows tests and debugging tools to observe what operations are performed
- */
-export interface IDBInterceptor {
-	/** Called when any IndexedDB operation is performed */
-	onOperation?: (operation: IDBOperation) => void;
-}
-
 export interface IndexedDBCollectionConfig<TTable extends Table> {
 	/**
 	 * Ref to the IndexedDB database instance
@@ -126,10 +59,6 @@ export interface IndexedDBCollectionConfig<TTable extends Table> {
 	 * Enable debug logging for index discovery and query optimization
 	 */
 	debug?: boolean;
-	/**
-	 * Optional interceptor for tracking IndexedDB operations (for testing/debugging)
-	 */
-	interceptor?: IDBInterceptor;
 }
 
 /**
@@ -259,68 +188,6 @@ export function getExpressionValue(
 	throw new Error(`Cannot get value from expression type: ${expression.type}`);
 }
 
-/**
- * Reads all items from an IndexedDB object store
- */
-async function getAllFromStore(
-	db: IDBDatabaseLike,
-	storeName: string,
-	interceptor?: IDBInterceptor,
-): Promise<IndexedDBSyncItem[]> {
-	const items = await db.getAll<IndexedDBSyncItem>(storeName);
-
-	// Log operation after executing with results
-	if (interceptor?.onOperation) {
-		interceptor.onOperation({
-			type: "getAll",
-			storeName,
-			itemsReturned: items,
-			itemCount: items.length,
-			context: "Full table scan",
-			timestamp: Date.now(),
-		});
-	}
-
-	return items;
-}
-
-/**
- * Reads items from an IndexedDB index with an optional key range
- * Note: Index existence is validated at collection creation time
- */
-async function getAllFromIndex(
-	db: IDBDatabaseLike,
-	storeName: string,
-	indexName: string,
-	keyRange?: KeyRangeSpec,
-	interceptor?: IDBInterceptor,
-): Promise<IndexedDBSyncItem[]> {
-	const items = await db.getAllByIndex<IndexedDBSyncItem>(
-		storeName,
-		indexName,
-		keyRange,
-	);
-
-	// Log operation after executing with results
-	if (interceptor?.onOperation) {
-		const rangeDesc = keyRange
-			? `[${keyRange.lower ?? keyRange.value ?? ""}..${keyRange.upper ?? keyRange.value ?? ""}]`
-			: "all";
-		interceptor.onOperation({
-			type: "index-getAll",
-			storeName,
-			indexName,
-			keyRange: keyRange as unknown as IDBKeyRange | undefined,
-			itemsReturned: items,
-			itemCount: items.length,
-			context: `Index query on ${indexName}, range: ${rangeDesc}`,
-			timestamp: Date.now(),
-		});
-	}
-
-	return items;
-}
-
 /**
  * Attempts to extract a simple indexed query from an IR expression
  * Returns the field name and key range if the query can be optimized
@@ -475,12 +342,13 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 	const discoverIndexesOnce = async () => {
 		await config.readyPromise;
 
+		const db = config.indexedDBRef.current;
+		if (!db) {
+			throw new Error("Database not ready");
+		}
+
 		if (!indexesDiscovered) {
-			discoveredIndexes = discoverIndexes(
-				// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-				config.indexedDBRef.current!,
-				config.storeName,
-			);
+			discoveredIndexes = discoverIndexes(db, config.storeName);
 
 			indexesDiscovered = true;
 		}
@@ -489,26 +357,14 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 	// Create backend-specific implementation
 	const backend: SyncBackend<TTable> = {
 		initialLoad: async (write) => {
+			const db = config.indexedDBRef.current;
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
 			await discoverIndexesOnce();
 
-			const items = await getAllFromStore(
-				// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-				config.indexedDBRef.current!,
-				config.storeName,
-				config.interceptor,
-			);
-
-			// Log what's being written to the collection
-			if (config.interceptor?.onOperation) {
-				config.interceptor.onOperation({
-					type: "write",
-					storeName: config.storeName,
-					itemsWritten: items,
-					writeCount: items.length,
-					context: "Initial load (eager mode)",
-					timestamp: Date.now(),
-				});
-			}
+			const items = await db.getAll<IndexedDBSyncItem>(config.storeName);
 
 			for (const item of items) {
 				write(item as unknown as InferSchemaOutput<SelectSchema<TTable>>);
@@ -516,13 +372,14 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 		},
 
 		loadSubset: async (options, write) => {
+			const db = config.indexedDBRef.current;
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
 			// Ensure indexes are discovered before we try to use them
 			if (!indexesDiscovered) {
-				discoveredIndexes = discoverIndexes(
-					// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-					config.indexedDBRef.current!,
-					config.storeName,
-				);
+				discoveredIndexes = discoverIndexes(db, config.storeName);
 				indexesDiscovered = true;
 			}
 
@@ -535,22 +392,15 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 
 			if (indexedQuery) {
 				// Use indexed query for better performance
-				items = await getAllFromIndex(
-					// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-					config.indexedDBRef.current!,
+
+				items = await db.getAllByIndex<IndexedDBSyncItem>(
 					config.storeName,
 					indexedQuery.indexName,
 					indexedQuery.keyRange,
-					config.interceptor,
 				);
 			} else {
 				// Fall back to getting all items
-				items = await getAllFromStore(
-					// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-					config.indexedDBRef.current!,
-					config.storeName,
-					config.interceptor,
-				);
+				items = await db.getAll<IndexedDBSyncItem>(config.storeName);
 
 				// Apply where filter in memory
 				if (options.where) {
@@ -595,37 +445,17 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 				items = items.slice(0, options.limit);
 			}
 
-			// Log what's being written to the collection
-			if (config.interceptor?.onOperation) {
-				const contextParts: string[] = ["On-demand load"];
-				if (indexedQuery) {
-					contextParts.push(`via index ${indexedQuery.indexName}`);
-				} else if (options.where) {
-					contextParts.push("via full scan + in-memory filter");
-				}
-				if (options.orderBy) {
-					contextParts.push("with sorting");
-				}
-				if (options.limit !== undefined) {
-					contextParts.push(`limit ${options.limit}`);
-				}
-
-				config.interceptor.onOperation({
-					type: "write",
-					storeName: config.storeName,
-					itemsWritten: items,
-					writeCount: items.length,
-					context: contextParts.join(", "),
-					timestamp: Date.now(),
-				});
-			}
-
 			for (const item of items) {
 				write(item as unknown as InferSchemaOutput<SelectSchema<TTable>>);
 			}
 		},
 
 		handleInsert: async (mutations) => {
+			const db = config.indexedDBRef.current;
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
 			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
 
 			try {
@@ -638,8 +468,7 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 				}
 
 				// Add all items in a single batch operation
-				// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-				await config.indexedDBRef.current!.add(config.storeName, itemsToInsert);
+				await db.add(config.storeName, itemsToInsert);
 			} catch (error) {
 				// Clear results on error so nothing gets written to reactive store
 				results.length = 0;
@@ -650,12 +479,15 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 		},
 
 		handleUpdate: async (mutations) => {
+			const db = config.indexedDBRef.current;
+
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
 			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
 			const itemsToUpdate: IndexedDBSyncItem[] = [];
 
-			// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-			const db = config.indexedDBRef.current!;
-
 			for (const mutation of mutations) {
 				const existing = await db.get<IndexedDBSyncItem>(
 					config.storeName,
@@ -689,11 +521,27 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 		},
 
 		handleDelete: async (mutations) => {
+			const db = config.indexedDBRef.current;
+
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
 			const keysToDelete: IDBValidKey[] = mutations.map((m) => m.key);
 
 			// Delete all items in a single batch operation
-			// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-			await config.indexedDBRef.current!.delete(config.storeName, keysToDelete);
+			await db.delete(config.storeName, keysToDelete);
+		},
+
+		handleTruncate: async () => {
+			const db = config.indexedDBRef.current;
+
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			// Clear all items from the store
+			await db.clear(config.storeName);
 		},
 	};