@firtoz/drizzle-indexeddb 0.2.0 → 0.4.0

package/src/function-migrator.ts

@@ -1,9 +1,55 @@
-// IndexedDB migrator that executes generated migration functions
+// IndexedDB migrator with declarative migration format
+
+import type { IDBCreator, IDBDatabaseLike } from "./idb-types";
+import { openIndexedDb } from "./idb-operations";
+
+// ============================================================================
+// Declarative Migration Types
+// ============================================================================
+
+export interface CreateTableOperation {
+	type: "createTable";
+	name: string;
+	keyPath?: string;
+	autoIncrement?: boolean;
+	indexes?: Array<{
+		name: string;
+		keyPath: string | string[];
+		unique?: boolean;
+	}>;
+}
+
+export interface DeleteTableOperation {
+	type: "deleteTable";
+	name: string;
+}
 
-export type IndexedDBMigrationFunction = (
-	db: IDBDatabase,
-	transaction: IDBTransaction,
-) => Promise<void>;
+export interface CreateIndexOperation {
+	type: "createIndex";
+	tableName: string;
+	indexName: string;
+	keyPath: string | string[];
+	unique?: boolean;
+}
+
+export interface DeleteIndexOperation {
+	type: "deleteIndex";
+	tableName: string;
+	indexName: string;
+}
+
+export type MigrationOperation =
+	| CreateTableOperation
+	| DeleteTableOperation
+	| CreateIndexOperation
+	| DeleteIndexOperation;
+
+/** A migration is an array of operations to perform */
+export type Migration = MigrationOperation[];
+
+// ============================================================================
+// Migration Record
+// ============================================================================
 
 interface MigrationRecord {
 	id: number;
@@ -12,160 +58,184 @@ interface MigrationRecord {
 
 const MIGRATIONS_STORE = "__drizzle_migrations";
 
+// ============================================================================
+// Migration Executor
+// ============================================================================
+
 /**
- * Runs IndexedDB migrations using generated migration functions
+ * Executes a single migration operation on the database.
+ */
+function executeMigrationOperation(
+	db: IDBDatabaseLike,
+	op: MigrationOperation,
+): void {
+	switch (op.type) {
+		case "createTable": {
+			if (!db.hasStore(op.name)) {
+				db.createStore(op.name, {
+					keyPath: op.keyPath,
+					autoIncrement: op.autoIncrement,
+				});
+				// Create indexes if specified
+				if (op.indexes) {
+					for (const idx of op.indexes) {
+						db.createIndex(op.name, idx.name, idx.keyPath, {
+							unique: idx.unique,
+						});
+					}
+				}
+			}
+			break;
+		}
+		case "deleteTable": {
+			if (db.hasStore(op.name)) {
+				db.deleteStore(op.name);
+			}
+			break;
+		}
+		case "createIndex": {
+			if (db.hasStore(op.tableName)) {
+				db.createIndex(op.tableName, op.indexName, op.keyPath, {
+					unique: op.unique,
+				});
+			}
+			break;
+		}
+		case "deleteIndex": {
+			if (db.hasStore(op.tableName)) {
+				db.deleteIndex(op.tableName, op.indexName);
+			}
+			break;
+		}
+	}
+}
+
+/**
+ * Executes a full migration (array of operations).
+ */
+function executeMigration(db: IDBDatabaseLike, migration: Migration): void {
+	for (const op of migration) {
+		executeMigrationOperation(db, op);
+	}
+}
+
+// ============================================================================
+// Main Migrator
+// ============================================================================
+
+/**
+ * Runs IndexedDB migrations using declarative migration arrays.
+ * Version = total migrations + 1.
  *
  * Example usage:
  * ```typescript
- * import { migrations } from './drizzle/indexeddb-migrations';
- * import { migrateIndexedDBWithFunctions } from '@firtoz/drizzle-indexeddb';
+ * const migrations: Migration[] = [
+ *   [
+ *     { type: "createTable", name: "todo", keyPath: "id", indexes: [
+ *       { name: "todo_user_id", keyPath: "user_id" }
+ *     ]}
+ *   ],
+ *   [
+ *     { type: "createTable", name: "user", keyPath: "id" }
+ *   ]
+ * ];
  *
- * const db = await migrateIndexedDBWithFunctions('my-db', migrations, true);
+ * const db = await migrateIndexedDBWithFunctions('my-db', migrations);
  * ```
  */
 export async function migrateIndexedDBWithFunctions(
 	dbName: string,
-	migrations: IndexedDBMigrationFunction[],
+	migrations: Migration[],
 	debug: boolean = false,
-): Promise<IDBDatabase> {
+	dbCreator?: IDBCreator,
+): Promise<IDBDatabaseLike> {
 	if (debug) {
-		console.log(
-			`[${new Date().toISOString()}] [PERF] IndexedDB migrator start for ${dbName}`,
-		);
+		console.log(`[IndexedDB] Starting migration for ${dbName}`);
 	}
 
-	// First, open the database to check which migrations have been applied
-	const currentDb = await openDatabaseForMigrationCheck(dbName);
-
-	const appliedMigrations = await getAppliedMigrations(currentDb);
+	const targetVersion = migrations.length + 1;
 
-	const latestAppliedIdx =
-		appliedMigrations.length > 0
-			? Math.max(...appliedMigrations.map((m) => m.id))
-			: -1;
+	// Open database to check current state
+	let db = await openIndexedDb(dbName, dbCreator);
+	const currentVersion = db.version;
 
 	if (debug) {
 		console.log(
-			`[${new Date().toISOString()}] [PERF] Latest applied migration index: ${latestAppliedIdx} (checked ${appliedMigrations.length} migrations)`,
+			`[IndexedDB] Current version: ${currentVersion}, Target: ${targetVersion}`,
 		);
 	}
 
-	// Determine which migrations need to be applied
+	// If already at target version, check if all migrations are recorded
+	if (currentVersion >= targetVersion) {
+		const applied = await getAppliedMigrations(db);
+		if (applied.length === migrations.length) {
+			if (debug) {
+				console.log("[IndexedDB] Already up to date");
+			}
+			return db;
+		}
+	}
+
+	// Get applied migrations before closing
+	const appliedMigrations = await getAppliedMigrations(db);
+	const appliedSet = new Set(appliedMigrations.map((m) => m.id));
+
+	// Find pending migrations
 	const pendingMigrations = migrations
-		.map((fn, idx) => ({ fn, idx }))
-		.filter(({ idx }) => idx > latestAppliedIdx);
+		.map((migration, idx) => ({ migration, idx }))
+		.filter(({ idx }) => !appliedSet.has(idx));
 
 	if (pendingMigrations.length === 0) {
 		if (debug) {
-			console.log(
-				`[${new Date().toISOString()}] [PERF] No pending migrations - database is up to date`,
-			);
-		}
-		currentDb.close();
-		// Re-open with correct version (migrations.length + 1 because version starts at 1)
-		const db = await openDatabase(dbName, migrations.length + 1);
-		if (debug) {
-			console.log(
-				`[${new Date().toISOString()}] [PERF] Migrator complete (no migrations needed)`,
-			);
+			console.log("[IndexedDB] No pending migrations");
 		}
 		return db;
 	}
 
 	if (debug) {
 		console.log(
-			`[${new Date().toISOString()}] [PERF] Found ${pendingMigrations.length} pending migrations to apply`,
+			`[IndexedDB] ${pendingMigrations.length} pending migrations to apply`,
 		);
 	}
 
-	currentDb.close();
-
-	// Calculate the target version (number of total migrations)
-	const targetVersion = migrations.length;
-
-	// Open database with version upgrade to trigger migration
-	const db = await new Promise<IDBDatabase>((resolve, reject) => {
-		// Use +1 here because first version is 1...
-		const request = indexedDB.open(dbName, targetVersion + 1);
-
-		request.onerror = () => reject(request.error);
-		request.onsuccess = () => {
-			resolve(request.result);
-		};
-
-		request.onupgradeneeded = async (event) => {
-			const db = (event.target as IDBOpenDBRequest).result;
-			const transaction = (event.target as IDBOpenDBRequest).transaction;
-
-			if (!transaction) {
-				reject(new Error("Transaction not available during upgrade"));
-				return;
-			}
-
-			if (debug) {
-				console.log(
-					`[${new Date().toISOString()}] [PERF] Upgrade started: v${event.oldVersion} → v${event.newVersion}`,
-				);
-			}
-
-			try {
-				// Ensure migrations store exists
-				if (!db.objectStoreNames.contains(MIGRATIONS_STORE)) {
-					const migrationStore = db.createObjectStore(MIGRATIONS_STORE, {
-						keyPath: "id",
-						autoIncrement: false,
-					});
-					migrationStore.createIndex("appliedAt", "appliedAt", {
-						unique: false,
-					});
-					if (debug) {
-						console.log(
-							`[${new Date().toISOString()}] [PERF] Created migrations tracking store`,
-						);
-					}
-				}
-
-				// Apply each pending migration
-				for (const { fn, idx } of pendingMigrations) {
-					if (debug) {
-						console.log(
-							`[${new Date().toISOString()}] [PERF] Applying migration ${idx}...`,
-						);
-					}
-
-					// Execute the migration function
-					await fn(db, transaction);
-
-					// Record the migration
-					const migrationStore = transaction.objectStore(MIGRATIONS_STORE);
-					migrationStore.add({
-						id: idx,
-						appliedAt: Date.now(),
-					});
-
-					if (debug) {
-						console.log(
-							`[${new Date().toISOString()}] [PERF] Migration ${idx} complete`,
-						);
-					}
+	// Close to allow version upgrade
+	db.close();
+
+	// Open with target version, running migrations during upgrade
+	await openIndexedDb(dbName, dbCreator, {
+		version: targetVersion,
+		onUpgrade: (upgradeDb) => {
+			// Ensure migrations store exists
+			if (!upgradeDb.hasStore(MIGRATIONS_STORE)) {
+				upgradeDb.createStore(MIGRATIONS_STORE, {
+					keyPath: "id",
+					autoIncrement: false,
+				});
+				if (debug) {
+					console.log("[IndexedDB] Created migrations store");
 				}
+			}
 
+			// Run pending migrations
+			for (const { migration, idx } of pendingMigrations) {
 				if (debug) {
-					console.log(
-						`[${new Date().toISOString()}] [PERF] All ${pendingMigrations.length} migrations applied successfully`,
-					);
+					console.log(`[IndexedDB] Running migration ${idx}`);
 				}
-			} catch (error) {
-				console.error("[IndexedDBMigrator] Migration failed:", error);
-				transaction.abort();
-				reject(error);
+				executeMigration(upgradeDb, migration);
 			}
-		};
+		},
 	});
 
+	// Reopen normally and record applied migrations
+	db = await openIndexedDb(dbName, dbCreator);
+
+	for (const { idx } of pendingMigrations) {
+		await db.add(MIGRATIONS_STORE, [{ id: idx, appliedAt: Date.now() }]);
+	}
+
 	if (debug) {
 		console.log(
-			`[${new Date().toISOString()}] [PERF] Migrator complete - database ready`,
+			`[IndexedDB] Applied ${pendingMigrations.length} migrations, now at version ${targetVersion}`,
 		);
 	}
 
@@ -173,62 +243,13 @@ export async function migrateIndexedDBWithFunctions(
 }
 
 /**
- * Opens database for checking migrations (without triggering upgrade)
- */
-async function openDatabaseForMigrationCheck(
-	dbName: string,
-): Promise<IDBDatabase> {
-	return new Promise((resolve, reject) => {
-		const request = indexedDB.open(dbName);
-		request.onerror = () => {
-			reject(request.error);
-		};
-		request.onsuccess = () => {
-			resolve(request.result);
-		};
-	});
-}
-
-/**
- * Opens database with a specific version
- */
-async function openDatabase(
-	dbName: string,
-	version: number,
-): Promise<IDBDatabase> {
-	return new Promise((resolve, reject) => {
-		const request = indexedDB.open(dbName, version);
-		request.onerror = () => {
-			reject(request.error);
-		};
-		request.onsuccess = () => {
-			resolve(request.result);
-		};
-	});
-}
-
-/**
- * Gets the list of applied migrations from the database
+ * Gets applied migrations from the database.
  */
 async function getAppliedMigrations(
-	db: IDBDatabase,
+	db: IDBDatabaseLike,
 ): Promise<MigrationRecord[]> {
-	if (!db.objectStoreNames.contains(MIGRATIONS_STORE)) {
+	if (!db.hasStore(MIGRATIONS_STORE)) {
 		return [];
 	}
-
-	return new Promise((resolve, reject) => {
-		const transaction = db.transaction(MIGRATIONS_STORE, "readonly");
-
-		const store = transaction.objectStore(MIGRATIONS_STORE);
-
-		const request = store.getAll();
-
-		request.onerror = () => {
-			reject(request.error);
-		};
-		request.onsuccess = () => {
-			resolve(request.result);
-		};
-	});
+	return db.getAll<MigrationRecord>(MIGRATIONS_STORE);
 }

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