@firtoz/drizzle-sqlite-wasm 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @firtoz/drizzle-sqlite-wasm
 
+## 0.2.2
+
+### Patch Changes
+
+- [`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0) Thanks [@firtoz](https://github.com/firtoz)! - Fix critical bug where debug mode prevented database operations from executing. Debug handlers now properly wrap and call the actual backend handlers instead of replacing them.
+
+  Add cursor-based and offset-based pagination support to `loadSubset` operations, enabling efficient navigation through large datasets.
+
+  Add `SQLInterceptor` support to log all SQL queries, including direct Drizzle queries, with the new `createInstrumentedDrizzle` function. This provides comprehensive query visibility for debugging and monitoring.
+
+  Add explicit return type `SqliteCollectionConfig<TTable>` to `sqliteCollectionOptions` function, improving type safety and eliminating the `any` cast at the return statement.
+
+- Updated dependencies [[`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0), [`8abab0a`](https://github.com/firtoz/fullstack-toolkit/commit/8abab0ae7a99320a4254cb128c0fd823726e58e0)]:
+  - @firtoz/maybe-error@1.5.2
+  - @firtoz/drizzle-utils@0.3.1
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [[`46059a2`](https://github.com/firtoz/fullstack-toolkit/commit/46059a28bd0135414b9ed022ffe162a2292adae3)]:
+  - @firtoz/drizzle-utils@0.3.0
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-sqlite-wasm",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "Drizzle SQLite WASM bindings",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -43,9 +43,7 @@
 		"typecheck": "tsc --noEmit -p ./tsconfig.json",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
-		"format": "biome format src --write",
-		"test": "bun test --pass-with-no-tests",
-		"test:watch": "bun test --watch"
+		"format": "biome format src --write"
 	},
 	"keywords": [
 		"typescript",
@@ -71,19 +69,19 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@firtoz/drizzle-utils": "^0.2.0",
-		"@firtoz/maybe-error": "^1.5.1",
+		"@firtoz/drizzle-utils": "^0.3.1",
+		"@firtoz/maybe-error": "^1.5.2",
 		"@firtoz/worker-helper": "^1.0.0",
-		"@sqlite.org/sqlite-wasm": "^3.51.1-build1",
-		"@tanstack/db": "^0.5.0",
-		"drizzle-orm": "^0.44.7",
+		"@sqlite.org/sqlite-wasm": "^3.51.1-build2",
+		"@tanstack/db": "^0.5.15",
+		"drizzle-orm": "^0.45.1",
 		"drizzle-valibot": "^0.4.2",
-		"react": "^19.2.0",
-		"valibot": "^1.1.0",
-		"zod": "^4.1.12"
+		"react": "^19.2.3",
+		"valibot": "^1.2.0",
+		"zod": "^4.2.1"
 	},
 	"devDependencies": {
-		"@standard-schema/spec": "^1.0.0",
-		"@types/react": "^19.2.5"
+		"@standard-schema/spec": "^1.1.0",
+		"@types/react": "^19.2.7"
 	}
 }

package/src/collections/sqlite-collection.ts

@@ -1,4 +1,8 @@
-import type { InferSchemaOutput, SyncMode } from "@tanstack/db";
+import type {
+	InferSchemaOutput,
+	SyncMode,
+	CollectionConfig,
+} from "@tanstack/db";
 import type { IR } from "@tanstack/db";
 import {
 	eq,
@@ -31,6 +35,7 @@ import type {
 	TableWithRequiredFields,
 	BaseSyncConfig,
 	SyncBackend,
+	CollectionUtils,
 } from "@firtoz/drizzle-utils";
 import {
 	createSyncFunction,
@@ -38,6 +43,7 @@ import {
 	createGetKeyFunction,
 	createCollectionConfig,
 } from "@firtoz/drizzle-utils";
+import type * as v from "valibot";
 
 export type AnyDrizzleDatabase = BaseSQLiteDatabase<
 	"async",
@@ -102,6 +108,16 @@ export type SQLOperation =
 			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;
 	  };
 
 /**
@@ -144,6 +160,25 @@ 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
+	>,
+	"utils"
+> & {
+	schema: v.GenericSchema<unknown>;
+	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
+};
+
 /**
  * Converts TanStack DB IR BasicExpression to Drizzle SQL expression
  *
@@ -262,7 +297,9 @@ 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: DrizzleCollectionConfig<TDrizzle, TTableName>,
+): SqliteCollectionConfig<TTable> {
 	const tableName = config.tableName as string &
 		ValidTableNames<DrizzleSchema<TDrizzle>>;
 
@@ -321,19 +358,40 @@ export function sqliteCollectionOptions<
 		},
 
 		loadSubset: async (options, write) => {
-			// Build the query with optional where, orderBy, and limit
+			// 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();
 
-			// Convert TanStack DB IR expressions to Drizzle expressions
+			// Combine where with cursor expressions if present
+			// The cursor.whereFrom gives us rows after the cursor position
 			let hasWhere = false;
-			if (options.where) {
-				const drizzleWhere = convertBasicExpressionToDrizzle(
-					options.where,
-					table,
-				);
-				query = query.where(drizzleWhere);
-				hasWhere = true;
+			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) {
@@ -345,6 +403,11 @@ export function sqliteCollectionOptions<
 				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>
 			>[];
@@ -358,6 +421,12 @@ export function sqliteCollectionOptions<
 				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({
@@ -393,6 +462,9 @@ export function sqliteCollectionOptions<
 				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",
@@ -544,21 +616,29 @@ 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
+					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
+					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
+					await syncResult.onDelete!(params);
 				}
 			: undefined,
 		syncMode: config.syncMode,
 	});
 
-	// biome-ignore lint/suspicious/noExplicitAny: Collection schema type needs to be flexible
-	return collectionConfig as any;
+	return collectionConfig;
 }

package/src/drizzle/worker.ts

@@ -1,6 +1,10 @@
 import type { DrizzleConfig } from "drizzle-orm";
 import { drizzle as drizzleSqliteProxy } from "drizzle-orm/sqlite-proxy";
 import type { ISqliteWorkerClient } from "../worker/client";
+import type {
+	SQLInterceptor,
+	SQLOperation,
+} from "../collections/sqlite-collection";
 
 export const drizzleSqliteWasmWorker = <
 	TSchema extends Record<string, unknown> = Record<string, never>,
@@ -22,3 +26,139 @@ export const drizzleSqliteWasmWorker = <
 		});
 	}, config);
 };
+
+/**
+ * Creates an instrumented Drizzle instance that logs all SQL queries.
+ * This wraps the standard drizzleSqliteWasmWorker to intercept every query.
+ */
+export const createInstrumentedDrizzle = <
+	TSchema extends Record<string, unknown> = Record<string, never>,
+>(
+	client: ISqliteWorkerClient,
+	config: DrizzleConfig<TSchema> = {},
+	interceptor?: SQLInterceptor,
+) => {
+	return drizzleSqliteProxy<TSchema>(async (sql, params, method) => {
+		const startTime = Date.now();
+
+		const result = await new Promise<{ rows: unknown[] }>((resolve, reject) => {
+			client.performRemoteCallback(
+				{
+					sql,
+					params,
+					method,
+				},
+				resolve,
+				reject,
+			);
+		});
+
+		// Log the operation if interceptor is provided
+		if (interceptor?.onOperation) {
+			// Parse SQL to determine context
+			const sqlLower = sql.toLowerCase().trim();
+			let context = "Direct Drizzle query";
+
+			if (sqlLower.startsWith("select")) {
+				// Extract table name from SELECT query
+				const fromMatch = sql.match(/from\s+["']?(\w+)["']?/i);
+				const tableName = fromMatch?.[1] || "unknown";
+
+				// Check for LIMIT/OFFSET - handle both literal values and ? placeholders
+				// Drizzle uses parameterized queries, so we need to check for `limit ?` style
+				const hasLimit = /limit\s+(\d+|\?|\$\d+)/i.test(sql);
+				const hasOffset = /offset\s+(\d+|\?|\$\d+)/i.test(sql);
+				const hasOrderBy = /order\s+by/i.test(sql);
+
+				if (hasLimit || hasOffset) {
+					// Extract actual values from params if using placeholders
+					// Drizzle typically puts LIMIT as second-to-last param, OFFSET as last
+					let limitVal = "?";
+					let offsetVal = "0";
+
+					// Try to extract literal values first
+					const literalLimit = sql.match(/limit\s+(\d+)/i);
+					const literalOffset = sql.match(/offset\s+(\d+)/i);
+
+					if (literalLimit) {
+						limitVal = literalLimit[1];
+					} else if (params && params.length > 0) {
+						// For parameterized queries, try to infer from params
+						// LIMIT/OFFSET are usually at the end
+						if (hasLimit && hasOffset && params.length >= 2) {
+							limitVal = String(params[params.length - 2]);
+							offsetVal = String(params[params.length - 1]);
+						} else if (hasLimit && params.length >= 1) {
+							limitVal = String(params[params.length - 1]);
+						}
+					}
+
+					if (literalOffset) {
+						offsetVal = literalOffset[1];
+					}
+
+					context = `SELECT with LIMIT ${limitVal} OFFSET ${offsetVal}`;
+				} else if (hasOrderBy) {
+					context = `SELECT all from ${tableName} (ordered)`;
+				} else {
+					context = `SELECT all from ${tableName}`;
+				}
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: result.rows?.length ?? 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			} else if (sqlLower.startsWith("insert")) {
+				const intoMatch = sql.match(/into\s+["']?(\w+)["']?/i);
+				context = `INSERT into ${intoMatch?.[1] || "unknown"}`;
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			} else if (sqlLower.startsWith("update")) {
+				const tableMatch = sql.match(/update\s+["']?(\w+)["']?/i);
+				context = `UPDATE ${tableMatch?.[1] || "unknown"}`;
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			} else if (sqlLower.startsWith("delete")) {
+				const fromMatch = sql.match(/from\s+["']?(\w+)["']?/i);
+				context = `DELETE from ${fromMatch?.[1] || "unknown"}`;
+
+				const operation: SQLOperation = {
+					type: "raw-query",
+					sql,
+					params: params as unknown[],
+					method,
+					rowCount: 0,
+					context,
+					timestamp: startTime,
+				};
+				interceptor.onOperation(operation);
+			}
+		}
+
+		return result;
+	}, config);
+};

package/src/hooks/useDrizzleSqliteDb.ts

@@ -3,12 +3,16 @@ import {
 	customSqliteMigrate,
 	type DurableSqliteMigrationConfig,
 } from "@firtoz/drizzle-sqlite-wasm/sqlite-wasm-migrator";
-import { drizzleSqliteWasmWorker } from "@firtoz/drizzle-sqlite-wasm/drizzle-sqlite-wasm-worker";
+import {
+	drizzleSqliteWasmWorker,
+	createInstrumentedDrizzle,
+} from "@firtoz/drizzle-sqlite-wasm/drizzle-sqlite-wasm-worker";
 import type { ISqliteWorkerClient } from "../worker/manager";
 import {
 	initializeSqliteWorker,
 	isSqliteWorkerInitialized,
 } from "../worker/global-manager";
+import type { SQLInterceptor } from "../collections/sqlite-collection";
 
 export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 	WorkerConstructor: new () => Worker,
@@ -16,6 +20,8 @@ export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 	schema: TSchema,
 	migrations: DurableSqliteMigrationConfig,
 	debug?: boolean,
+	/** Optional interceptor to log ALL SQL queries (including direct Drizzle queries) */
+	interceptor?: SQLInterceptor,
 ) => {
 	const resolveRef = useRef<null | (() => void)>(null);
 	const rejectRef = useRef<null | ((error: unknown) => void)>(null);
@@ -72,45 +78,66 @@ export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 		};
 	}, [dbName, WorkerConstructor]);
 
+	// Store interceptor in a ref to avoid recreating drizzle on interceptor changes
+	const interceptorRef = useRef(interceptor);
+	interceptorRef.current = interceptor;
+
 	// Create drizzle instance with a callback-based approach that waits for the client
+	// Use instrumented version if interceptor is provided to log ALL queries
 	const drizzle = useMemo(() => {
 		if (debug) {
 			console.log(`[DEBUG] ${dbName} - creating drizzle proxy wrapper`);
 		}
-		return drizzleSqliteWasmWorker<TSchema>(
-			{
-				performRemoteCallback: (data, resolve, reject) => {
-					const client = sqliteClientRef.current;
-					if (!client) {
-						console.error(
-							`[DEBUG] ${dbName} - performRemoteCallback called but no sqliteClient yet`,
-						);
-						reject(
-							new Error(
-								`Database ${dbName} not ready yet - still initializing`,
-							),
-						);
-						return;
-					}
-					client.performRemoteCallback(data, resolve, reject);
-				},
-				onStarted: (callback) => {
-					const client = sqliteClientRef.current;
-					if (!client) {
-						console.warn(
-							`[DEBUG] ${dbName} - onStarted called but no sqliteClient yet`,
-						);
-						return;
-					}
-					client.onStarted(callback);
-				},
-				terminate: () => {
-					sqliteClientRef.current?.terminate();
-				},
+
+		const client: ISqliteWorkerClient = {
+			performRemoteCallback: (data, resolve, reject) => {
+				const actualClient = sqliteClientRef.current;
+				if (!actualClient) {
+					console.error(
+						`[DEBUG] ${dbName} - performRemoteCallback called but no sqliteClient yet`,
+					);
+					reject(
+						new Error(`Database ${dbName} not ready yet - still initializing`),
+					);
+					return;
+				}
+				actualClient.performRemoteCallback(data, resolve, reject);
+			},
+			onStarted: (callback) => {
+				const actualClient = sqliteClientRef.current;
+				if (!actualClient) {
+					console.warn(
+						`[DEBUG] ${dbName} - onStarted called but no sqliteClient yet`,
+					);
+					return;
+				}
+				actualClient.onStarted(callback);
 			},
-			{ schema },
-		);
-	}, [schema, dbName]); // Using ref for sqliteClient to avoid recreating drizzle
+			terminate: () => {
+				sqliteClientRef.current?.terminate();
+			},
+			checkpoint: () => {
+				return sqliteClientRef.current?.checkpoint() ?? Promise.resolve();
+			},
+		};
+
+		// Use instrumented version if interceptor is provided
+		// Use a wrapper that accesses the ref so interceptor changes don't recreate drizzle
+		const interceptorWrapper: SQLInterceptor = {
+			onOperation: (op) => interceptorRef.current?.onOperation?.(op),
+		};
+
+		// Always use instrumented if initial interceptor was provided
+		if (interceptor) {
+			return createInstrumentedDrizzle<TSchema>(
+				client,
+				{ schema },
+				interceptorWrapper,
+			);
+		}
+
+		return drizzleSqliteWasmWorker<TSchema>(client, { schema });
+	}, [schema, dbName, !!interceptor]); // Only recreate if interceptor presence changes, not on every render
 
 	useEffect(() => {
 		if (!sqliteClient) {