@firtoz/drizzle-indexeddb 0.2.0 → 0.4.0

package/src/index.ts

@@ -1,21 +1,42 @@
-export {
-	migrateIndexedDB,
-	type IndexedDBMigrationConfig,
-} from "./snapshot-migrator";
-
 export {
 	migrateIndexedDBWithFunctions,
-	type IndexedDBMigrationFunction,
+	type Migration,
+	type MigrationOperation,
+	type CreateTableOperation,
+	type DeleteTableOperation,
+	type CreateIndexOperation,
+	type DeleteIndexOperation,
 } from "./function-migrator";
 
-export { deleteIndexedDB } from "./utils";
+// IDB Types
+export type {
+	IDBCreator,
+	IDBOpenOptions,
+	IDBDatabaseLike,
+	IDBDeleter,
+	IndexInfo,
+	CreateStoreOptions,
+	CreateIndexOptions,
+	KeyRangeSpec,
+} from "./idb-types";
+
+// IDB Interceptor (for testing/debugging)
+export type { IDBInterceptor, IDBOperation } from "./idb-interceptor";
+
+// IDB Operations
+export { openIndexedDb, deleteIndexedDB } from "./idb-operations";
 
+// Native IDB Implementation
+export { defaultIDBCreator } from "./native-idb-database";
+
+// Instrumented IDB (for testing)
+export { createInstrumentedDbCreator } from "./instrumented-idb-database";
+
+// Collection
 export {
 	indexedDBCollectionOptions,
 	type IndexedDBCollectionConfig,
 	type IndexedDBSyncItem,
-	type IDBInterceptor,
-	type IDBOperation,
 } from "./collections/indexeddb-collection";
 
 // IndexedDB Provider
@@ -30,3 +51,30 @@ 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,
+	createProxyDbCreator,
+	type SyncHandler,
+	// Server
+	IDBProxyServer,
+	createProxyServer,
+	type IDBProxyServerOptions,
+	// Sync adapter (connects proxy sync to collection)
+	createCollectionSyncHandler,
+	combineSyncHandlers,
+} from "./proxy";

package/src/instrumented-idb-database.ts

