@firtoz/drizzle-indexeddb 0.2.0 → 0.4.0

package/src/collections/indexeddb-collection.ts

@@ -14,6 +14,8 @@ import {
 	createCollectionConfig,
 } from "@firtoz/drizzle-utils";
 
+import type { IDBDatabaseLike, KeyRangeSpec } from "../idb-types";
+
 // biome-ignore lint/suspicious/noExplicitAny: intentional
 type AnyId = IdOf<any>;
 
@@ -28,78 +30,11 @@ 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
 	 */
-	indexedDBRef: React.RefObject<IDBDatabase | null>;
+	indexedDBRef: React.RefObject<IDBDatabaseLike | null>;
 	/**
 	 * The database name (for perf markers)
 	 */
@@ -124,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;
 }
 
 /**
@@ -257,99 +188,6 @@ export function getExpressionValue(
 	throw new Error(`Cannot get value from expression type: ${expression.type}`);
 }
 
-/**
- * Reads all items from an IndexedDB object store
- */
-function getAllFromStore(
-	db: IDBDatabase,
-	storeName: string,
-	interceptor?: IDBInterceptor,
-): Promise<IndexedDBSyncItem[]> {
-	return new Promise((resolve, reject) => {
-		if (!db.objectStoreNames.contains(storeName)) {
-			resolve([]);
-			return;
-		}
-
-		const transaction = db.transaction(storeName, "readonly");
-
-		const store = transaction.objectStore(storeName);
-
-		const request = store.getAll();
-
-		request.onsuccess = () => {
-			const items = request.result as IndexedDBSyncItem[];
-
-			// 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(),
-				});
-			}
-
-			resolve(items);
-		};
-
-		request.onerror = () => {
-			reject(request.error);
-		};
-	});
-}
-
-/**
- * Reads items from an IndexedDB index with an optional key range
- * Note: Index existence is validated at collection creation time
- */
-function getAllFromIndex(
-	db: IDBDatabase,
-	storeName: string,
-	indexName: string,
-	keyRange?: IDBKeyRange,
-	interceptor?: IDBInterceptor,
-): Promise<IndexedDBSyncItem[]> {
-	return new Promise((resolve, reject) => {
-		const transaction = db.transaction(storeName, "readonly");
-
-		const store = transaction.objectStore(storeName);
-
-		const index = store.index(indexName);
-
-		const request = keyRange ? index.getAll(keyRange) : index.getAll();
-
-		request.onsuccess = () => {
-			const items = request.result as IndexedDBSyncItem[];
-
-			// Log operation after executing with results
-			if (interceptor?.onOperation) {
-				const rangeDesc = keyRange
-					? `[${keyRange.lower ?? ""}..${keyRange.upper ?? ""}]`
-					: "all";
-				interceptor.onOperation({
-					type: "index-getAll",
-					storeName,
-					indexName,
-					keyRange,
-					itemsReturned: items,
-					itemCount: items.length,
-					context: `Index query on ${indexName}, range: ${rangeDesc}`,
-					timestamp: Date.now(),
-				});
-			}
-
-			resolve(items);
-		};
-
-		request.onerror = () => {
-			reject(request.error);
-		};
-	});
-}
-
 /**
  * Attempts to extract a simple indexed query from an IR expression
  * Returns the field name and key range if the query can be optimized
@@ -369,7 +207,7 @@ export function tryExtractIndexedQuery(
 	expression: IR.BasicExpression,
 	indexes?: Record<string, string>,
 	debug?: boolean,
-): { fieldName: string; indexName: string; keyRange: IDBKeyRange } | null {
+): { fieldName: string; indexName: string; keyRange: KeyRangeSpec } | null {
 	if (!indexes) {
 		return null;
 	}
@@ -391,25 +229,40 @@ export function tryExtractIndexedQuery(
 			return null;
 		}
 
-		// Convert operator to IndexedDB key range
-
-		let keyRange: IDBKeyRange | null = null;
+		// Convert operator to key range spec
+		let keyRange: KeyRangeSpec | null = null;
 
 		switch (comparison.operator) {
 			case "eq":
-				keyRange = IDBKeyRange.only(comparison.value);
+				keyRange = { type: "only", value: comparison.value };
 				break;
 			case "gt":
-				keyRange = IDBKeyRange.lowerBound(comparison.value, true);
+				keyRange = {
+					type: "lowerBound",
+					lower: comparison.value,
+					lowerOpen: true,
+				};
 				break;
 			case "gte":
-				keyRange = IDBKeyRange.lowerBound(comparison.value, false);
+				keyRange = {
+					type: "lowerBound",
+					lower: comparison.value,
+					lowerOpen: false,
+				};
 				break;
 			case "lt":
-				keyRange = IDBKeyRange.upperBound(comparison.value, true);
+				keyRange = {
+					type: "upperBound",
+					upper: comparison.value,
+					upperOpen: true,
+				};
 				break;
 			case "lte":
-				keyRange = IDBKeyRange.upperBound(comparison.value, false);
+				keyRange = {
+					type: "upperBound",
+					upper: comparison.value,
+					upperOpen: false,
+				};
 				break;
 			default:
 				if (debug) {
@@ -433,104 +286,7 @@ export function tryExtractIndexedQuery(
 	}
 }
 
-/**
- * Adds an item to an IndexedDB object store using an existing transaction
- */
-function addToStoreInTransaction(
-	store: IDBObjectStore,
-	item: IndexedDBSyncItem,
-): Promise<void> {
-	return new Promise((resolve, reject) => {
-		const request = store.add(item);
-
-		request.onsuccess = () => {
-			resolve();
-		};
-
-		request.onerror = () => {
-			reject(request.error);
-		};
-	});
-}
-
-/**
- * Updates an item in an IndexedDB object store using an existing transaction
- */
-function updateInStoreInTransaction(
-	store: IDBObjectStore,
-	item: IndexedDBSyncItem,
-): Promise<void> {
-	return new Promise((resolve, reject) => {
-		const request = store.put(item);
-
-		request.onsuccess = () => {
-			resolve();
-		};
-
-		request.onerror = () => {
-			reject(request.error);
-		};
-	});
-}
-
-/**
- * Deletes an item from an IndexedDB object store using an existing transaction
- */
-function deleteFromStoreInTransaction(
-	store: IDBObjectStore,
-	id: string,
-): Promise<void> {
-	return new Promise((resolve, reject) => {
-		const request = store.delete(id);
-
-		request.onsuccess = () => {
-			resolve();
-		};
-
-		request.onerror = () => {
-			reject(request.error);
-		};
-	});
-}
-
-/**
- * Gets a single item from an IndexedDB object store by ID using an existing transaction
- */
-function getFromStoreInTransaction(
-	store: IDBObjectStore,
-	id: AnyId,
-): Promise<IndexedDBSyncItem | undefined> {
-	return new Promise((resolve, reject) => {
-		const request = store.get(id);
-
-		request.onsuccess = () => {
-			resolve(request.result as IndexedDBSyncItem | undefined);
-		};
-
-		request.onerror = () => {
-			reject(request.error);
-		};
-	});
-}
-
-/**
- * Executes a transaction and returns a promise that resolves when the transaction completes
- */
-function commitTransaction(transaction: IDBTransaction): Promise<void> {
-	return new Promise((resolve, reject) => {
-		transaction.oncomplete = () => {
-			resolve();
-		};
-
-		transaction.onerror = () => {
-			reject(transaction.error);
-		};
-
-		transaction.onabort = () => {
-			reject(new Error("Transaction aborted"));
-		};
-	});
-}
+// Note: Low-level transaction helpers have been replaced by high-level IDBDatabaseLike methods
 
 /**
  * Auto-discovers indexes from the IndexedDB store
@@ -553,30 +309,17 @@ function commitTransaction(transaction: IDBTransaction): Promise<void> {
  * // This collection will auto-detect and use them for optimized queries
  */
 function discoverIndexes(
-	db: IDBDatabase,
+	db: IDBDatabaseLike,
 	storeName: string,
 ): Record<string, string> {
-	if (!db.objectStoreNames.contains(storeName)) {
-		return {};
-	}
-
-	const transaction = db.transaction(storeName, "readonly");
-
-	const store = transaction.objectStore(storeName);
-
+	const indexes = db.getStoreIndexes(storeName);
 	const indexMap: Record<string, string> = {};
 
-	// Iterate through all indexes in the store
-	const indexNames = Array.from(store.indexNames);
-
-	for (const indexName of indexNames) {
-		const index = store.index(indexName);
-		const keyPath = index.keyPath;
-
+	for (const index of indexes) {
 		// Only map single-column indexes (string keyPath)
 		// Compound indexes (array keyPath) are more complex and not currently optimized
-		if (typeof keyPath === "string") {
-			indexMap[keyPath] = indexName;
+		if (typeof index.keyPath === "string") {
+			indexMap[index.keyPath] = index.name;
 		}
 	}
 
@@ -599,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;
 		}
@@ -613,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>>);
@@ -640,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;
 			}
 
