@firtoz/drizzle-indexeddb 0.3.0 → 0.4.0

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>;

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);
+	};
+}