@firtoz/drizzle-indexeddb 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-indexeddb",
-	"version": "0.4.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"
@@ -65,13 +71,13 @@
 	},
 	"dependencies": {
 		"@firtoz/drizzle-utils": "^0.3.0",
-		"@tanstack/db": "^0.5.10",
-		"drizzle-orm": "^0.44.7",
+		"@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/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>
+	>;
+}