@@ -659,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) {
@@ -719,65 +445,30 @@ 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 {
-				// Use a single transaction for all inserts
-				// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-				const transaction = config.indexedDBRef.current!.transaction(
-					config.storeName,
-					"readwrite",
-				);
-				const store = transaction.objectStore(config.storeName);
-
-				const addPromises: Promise<void>[] = [];
+				const itemsToInsert: IndexedDBSyncItem[] = [];
 
 				for (const mutation of mutations) {
 					const itemToInsert = mutation.modified;
-
-					// Add result for reactive store
 					results.push(itemToInsert);
-
-					// Add to IndexedDB in parallel (don't await yet)
-					addPromises.push(
-						addToStoreInTransaction(store, itemToInsert as IndexedDBSyncItem),
-					);
+					itemsToInsert.push(itemToInsert as IndexedDBSyncItem);
 				}
 
-				// Wait for all IndexedDB writes to complete
-				await Promise.all(addPromises);
-				await commitTransaction(transaction);
+				// Add all items in a single batch operation
+				await db.add(config.storeName, itemsToInsert);
 			} catch (error) {
 				// Clear results on error so nothing gets written to reactive store
 				results.length = 0;
@@ -788,20 +479,20 @@ 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 originalValues: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
-			// Use a single transaction for all updates
-			// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-			const transaction = config.indexedDBRef.current!.transaction(
-				config.storeName,
-				"readwrite",
-			);
-			const store = transaction.objectStore(config.storeName);
+			const itemsToUpdate: IndexedDBSyncItem[] = [];
 
 			for (const mutation of mutations) {
-				originalValues.push(mutation.original);
-
-				const existing = await getFromStoreInTransaction(store, mutation.key);
+				const existing = await db.get<IndexedDBSyncItem>(
+					config.storeName,
+					mutation.key,
+				);
 
 				if (existing) {
 					const updateTime = new Date();
@@ -811,7 +502,7 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 						updatedAt: updateTime,
 					} as IndexedDBSyncItem;
 
-					await updateInStoreInTransaction(store, updatedItem);
+					itemsToUpdate.push(updatedItem);
 					results.push(
 						updatedItem as unknown as InferSchemaOutput<SelectSchema<TTable>>,
 					);
@@ -821,27 +512,36 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 				}
 			}
 
