@firtoz/drizzle-sqlite-wasm 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @firtoz/drizzle-sqlite-wasm
 
+## 0.2.17
+
+### Patch Changes
+
+- [`8b839f2`](https://github.com/firtoz/fullstack-toolkit/commit/8b839f2227f50409af649aab87178e039aad55dc) Thanks [@firtoz](https://github.com/firtoz)! - Export collection helper types for Drizzle-backed TanStack DB collections so users can declare collection variables with preserved select and insert inference from table schemas.
+
+## 0.2.16
+
+### Patch Changes
+
+- [`b714ebb`](https://github.com/firtoz/fullstack-toolkit/commit/b714ebbb62ec0e3c3aa56c4105e7499fac11d1e5) Thanks [@firtoz](https://github.com/firtoz)! - Extract shared SQLite TanStack sync backend (`createSqliteTableSyncBackend`, IR→Drizzle helpers, `SQLOperation` types) into `@firtoz/drizzle-utils`. Add `@firtoz/drizzle-durable-sqlite` for Durable Object SQLite collections (`durableSqliteCollectionOptions`). Refactor `@firtoz/drizzle-sqlite-wasm` to use the shared backend with `driverMode: "async"`. `durableSqliteCollectionOptions` accepts optional `readyPromise` (defaults to immediate readiness). README documents the class-field Hono pattern, `app.fetch(request, env)` for bindings, optional `on-demand` + `preload` vs eager + `onFirstReady`, and `honoDoFetcherWithName` without a separate exported app type. Restore JSDoc on `DrizzleSqliteCollectionConfig` (`debug`, `checkpoint`, `interceptor`) for editor tooltips. Align `createStandaloneCollection` generics with `InsertToSelectSchema` from `@firtoz/drizzle-utils`.
+
+- Updated dependencies [[`b714ebb`](https://github.com/firtoz/fullstack-toolkit/commit/b714ebbb62ec0e3c3aa56c4105e7499fac11d1e5)]:
+  - @firtoz/drizzle-utils@1.1.0
+
 ## 0.2.15
 
 ### Patch Changes

package/README.md

@@ -227,7 +227,11 @@ Create TanStack DB collections backed by SQLite:
 
 ```typescript
 import { createCollection } from "@tanstack/db";
-import { drizzleCollectionOptions } from "@firtoz/drizzle-sqlite-wasm/drizzleCollectionOptions";
+import {
+	drizzleCollectionOptions,
+	type DrizzleSqliteCollection,
+} from "@firtoz/drizzle-sqlite-wasm";
+import * as schema from "./schema";
 
 const collection = createCollection(
   drizzleCollectionOptions({
@@ -249,12 +253,16 @@ const completed = await collection.find({
   orderBy: { createdAt: "desc" },
 });
 
+type TodosCollection = DrizzleSqliteCollection<typeof schema.todoTable>;
+
 // Subscribe to changes
 collection.subscribe((todos) => {
   console.log("Todos updated:", todos);
 });
 ```
 
+Use `DrizzleSqliteCollection<TTable>` when you want a reusable collection type alias that keeps inferred select/insert types from your table.
+
 ### Collection Options
 
 **Config:**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-sqlite-wasm",
-	"version": "0.2.15",
+	"version": "0.2.17",
 	"description": "Drizzle SQLite WASM bindings",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -70,7 +70,7 @@
 	},
 	"dependencies": {
 		"@firtoz/db-helpers": "^2.0.0",
-		"@firtoz/drizzle-utils": "^1.0.2",
+		"@firtoz/drizzle-utils": "^1.1.0",
 		"@firtoz/maybe-error": "^1.5.2",
 		"@firtoz/worker-helper": "^1.5.1",
 		"@sqlite.org/sqlite-wasm": "^3.51.2-build8",

package/src/collections/sqlite-collection.ts

@@ -1,50 +1,30 @@
 import type {
+	Collection,
+	InferSchemaInput,
 	InferSchemaOutput,
 	SyncMode,
 	CollectionConfig,
 } from "@tanstack/db";
-import type { IR } from "@tanstack/db";
-import {
-	eq,
-	sql,
-	type Table,
-	gt,
-	gte,
-	lt,
-	lte,
-	ne,
-	and,
-	or,
-	not,
-	isNull,
-	isNotNull,
-	like,
-	inArray,
-	asc,
-	desc,
-	type SQL,
-} from "drizzle-orm";
-import {
-	type SQLiteUpdateSetSource,
-	type BaseSQLiteDatabase,
-	type SQLiteInsertValue,
-	SQLiteColumn,
-} from "drizzle-orm/sqlite-core";
+import type { Table } from "drizzle-orm";
+import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
 import type { CollectionUtils } from "@firtoz/db-helpers";
 import type {
 	SelectSchema,
+	InsertToSelectSchema,
 	TableWithRequiredFields,
 	BaseSyncConfig,
-	SyncBackend,
+	IdOf,
 } from "@firtoz/drizzle-utils";
 import {
 	createSyncFunction,
 	createInsertSchemaWithIdDefault,
 	createGetKeyFunction,
 	createCollectionConfig,
+	createSqliteTableSyncBackend,
+	type SQLOperation,
+	type SQLInterceptor,
 } from "@firtoz/drizzle-utils";
-import { exhaustiveGuard } from "@firtoz/maybe-error";
-import type * as v from "valibot";
+export type { SQLOperation, SQLInterceptor };
 
 export type AnyDrizzleDatabase = BaseSQLiteDatabase<
 	"async",
@@ -56,81 +36,7 @@ export type AnyDrizzleDatabase = BaseSQLiteDatabase<
 export type DrizzleSchema<TDrizzle extends AnyDrizzleDatabase> =
 	TDrizzle["_"]["fullSchema"];
 
-/**
- * Operation tracking for SQLite 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 SQLOperation =
-	| {
-			type: "select-all";
-			tableName: string;
-			itemsReturned: unknown[];
-			itemCount: number;
-			context: string;
-			sql?: string;
-			timestamp: number;
-	  }
-	| {
-			type: "select-where";
-			tableName: string;
-			whereClause: string;
-			itemsReturned: unknown[];
-			itemCount: number;
-			context: string;
-			sql?: string;
-			timestamp: number;
-	  }
-	| {
-			type: "write";
-			tableName: string;
-			itemsWritten: unknown[];
-			writeCount: number;
-			context: string;
-			timestamp: number;
-	  }
-	| {
-			type: "insert";
-			tableName: string;
-			item: unknown;
-			sql?: string;
-			timestamp: number;
-	  }
-	| {
-			type: "update";
-			tableName: string;
-			updates: unknown;
-			sql?: string;
-			timestamp: number;
-	  }
-	| {
-			type: "delete";
-			tableName: string;
-			sql?: string;
-			timestamp: number;
-	  }
-	| {
-			/** Raw SQL query executed directly via Drizzle (not through collection) */
-			type: "raw-query";
-			sql: string;
-			params?: unknown[];
-			method: string;
-			rowCount: number;
-			context: string;
-			timestamp: number;
-	  };
-
-/**
- * Interceptor interface for tracking SQLite operations
- * Allows tests and debugging tools to observe what operations are performed
- */
-export interface SQLInterceptor {
-	/** Called when any SQLite operation is performed */
-	onOperation?: (operation: SQLOperation) => void;
-}
-
-export interface DrizzleCollectionConfig<
+export interface DrizzleSqliteCollectionConfig<
 	TDrizzle extends AnyDrizzleDatabase,
 	TTableName extends ValidTableNames<DrizzleSchema<TDrizzle>>,
 > {
@@ -161,427 +67,50 @@ export type ValidTableNames<TSchema extends Record<string, unknown>> = {
 	[K in keyof TSchema]: TSchema[K] extends TableWithRequiredFields ? K : never;
 }[keyof TSchema];
 
-/**
- * Return type for sqliteCollectionOptions - configuration object for creating SQLite collections
- *
- * Note: The third type parameter of CollectionConfig uses `any` to maintain compatibility with
- * TanStack DB's type system, which expects different schema types in different contexts.
- */
 export type SqliteCollectionConfig<TTable extends Table> = Omit<
 	CollectionConfig<
 		InferSchemaOutput<SelectSchema<TTable>>,
-		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Required for TanStack DB type compatibility
-		any
+		IdOf<TTable>,
+		InsertToSelectSchema<TTable>,
+		CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>
 	>,
 	"utils"
 > & {
-	schema: v.GenericSchema<unknown>;
+	schema: InsertToSelectSchema<TTable>;
 	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
 };
 
-/**
- * Converts TanStack DB IR BasicExpression to Drizzle SQL expression
- *
- * Supported operators that TanStack DB pushes down to backend (SUPPORTED_COLLECTION_FUNCS):
- * - eq, gt, lt, gte, lte, and, or, in, isNull, isUndefined, not
- *
- * Additional operators handled for completeness (won't be pushed down in on-demand mode):
- * - ne, isNotNull, like
- */
-function convertBasicExpressionToDrizzle<TTable extends Table>(
-	expression: IR.BasicExpression,
-	table: TTable,
-): SQL {
-	switch (expression.type) {
-		case "ref": {
-			const propRef = expression;
-			const columnName = propRef.path[propRef.path.length - 1];
-			const column = table[columnName as keyof typeof table];
-
-			if (!column || !(column instanceof SQLiteColumn)) {
-				console.error("[SQLite Collection] Column lookup failed:", {
-					columnName,
-					column,
-					tableKeys: Object.keys(table),
-					hasColumn: columnName in table,
-				});
-				throw new Error(`Column ${String(columnName)} not found in table`);
-			}
-
-			return column as unknown as SQL;
-		}
-		case "val": {
-			const value = expression;
-			return sql`${value.value}`;
-		}
-		case "func": {
-			const func = expression;
-			const args = func.args.map((arg) =>
-				convertBasicExpressionToDrizzle(arg, table),
-			);
-
-			switch (func.name) {
-				case "eq":
-					return eq(args[0], args[1]);
-				case "ne":
-					return ne(args[0], args[1]);
-				case "gt":
-					return gt(args[0], args[1]);
-				case "gte":
-					return gte(args[0], args[1]);
-				case "lt":
-					return lt(args[0], args[1]);
-				case "lte":
-					return lte(args[0], args[1]);
-				case "and": {
-					const result = and(...args);
-					if (!result) {
-						throw new Error("Invalid 'and' expression - no arguments provided");
-					}
-					return result;
-				}
-				case "or": {
-					const result = or(...args);
-					if (!result) {
-						throw new Error("Invalid 'or' expression - no arguments provided");
-					}
-					return result;
-				}
-				case "not":
-					return not(args[0]);
-				case "isNull":
-					return isNull(args[0]);
-				case "isNotNull":
-					return isNotNull(args[0]);
-				case "like":
-					return like(args[0], args[1]);
-				case "in":
-					return inArray(args[0], args[1]);
-				case "isUndefined":
-					// isUndefined is same as isNull in SQLite
-					return isNull(args[0]);
-				default:
-					throw new Error(`Unsupported function: ${func.name}`);
-			}
-		}
-		default:
-			exhaustiveGuard(expression);
-	}
-}
-
-/**
- * Converts TanStack DB OrderBy to Drizzle orderBy
- */
-function convertOrderByToDrizzle<TTable extends Table>(
-	orderBy: IR.OrderBy,
-	table: TTable,
-): SQL[] {
-	return orderBy.map((clause) => {
-		const expression = convertBasicExpressionToDrizzle(
-			clause.expression,
-			table,
-		);
-		const direction = clause.compareOptions.direction || "asc";
-
-		return direction === "asc" ? asc(expression) : desc(expression);
-	});
-}
+export type DrizzleSqliteCollection<TTable extends TableWithRequiredFields> =
+	Collection<
+		InferSchemaOutput<SelectSchema<TTable>>,
+		IdOf<TTable>,
+		CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>,
+		InsertToSelectSchema<TTable>,
+		InferSchemaInput<InsertToSelectSchema<TTable>>
+	>;
 
 export function sqliteCollectionOptions<
 	const TDrizzle extends AnyDrizzleDatabase,
 	const TTableName extends string & ValidTableNames<DrizzleSchema<TDrizzle>>,
 	TTable extends DrizzleSchema<TDrizzle>[TTableName] & TableWithRequiredFields,
 >(
-	config: DrizzleCollectionConfig<TDrizzle, TTableName>,
+	config: DrizzleSqliteCollectionConfig<TDrizzle, TTableName>,
 ): SqliteCollectionConfig<TTable> {
 	const tableName = config.tableName as string &
 		ValidTableNames<DrizzleSchema<TDrizzle>>;
 
 	const table = config.drizzle?._.fullSchema[tableName] as TTable;
 
-	// Transaction queue to serialize SQLite transactions (SQLite only supports one transaction at a time)
-	// The queue ensures transactions run sequentially and continues even if one fails
-	let transactionQueue = Promise.resolve();
-	const queueTransaction = <T>(fn: () => Promise<T>): Promise<T> => {
-		// Chain this transaction after the previous one (whether it succeeded or failed)
-		const result = transactionQueue.then(fn, fn);
-		// Update the queue to continue after this transaction completes (success or failure)
-		// This ensures the queue doesn't get stuck if a transaction fails
-		transactionQueue = result.then(
-			() => {}, // Success handler - return undefined to reset queue
-			() => {}, // Error handler - return undefined to reset queue (queue continues)
-		);
-		// Return the actual result so errors propagate to the caller
-		return result;
-	};
-
-	// Create backend-specific implementation
-	const backend: SyncBackend<TTable> = {
-		initialLoad: async () => {
-			const items = (await config.drizzle
-				.select()
-				.from(table)) as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
-
-			// Log SQL operation
-			if (config.interceptor?.onOperation) {
-				config.interceptor.onOperation({
-					type: "select-all",
-					tableName: config.tableName as string,
-					itemsReturned: items,
-					itemCount: items.length,
-					context: "Initial load (eager mode)",
-					timestamp: Date.now(),
-				});
-			}
-
-			// Log write operation
-			if (config.interceptor?.onOperation) {
-				config.interceptor.onOperation({
-					type: "write",
-					tableName: config.tableName as string,
-					itemsWritten: items,
-					writeCount: items.length,
-					context: "Initial load (eager mode)",
-					timestamp: Date.now(),
-				});
-			}
-
-			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
-		},
-
-		loadSubset: async (options) => {
-			// Build the query with optional where, orderBy, limit, and offset
-			// Use $dynamic() to enable dynamic query building
-			let query = config.drizzle.select().from(table).$dynamic();
-
-			// Combine where with cursor expressions if present
-			// The cursor.whereFrom gives us rows after the cursor position
-			let hasWhere = false;
-			if (options.where || options.cursor?.whereFrom) {
-				let drizzleWhere: SQL | undefined;
-
-				if (options.where && options.cursor?.whereFrom) {
-					// Combine main where with cursor expression using AND
-					const mainWhere = convertBasicExpressionToDrizzle(
-						options.where,
-						table,
-					);
-					const cursorWhere = convertBasicExpressionToDrizzle(
-						options.cursor.whereFrom,
-						table,
-					);
-					drizzleWhere = and(mainWhere, cursorWhere);
-				} else if (options.where) {
-					drizzleWhere = convertBasicExpressionToDrizzle(options.where, table);
-				} else if (options.cursor?.whereFrom) {
-					drizzleWhere = convertBasicExpressionToDrizzle(
-						options.cursor.whereFrom,
-						table,
-					);
-				}
-
-				if (drizzleWhere) {
-					query = query.where(drizzleWhere);
-					hasWhere = true;
-				}
-			}
-
-			if (options.orderBy) {
-				const drizzleOrderBy = convertOrderByToDrizzle(options.orderBy, table);
-				query = query.orderBy(...drizzleOrderBy);
-			}
-
-			if (options.limit !== undefined) {
-				query = query.limit(options.limit);
-			}
-
-			// Apply offset for offset-based pagination
-			if (options.offset !== undefined && options.offset > 0) {
-				query = query.offset(options.offset);
-			}
-
-			const items = (await query) as unknown as InferSchemaOutput<
-				SelectSchema<TTable>
-			>[];
-
-			// Log SQL operation
-			if (config.interceptor?.onOperation) {
-				const contextParts: string[] = ["On-demand load"];
-				if (options.orderBy) {
-					contextParts.push("with sorting");
-				}
-				if (options.limit !== undefined) {
-					contextParts.push(`limit ${options.limit}`);
-				}
-				if (options.offset !== undefined && options.offset > 0) {
-					contextParts.push(`offset ${options.offset}`);
-				}
-				if (options.cursor) {
-					contextParts.push("with cursor pagination");
-				}
-
-				if (hasWhere) {
-					config.interceptor.onOperation({
-						type: "select-where",
-						tableName: config.tableName as string,
-						whereClause: "WHERE clause applied",
-						itemsReturned: items,
-						itemCount: items.length,
-						context: contextParts.join(", "),
-						timestamp: Date.now(),
-					});
-				} else {
-					config.interceptor.onOperation({
-						type: "select-all",
-						tableName: config.tableName as string,
-						itemsReturned: items,
-						itemCount: items.length,
-						context: contextParts.join(", "),
-						timestamp: Date.now(),
-					});
-				}
-			}
-
-			// Log write operation
-			if (config.interceptor?.onOperation) {
-				const contextParts: string[] = ["On-demand load"];
-				if (hasWhere) {
-					contextParts.push("with WHERE clause");
-				}
-				if (options.orderBy) {
-					contextParts.push("with sorting");
-				}
-				if (options.limit !== undefined) {
-					contextParts.push(`limit ${options.limit}`);
-				}
-				if (options.offset !== undefined && options.offset > 0) {
-					contextParts.push(`offset ${options.offset}`);
-				}
-
-				config.interceptor.onOperation({
-					type: "write",
-					tableName: config.tableName as string,
-					itemsWritten: items,
-					writeCount: items.length,
-					context: contextParts.join(", "),
-					timestamp: Date.now(),
-				});
-			}
-
-			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
-		},
-
-		handleInsert: async (items) => {
-			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
-
-			// Queue the transaction to serialize SQLite operations
-			await queueTransaction(async () => {
-				await config.drizzle.transaction(async (tx) => {
-					for (const itemToInsert of items) {
-						if (config.debug) {
-							console.log(
-								`[${new Date().toISOString()}] insertListener inserting`,
-								itemToInsert,
-							);
-						}
-
-						const result: Array<InferSchemaOutput<SelectSchema<TTable>>> =
-							(await tx
-								.insert(table)
-								.values(
-									itemToInsert as unknown as SQLiteInsertValue<typeof table>,
-								)
-								.returning()) as Array<InferSchemaOutput<SelectSchema<TTable>>>;
-
-						if (config.debug) {
-							console.log(
-								`[${new Date().toISOString()}] insertListener result`,
-								result,
-							);
-						}
-
-						if (result.length > 0) {
-							results.push(result[0]);
-						}
-					}
-				});
-
-				// Checkpoint to ensure WAL is flushed to main DB file
-				if (config.checkpoint) {
-					await config.checkpoint();
-				}
-			});
-
-			return results;
-		},
-
-		handleUpdate: async (mutations) => {
-			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
-
-			// Queue the transaction to serialize SQLite operations
-			await queueTransaction(async () => {
-				await config.drizzle.transaction(async (tx) => {
-					for (const mutation of mutations) {
-						if (config.debug) {
-							console.log(
-								`[${new Date().toISOString()}] updateListener updating`,
-								mutation,
-							);
-						}
-
-						const updateTime = new Date();
-						const result: Array<InferSchemaOutput<SelectSchema<TTable>>> =
-							(await tx
-								.update(table)
-								.set({
-									...mutation.changes,
-									updatedAt: updateTime,
-								} as SQLiteUpdateSetSource<typeof table>)
-								// biome-ignore lint/suspicious/noExplicitAny: Key is string but table.id is branded type
-								.where(eq(table.id, mutation.key as any))
-								.returning()) as Array<InferSchemaOutput<SelectSchema<TTable>>>;
-
-						if (config.debug) {
-							console.log(
-								`[${new Date().toISOString()}] updateListener result`,
-								result,
-							);
-						}
-
-						results.push(...result);
-					}
-				});
-
-				// Checkpoint to ensure WAL is flushed to main DB file BEFORE UI updates
-				// This ensures persistence before the updateListener completes
-				if (config.checkpoint) {
-					await config.checkpoint();
-				}
-			});
-
-			return results;
-		},
-
-		handleDelete: async (mutations) => {
-			// Queue the transaction to serialize SQLite operations
-			await queueTransaction(async () => {
-				await config.drizzle.transaction(async (tx) => {
-					for (const mutation of mutations) {
-						// biome-ignore lint/suspicious/noExplicitAny: Key is string but table.id is branded type
-						await tx.delete(table).where(eq(table.id, mutation.key as any));
-					}
-				});
-
-				// Checkpoint to ensure WAL is flushed to main DB file
-				if (config.checkpoint) {
-					await config.checkpoint();
-				}
-			});
-		},
-	};
+	const backend = createSqliteTableSyncBackend({
+		drizzle: config.drizzle,
+		table,
+		tableName: config.tableName as string,
+		debug: config.debug,
+		checkpoint: config.checkpoint,
+		interceptor: config.interceptor,
+		driverMode: "async",
+	});
 
-	// Create sync function using shared utilities
 	const baseSyncConfig: BaseSyncConfig<TTable> = {
 		table,
 		readyPromise: config.readyPromise,
@@ -591,11 +120,8 @@ export function sqliteCollectionOptions<
 
 	const syncResult = createSyncFunction(baseSyncConfig, backend);
 
-	// Create insert schema with ID default
-	// (Other defaults like createdAt/updatedAt are handled by SQLite)
 	const schema = createInsertSchemaWithIdDefault(table);
 
-	// Create collection config using shared utilities
 	const collectionConfig = createCollectionConfig({
 		schema,
 		getKey: createGetKeyFunction<TTable>(),
@@ -603,24 +129,21 @@ export function sqliteCollectionOptions<
 		onInsert: config.debug
 			? async (params) => {
 					console.log("onInsert", params);
-					// Call the actual handler from syncResult (always defined in createSyncFunction)
-					// biome-ignore lint/style/noNonNullAssertion: onInsert is always defined in SyncFunctionResult
+					// biome-ignore lint/style/noNonNullAssertion: onInsert is always defined in createSyncFunction
 					await syncResult.onInsert!(params);
 				}
 			: undefined,
 		onUpdate: config.debug
 			? async (params) => {
 					console.log("onUpdate", params);
-					// Call the actual handler from syncResult (always defined in createSyncFunction)
-					// biome-ignore lint/style/noNonNullAssertion: onUpdate is always defined in SyncFunctionResult
+					// biome-ignore lint/style/noNonNullAssertion: onUpdate is always defined in createSyncFunction
 					await syncResult.onUpdate!(params);
 				}
 			: undefined,
 		onDelete: config.debug
 			? async (params) => {
 					console.log("onDelete", params);
-					// Call the actual handler from syncResult (always defined in createSyncFunction)
-					// biome-ignore lint/style/noNonNullAssertion: onDelete is always defined in SyncFunctionResult
+					// biome-ignore lint/style/noNonNullAssertion: onDelete is always defined in createSyncFunction
 					await syncResult.onDelete!(params);
 				}
 			: undefined,

package/src/index.ts

@@ -1,6 +1,8 @@
 export { drizzleSqliteWasm } from "./drizzle/direct";
 export {
 	sqliteCollectionOptions as drizzleCollectionOptions,
+	type DrizzleSqliteCollection,
+	type SqliteCollectionConfig,
 	type SQLOperation,
 	type SQLInterceptor,
 } from "./collections/sqlite-collection";