@firtoz/drizzle-indexeddb 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @firtoz/drizzle-indexeddb
 
+## 0.5.0
+
+### Minor Changes
+
+- [`9e532bb`](https://github.com/firtoz/fullstack-toolkit/commit/9e532bbd83bc671c62fd1333ae25fd9829112464) Thanks [@firtoz](https://github.com/firtoz)! - Add `createStandaloneCollection` utility for using IndexedDB collections outside of React context.
+
+  Features:
+
+  - Simple API for standalone usage without React providers
+  - Async mutation methods (`insert`, `update`, `delete`, `truncate`) that return Promises
+  - Sync accessors (`getAll`, `get`, `isReady`)
+  - Full access to collection utils (`truncate`, `pushExternalSync`)
+  - Automatic database initialization with migration support
+
+  Also:
+
+  - Update `IndexedDbCollection` type to use `CollectionUtils` instead of generic `UtilsRecord` for proper typing of `truncate` and `pushExternalSync`
+  - Export `IndexedDbCollection` type from package
+
+### Patch Changes
+
+- [`c772c2c`](https://github.com/firtoz/fullstack-toolkit/commit/c772c2cf74af560dc04080933591ccd3014f85a1) Thanks [@firtoz](https://github.com/firtoz)! - Improve types returned and simplify internal logic
+
 ## 0.4.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-indexeddb",
-	"version": "0.4.3",
+	"version": "0.5.0",
 	"description": "IndexedDB migrations powered by Drizzle ORM",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",

package/src/collections/indexeddb-collection.ts

@@ -35,10 +35,6 @@ export interface IndexedDBCollectionConfig<TTable extends Table> {
 	 * Ref to the IndexedDB database instance
 	 */
 	indexedDBRef: React.RefObject<IDBDatabaseLike | null>;
-	/**
-	 * The database name (for perf markers)
-	 */
-	dbName: string;
 	/**
 	 * The Drizzle table definition (used for schema and type inference only)
 	 */

package/src/context/DrizzleIndexedDBProvider.tsx

@@ -10,7 +10,6 @@ import {
 import {
 	createCollection,
 	type InferSchemaInput,
-	type UtilsRecord,
 	type Collection,
 	type InferSchemaOutput,
 	type SyncMode,
@@ -26,7 +25,7 @@ import type {
 	SelectSchema,
 	GetTableFromSchema,
 	InferCollectionFromTable,
-	ExternalSyncHandler,
+	CollectionUtils,
 } from "@firtoz/drizzle-utils";
 import {
 	type Migration,
@@ -38,21 +37,21 @@ 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>;
+	collection: Collection<any, string, CollectionUtils<any>, any, any>;
 	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<
+export type IndexedDbCollection<
 	TSchema extends Record<string, unknown>,
 	TTableName extends keyof TSchema & string,
 > = Collection<
 	InferSchemaOutput<SelectSchema<GetTableFromSchema<TSchema, TTableName>>>,
 	IdOf<GetTableFromSchema<TSchema, TTableName>>,
-	UtilsRecord,
+	CollectionUtils<
+		InferSchemaOutput<SelectSchema<GetTableFromSchema<TSchema, TTableName>>>
+	>,
 	SelectSchema<GetTableFromSchema<TSchema, TTableName>>,
 	InferSchemaInput<InsertSchema<GetTableFromSchema<TSchema, TTableName>>>
 >;
@@ -195,7 +194,6 @@ export function DrizzleIndexedDBProvider<
 				// Create collection options
 				const collectionConfig = indexedDBCollectionOptions({
 					indexedDBRef,
-					dbName,
 					table,
 					storeName: actualTableName,
 					readyPromise: readyPromise.promise,
@@ -205,12 +203,14 @@ export function DrizzleIndexedDBProvider<
 
 				// Create new collection and cache it with ref count 0
 				// The collection will wait for readyPromise before accessing the database
-				const collection = createCollection(collectionConfig);
+				// Cast is safe: our collectionConfig provides CollectionUtils, but createCollection types it as UtilsRecord
+				const collection = createCollection(
+					collectionConfig,
+				) as CollectionCacheEntry["collection"];
 
 				collections.set(cacheKey, {
 					collection,
 					refCount: 0,
-					pushExternalSync: collectionConfig.utils.pushExternalSync,
 				});
 			}
 
@@ -218,7 +218,7 @@ export function DrizzleIndexedDBProvider<
 			return collections.get(cacheKey)!
 				.collection as unknown as IndexedDbCollection<TSchema, TTableName>;
 		},
-		[collections, schema, readyPromise.promise, debug, dbName, syncMode],
+		[collections, schema, readyPromise.promise, debug, syncMode],
 	);
 
 	const incrementRefCount: DrizzleIndexedDBContextValue<TSchema>["incrementRefCount"] =
@@ -257,30 +257,31 @@ export function DrizzleIndexedDBProvider<
 					const actualStoreName = getTableName(table as Table);
 					if (actualStoreName === message.storeName) {
 						const entry = collections.get(tableName);
-						if (entry?.pushExternalSync) {
+						if (entry) {
+							const { pushExternalSync } = entry.collection.utils;
 							// Route sync message to collection
 							switch (message.type) {
 								case "sync:add":
-									entry.pushExternalSync({
+									pushExternalSync({
 										type: "insert",
 										items: message.items,
 									});
 									break;
 								case "sync:put":
-									entry.pushExternalSync({
+									pushExternalSync({
 										type: "update",
 										items: message.items,
 									});
 									break;
 								case "sync:delete":
 									// For delete, construct items with id
-									entry.pushExternalSync({
+									pushExternalSync({
 										type: "delete",
 										items: message.keys.map((key) => ({ id: key })),
 									});
 									break;
 								case "sync:clear":
-									entry.pushExternalSync({
+									pushExternalSync({
 										type: "truncate",
 									});
 									break;

package/src/index.ts

@@ -39,12 +39,20 @@ export {
 	type IndexedDBSyncItem,
 } from "./collections/indexeddb-collection";
 
+// Standalone Collection (for use outside React)
+export {
+	createStandaloneCollection,
+	type StandaloneCollection,
+	type StandaloneCollectionConfig,
+} from "./standalone-collection";
+
 // IndexedDB Provider
 export {
 	DrizzleIndexedDBProvider,
 	DrizzleIndexedDBContext,
 	useIndexedDBCollection,
 	type DrizzleIndexedDBContextValue,
+	type IndexedDbCollection,
 } from "./context/DrizzleIndexedDBProvider";
 
 export {

package/src/standalone-collection.ts

@@ -0,0 +1,372 @@
+import {
+	createCollection,
+	type Collection,
+	type InferSchemaInput,
+	type InferSchemaOutput,
+	type SyncMode,
+	type Transaction,
+	type WritableDeep,
+} from "@tanstack/db";
+import type { Table } from "drizzle-orm";
+import type {
+	IdOf,
+	InsertSchema,
+	SelectSchema,
+	CollectionUtils,
+} from "@firtoz/drizzle-utils";
+import {
+	indexedDBCollectionOptions,
+	type IndexedDBCollectionConfig,
+} from "./collections/indexeddb-collection";
+import {
+	migrateIndexedDBWithFunctions,
+	type Migration,
+} from "./function-migrator";
+import { openIndexedDb } from "./idb-operations";
+import type { IDBCreator, IDBDatabaseLike } from "./idb-types";
+
+/**
+ * Configuration for creating a standalone IndexedDB collection
+ */
+export interface StandaloneCollectionConfig<TTable extends Table> {
+	/**
+	 * Name of the IndexedDB database
+	 */
+	dbName: string;
+	/**
+	 * The Drizzle table definition
+	 */
+	table: TTable;
+	/**
+	 * The name of the IndexedDB object store (defaults to table name)
+	 */
+	storeName?: string;
+	/**
+	 * Migrations to apply (optional)
+	 */
+	migrations?: Migration[];
+	/**
+	 * Custom database creator (for testing/mocking)
+	 */
+	dbCreator?: IDBCreator;
+	/**
+	 * Enable debug logging
+	 */
+	debug?: boolean;
+	/**
+	 * Sync mode: 'eager' (immediate) or 'lazy' (on-demand)
+	 */
+	syncMode?: SyncMode;
+}
+
+/**
+ * Type for the underlying collection
+ */
+type InternalCollection<TTable extends Table> = Collection<
+	InferSchemaOutput<SelectSchema<TTable>>,
+	IdOf<TTable>,
+	CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>,
+	SelectSchema<TTable>,
+	InferSchemaInput<InsertSchema<TTable>>
+>;
+
+/**
+ * Transaction type for mutations
+ */
+type MutationTransaction<TTable extends Table> = Transaction<
+	InferSchemaOutput<SelectSchema<TTable>>
+>;
+
+/**
+ * Insert input type (what you pass to insert)
+ */
+type InsertInput<TTable extends Table> = InferSchemaInput<InsertSchema<TTable>>;
+
+/**
+ * Item type (what you get back from getAll, etc.)
+ */
+type ItemType<TTable extends Table> = InferSchemaOutput<SelectSchema<TTable>>;
+
+/**
+ * Writable draft type for update callbacks
+ */
+type DraftType<TTable extends Table> = WritableDeep<InsertInput<TTable>>;
+
+/**
+ * Standalone IndexedDB collection API
+ */
+export interface StandaloneCollection<TTable extends Table> {
+	/**
+	 * Promise that resolves when the collection is ready
+	 */
+	ready: Promise<void>;
+
+	/**
+	 * Check if the collection is ready (sync)
+	 */
+	isReady(): boolean;
+
+	/**
+	 * Get all items (sync - returns current state)
+	 */
+	getAll(): ItemType<TTable>[];
+
+	/**
+	 * Get an item by key (sync)
+	 */
+	get(key: IdOf<TTable>): ItemType<TTable> | undefined;
+
+	/**
+	 * Insert item(s)
+	 * @returns Promise that resolves when persisted
+	 */
+	insert(
+		data: InsertInput<TTable> | InsertInput<TTable>[],
+		callback?: (transaction: MutationTransaction<TTable>) => void,
+	): Promise<MutationTransaction<TTable>>;
+
+	/**
+	 * Update an item by key using a callback that receives a draft
+	 * @returns Promise that resolves when persisted
+	 */
+	update(
+		key: IdOf<TTable>,
+		updater: (draft: DraftType<TTable>) => void,
+		callback?: (transaction: MutationTransaction<TTable>) => void,
+	): Promise<MutationTransaction<TTable>>;
+
+	/**
+	 * Delete item(s) by key
+	 * @returns Promise that resolves when persisted
+	 */
+	delete(
+		key: IdOf<TTable> | IdOf<TTable>[],
+		callback?: (transaction: MutationTransaction<TTable>) => void,
+	): Promise<MutationTransaction<TTable>>;
+
+	/**
+	 * Clear all items from the store
+	 * @returns Promise that resolves when truncate is complete
+	 */
+	truncate(): Promise<void>;
+
+	/**
+	 * Access to collection utils (truncate, pushExternalSync)
+	 */
+	utils: CollectionUtils<ItemType<TTable>>;
+
+	/**
+	 * The underlying TanStack DB collection (for advanced usage)
+	 */
+	collection: InternalCollection<TTable>;
+
+	/**
+	 * The IndexedDB database instance (available after ready)
+	 */
+	db: IDBDatabaseLike | null;
+
+	/**
+	 * Close the database connection
+	 */
+	close(): void;
+}
+
+/**
+ * Create a standalone IndexedDB collection for use outside of React.
+ *
+ * @example
+ * ```ts
+ * const db = await createStandaloneCollection({
+ *   dbName: "myapp.db",
+ *   table: schema.todos,
+ *   migrations,
+ * });
+ *
+ * // Wait for ready
+ * await db.ready;
+ *
+ * // Get all items
+ * const items = db.getAll();
+ *
+ * // Insert
+ * await db.insert({ title: "New todo" });
+ *
+ * // Update
+ * await db.update(itemId, { title: "Updated" });
+ *
+ * // Delete
+ * await db.delete(itemId);
+ *
+ * // Truncate
+ * await db.truncate();
+ *
+ * // Clean up
+ * db.close();
+ * ```
+ */
+export function createStandaloneCollection<TTable extends Table>(
+	config: StandaloneCollectionConfig<TTable>,
+): StandaloneCollection<TTable> {
+	const {
+		dbName,
+		table,
+		storeName = (table as unknown as { _: { name: string } })._.name,
+		migrations = [],
+		dbCreator,
+		debug = false,
+		syncMode = "eager",
+	} = config;
+
+	// Create ready promise
+	let resolveReady: () => void;
+	const readyPromise = new Promise<void>((resolve) => {
+		resolveReady = resolve;
+	});
+
+	// Database ref
+	const indexedDBRef: { current: IDBDatabaseLike | null } = { current: null };
+
+	// Initialize database
+	const initDB = async () => {
+		try {
+			if (migrations.length === 0) {
+				if (debug) {
+					console.log(
+						`[StandaloneCollection] Opening database "${dbName}" directly`,
+					);
+				}
+				indexedDBRef.current = await openIndexedDb(dbName, dbCreator);
+			} else {
+				if (debug) {
+					console.log(`[StandaloneCollection] Migrating database "${dbName}"`);
+				}
+				indexedDBRef.current = await migrateIndexedDBWithFunctions(
+					dbName,
+					migrations,
+					debug,
+					dbCreator,
+				);
+			}
+
+			if (debug) {
+				console.log(`[StandaloneCollection] Database "${dbName}" initialized`);
+			}
+			// biome-ignore lint/style/noNonNullAssertion: resolveReady is set in promise constructor
+			resolveReady!();
+		} catch (error) {
+			console.error(
+				`[StandaloneCollection] Failed to initialize database "${dbName}":`,
+				error,
+			);
+			throw error;
+		}
+	};
+
+	// Start initialization
+	initDB();
+
+	// Create collection config
+	const collectionConfig = indexedDBCollectionOptions({
+		indexedDBRef,
+		table,
+		storeName,
+		readyPromise,
+		debug,
+		syncMode,
+	} as IndexedDBCollectionConfig<TTable>);
+
+	// Create the collection
+	const collection = createCollection(
+		collectionConfig,
+	) as unknown as InternalCollection<TTable>;
+
+	// Wait for collection to be ready
+	const collectionReady = new Promise<void>((resolve) => {
+		if (collection.isReady()) {
+			resolve();
+			return;
+		}
+		collection.preload();
+		collection.onFirstReady(() => resolve());
+	});
+
+	// Combined ready promise
+	const ready = Promise.all([readyPromise, collectionReady]).then(() => {});
+
+	// Helper to wait for transaction to persist
+	const waitForPersist = (
+		// biome-ignore lint/suspicious/noExplicitAny: Transaction types are complex, runtime is correct
+		transaction: any,
+		// biome-ignore lint/suspicious/noExplicitAny: Transaction types are complex, runtime is correct
+		callback?: (transaction: any) => void,
+	): Promise<MutationTransaction<TTable>> => {
+		if (callback) {
+			callback(transaction);
+		}
+		return transaction.isPersisted.promise.then(() => transaction);
+	};
+
+	return {
+		ready,
+
+		isReady(): boolean {
+			return collection.isReady();
+		},
+
+		getAll(): ItemType<TTable>[] {
+			return collection.toArray;
+		},
+
+		get(key: IdOf<TTable>): ItemType<TTable> | undefined {
+			return collection.state.get(key);
+		},
+
+		insert(
+			data: InsertInput<TTable> | InsertInput<TTable>[],
+			callback?: (transaction: MutationTransaction<TTable>) => void,
+		): Promise<MutationTransaction<TTable>> {
+			const items = Array.isArray(data) ? data : [data];
+			// @ts-expect-error - Type inference is complex here but runtime is correct
+			const transaction = collection.insert(...items);
+			return waitForPersist(transaction, callback);
+		},
+
+		update(
+			key: IdOf<TTable>,
+			updater: (draft: DraftType<TTable>) => void,
+			callback?: (transaction: MutationTransaction<TTable>) => void,
+		): Promise<MutationTransaction<TTable>> {
+			const transaction = collection.update(
+				key,
+				updater as (draft: any) => void,
+			);
+			return waitForPersist(transaction, callback);
+		},
+
+		delete(
+			key: IdOf<TTable> | IdOf<TTable>[],
+			callback?: (transaction: MutationTransaction<TTable>) => void,
+		): Promise<MutationTransaction<TTable>> {
+			const keys = Array.isArray(key) ? key : [key];
+			const transaction = collection.delete(keys);
+			return waitForPersist(transaction, callback);
+		},
+
+		truncate(): Promise<void> {
+			return collection.utils.truncate();
+		},
+
+		utils: collection.utils,
+
+		collection,
+
+		get db(): IDBDatabaseLike | null {
+			return indexedDBRef.current;
+		},
+
+		close(): void {
+			indexedDBRef.current?.close();
+			indexedDBRef.current = null;
+		},
+	};
+}