@firtoz/drizzle-indexeddb 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @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
+
+- [`ed6dfce`](https://github.com/firtoz/fullstack-toolkit/commit/ed6dfce75be95d5349381ab43c6c22b25b164414) Thanks [@firtoz](https://github.com/firtoz)! - Enable drizzle and output dir configuration in drizzle-indexeddb-generate
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -385,8 +385,8 @@ bun drizzle-indexeddb-generate --help
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--drizzle-dir <path>` | Path to Drizzle directory | `./drizzle` |
-| `--output-dir <path>` | Path to output directory | `./drizzle/indexeddb-migrations` |
+| `--drizzle-dir <path>`, `-d` | Path to Drizzle directory | `./drizzle` |
+| `--output-dir <path>`, `-o` | Path to output directory | `<drizzle-dir>/indexeddb-migrations` |
 
 ### npm scripts
 
@@ -395,11 +395,13 @@ Add to your `package.json`:
 ```json
 {
   "scripts": {
-    "db:generate": "bun drizzle-kit generate && bun drizzle-indexeddb-generate"
+    "db:generate": "bun --bun drizzle-kit generate && bun drizzle-indexeddb-generate"
   }
 }
 ```
 
+> **Note:** The `--bun` flag forces bun's runtime instead of Node, which is needed because this package exports raw TypeScript. See [Troubleshooting](#err_unsupported_node_modules_type_stripping-error) if you encounter type stripping errors.
+
 ## Advanced Usage
 
 ### Custom Sync Configuration
@@ -666,6 +668,38 @@ Remove from schema and regenerate - the migrator will delete the object store.
 
 ## Troubleshooting
 
+### "ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING" Error
+
+If you see this error when running `drizzle-kit generate`:
+
+```
+Error [ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING]: Stripping types is currently unsupported for files under node_modules
+```
+
+This happens because this package exports raw TypeScript files, and Node's built-in type stripping doesn't work inside `node_modules`.
+
+**Solution:** Use `bun --bun` to force bun's runtime instead of Node:
+
+```bash
+bun --bun drizzle-kit generate
+```
+
+Or in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "db:generate": "bun --bun drizzle-kit generate && bun drizzle-indexeddb-generate"
+  }
+}
+```
+
+**Alternative:** If you're not using bun, use `tsx`:
+
+```bash
+npx tsx node_modules/drizzle-kit/bin.cjs generate --config ./drizzle.config.ts
+```
+
 ### "Primary key structure changed" Error
 
 This happens when you change the primary key of a table. IndexedDB doesn't support changing keyPath after creation.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-indexeddb",
-	"version": "0.4.2",
+	"version": "0.5.0",
 	"description": "IndexedDB migrations powered by Drizzle ORM",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -83,5 +83,8 @@
 		"drizzle-valibot": "^0.4.2",
 		"react": "^19.2.1",
 		"valibot": "^1.2.0"
+	},
+	"dependencies": {
+		"citty": "^0.1.6"
 	}
 }

package/src/bin/generate-migrations.ts

@@ -9,6 +9,7 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { defineCommand, runMain } from "citty";
 import type {
 	JournalEntry,
 	Journal,
@@ -240,49 +241,34 @@ export default migrations;
 }
 
 // CLI entry point
-function main(): void {
-	const args = process.argv.slice(2);
-	const command = args[0];
-
-	if (command === "generate" || command === undefined) {
-		// Parse options
-		const options: GenerateOptions = {};
-
-		for (let i = 1; i < args.length; i++) {
-			const arg = args[i];
-			if (arg === "--drizzle-dir" && args[i + 1]) {
-				options.drizzleDir = args[++i];
-			} else if (arg === "--output-dir" && args[i + 1]) {
-				options.outputDir = args[++i];
-			}
-		}
-
-		generateIndexedDBMigrations(options);
-	} else if (command === "--help" || command === "-h") {
-		console.log(`
-drizzle-indexeddb-generate - Generate IndexedDB migrations from Drizzle schema
-
-Usage:
-  bun drizzle-indexeddb-generate [options]
-
-Options:
-  --drizzle-dir <path>  Path to Drizzle directory (default: ./drizzle)
-  --output-dir <path>   Path to output directory (default: ./drizzle/indexeddb-migrations)
-  -h, --help            Show this help message
-
-Examples:
-  bun drizzle-indexeddb-generate
-  bun drizzle-indexeddb-generate --drizzle-dir ./db/drizzle
-  bun drizzle-indexeddb-generate --output-dir ./src/migrations
-`);
-	} else {
-		console.error(`Unknown command: ${command}`);
-		console.error(`Run 'bun drizzle-indexeddb-generate --help' for usage`);
-		process.exit(1);
-	}
-}
+const main = defineCommand({
+	meta: {
+		name: "drizzle-indexeddb-generate",
+		description: "Generate IndexedDB migrations from Drizzle schema",
+	},
+	args: {
+		drizzleDir: {
+			type: "string",
+			alias: "d",
+			default: "./drizzle",
+			description: "Path to Drizzle directory",
+		},
+		outputDir: {
+			type: "string",
+			alias: "o",
+			description:
+				"Path to output directory (default: <drizzle-dir>/indexeddb-migrations)",
+		},
+	},
+	run({ args }) {
+		generateIndexedDBMigrations({
+			drizzleDir: args.drizzleDir,
+			outputDir: args.outputDir,
+		});
+	},
+});
 
 // Only run CLI when executed directly (not when imported)
 if (import.meta.main) {
-	main();
+	runMain(main);
 }

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