@firtoz/drizzle-utils 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @firtoz/drizzle-utils
 
+## 1.2.0
+
+### Minor Changes
+
+- [#64](https://github.com/firtoz/fullstack-toolkit/pull/64) [`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f) Thanks [@firtoz](https://github.com/firtoz)! - **`@firtoz/drizzle-utils`:** Export `DrizzleSqliteTableCollection`; extend `BaseSyncConfig` / `createCollectionConfig` for typed `getSyncPersistKey` and `getKey` as `IdOf<TTable>`; avoid executing `syncableTable` default functions during table definition for Worker/DO globals; export collection helper types for Drizzle-backed TanStack collections.
+
+  **`@firtoz/drizzle-indexeddb` (major):** `deferLocalPersistence`, `handleBatchPut`, and related collection options; `receiveSync` persistence aligned with generic sync and partial-sync traffic; remove debug ingest usage. **Breaking** alongside the `@firtoz/drizzle-utils` sync/collection typing changes above (including `DrizzleSqliteTableCollection` and `BaseSyncConfig` expectations).
+
+### Patch Changes
+
+- Updated dependencies [[`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f)]:
+  - @firtoz/db-helpers@2.1.0
+
+## 1.1.0
+
+### Minor 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`.
+
 ## 1.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-utils",
-	"version": "1.0.2",
+	"version": "1.2.0",
 	"description": "Shared utilities and types for Drizzle-based packages",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -25,7 +25,7 @@
 		"CHANGELOG.md"
 	],
 	"scripts": {
-		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"typecheck": "tsgo --noEmit -p ./tsconfig.json",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
 		"format": "biome format src --write"
@@ -53,19 +53,19 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@tanstack/db": ">=0.5.33",
-		"drizzle-orm": ">=0.45.1",
+		"@tanstack/db": ">=0.6.1",
+		"drizzle-orm": ">=0.45.2",
 		"drizzle-valibot": ">=0.4.0",
 		"valibot": ">=1.3.1"
 	},
 	"devDependencies": {
-		"@tanstack/db": "^0.5.33",
-		"drizzle-orm": "^0.45.1",
+		"@tanstack/db": "^0.6.1",
+		"drizzle-orm": "^0.45.2",
 		"drizzle-valibot": "^0.4.2",
 		"valibot": "^1.3.1"
 	},
 	"dependencies": {
-		"@firtoz/db-helpers": "^2.0.0",
+		"@firtoz/db-helpers": "^2.1.0",
 		"@firtoz/maybe-error": "^1.5.2"
 	}
 }

package/src/collection-utils.ts

@@ -66,6 +66,15 @@ export type InsertSchema<TTable extends Table> = BuildSchema<
 	undefined
 >;
 
+/**
+ * Schema type with insert input (optionals for defaults) and select output (all fields present).
+ * Represents the standard input/output pair for collection schemas.
+ */
+export type InsertToSelectSchema<TTable extends Table> = v.GenericSchema<
+	v.InferInput<InsertSchema<TTable>>,
+	v.InferOutput<SelectSchema<TTable>>
+>;
+
 /**
  * Helper type to get the table from schema by name
  */
@@ -82,7 +91,7 @@ export type InferCollectionFromTable<TTable extends Table> = Collection<
 	TTable["$inferSelect"],
 	IdOf<TTable>,
 	UtilsRecord,
-	SelectSchema<TTable>,
+	InsertToSelectSchema<TTable>,
 	Omit<
 		TTable["$inferInsert"],
 		"id"
@@ -99,7 +108,7 @@ export const USE_DEDUPE = _USE_DEDUPE;
  * Extends the generic (Drizzle-free) config with a Drizzle table reference.
  */
 export interface BaseSyncConfig<TTable extends Table>
-	extends GenericBaseSyncConfig {
+	extends GenericBaseSyncConfig<InferSchemaOutput<SelectSchema<TTable>>> {
 	table: TTable;
 }
 
@@ -135,7 +144,7 @@ export function createSyncFunction<TTable extends Table>(
  */
 export function createInsertSchemaWithDefaults<TTable extends Table>(
 	table: TTable,
-): v.GenericSchema<unknown> {
+): InsertToSelectSchema<TTable> {
 	const insertSchema = createInsertSchema(table);
 	const columns = getTableColumns(table);
 
@@ -194,7 +203,7 @@ export function createInsertSchemaWithDefaults<TTable extends Table>(
 
 			return result;
 		}),
-	) as v.GenericSchema<unknown>;
+	) as InsertToSelectSchema<TTable>;
 }
 
 /**
@@ -203,7 +212,7 @@ export function createInsertSchemaWithDefaults<TTable extends Table>(
  */
 export function createInsertSchemaWithIdDefault<TTable extends Table>(
 	table: TTable,
-): v.GenericSchema<unknown> {
+): InsertToSelectSchema<TTable> {
 	const insertSchema = createInsertSchema(table);
 	const columns = getTableColumns(table);
 	const idColumn = columns.id;
@@ -220,17 +229,16 @@ export function createInsertSchemaWithIdDefault<TTable extends Table>(
 
 			return result;
 		}),
