@firtoz/drizzle-indexeddb 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @firtoz/drizzle-indexeddb
 
+## 0.5.1
+
+### Patch Changes
+
+- [`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0) Thanks [@firtoz](https://github.com/firtoz)! - Add cursor-based and offset-based pagination support to `loadSubset` operations, enabling efficient navigation through large datasets with consistent behavior across collection backends.
+
+- Updated dependencies [[`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0)]:
+  - @firtoz/drizzle-utils@0.3.1
+
+## 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.1",
 	"description": "IndexedDB migrations powered by Drizzle ORM",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -68,20 +68,20 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@firtoz/drizzle-utils": ">=0.3.0",
-		"@tanstack/db": ">=0.5.0",
-		"drizzle-orm": ">=0.44.0",
+		"@firtoz/drizzle-utils": ">=0.3.1",
+		"@tanstack/db": ">=0.5.15",
+		"drizzle-orm": ">=0.45.1",
 		"drizzle-valibot": ">=0.4.0",
-		"react": ">=18.0.0",
+		"react": ">=19.2.3",
 		"valibot": ">=1.0.0"
 	},
 	"devDependencies": {
-		"@firtoz/drizzle-utils": "^0.3.0",
-		"@tanstack/db": "^0.5.11",
+		"@firtoz/drizzle-utils": "^0.3.1",
+		"@tanstack/db": "^0.5.15",
 		"@types/react": "^19.2.7",
-		"drizzle-orm": "^0.45.0",
+		"drizzle-orm": "^0.45.1",
 		"drizzle-valibot": "^0.4.2",
-		"react": "^19.2.1",
+		"react": "^19.2.3",
 		"valibot": "^1.2.0"
 	},
 	"dependencies": {

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)
 	 */
@@ -385,14 +381,30 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 
 			let items: IndexedDBSyncItem[];
 
+			// Combine where with cursor expressions if present
+			// The cursor.whereFrom gives us rows after the cursor position
+			let combinedWhere = options.where;
+			if (options.cursor?.whereFrom) {
+				if (combinedWhere) {
+					// Combine main where with cursor expression using AND
+					combinedWhere = {
+						type: "func",
+						name: "and",
+						args: [combinedWhere, options.cursor.whereFrom],
+					} as IR.Func;
+				} else {
+					combinedWhere = options.cursor.whereFrom;
+				}
+			}
+
 			// Try to use an index for efficient querying
-			const indexedQuery = options.where
-				? tryExtractIndexedQuery(options.where, discoveredIndexes, config.debug)
+			const indexedQuery = combinedWhere
+				? tryExtractIndexedQuery(combinedWhere, discoveredIndexes, config.debug)
 				: null;
 
 			if (indexedQuery) {
 				// Use indexed query for better performance
-
+				// Index returns exact results for single-field queries, no additional filtering needed
 				items = await db.getAllByIndex<IndexedDBSyncItem>(
 					config.storeName,
 					indexedQuery.indexName,
@@ -402,9 +414,9 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 				// Fall back to getting all items
 				items = await db.getAll<IndexedDBSyncItem>(config.storeName);
 
-				// Apply where filter in memory
-				if (options.where) {
-					const whereExpression = options.where;
+				// Apply combined where filter in memory
+				if (combinedWhere) {
+					const whereExpression = combinedWhere;
 					items = items.filter((item) =>
 						evaluateExpression(
 							whereExpression,
@@ -440,6 +452,11 @@ export function indexedDBCollectionOptions<const TTable extends Table>(
 				});
 			}
 
+			// Apply offset (skip first N items for pagination)
+			if (options.offset !== undefined && options.offset > 0) {
+				items = items.slice(options.offset);
+			}
+
 			// Apply limit
 			if (options.limit !== undefined) {
 				items = items.slice(0, options.limit);

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,374 @@
+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`);
+			}
+
+			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 = async (
+		transaction: MutationTransaction<TTable>,
+		callback?: (transaction: MutationTransaction<TTable>) => void,
+	): Promise<MutationTransaction<TTable>> => {
+		if (callback) {
+			callback(transaction);
+		}
+		await transaction.isPersisted.promise;
+		return 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]) as InferSchemaOutput<
+				SelectSchema<TTable>
+			>;
+			const transaction = collection.insert(
+				items,
+			) as MutationTransaction<TTable>;
+			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 MutationTransaction<TTable>;
+			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;
+		},
+	};
+}