@@ -0,0 +1,188 @@
+import type {
+	IDBDatabaseLike,
+	IDBCreator,
+	IDBOpenOptions,
+	IndexInfo,
+	CreateStoreOptions,
+	CreateIndexOptions,
+	KeyRangeSpec,
+} from "./idb-types";
+import type { IDBInterceptor } from "./idb-interceptor";
+import { defaultIDBCreator } from "./native-idb-database";
+
+/**
+ * A database wrapper that intercepts operations and reports them to an interceptor.
+ * Useful for testing to verify what IndexedDB operations are actually performed.
+ */
+class InstrumentedIDBDatabase implements IDBDatabaseLike {
+	constructor(
+		private db: IDBDatabaseLike,
+		private interceptor: IDBInterceptor,
+	) {}
+
+	get version(): number {
+		return this.db.version;
+	}
+
+	// Schema operations (pass through without interception)
+	hasStore(storeName: string): boolean {
+		return this.db.hasStore(storeName);
+	}
+
+	getStoreNames(): string[] {
+		return this.db.getStoreNames();
+	}
+
+	createStore(storeName: string, options?: CreateStoreOptions): void {
+		this.db.createStore(storeName, options);
+	}
+
+	deleteStore(storeName: string): void {
+		this.db.deleteStore(storeName);
+	}
+
+	createIndex(
+		storeName: string,
+		indexName: string,
+		keyPath: string | string[],
+		options?: CreateIndexOptions,
+	): void {
+		this.db.createIndex(storeName, indexName, keyPath, options);
+	}
+
+	deleteIndex(storeName: string, indexName: string): void {
+		this.db.deleteIndex(storeName, indexName);
+	}
+
+	getStoreIndexes(storeName: string): IndexInfo[] {
+		return this.db.getStoreIndexes(storeName);
+	}
+
+	// Data operations (intercepted)
+	async getAll<T = unknown>(storeName: string): Promise<T[]> {
+		const items = await this.db.getAll<T>(storeName);
+
+		this.interceptor.onOperation?.({
+			type: "getAll",
+			storeName,
+			itemsReturned: items,
+			itemCount: items.length,
+			timestamp: Date.now(),
+		});
+
+		return items;
+	}
+
+	async getAllByIndex<T = unknown>(
+		storeName: string,
+		indexName: string,
+		keyRange?: KeyRangeSpec,
+	): Promise<T[]> {
+		const items = await this.db.getAllByIndex<T>(
+			storeName,
+			indexName,
+			keyRange,
+		);
+
+		this.interceptor.onOperation?.({
+			type: "index-getAll",
+			storeName,
+			indexName,
+			keyRange: keyRange as unknown as IDBKeyRange | undefined,
+			itemsReturned: items,
+			itemCount: items.length,
+			timestamp: Date.now(),
+		});
+
+		return items;
+	}
+
+	async get<T = unknown>(
+		storeName: string,
+		key: IDBValidKey,
+	): Promise<T | undefined> {
+		const item = await this.db.get<T>(storeName, key);
+
+		this.interceptor.onOperation?.({
+			type: "get",
+			storeName,
+			key,
+			itemReturned: item,
+			timestamp: Date.now(),
+		});
+
+		return item;
+	}
+
+	async add(storeName: string, items: unknown[]): Promise<void> {
+		await this.db.add(storeName, items);
+
+		this.interceptor.onOperation?.({
+			type: "add",
+			storeName,
+			items,
+			itemCount: items.length,
+			timestamp: Date.now(),
+		});
+	}
+
+	async put(storeName: string, items: unknown[]): Promise<void> {
+		await this.db.put(storeName, items);
+
+		this.interceptor.onOperation?.({
+			type: "put",
+			storeName,
+			items,
+			itemCount: items.length,
+			timestamp: Date.now(),
+		});
+	}
+
+	async delete(storeName: string, keys: IDBValidKey[]): Promise<void> {
+		await this.db.delete(storeName, keys);
+
+		this.interceptor.onOperation?.({
+			type: "delete",
+			storeName,
+			keys,
+			keyCount: keys.length,
+			timestamp: Date.now(),
+		});
+	}
+
+	async clear(storeName: string): Promise<void> {
+		await this.db.clear(storeName);
+
+		this.interceptor.onOperation?.({
+			type: "clear",
+			storeName,
+			timestamp: Date.now(),
+		});
+	}
+
+	close(): void {
+		this.db.close();
+	}
+}
+
+/**
+ * Creates an instrumented database creator that wraps operations with interception.
+ * Use this for testing to verify what IndexedDB operations are performed.
+ *
+ * @example
+ * const interceptor = { onOperation: (op) => console.log(op) };
+ * const dbCreator = createInstrumentedDbCreator(interceptor);
+ *
+ * <DrizzleIndexedDBProvider dbCreator={dbCreator} ... />
+ */
+export function createInstrumentedDbCreator(
+	interceptor: IDBInterceptor,
+	baseCreator?: IDBCreator,
+): IDBCreator {
+	const creator = baseCreator ?? defaultIDBCreator;
+
+	return async (name: string, options?: IDBOpenOptions) => {
+		const db = await creator(name, options);
+		return new InstrumentedIDBDatabase(db, interceptor);
+	};
+}

package/src/native-idb-database.ts

