@firtoz/drizzle-indexeddb 0.3.0 → 0.4.1

package/src/index.ts

@@ -8,23 +8,35 @@ export {
 	type DeleteIndexOperation,
 } from "./function-migrator";
 
-export {
-	deleteIndexedDB,
-	type IDBCreator,
-	type IDBOpenOptions,
-	type IDBDatabaseLike,
-	type IndexInfo,
-	type CreateStoreOptions,
-	type CreateIndexOptions,
-	type KeyRangeSpec,
-} 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
@@ -39,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/{utils.ts → native-idb-database.ts}

@@ -1,128 +1,12 @@
-// ============================================================================
-// Minimal IDB Interface - High-Level Async API
-// ============================================================================
-// These interfaces define a simple, high-level async API for IndexedDB operations.
-// This makes it easy to:
-// - Create mock implementations for testing
-// - Implement alternative backends (e.g., Chrome extension message-based IDB)
-// - Use with any async storage that supports similar operations
-// ============================================================================
-
-/**
- * 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;
-}
-
-// ============================================================================
-// Default Implementation (wraps native IndexedDB)
-// ============================================================================
+import type {
+	IDBDatabaseLike,
+	IDBCreator,
+	IDBOpenOptions,
+	IndexInfo,
+	CreateStoreOptions,
+	CreateIndexOptions,
+	KeyRangeSpec,
+} from "./idb-types";
 
 /**
  * Creates a KeyRange from a KeyRangeSpec
@@ -321,69 +205,6 @@ class NativeIDBDatabase implements IDBDatabaseLike {
 	}
 }
 
-// ============================================================================
-// IDB Creator / Opener
-// ============================================================================
-
-/**
- * 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>;
-
-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));
-	});
-};
-
 /**
  * Upgrade-mode database wrapper used during version changes.
  * Provides IDBDatabaseLike interface with schema modification capabilities.
@@ -490,36 +311,45 @@ class UpgradeModeDatabase implements IDBDatabaseLike {
 	}
 }
 
-export async function openIndexedDb(
+/**
+ * Default IDB creator that uses the native IndexedDB API.
+ */
+export const defaultIDBCreator: IDBCreator = (
 	name: string,
-	dbCreator?: IDBCreator,
 	options?: IDBOpenOptions,
-): Promise<IDBDatabaseLike> {
-	const dbCreatorToUse = dbCreator ?? defaultIDBCreator;
-	return dbCreatorToUse(name, options);
-}
+): Promise<IDBDatabaseLike> => {
+	return new Promise((resolve, reject) => {
+		const request = options?.version
+			? indexedDB.open(name, options.version)
+			: indexedDB.open(name);
 
-// ============================================================================
-// IDB Deleter
-// ============================================================================
+		request.onerror = () => reject(request.error);
 
-export type IDBDeleter = (name: string) => Promise<void>;
+		request.onblocked = () => {
+			setTimeout(() => {
+				reject(new Error("Database upgrade blocked - close other tabs"));
+			}, 3000);
+		};
 
-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();
+		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));
 	});
 };
-
-/**
- * Deletes the database (useful for testing)
- */
-export async function deleteIndexedDB(
-	dbName: string,
-	dbDeleter?: IDBDeleter,
-): Promise<void> {
-	const dbDeleterToUse = dbDeleter ?? defaultIDBDeleter;
-	return dbDeleterToUse(dbName);
-}