-			// Wait for transaction to complete
-			await commitTransaction(transaction);
+			// Update all items in a single batch operation
+			if (itemsToUpdate.length > 0) {
+				await db.put(config.storeName, itemsToUpdate);
+			}
 
 			return results;
 		},
 
 		handleDelete: async (mutations) => {
-			// Use a single transaction for all deletes
-			// biome-ignore lint/style/noNonNullAssertion: DB is guaranteed to be ready after readyPromise resolves
-			const transaction = config.indexedDBRef.current!.transaction(
-				config.storeName,
-				"readwrite",
-			);
-			const store = transaction.objectStore(config.storeName);
+			const db = config.indexedDBRef.current;
 
-			for (const mutation of mutations) {
-				await deleteFromStoreInTransaction(store, mutation.key);
+			if (!db) {
+				throw new Error("Database not ready");
+			}
+
+			const keysToDelete: IDBValidKey[] = mutations.map((m) => m.key);
+
+			// Delete all items in a single batch operation
+			await db.delete(config.storeName, keysToDelete);
+		},
+
+		handleTruncate: async () => {
+			const db = config.indexedDBRef.current;
+
+			if (!db) {
+				throw new Error("Database not ready");
 			}
 
-			// Wait for transaction to complete
-			await commitTransaction(transaction);
+			// Clear all items from the store
+			await db.clear(config.storeName);
 		},
 	};
 

package/src/context/useDrizzleIndexedDB.ts

@@ -4,6 +4,7 @@ import {
 	useIndexedDBCollection,
 	type DrizzleIndexedDBContextValue,
 } from "./DrizzleIndexedDBProvider";
+import type { IDBDatabaseLike } from "../idb-types";
 
 export type UseDrizzleIndexedDBContextReturn<
 	TSchema extends Record<string, unknown>,
@@ -11,7 +12,7 @@ export type UseDrizzleIndexedDBContextReturn<
 	useCollection: <TTableName extends keyof TSchema & string>(
 		tableName: TTableName,
 	) => ReturnType<typeof useIndexedDBCollection<TSchema, TTableName>>;
-	indexedDB: IDBDatabase | null;
+	indexedDB: IDBDatabaseLike | null;
 };
 
 export function useDrizzleIndexedDB<