@@ -0,0 +1,355 @@
+import type {
+	IDBDatabaseLike,
+	IDBCreator,
+	IDBOpenOptions,
+	IndexInfo,
+	CreateStoreOptions,
+	CreateIndexOptions,
+	KeyRangeSpec,
+} from "./idb-types";
+
+/**
+ * Creates a KeyRange from a KeyRangeSpec
+ */
+function createKeyRange(spec: KeyRangeSpec): IDBKeyRange {
+	switch (spec.type) {
+		case "only":
+			return IDBKeyRange.only(spec.value);
+		case "lowerBound":
+			return IDBKeyRange.lowerBound(spec.lower, spec.lowerOpen);
+		case "upperBound":
+			return IDBKeyRange.upperBound(spec.upper, spec.upperOpen);
+		case "bound":
+			return IDBKeyRange.bound(
+				spec.lower,
+				spec.upper,
+				spec.lowerOpen,
+				spec.upperOpen,
+			);
+	}
+}
+
+/**
+ * Default implementation that wraps native IndexedDB
+ */
+class NativeIDBDatabase implements IDBDatabaseLike {
+	constructor(private db: IDBDatabase) {
+		// Listen for version change events - close connection when another tab/process
+		// wants to upgrade the database. This prevents blocking issues.
+		this.db.onversionchange = () => {
+			this.db.close();
+		};
+	}
+
+	get version(): number {
+		return this.db.version;
+	}
+
+	hasStore(storeName: string): boolean {
+		return this.db.objectStoreNames.contains(storeName);
+	}
+
+	getStoreNames(): string[] {
+		return Array.from(this.db.objectStoreNames);
+	}
+
+	createStore(storeName: string, options?: CreateStoreOptions): void {
+		this.db.createObjectStore(storeName, options);
+	}
+
+	deleteStore(storeName: string): void {
+		this.db.deleteObjectStore(storeName);
+	}
+
+	createIndex(
+		storeName: string,
+		indexName: string,
+		keyPath: string | string[],
+		options?: CreateIndexOptions,
+	): void {
+		const transaction = this.db.transaction(storeName, "readonly");
+		const store = transaction.objectStore(storeName);
+		store.createIndex(indexName, keyPath, options);
+	}
+
+	deleteIndex(storeName: string, indexName: string): void {
+		const transaction = this.db.transaction(storeName, "readonly");
+		const store = transaction.objectStore(storeName);
+		store.deleteIndex(indexName);
+	}
+
+	getStoreIndexes(storeName: string): IndexInfo[] {
+		if (!this.hasStore(storeName)) {
+			return [];
+		}
+
+		const transaction = this.db.transaction(storeName, "readonly");
+		const store = transaction.objectStore(storeName);
+		const indexes: IndexInfo[] = [];
+
+		for (const indexName of Array.from(store.indexNames)) {
+			const index = store.index(indexName);
+			indexes.push({
+				name: indexName,
+				keyPath: index.keyPath,
+			});
+		}
+
+		return indexes;
+	}
+
+	async getAll<T = unknown>(storeName: string): Promise<T[]> {
+		if (!this.hasStore(storeName)) {
+			return [];
+		}
+
+		return new Promise((resolve, reject) => {
+			const transaction = this.db.transaction(storeName, "readonly");
+			const store = transaction.objectStore(storeName);
+			const request = store.getAll();
+
+			request.onsuccess = () => resolve(request.result as T[]);
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	async getAllByIndex<T = unknown>(
+		storeName: string,
+		indexName: string,
+		keyRange?: KeyRangeSpec,
+	): Promise<T[]> {
+		return new Promise((resolve, reject) => {
+			const transaction = this.db.transaction(storeName, "readonly");
+			const store = transaction.objectStore(storeName);
+			const index = store.index(indexName);
+			const range = keyRange ? createKeyRange(keyRange) : undefined;
+			const request = index.getAll(range);
+
+			request.onsuccess = () => resolve(request.result as T[]);
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	async get<T = unknown>(
+		storeName: string,
+		key: IDBValidKey,
+	): Promise<T | undefined> {
+		return new Promise((resolve, reject) => {
+			const transaction = this.db.transaction(storeName, "readonly");
+			const store = transaction.objectStore(storeName);
+			const request = store.get(key);
+
+			request.onsuccess = () => resolve(request.result as T | undefined);
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	async add(storeName: string, items: unknown[]): Promise<void> {
+		return new Promise((resolve, reject) => {
+			const transaction = this.db.transaction(storeName, "readwrite");
+			const store = transaction.objectStore(storeName);
+
+			for (const item of items) {
+				store.add(item);
+			}
+
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+			transaction.onabort = () => reject(new Error("Transaction aborted"));
+		});
+	}
+
+	async put(storeName: string, items: unknown[]): Promise<void> {
+		return new Promise((resolve, reject) => {
+			const transaction = this.db.transaction(storeName, "readwrite");
+			const store = transaction.objectStore(storeName);
+
+			for (const item of items) {
+				store.put(item);
+			}
+
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+			transaction.onabort = () => reject(new Error("Transaction aborted"));
+		});
+	}
+
+	async delete(storeName: string, keys: IDBValidKey[]): Promise<void> {
+		return new Promise((resolve, reject) => {
+			const transaction = this.db.transaction(storeName, "readwrite");
+			const store = transaction.objectStore(storeName);
+
+			for (const key of keys) {
+				store.delete(key);
+			}
+
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+			transaction.onabort = () => reject(new Error("Transaction aborted"));
+		});
+	}
+
+	async clear(storeName: string): Promise<void> {
+		return new Promise((resolve, reject) => {
+			const transaction = this.db.transaction(storeName, "readwrite");
+			const store = transaction.objectStore(storeName);
+			const request = store.clear();
+
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	close(): void {
+		this.db.close();
+	}
+}
+
+/**
+ * Upgrade-mode database wrapper used during version changes.
+ * Provides IDBDatabaseLike interface with schema modification capabilities.
+ */
+class UpgradeModeDatabase implements IDBDatabaseLike {
+	private createdStores: Map<string, IDBObjectStore> = new Map();
+
+	constructor(
+		private db: IDBDatabase,
+		private transaction: IDBTransaction,
+	) {}
+
+	get version(): number {
+		return this.db.version;
+	}
+
+	hasStore(storeName: string): boolean {
+		return this.db.objectStoreNames.contains(storeName);
+	}
+
+	getStoreNames(): string[] {
+		return Array.from(this.db.objectStoreNames);
+	}
+
+	createStore(storeName: string, options?: CreateStoreOptions): void {
+		const store = this.db.createObjectStore(storeName, options);
+		this.createdStores.set(storeName, store);
+	}
+
+	deleteStore(storeName: string): void {
+		this.db.deleteObjectStore(storeName);
+		this.createdStores.delete(storeName);
+	}
+
+	createIndex(
+		storeName: string,
+		indexName: string,
+		keyPath: string | string[],
+		options?: CreateIndexOptions,
+	): void {
+		let store = this.createdStores.get(storeName);
+		if (!store) {
+			try {
+				store = this.transaction.objectStore(storeName);
+			} catch {
+				throw new Error(`Cannot create index - store "${storeName}" not found`);
+			}
+		}
+		store.createIndex(indexName, keyPath, options);
+	}
+
+	deleteIndex(storeName: string, indexName: string): void {
+		let store = this.createdStores.get(storeName);
+		if (!store) {
+			try {
+				store = this.transaction.objectStore(storeName);
+			} catch {
+				throw new Error(`Cannot delete index - store "${storeName}" not found`);
+			}
+		}
+		store.deleteIndex(indexName);
+	}
+
+	getStoreIndexes(storeName: string): IndexInfo[] {
+		if (!this.hasStore(storeName)) return [];
+		let store = this.createdStores.get(storeName);
+		if (!store) {
+			try {
+				store = this.transaction.objectStore(storeName);
+			} catch {
+				return [];
+			}
+		}
+		return Array.from(store.indexNames).map((name) => ({
+			name,
+			keyPath: store.index(name).keyPath,
+		}));
+	}
+
+	// Data operations not available during upgrade
+	async getAll<T = unknown>(): Promise<T[]> {
+		throw new Error("getAll not available during upgrade");
+	}
+	async getAllByIndex<T = unknown>(): Promise<T[]> {
+		throw new Error("getAllByIndex not available during upgrade");
+	}
+	async get<T = unknown>(): Promise<T | undefined> {
+		throw new Error("get not available during upgrade");
+	}
+	async add(): Promise<void> {
+		throw new Error("add not available during upgrade");
+	}
+	async put(): Promise<void> {
+		throw new Error("put not available during upgrade");
+	}
+	async delete(): Promise<void> {
+		throw new Error("delete not available during upgrade");
+	}
+	async clear(): Promise<void> {
+		throw new Error("clear not available during upgrade");
+	}
+	close(): void {
+		this.db.close();
+	}
+}
+
+/**
+ * Default IDB creator that uses the native IndexedDB API.
+ */
+export const defaultIDBCreator: IDBCreator = (
+	name: string,
+	options?: IDBOpenOptions,
+): Promise<IDBDatabaseLike> => {
+	return new Promise((resolve, reject) => {
+		const request = options?.version
+			? indexedDB.open(name, options.version)
+			: indexedDB.open(name);
+
+		request.onerror = () => reject(request.error);
+
+		request.onblocked = () => {
+			setTimeout(() => {
+				reject(new Error("Database upgrade blocked - close other tabs"));
+			}, 3000);
+		};
+
+		request.onupgradeneeded = (event) => {
+			if (options?.onUpgrade) {
+				const db = request.result;
+				const transaction = (event.target as IDBOpenDBRequest).transaction;
+				if (!transaction) {
+					reject(new Error("No transaction during upgrade"));
+					return;
+				}
+				// Create an upgrade-mode database wrapper
+				const upgradeDb = new UpgradeModeDatabase(db, transaction);
+				try {
+					options.onUpgrade(upgradeDb);
+				} catch (error) {
+					transaction.abort();
+					reject(error);
+				}
+			}
+		};
+
+		request.onsuccess = () => resolve(new NativeIDBDatabase(request.result));
+	});
+};