@firtoz/drizzle-indexeddb 0.6.2 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @firtoz/drizzle-indexeddb
 
+## 2.0.0
+
+### Major Changes
+
+- [`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3) Thanks [@firtoz](https://github.com/firtoz)! - BREAKING: Renamed Drizzle-specific exports with `Drizzle` prefix for clarity. `indexedDBCollectionOptions` → `drizzleIndexedDBCollectionOptions`, `IndexedDBCollectionConfig` → `DrizzleIndexedDBCollectionConfig`, `IndexedDBSyncItem` → `DrizzleIndexedDBSyncItem`. Removed `KeyRangeSpec` re-export (import from `@firtoz/idb-collections` instead). `tryExtractIndexedQuery` moved to `@firtoz/idb-collections`.
+
+### Patch Changes
+
+- Updated dependencies [[`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3), [`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3), [`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3), [`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3)]:
+  - @firtoz/idb-collections@0.2.0
+  - @firtoz/db-helpers@2.0.0
+  - @firtoz/drizzle-utils@1.0.1
+
+## 1.0.0
+
+### Major Changes
+
+- [`3c7ce1d`](https://github.com/firtoz/fullstack-toolkit/commit/3c7ce1dbca5c5396386db9927ae7f5e19a562cf6) Thanks [@firtoz](https://github.com/firtoz)! - **IndexedDB proxy removed**
+
+  The IDB proxy layer (proxy client/server, transport, sync adapter) has been removed. Provider no longer exposes proxy sync; use native IndexedDB only.
+
+  **Upgrade:** If you were using the IDB proxy (e.g. `idb-proxy-client`, `idb-proxy-server`, `handleProxySync`, `onSyncReady`): remove that code. There is no replacement API; you implement the transport and call `receiveSync` with `SyncMessage[]` from `@firtoz/drizzle-utils` on each side.
+
+  **Remote / multi-context setup:** Use a **memory collection** (`@firtoz/db-helpers`) in the context that cannot access IndexedDB and keep the **IDB collection** where IndexedDB is available (source of truth). Implement your own channel (e.g. BroadcastChannel, `postMessage`, or WebSocket): when a context receives sync messages, call `utils.receiveSync(messages)` on its collection. Use `SyncMessage` from `@firtoz/db-helpers` (or `@firtoz/drizzle-utils`). The side that holds IDB can push initial state and updates as `SyncMessage[]` so the other side’s memory collection stays in sync.
+
+### Patch Changes
+
+- Updated dependencies [[`3c7ce1d`](https://github.com/firtoz/fullstack-toolkit/commit/3c7ce1dbca5c5396386db9927ae7f5e19a562cf6), [`3c7ce1d`](https://github.com/firtoz/fullstack-toolkit/commit/3c7ce1dbca5c5396386db9927ae7f5e19a562cf6)]:
+  - @firtoz/db-helpers@1.0.0
+  - @firtoz/drizzle-utils@1.0.0
+
 ## 0.6.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-indexeddb",
-	"version": "0.6.2",
+	"version": "2.0.0",
 	"description": "IndexedDB migrations powered by Drizzle ORM",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -68,23 +68,26 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@firtoz/drizzle-utils": ">=0.3.3",
-		"@tanstack/db": ">=0.5.25",
+		"@firtoz/drizzle-utils": ">=1.0.1",
+		"@tanstack/db": ">=0.5.33",
 		"drizzle-orm": ">=0.45.1",
 		"drizzle-valibot": ">=0.4.0",
 		"react": ">=19.2.4",
 		"valibot": ">=1.0.0"
 	},
 	"devDependencies": {
-		"@firtoz/drizzle-utils": "^0.3.3",
-		"@tanstack/db": "^0.5.25",
-		"@types/react": "^19.2.13",
+		"@firtoz/drizzle-utils": "^1.0.1",
+		"@tanstack/db": "^0.5.33",
+		"@types/react": "^19.2.14",
 		"drizzle-orm": "^0.45.1",
 		"drizzle-valibot": "^0.4.2",
 		"react": "^19.2.4",
 		"valibot": "^1.2.0"
 	},
 	"dependencies": {
-		"citty": "^0.2.0"
+		"@firtoz/db-helpers": "^2.0.0",
+		"@firtoz/idb-collections": "^0.2.0",
+		"@firtoz/maybe-error": "^1.5.2",
+		"citty": "^0.2.1"
 	}
 }

package/src/collections/drizzle-indexeddb-collection.ts

@@ -0,0 +1,310 @@
+import type { InferSchemaOutput, SyncMode } from "@tanstack/db";
+import type { IR } from "@tanstack/db";
+import { parseOrderByExpression } from "@tanstack/db";
+import type { Table } from "drizzle-orm";
+
+import {
+	type IdOf,
+	type SelectSchema,
+	type BaseSyncConfig,
+	type SyncBackend,
+	createSyncFunction,
+	createInsertSchemaWithDefaults,
+	createGetKeyFunction,
+	createCollectionConfig,
+} from "@firtoz/drizzle-utils";
+import { evaluateExpression } from "@firtoz/db-helpers";
+import { tryExtractIndexedQuery } from "@firtoz/idb-collections";
+
+import type { IDBDatabaseLike } from "../idb-types";
+
+// biome-ignore lint/suspicious/noExplicitAny: intentional
+type AnyId = IdOf<any>;
+
+/**
+ * Type for items stored in IndexedDB (must have required sync fields)
+ */
+export type DrizzleIndexedDBSyncItem = {
+	id: AnyId;
+	createdAt: Date;
+	updatedAt: Date;
+	deletedAt: Date | null;
+	[key: string]: unknown;
+};
+
+export interface DrizzleIndexedDBCollectionConfig<TTable extends Table> {
+	/**
+	 * Ref to the IndexedDB database instance
+	 */
+	indexedDBRef: React.RefObject<IDBDatabaseLike | null>;
+	/**
+	 * The Drizzle table definition (used for schema and type inference only)
+	 */
+	table: TTable;
+	/**
+	 * The name of the IndexedDB object store (should match the table name)
+	 */
+	storeName: string;
+	/**
+	 * Promise that resolves when the database is ready
+	 */
+	readyPromise: Promise<void>;
+	/**
+	 * Sync mode: 'eager' (immediate) or 'on-demand'
+	 */
+	syncMode?: SyncMode;
+	/**
+	 * Enable debug logging for index discovery and query optimization
+	 */
+	debug?: boolean;
+}
+
+/**
+ * Auto-discovers indexes from the IndexedDB store.
+ * Returns a map of field names to index names for single-column indexes.
+ */
+function discoverIndexes(
+	db: IDBDatabaseLike,
+	storeName: string,
+): Record<string, string> {
+	const indexes = db.getStoreIndexes(storeName);
+	const indexMap: Record<string, string> = {};
+
+	for (const index of indexes) {
+		if (typeof index.keyPath === "string") {
+			indexMap[index.keyPath] = index.name;
+		}
+	}
+
+	return indexMap;
+}
+
+/**
+ * Creates a TanStack DB collection config for IndexedDB backed by Drizzle ORM.
+ */
+export function drizzleIndexedDBCollectionOptions<const TTable extends Table>(
+	config: DrizzleIndexedDBCollectionConfig<TTable>,
+) {
+	let discoveredIndexes: Record<string, string> = {};
+	let indexesDiscovered = false;
+
+	const table = config.table;
+
+	const discoverIndexesOnce = async () => {
+		await config.readyPromise;
+
+		const db = config.indexedDBRef.current;
+		if (!db) {
+			throw new Error("Database not ready");
+		}
+
+		if (!indexesDiscovered) {
+			discoveredIndexes = discoverIndexes(db, config.storeName);
+
+			indexesDiscovered = true;
+		}
+	};
+
+	const backend: SyncBackend<TTable> = {
+		initialLoad: async () => {
+			const db = config.indexedDBRef.current;
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			await discoverIndexesOnce();
+
+			const items = await db.getAll<DrizzleIndexedDBSyncItem>(config.storeName);
+
+			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
+		},
+		loadSubset: async (options) => {
+			const db = config.indexedDBRef.current;
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			if (!indexesDiscovered) {
+				discoveredIndexes = discoverIndexes(db, config.storeName);
+				indexesDiscovered = true;
+			}
+
+			let items: DrizzleIndexedDBSyncItem[];
+
+			let combinedWhere = options.where;
+			if (options.cursor?.whereFrom) {
+				if (combinedWhere) {
+					combinedWhere = {
+						type: "func",
+						name: "and",
+						args: [combinedWhere, options.cursor.whereFrom],
+					} as IR.Func;
+				} else {
+					combinedWhere = options.cursor.whereFrom;
+				}
+			}
+
+			const indexedQuery = combinedWhere
+				? tryExtractIndexedQuery(combinedWhere, discoveredIndexes, config.debug)
+				: null;
+
+			if (indexedQuery) {
+				items = await db.getAllByIndex<DrizzleIndexedDBSyncItem>(
+					config.storeName,
+					indexedQuery.indexName,
+					indexedQuery.keyRange,
+				);
+			} else {
+				items = await db.getAll<DrizzleIndexedDBSyncItem>(config.storeName);
+
+				if (combinedWhere) {
+					const whereExpression = combinedWhere;
+					items = items.filter((item) =>
+						evaluateExpression(
+							whereExpression,
+							item as Record<string, unknown>,
+						),
+					);
+				}
+			}
+
+			if (options.orderBy) {
+				const sorts = parseOrderByExpression(options.orderBy);
+				items.sort((a, b) => {
+					for (const sort of sorts) {
+						// biome-ignore lint/suspicious/noExplicitAny: Need any for dynamic field access
+						let aValue: any = a;
+						// biome-ignore lint/suspicious/noExplicitAny: Need any for dynamic field access
+						let bValue: any = b;
+						for (const fieldName of sort.field) {
+							aValue = aValue?.[fieldName];
+							bValue = bValue?.[fieldName];
+						}
+
+						if (aValue < bValue) {
+							return sort.direction === "asc" ? -1 : 1;
+						}
+						if (aValue > bValue) {
+							return sort.direction === "asc" ? 1 : -1;
+						}
+					}
+					return 0;
+				});
+			}
+
+			if (options.offset !== undefined && options.offset > 0) {
+				items = items.slice(options.offset);
+			}
+
+			if (options.limit !== undefined) {
+				items = items.slice(0, options.limit);
+			}
+
+			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
+		},
+
+		handleInsert: async (itemsToInsert) => {
+			const db = config.indexedDBRef.current;
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			await db.add(config.storeName, itemsToInsert);
+
+			return itemsToInsert;
+		},
+
+		handleUpdate: async (mutations) => {
+			const db = config.indexedDBRef.current;
+
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
+			const itemsToUpdate: DrizzleIndexedDBSyncItem[] = [];
+
+			for (const mutation of mutations) {
+				const existing = await db.get<DrizzleIndexedDBSyncItem>(
+					config.storeName,
+					mutation.key,
+				);
+
+				if (existing) {
+					const updateTime = new Date();
+					const updatedItem = {
+						...existing,
+						...mutation.changes,
+						updatedAt: updateTime,
+					} as DrizzleIndexedDBSyncItem;
+
+					itemsToUpdate.push(updatedItem);
+					results.push(
+						updatedItem as unknown as InferSchemaOutput<SelectSchema<TTable>>,
+					);
+				} else {
+					results.push(mutation.original);
+				}
+			}
+
+			if (itemsToUpdate.length > 0) {
+				await db.put(config.storeName, itemsToUpdate);
+			}
+
+			return results;
+		},
+
+		handleDelete: async (mutations) => {
+			const db = config.indexedDBRef.current;
+
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			const keysToDelete: IDBValidKey[] = mutations.map((m) => m.key);
+
+			await db.delete(config.storeName, keysToDelete);
+		},
+
+		handleTruncate: async () => {
+			const db = config.indexedDBRef.current;
+
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			await db.clear(config.storeName);
+		},
+	};
+
+	const wrappedBackend: SyncBackend<TTable> = {
+		...backend,
+		initialLoad: async () => {
+			if (config.syncMode === "eager" || !config.syncMode) {
+				return await backend.initialLoad();
+			}
+
+			await discoverIndexesOnce();
+
+			return [];
+		},
+	};
+
+	const baseSyncConfig: BaseSyncConfig<TTable> = {
+		table,
+		readyPromise: config.readyPromise,
+		syncMode: config.syncMode,
+		debug: config.debug,
+	};
+
+	const syncResult = createSyncFunction(baseSyncConfig, wrappedBackend);
+
+	const schema = createInsertSchemaWithDefaults(table);
+
+	return createCollectionConfig({
+		schema,
+		getKey: createGetKeyFunction<TTable>(),
+		syncResult,
+		syncMode: config.syncMode,
+	});
+}

package/src/context/DrizzleIndexedDBProvider.tsx

@@ -16,16 +16,16 @@ import {
 } from "@tanstack/db";
 import { getTableName, type Table } from "drizzle-orm";
 import {
-	indexedDBCollectionOptions,
-	type IndexedDBCollectionConfig,
+	drizzleIndexedDBCollectionOptions,
+	type DrizzleIndexedDBCollectionConfig,
 } from "@firtoz/drizzle-indexeddb";
+import type { CollectionUtils } from "@firtoz/db-helpers";
 import type {
 	IdOf,
 	InsertSchema,
 	SelectSchema,
 	GetTableFromSchema,
 	InferCollectionFromTable,
-	CollectionUtils,
 } from "@firtoz/drizzle-utils";
 import {
 	type Migration,
@@ -33,7 +33,6 @@ import {
 } from "../function-migrator";
 import type { IDBCreator, IDBDatabaseLike } from "../idb-types";
 import { openIndexedDb } from "../idb-operations";
-import type { IDBProxySyncMessage } from "../proxy/idb-proxy-types";
 
 interface CollectionCacheEntry {
 	// biome-ignore lint/suspicious/noExplicitAny: Cache needs to store collections of various types
@@ -65,11 +64,6 @@ export type DrizzleIndexedDBContextValue<
 	) => IndexedDbCollection<TSchema, TTableName>;
 	incrementRefCount: (tableName: string) => void;
 	decrementRefCount: (tableName: string) => void;
-	/**
-	 * Handle a sync message from a proxy server.
-	 * Routes the message to the appropriate collection's external sync handler.
-	 */
-	handleProxySync: (message: IDBProxySyncMessage) => void;
 };
 
 export const DrizzleIndexedDBContext =
@@ -94,18 +88,6 @@ type DrizzleIndexedDBProviderProps<TSchema extends Record<string, unknown>> =
 		 * Use createInstrumentedDbCreator() to track IndexedDB operations.
 		 */
 		dbCreator?: IDBCreator;
-		/**
-		 * Called when the sync handler is ready.
-		 * Use this to connect proxy sync messages to the provider.
-		 *
-		 * @example
-		 * const proxyClient = ...;
-		 * <DrizzleIndexedDBProvider
-		 *   onSyncReady={(handleSync) => proxyClient.onSync(handleSync)}
-		 *   ...
-		 * />
-		 */
-		onSyncReady?: (handleSync: (message: IDBProxySyncMessage) => void) => void;
 	}>;
 
 export function DrizzleIndexedDBProvider<
@@ -119,7 +101,6 @@ export function DrizzleIndexedDBProvider<
 	debug = false,
 	syncMode = "eager",
 	dbCreator,
-	onSyncReady,
 }: DrizzleIndexedDBProviderProps<TSchema>) {
 	const [indexedDB, setIndexedDB] = useState<IDBDatabaseLike | null>(null);
 	const indexedDBRef = useRef<IDBDatabaseLike | null>(null);
@@ -192,14 +173,14 @@ export function DrizzleIndexedDBProvider<
 				const actualTableName = getTableName(table);
 
 				// Create collection options
-				const collectionConfig = indexedDBCollectionOptions({
+				const collectionConfig = drizzleIndexedDBCollectionOptions({
 					indexedDBRef,
 					table,
 					storeName: actualTableName,
 					readyPromise: readyPromise.promise,
 					debug,
 					syncMode,
-				} as IndexedDBCollectionConfig<Table>);
+				} as DrizzleIndexedDBCollectionConfig<Table>);
 
 				// Create new collection and cache it with ref count 0
 				// The collection will wait for readyPromise before accessing the database
@@ -248,80 +229,14 @@ export function DrizzleIndexedDBProvider<
 			[collections],
 		);
 
-	// Handle proxy sync messages by routing to the appropriate collection
-	const handleProxySync: DrizzleIndexedDBContextValue<TSchema>["handleProxySync"] =
-		useCallback(
-			(message: IDBProxySyncMessage) => {
-				// Find the collection for this store by checking the schema
-				for (const [tableName, table] of Object.entries(schema)) {
-					const actualStoreName = getTableName(table as Table);
-					if (actualStoreName === message.storeName) {
-						const entry = collections.get(tableName);
-						if (entry) {
-							const { pushExternalSync } = entry.collection.utils;
-							// Route sync message to collection
-							switch (message.type) {
-								case "sync:add":
-									pushExternalSync({
-										type: "insert",
-										items: message.items,
-									});
-									break;
-								case "sync:put":
-									pushExternalSync({
-										type: "update",
-										items: message.items,
-									});
-									break;
-								case "sync:delete":
-									// For delete, construct items with id
-									pushExternalSync({
-										type: "delete",
-										items: message.keys.map((key) => ({ id: key })),
-									});
-									break;
-								case "sync:truncate":
-									pushExternalSync({
-										type: "truncate",
-									});
-									break;
-							}
-						}
-						return;
-					}
-				}
-
-				if (debug) {
-					console.warn(
-						`[DrizzleIndexedDBProvider] No collection found for store: ${message.storeName}`,
-					);
-				}
-			},
-			[collections, schema, debug],
-		);
-
-	// Call onSyncReady when handleProxySync is available
-	useEffect(() => {
-		if (onSyncReady) {
-			onSyncReady(handleProxySync);
-		}
-	}, [onSyncReady, handleProxySync]);
-
 	const contextValue: DrizzleIndexedDBContextValue<TSchema> = useMemo(
 		() => ({
 			indexedDB,
 			getCollection,
 			incrementRefCount,
 			decrementRefCount,
-			handleProxySync,
 		}),
-		[
-			indexedDB,
-			getCollection,
-			incrementRefCount,
-			decrementRefCount,
-			handleProxySync,
-		],
+		[indexedDB, getCollection, incrementRefCount, decrementRefCount],
 	);
 
 	return (

package/src/function-migrator.ts

@@ -1,5 +1,6 @@
 // IndexedDB migrator with declarative migration format
 
+import { exhaustiveGuard } from "@firtoz/maybe-error";
 import type { IDBCreator, IDBDatabaseLike } from "./idb-types";
 import { openIndexedDb } from "./idb-operations";
 
@@ -107,6 +108,8 @@ function executeMigrationOperation(
 			}
 			break;
 		}
+		default:
+			exhaustiveGuard(op);
 	}
 }
 

package/src/idb-types.ts

@@ -1,3 +1,5 @@
+import type { KeyRangeSpec } from "@firtoz/idb-collections";
+
 /**
  * Index information returned by getStoreIndexes
  */
@@ -21,18 +23,6 @@ export interface CreateIndexOptions {
 	unique?: boolean;
 }
 
-/**
- * Key range specification for index queries
- */
-export interface KeyRangeSpec {
-	type: "only" | "lowerBound" | "upperBound" | "bound";
-	value?: unknown;
-	lower?: unknown;
-	upper?: unknown;
-	lowerOpen?: boolean;
-	upperOpen?: boolean;
-}
-
 /**
  * Minimal database interface with high-level async operations.
  * This is the interface that custom implementations (mocks, Chrome extension proxies, etc.) need to implement.

package/src/index.ts

@@ -17,7 +17,6 @@ export type {
 	IndexInfo,
 	CreateStoreOptions,
 	CreateIndexOptions,
-	KeyRangeSpec,
 } from "./idb-types";
 
 // IDB Interceptor (for testing/debugging)
@@ -34,10 +33,10 @@ export { createInstrumentedDbCreator } from "./instrumented-idb-database";
 
 // Collection
 export {
-	indexedDBCollectionOptions,
-	type IndexedDBCollectionConfig,
-	type IndexedDBSyncItem,
-} from "./collections/indexeddb-collection";
+	drizzleIndexedDBCollectionOptions,
+	type DrizzleIndexedDBCollectionConfig,
+	type DrizzleIndexedDBSyncItem,
+} from "./collections/drizzle-indexeddb-collection";
 
 // Standalone Collection (for use outside React)
 export {
@@ -59,30 +58,3 @@ export {
 	useDrizzleIndexedDB,
 	type UseDrizzleIndexedDBContextReturn,
 } from "./context/useDrizzleIndexedDB";
-
-// IDB Proxy (for Chrome extension, messaging-based IDB access)
-export {
-	// Types
-	type IDBProxyRequest,
-	type IDBProxyRequestBody,
-	type IDBProxyResponse,
-	type IDBProxySyncMessage,
-	generateRequestId,
-	generateClientId,
-	// Transport
-	type IDBProxyClientTransport,
-	type IDBProxyServerTransport,
-	createInMemoryTransport,
-	createMultiClientTransport,
-	// Client
-	IDBProxyClient,
-	createProxyIDbCreator,
-	type SyncHandler,
-	// Server
-	IDBProxyServer,
-	createProxyServer,
-	type IDBProxyServerOptions,
-	// Sync adapter (connects proxy sync to collection)
-	createCollectionSyncHandler,
-	combineSyncHandlers,
-} from "./proxy";

package/src/instrumented-idb-database.ts

@@ -1,3 +1,4 @@
+import type { KeyRangeSpec } from "@firtoz/idb-collections";
 import type {
 	IDBDatabaseLike,
 	IDBCreator,
@@ -5,7 +6,6 @@ import type {
 	IndexInfo,
 	CreateStoreOptions,
 	CreateIndexOptions,
-	KeyRangeSpec,
 } from "./idb-types";
 import type { IDBInterceptor } from "./idb-interceptor";
 import { defaultIDBCreator } from "./native-idb-database";

package/src/native-idb-database.ts

@@ -1,3 +1,5 @@
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { KeyRangeSpec } from "@firtoz/idb-collections";
 import type {
 	IDBDatabaseLike,
 	IDBCreator,
@@ -5,7 +7,6 @@ import type {
 	IndexInfo,
 	CreateStoreOptions,
 	CreateIndexOptions,
-	KeyRangeSpec,
 } from "./idb-types";
 
 /**
@@ -26,6 +27,8 @@ function createKeyRange(spec: KeyRangeSpec): IDBKeyRange {
 				spec.lowerOpen,
 				spec.upperOpen,
 			);
+		default:
+			exhaustiveGuard(spec.type);
 	}
 }