-	) as v.GenericSchema<unknown>;
+	) as InsertToSelectSchema<TTable>;
 }
 
 /**
  * Standard getKey function for collections
  */
 export function createGetKeyFunction<TTable extends Table>() {
-	return (item: InferSchemaOutput<SelectSchema<TTable>>) => {
-		const id = (item as { id: string }).id;
-		return id;
-	};
+	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
+	type TKey = IdOf<TTable>;
+	return (item: TItem): TKey => (item as { id: TKey }).id;
 }
 
 /**
@@ -242,33 +250,30 @@ export function createCollectionConfig<
 	TSchema extends v.GenericSchema<unknown>,
 >(config: {
 	schema: TSchema;
-	getKey: (item: InferSchemaOutput<SelectSchema<TTable>>) => string;
+	getKey: (item: InferSchemaOutput<SelectSchema<TTable>>) => IdOf<TTable>;
 	syncResult: SyncFunctionResult<TTable>;
 	onInsert?: CollectionConfig<
 		InferSchemaOutput<SelectSchema<TTable>>,
 		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
+		TSchema
 	>["onInsert"];
 	onUpdate?: CollectionConfig<
 		InferSchemaOutput<SelectSchema<TTable>>,
 		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
+		TSchema
 	>["onUpdate"];
 	onDelete?: CollectionConfig<
 		InferSchemaOutput<SelectSchema<TTable>>,
 		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
+		TSchema
 	>["onDelete"];
 	syncMode?: SyncMode;
 }): Omit<
 	CollectionConfig<
 		InferSchemaOutput<SelectSchema<TTable>>,
-		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
+		IdOf<TTable>,
+		TSchema,
+		CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>
 	>,
 	"utils"
 > & {
@@ -277,17 +282,17 @@ export function createCollectionConfig<
 } {
 	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
 	type ReturnType = Omit<
-		CollectionConfig<
-			TItem,
-			string,
-			// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-			any
-		>,
+		CollectionConfig<TItem, IdOf<TTable>, TSchema, CollectionUtils<TItem>>,
 		"utils"
 	> & {
 		schema: TSchema;
 		utils: CollectionUtils<TItem>;
 	};
 
-	return createGenericCollectionConfig<TItem, TSchema>(config) as ReturnType;
+	const { getKey: getId, ...rest } = config;
+	return createGenericCollectionConfig<TItem, TSchema>({
+		...rest,
+		// Generic sync is typed with string keys; runtime id may be number — same value as Drizzle row id.
+		getKey: (item: TItem) => getId(item) as string,
+	}) as ReturnType;
 }

package/src/drizzle-sqlite-table-collection.ts

@@ -0,0 +1,29 @@
+import type { CollectionUtils } from "@firtoz/db-helpers";
+import type {
+	Collection,
+	InferSchemaInput,
+	InferSchemaOutput,
+} from "@tanstack/db";
+import type {
+	IdOf,
+	InsertToSelectSchema,
+	SelectSchema,
+} from "./collection-utils";
+import type { TableWithRequiredFields } from "./syncableTable";
+
+/**
+ * TanStack {@link Collection} for a syncable Drizzle SQLite table (`syncableTable` columns).
+ *
+ * Shared by `@firtoz/drizzle-sqlite-wasm` (async driver) and `@firtoz/drizzle-durable-sqlite`
+ * (Durable Object sync driver). Import this type from `@firtoz/drizzle-utils` rather than
+ * duplicating it per package.
+ */
+export type DrizzleSqliteTableCollection<
+	TTable extends TableWithRequiredFields,
+> = Collection<
+	InferSchemaOutput<SelectSchema<TTable>>,
+	IdOf<TTable>,
+	CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>,
+	InsertToSelectSchema<TTable>,
+	InferSchemaInput<InsertToSelectSchema<TTable>>
+>;

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
 	IdOf,
 	SelectSchema,
 	InsertSchema,
