@firtoz/drizzle-indexeddb 0.3.0 → 0.4.1

package/src/context/DrizzleIndexedDBProvider.tsx

@@ -0,0 +1,374 @@
+import type { PropsWithChildren } from "react";
+import {
+	createContext,
+	useMemo,
+	useCallback,
+	useEffect,
+	useState,
+	useRef,
+} from "react";
+import {
+	createCollection,
+	type InferSchemaInput,
+	type UtilsRecord,
+	type Collection,
+	type InferSchemaOutput,
+	type SyncMode,
+} from "@tanstack/db";
+import { getTableName, type Table } from "drizzle-orm";
+import {
+	indexedDBCollectionOptions,
+	type IndexedDBCollectionConfig,
+} from "@firtoz/drizzle-indexeddb";
+import type {
+	IdOf,
+	InsertSchema,
+	SelectSchema,
+	GetTableFromSchema,
+	InferCollectionFromTable,
+	ExternalSyncHandler,
+} from "@firtoz/drizzle-utils";
+import {
+	type Migration,
+	migrateIndexedDBWithFunctions,
+} 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
+	collection: Collection<any, string>;
+	refCount: number;
+	// biome-ignore lint/suspicious/noExplicitAny: External sync needs to accept any item type
+	pushExternalSync: ExternalSyncHandler<any>;
+}
+
+// Type for migration functions (generated by Drizzle)
+
+type IndexedDbCollection<
+	TSchema extends Record<string, unknown>,
+	TTableName extends keyof TSchema & string,
+> = Collection<
+	InferSchemaOutput<SelectSchema<GetTableFromSchema<TSchema, TTableName>>>,
+	IdOf<GetTableFromSchema<TSchema, TTableName>>,
+	UtilsRecord,
+	SelectSchema<GetTableFromSchema<TSchema, TTableName>>,
+	InferSchemaInput<InsertSchema<GetTableFromSchema<TSchema, TTableName>>>
+>;
+
+export type DrizzleIndexedDBContextValue<
+	TSchema extends Record<string, unknown>,
+> = {
+	indexedDB: IDBDatabaseLike | null;
+	getCollection: <TTableName extends keyof TSchema & string>(
+		tableName: TTableName,
+	) => 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 =
+	// biome-ignore lint/suspicious/noExplicitAny: Context needs to accept any schema type
+	createContext<DrizzleIndexedDBContextValue<any> | null>(null);
+
+type DrizzleIndexedDBProviderProps<TSchema extends Record<string, unknown>> =
+	PropsWithChildren<{
+		dbName: string;
+		schema: TSchema;
+		migrations?: Migration[];
+		migrateFunction?: (
+			dbName: string,
+			migrations: Migration[],
+			debug?: boolean,
+			dbCreator?: IDBCreator,
+		) => Promise<IDBDatabaseLike>;
+		debug?: boolean;
+		syncMode?: SyncMode;
+		/**
+		 * Optional custom database creator for testing/mocking.
+		 * 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<
+	TSchema extends Record<string, unknown>,
+>({
+	children,
+	dbName,
+	schema,
+	migrations = [],
+	migrateFunction = migrateIndexedDBWithFunctions,
+	debug = false,
+	syncMode = "eager",
+	dbCreator,
+	onSyncReady,
+}: DrizzleIndexedDBProviderProps<TSchema>) {
+	const [indexedDB, setIndexedDB] = useState<IDBDatabaseLike | null>(null);
+	const indexedDBRef = useRef<IDBDatabaseLike | null>(null);
+	const [readyPromise] = useState(() => {
+		let resolveReady: () => void;
+		const promise = new Promise<void>((resolve) => {
+			resolveReady = resolve;
+		});
+		// biome-ignore lint/style/noNonNullAssertion: resolveReady is guaranteed to be set
+		return { promise, resolve: resolveReady! };
+	});
+
+	useEffect(() => {
+		const initDB = async () => {
+			try {
+				let db: IDBDatabaseLike;
+
+				if (migrations.length === 0) {
+					// Open database directly without migration logic
+					db = await openIndexedDb(dbName, dbCreator);
+				} else {
+					db = await migrateFunction(dbName, migrations, debug, dbCreator);
+				}
+
+				indexedDBRef.current = db;
+				setIndexedDB(db);
+				readyPromise.resolve();
+			} catch (error) {
+				console.error(
+					`[DrizzleIndexedDBProvider] Failed to initialize database ${dbName}:`,
+					error,
+				);
+				throw error;
+			}
+		};
+
+		initDB();
+
+		// Cleanup on unmount
+		return () => {
+			if (indexedDB) {
+				indexedDB.close();
+			}
+		};
+	}, [dbName, migrations, migrateFunction, debug, readyPromise]);
+
+	// Collection cache with ref counting
+	const collections = useMemo<Map<string, CollectionCacheEntry>>(
+		() => new Map(),
+		[],
+	);
+
+	const getCollection = useCallback<
+		DrizzleIndexedDBContextValue<TSchema>["getCollection"]
+	>(
+		<TTableName extends keyof TSchema & string>(tableName: TTableName) => {
+			const cacheKey = tableName;
+
+			// Check if collection already exists in cache
+			if (!collections.has(cacheKey)) {
+				// Get the table definition from schema
+				const table = schema[tableName] as Table;
+
+				if (!table) {
+					throw new Error(
+						`Table "${tableName}" not found in schema. Available tables: ${Object.keys(schema).join(", ")}`,
+					);
+				}
+
+				// Extract the actual store/table name from the table definition
+				const actualTableName = getTableName(table);
+
+				// Create collection options
+				const collectionConfig = indexedDBCollectionOptions({
+					indexedDBRef,
+					dbName,
+					table,
+					storeName: actualTableName,
+					readyPromise: readyPromise.promise,
+					debug,
+					syncMode,
+				} as IndexedDBCollectionConfig<Table>);
+
+				// Create new collection and cache it with ref count 0
+				// The collection will wait for readyPromise before accessing the database
+				const collection = createCollection(collectionConfig);
+
+				collections.set(cacheKey, {
+					collection,
+					refCount: 0,
+					pushExternalSync: collectionConfig.utils.pushExternalSync,
+				});
+			}
+
+			// biome-ignore lint/style/noNonNullAssertion: We just ensured the collection exists
+			return collections.get(cacheKey)!
+				.collection as unknown as IndexedDbCollection<TSchema, TTableName>;
+		},
+		[
+			indexedDBRef,
+			collections,
+			schema,
+			readyPromise.promise,
+			debug,
+			dbName,
+			syncMode,
+		],
+	);
+
+	const incrementRefCount: DrizzleIndexedDBContextValue<TSchema>["incrementRefCount"] =
+		useCallback(
+			(tableName: string) => {
+				const entry = collections.get(tableName);
+				if (entry) {
+					entry.refCount++;
+				}
+			},
+			[collections],
+		);
+
+	const decrementRefCount: DrizzleIndexedDBContextValue<TSchema>["decrementRefCount"] =
+		useCallback(
+			(tableName: string) => {
+				const entry = collections.get(tableName);
+				if (entry) {
+					entry.refCount--;
+
+					// If ref count reaches 0, remove from cache
+					if (entry.refCount <= 0) {
+						collections.delete(tableName);
+					}
+				}
+			},
+			[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?.pushExternalSync) {
+							// Route sync message to collection
+							switch (message.type) {
+								case "sync:add":
+									entry.pushExternalSync({
+										type: "insert",
+										items: message.items,
+									});
+									break;
+								case "sync:put":
+									entry.pushExternalSync({
+										type: "update",
+										items: message.items,
+									});
+									break;
+								case "sync:delete":
+									// For delete, construct items with id
+									entry.pushExternalSync({
+										type: "delete",
+										items: message.keys.map((key) => ({ id: key })),
+									});
+									break;
+								case "sync:clear":
+									entry.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,
+		],
+	);
+
+	return (
+		<DrizzleIndexedDBContext.Provider value={contextValue}>
+			{children}
+		</DrizzleIndexedDBContext.Provider>
+	);
+}
+
+// Hook that components use to get a collection with automatic ref counting
+export function useIndexedDBCollection<
+	TSchema extends Record<string, unknown>,
+	TTableName extends keyof TSchema & string,
+>(
+	context: DrizzleIndexedDBContextValue<TSchema>,
+	tableName: TTableName,
+): InferCollectionFromTable<GetTableFromSchema<TSchema, TTableName>> {
+	const { collection, unsubscribe } = useMemo(() => {
+		// Get the collection and increment ref count
+		const col = context.getCollection(tableName);
+		context.incrementRefCount(tableName);
+
+		// Return collection and unsubscribe function
+		return {
+			collection: col,
+			unsubscribe: () => {
+				context.decrementRefCount(tableName);
+			},
+		};
+	}, [context, tableName]);
+
+	// Cleanup on unmount
+	useEffect(() => {
+		return () => {
+			unsubscribe();
+		};
+	}, [unsubscribe]);
+
+	return collection as unknown as InferCollectionFromTable<
+		GetTableFromSchema<TSchema, TTableName>
+	>;
+}

package/src/context/useDrizzleIndexedDB.ts

@@ -4,7 +4,7 @@ import {
 	useIndexedDBCollection,
 	type DrizzleIndexedDBContextValue,
 } from "./DrizzleIndexedDBProvider";
-import type { IDBDatabaseLike } from "../utils";
+import type { IDBDatabaseLike } from "../idb-types";
 
 export type UseDrizzleIndexedDBContextReturn<
 	TSchema extends Record<string, unknown>,

package/src/function-migrator.ts

@@ -1,6 +1,7 @@
 // IndexedDB migrator with declarative migration format
 
-import { type IDBCreator, type IDBDatabaseLike, openIndexedDb } from "./utils";
+import type { IDBCreator, IDBDatabaseLike } from "./idb-types";
+import { openIndexedDb } from "./idb-operations";
 
 // ============================================================================
 // Declarative Migration Types

package/src/idb-interceptor.ts

@@ -0,0 +1,75 @@
+/**
+ * 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;
+			items: unknown[];
+			itemCount: number;
+			timestamp: number;
+	  }
+	| {
+			type: "add";
+			storeName: string;
+			items: unknown[];
+			itemCount: number;
+			timestamp: number;
+	  }
+	| {
+			type: "delete";
+			storeName: string;
+			keys: IDBValidKey[];
+			keyCount: number;
+			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;
+}

package/src/idb-operations.ts

@@ -0,0 +1,41 @@
+import type {
+	IDBDatabaseLike,
+	IDBCreator,
+	IDBOpenOptions,
+	IDBDeleter,
+} from "./idb-types";
+import { defaultIDBCreator } from "./native-idb-database";
+
+/**
+ * Opens an IndexedDB database using the provided creator or the default native implementation.
+ */
+export async function openIndexedDb(
+	name: string,
+	dbCreator?: IDBCreator,
+	options?: IDBOpenOptions,
+): Promise<IDBDatabaseLike> {
+	const dbCreatorToUse = dbCreator ?? defaultIDBCreator;
+	return dbCreatorToUse(name, options);
+}
+
+/**
+ * Default IDB deleter that uses the native IndexedDB API.
+ */
+const defaultIDBDeleter: IDBDeleter = (name: string): Promise<void> => {
+	return new Promise((resolve, reject) => {
+		const request = indexedDB.deleteDatabase(name);
+		request.onerror = () => reject(request.error);
+		request.onsuccess = () => resolve();
+	});
+};
+
+/**
+ * Deletes an IndexedDB database (useful for testing)
+ */
+export async function deleteIndexedDB(
+	dbName: string,
+	dbDeleter?: IDBDeleter,
+): Promise<void> {
+	const dbDeleterToUse = dbDeleter ?? defaultIDBDeleter;
+	return dbDeleterToUse(dbName);
+}

package/src/idb-types.ts

@@ -0,0 +1,135 @@
+/**
+ * Index information returned by getStoreIndexes
+ */
+export interface IndexInfo {
+	name: string;
+	keyPath: string | string[];
+}
+
+/**
+ * Options for creating an object store
+ */
+export interface CreateStoreOptions {
+	keyPath?: string;
+	autoIncrement?: boolean;
+}
+
+/**
+ * Options for creating an index
+ */
+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.
+ *
+ * All operations are simple async functions - no transactions, requests, or callbacks to deal with.
+ */
+export interface IDBDatabaseLike {
+	/** Database version number */
+	readonly version: number;
+
+	// =========================================================================
+	// Schema Operations (for migrations)
+	// =========================================================================
+
+	/** Check if a store exists */
+	hasStore(storeName: string): boolean;
+
+	/** Get list of all store names */
+	getStoreNames(): string[];
+
+	/** Create an object store (only valid during migrations) */
+	createStore(storeName: string, options?: CreateStoreOptions): void;
+
+	/** Delete an object store (only valid during migrations) */
+	deleteStore(storeName: string): void;
+
+	/** Create an index on a store (only valid during migrations) */
+	createIndex(
+		storeName: string,
+		indexName: string,
+		keyPath: string | string[],
+		options?: CreateIndexOptions,
+	): void;
+
+	/** Delete an index from a store (only valid during migrations) */
+	deleteIndex(storeName: string, indexName: string): void;
+
+	/** Get all indexes for a store (for index discovery) */
+	getStoreIndexes(storeName: string): IndexInfo[];
+
+	// =========================================================================
+	// Data Operations (all async, handle transactions internally)
+	// =========================================================================
+
+	/** Get all items from a store */
+	getAll<T = unknown>(storeName: string): Promise<T[]>;
+
+	/** Get items from a store using an index with optional key range */
+	getAllByIndex<T = unknown>(
+		storeName: string,
+		indexName: string,
+		keyRange?: KeyRangeSpec,
+	): Promise<T[]>;
+
+	/** Get a single item by key */
+	get<T = unknown>(storeName: string, key: IDBValidKey): Promise<T | undefined>;
+
+	/** Add items to a store (batch operation) */
+	add(storeName: string, items: unknown[]): Promise<void>;
+
+	/** Update items in a store (batch operation, uses put) */
+	put(storeName: string, items: unknown[]): Promise<void>;
+
+	/** Delete items from a store by keys (batch operation) */
+	delete(storeName: string, keys: IDBValidKey[]): Promise<void>;
+
+	/** Clear all items from a store */
+	clear(storeName: string): Promise<void>;
+
+	// =========================================================================
+	// Lifecycle
+	// =========================================================================
+
+	/** Close the database connection */
+	close(): void;
+}
+
+/**
+ * Options for opening a database with version upgrade support.
+ */
+export interface IDBOpenOptions {
+	/** Target version for the database. If higher than current, triggers upgrade. */
+	version?: number;
+	/** Called during version upgrade - this is where schema changes (createStore, createIndex) are allowed. */
+	onUpgrade?: (db: IDBDatabaseLike) => void;
+}
+
+/**
+ * Function type for creating/opening an IndexedDB-like database.
+ * Custom implementations can use this to provide proxy/mock/alternative backends.
+ */
+export type IDBCreator = (
+	name: string,
+	options?: IDBOpenOptions,
+) => Promise<IDBDatabaseLike>;
+
+/**
+ * Function type for deleting an IndexedDB database.
+ */
+export type IDBDeleter = (name: string) => Promise<void>;