+	InsertToSelectSchema,
 	GetTableFromSchema,
 	InferCollectionFromTable,
 	BaseSyncConfig,
@@ -47,3 +48,17 @@ export {
 } from "./syncableTable";
 
 export type { TableWithRequiredFields } from "./syncableTable";
+
+export type { DrizzleSqliteTableCollection } from "./drizzle-sqlite-table-collection";
+
+export type {
+	SQLOperation,
+	SQLInterceptor,
+	SqliteDriverMode,
+	SqliteTableSyncBackendConfig,
+} from "./sqlite-table-sync";
+export {
+	convertBasicExpressionToDrizzle,
+	convertOrderByToDrizzle,
+	createSqliteTableSyncBackend,
+} from "./sqlite-table-sync";

package/src/sqlite-table-sync/convert-ir.ts

@@ -0,0 +1,121 @@
+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 { SQLiteColumn } from "drizzle-orm/sqlite-core";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+
+/**
+ * Converts TanStack DB IR BasicExpression to Drizzle SQL expression.
+ */
+export 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 sync backend] 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":
+					return isNull(args[0]);
+				default:
+					throw new Error(`Unsupported function: ${func.name}`);
+			}
+		}
+		default:
+			exhaustiveGuard(expression);
+	}
+}
+
+export 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);
+	});
+}

package/src/sqlite-table-sync/index.ts

@@ -0,0 +1,10 @@
+export type { SQLOperation, SQLInterceptor } from "./types";
+export {
+	convertBasicExpressionToDrizzle,
+	convertOrderByToDrizzle,
+} from "./convert-ir";
+export {
+	createSqliteTableSyncBackend,
+	type SqliteDriverMode,
+	type SqliteTableSyncBackendConfig,
+} from "./sqlite-table-sync-backend";

package/src/sqlite-table-sync/sqlite-table-sync-backend.ts

@@ -0,0 +1,535 @@
+import type { ReceiveSyncDurableOp } from "@firtoz/db-helpers";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { InferSchemaOutput } from "@tanstack/db";
+import { and, eq, getTableColumns, sql, type SQL } from "drizzle-orm";
+import type {
+	SQLiteInsertValue,
+	SQLiteUpdateSetSource,
+} from "drizzle-orm/sqlite-core";
+import type { SelectSchema, SyncBackend } from "../collection-utils";
+import type { TableWithRequiredFields } from "../syncableTable";
+import {
+	convertBasicExpressionToDrizzle,
+	convertOrderByToDrizzle,
+} from "./convert-ir";
+import type { SQLInterceptor } from "./types";
+
+export type SqliteDriverMode = "async" | "sync";
+
+/**
+ * `ON CONFLICT DO UPDATE` set map using SQLite `excluded.*` so inserts are idempotent
+ * (matches IndexedDB `put` / replayed partial-sync rows already present from `initialLoad`).
+ */
+function sqliteExcludedUpsertSet<TTable extends TableWithRequiredFields>(
+	table: TTable,
+): SQLiteUpdateSetSource<TTable> {
+	const cols = getTableColumns(table);
+	const set: Record<string, SQL> = {};
+	for (const [jsName, col] of Object.entries(cols)) {
+		if (jsName === "id") continue;
+		set[jsName] = sql.raw(`excluded."${col.name}"`);
+	}
+	return set as SQLiteUpdateSetSource<TTable>;
+}
+
+export interface SqliteTableSyncBackendConfig<
+	TTable extends TableWithRequiredFields,
+> {
+	/** drizzle-orm SQLite database (async WASM/libsql or sync Durable Object) */
+	// biome-ignore lint/suspicious/noExplicitAny: generic over sync/async Drizzle DB shapes
+	drizzle: any;
+	table: TTable;
+	tableName: string;
+	debug?: boolean;
+	checkpoint?: () => Promise<void>;
+	interceptor?: SQLInterceptor;
+	/**
+	 * `async`: libsql/WASM — use `await db.transaction(async (tx) => …)`.
+	 * `sync`: Cloudflare DO SQLite — `transactionSync` requires a **synchronous** callback; use `.all()` / `.run()` on builders inside `tx`.
+	 */
+	driverMode: SqliteDriverMode;
+}
+
+export function createSqliteTableSyncBackend<
+	TTable extends TableWithRequiredFields,
+>(config: SqliteTableSyncBackendConfig<TTable>): SyncBackend<TTable> {
+	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
+	const table = config.table;
+	const driverMode = config.driverMode;
+
+	let transactionQueue = Promise.resolve();
+	const queueTransaction = <T>(
+		_label: string,
+		fn: () => Promise<T>,
+	): Promise<T> => {
+		const run = (): Promise<T> => fn();
+		const result = transactionQueue.then(run, run);
+		transactionQueue = result.then(
+			() => {},
+			() => {},
+		);
+		return result;
+	};
+
+	const backend: SyncBackend<TTable> = {
+		initialLoad: async () => {
+			const items = (await config.drizzle
+				.select()
+				.from(table)) as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
+
+			if (config.interceptor?.onOperation) {
+				config.interceptor.onOperation({
+					type: "select-all",
+					tableName: config.tableName,
+					itemsReturned: items,
+					itemCount: items.length,
+					context: "Initial load (eager mode)",
+					timestamp: Date.now(),
+				});
+			}
+			if (config.interceptor?.onOperation) {
+				config.interceptor.onOperation({
+					type: "write",
+					tableName: config.tableName,
+					itemsWritten: items,
+					writeCount: items.length,
+					context: "Initial load (eager mode)",
+					timestamp: Date.now(),
+				});
+			}
+
+			return items as unknown as InferSchemaOutput<SelectSchema<TTable>>[];
+		},
+
+		loadSubset: async (options) => {
+			let query = config.drizzle.select().from(table).$dynamic();
+
+			let hasWhere = false;
+			if (options.where || options.cursor?.whereFrom) {
+				let drizzleWhere: SQL | undefined;
+
+				if (options.where && options.cursor?.whereFrom) {
+					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);
+			}
+
+			if (options.offset !== undefined && options.offset > 0) {
+				query = query.offset(options.offset);
+			}
+
+			const items = (await query) as unknown as InferSchemaOutput<
+				SelectSchema<TTable>
+			>[];
+
+			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,
+						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,
+						itemsReturned: items,
+						itemCount: items.length,
+						context: contextParts.join(", "),
+						timestamp: Date.now(),
+					});
+				}
+			}
+
+			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,
+					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>>> = [];
+
+			await queueTransaction("handleInsert", async () => {
+				if (driverMode === "sync") {
+					config.drizzle.transaction((tx: typeof config.drizzle) => {
+						for (const itemToInsert of items) {
+							if (config.debug) {
+								console.log(
+									`[${new Date().toISOString()}] insertListener inserting`,
+									itemToInsert,
+								);
+							}
+							const result = tx
+								.insert(table)
+								.values(
+									itemToInsert as unknown as SQLiteInsertValue<typeof table>,
+								)
+								.onConflictDoUpdate({
+									target: table.id,
+									set: sqliteExcludedUpsertSet(table),
+								})
+								.returning()
+								.all() as Array<InferSchemaOutput<SelectSchema<TTable>>>;
+							if (config.debug) {
+								console.log(
+									`[${new Date().toISOString()}] insertListener result`,
+									result,
+								);
+							}
+							if (result.length > 0) {
+								results.push(result[0]);
+							}
+						}
+					});
+				} else {
+					await config.drizzle.transaction(
+						async (tx: typeof config.drizzle) => {
+							for (const itemToInsert of items) {
+								if (config.debug) {
+									console.log(
+										`[${new Date().toISOString()}] insertListener inserting`,
+										itemToInsert,
+									);
+								}
+								const result = (await tx
+									.insert(table)
+									.values(
+										itemToInsert as unknown as SQLiteInsertValue<typeof table>,
+									)
+									.onConflictDoUpdate({
+										target: table.id,
+										set: sqliteExcludedUpsertSet(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]);
+								}
+							}
+						},
+					);
+				}
+
+				if (config.checkpoint) {
+					await config.checkpoint();
+				}
+			});
+
+			return results;
+		},
+
+		handleUpdate: async (mutations) => {
+			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
+
+			await queueTransaction("handleUpdate", async () => {
+				if (driverMode === "sync") {
+					config.drizzle.transaction((tx: typeof config.drizzle) => {
+						for (const mutation of mutations) {
+							if (config.debug) {
+								console.log(
+									`[${new Date().toISOString()}] updateListener updating`,
+									mutation,
+								);
+							}
+							const updateTime = new Date();
+							const result = tx
+								.update(table)
+								.set({
+									...mutation.changes,
+									updatedAt: updateTime,
+								} as SQLiteUpdateSetSource<typeof table>)
+								// biome-ignore lint/suspicious/noExplicitAny: branded id key
+								.where(eq(table.id, mutation.key as any))
+								.returning()
+								.all() as Array<InferSchemaOutput<SelectSchema<TTable>>>;
+							if (config.debug) {
+								console.log(
+									`[${new Date().toISOString()}] updateListener result`,
+									result,
+								);
+							}
+							results.push(...result);
+						}
+					});
+				} else {
+					await config.drizzle.transaction(
+						async (tx: typeof config.drizzle) => {
+							for (const mutation of mutations) {
+								if (config.debug) {
+									console.log(
+										`[${new Date().toISOString()}] updateListener updating`,
+										mutation,
+									);
+								}
+								const updateTime = new Date();
+								const result = (await tx
+									.update(table)
+									.set({
+										...mutation.changes,
+										updatedAt: updateTime,
+									} as SQLiteUpdateSetSource<typeof table>)
+									// biome-ignore lint/suspicious/noExplicitAny: branded id key
+									.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);
+							}
+						},
+					);
+				}
+
+				if (config.checkpoint) {
+					await config.checkpoint();
+				}
+			});
+
+			return results;
+		},
+
+		handleDelete: async (mutations) => {
+			await queueTransaction("handleDelete", async () => {
+				if (driverMode === "sync") {
+					config.drizzle.transaction((tx: typeof config.drizzle) => {
+						for (const mutation of mutations) {
+							tx.delete(table)
+								// biome-ignore lint/suspicious/noExplicitAny: branded id key
+								.where(eq(table.id, mutation.key as any))
+								.run();
+						}
+					});
+				} else {
+					await config.drizzle.transaction(
+						async (tx: typeof config.drizzle) => {
+							for (const mutation of mutations) {
+								await tx
+									.delete(table)
+									// biome-ignore lint/suspicious/noExplicitAny: branded id key
+									.where(eq(table.id, mutation.key as any));
+							}
+						},
+					);
+				}
+
+				if (config.checkpoint) {
+					await config.checkpoint();
+				}
+			});
+		},
+		handleTruncate: async () => {
+			await queueTransaction("handleTruncate", async () => {
+				if (driverMode === "sync") {
+					config.drizzle.transaction((tx: typeof config.drizzle) => {
+						tx.delete(table).run();
+					});
+				} else {
+					await config.drizzle.transaction(
+						async (tx: typeof config.drizzle) => {
+							await tx.delete(table);
+						},
+					);
+				}
+
+				if (config.checkpoint) {
+					await config.checkpoint();
+				}
+			});
+		},
+
+		applyReceiveSyncDurableWrites: async (
+			ops: ReceiveSyncDurableOp<TItem>[],
+		) => {
+			if (ops.length === 0) return;
+
+			await queueTransaction("applyReceiveSyncDurableWrites", async () => {
+				if (driverMode === "sync") {
+					config.drizzle.transaction((tx: typeof config.drizzle) => {
+						for (const op of ops) {
+							switch (op.type) {
+								case "insert": {
+									if (config.debug) {
+										console.log(
+											`[${new Date().toISOString()}] receiveSync batch insert`,
+											op.value,
+										);
+									}
+									tx.insert(table)
+										.values(
+											op.value as unknown as SQLiteInsertValue<typeof table>,
+										)
+										.onConflictDoUpdate({
+											target: table.id,
+											set: sqliteExcludedUpsertSet(table),
+										})
+										.run();
+									break;
+								}
+								case "update": {
+									if (config.debug) {
+										console.log(
+											`[${new Date().toISOString()}] receiveSync batch update`,
+											op,
+										);
+									}
+									const updateTime = new Date();
+									tx.update(table)
+										.set({
+											...op.changes,
+											updatedAt: updateTime,
+										} as SQLiteUpdateSetSource<typeof table>)
+										// biome-ignore lint/suspicious/noExplicitAny: branded id key
+										.where(eq(table.id, op.key as any))
+										.run();
+									break;
+								}
+								case "delete":
+									tx.delete(table)
+										// biome-ignore lint/suspicious/noExplicitAny: branded id key
+										.where(eq(table.id, op.key as any))
+										.run();
+									break;
+								case "truncate":
+									tx.delete(table).run();
+									break;
+								default:
+									exhaustiveGuard(op);
+							}
+						}
+					});
+				} else {
+					await config.drizzle.transaction(
+						async (tx: typeof config.drizzle) => {
+							for (const op of ops) {
+								switch (op.type) {
+									case "insert": {
+										if (config.debug) {
+											console.log(
+												`[${new Date().toISOString()}] receiveSync batch insert`,
+												op.value,
+											);
+										}
+										await tx
+											.insert(table)
+											.values(
+												op.value as unknown as SQLiteInsertValue<typeof table>,
+											)
+											.onConflictDoUpdate({
+												target: table.id,
+												set: sqliteExcludedUpsertSet(table),
+											});
+										break;
+									}
+									case "update": {
+										if (config.debug) {
+											console.log(
+												`[${new Date().toISOString()}] receiveSync batch update`,
+												op,
+											);
+										}
+										const updateTime = new Date();
+										await tx
+											.update(table)
+											.set({
+												...op.changes,
+												updatedAt: updateTime,
+											} as SQLiteUpdateSetSource<typeof table>)
+											// biome-ignore lint/suspicious/noExplicitAny: branded id key
+											.where(eq(table.id, op.key as any));
+										break;
+									}
+									case "delete":
+										await tx
+											.delete(table)
+											// biome-ignore lint/suspicious/noExplicitAny: branded id key
+											.where(eq(table.id, op.key as any));
+										break;
+									case "truncate":
+										await tx.delete(table);
+										break;
+									default:
+										exhaustiveGuard(op);
+								}
+							}
+						},
+					);
+				}
+
+				if (config.checkpoint) {
+					await config.checkpoint();
+				}
+			});
+		},
+	};
+
+	return backend;
+}

package/src/sqlite-table-sync/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Operation tracking for SQLite-backed TanStack sync backends.
+ * Uses discriminated unions so TypeScript can narrow on `type`.
+ */
+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;
+	  }
+	| {
+			type: "raw-query";
+			sql: string;
+			params?: unknown[];
+			method: string;
+			rowCount: number;
+			context: string;
+			timestamp: number;
+	  };
+
+export interface SQLInterceptor {
+	onOperation?: (operation: SQLOperation) => void;
+}

package/src/syncableTable.ts

@@ -75,14 +75,12 @@ export const syncableTable = <
 	for (const columnName in tableColumns) {
 		const column = tableColumns[columnName];
 
-		let defaultValue: unknown | undefined;
+		// Avoid executing defaultFn at module initialization time.
+		// In Cloudflare Workers this can trigger disallowed global-scope APIs.
 		if (column.defaultFn) {
-			defaultValue = column.defaultFn();
-		} else if (column.default !== undefined) {
-			defaultValue = column.default;
+			continue;
 		}
-
-		if (defaultValue instanceof SQL) {
+		if (column.default instanceof SQL) {
 			throw new Error(
 				`Default value for column ${tableName}.${columnName} is a SQL expression, which is not supported for IndexedDB.\n\nYou can use a default value or a default function instead.`,
 			);