@firtoz/db-helpers 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/db-helpers",
-	"version": "2.0.0",
+	"version": "2.1.0",
 	"description": "TanStack DB helpers and utilities",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -18,7 +18,7 @@
 		"README.md"
 	],
 	"scripts": {
-		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"typecheck": "tsgo --noEmit -p ./tsconfig.json",
 		"test": "bun test",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
@@ -49,12 +49,12 @@
 	},
 	"peerDependencies": {
 		"@standard-schema/spec": ">=1.1.0",
-		"@tanstack/db": ">=0.5.33"
+		"@tanstack/db": ">=0.6.1"
 	},
 	"devDependencies": {
 		"@standard-schema/spec": "^1.1.0",
-		"@tanstack/db": "^0.5.33",
-		"bun-types": "^1.3.10",
+		"@tanstack/db": "^0.6.1",
+		"bun-types": "^1.3.11",
 		"zod": "^4.3.6"
 	},
 	"dependencies": {

package/src/deferred-write-queue.ts

@@ -0,0 +1,202 @@
+import type { GenericSyncBackend } from "./generic-sync";
+
+export type DeferredUpdateMutation<TItem extends object> = {
+	key: string;
+	changes: Partial<TItem>;
+	original: TItem;
+};
+
+export type DeferredDeleteMutation<TItem extends object> = {
+	key: string;
+	modified: TItem;
+	original: TItem;
+};
+
+type PendingRow<TItem extends object> =
+	| { kind: "row"; value: TItem; insertedOnly: boolean }
+	| { kind: "delete" };
+
+function mergeUpdate<TItem extends object>(
+	m: DeferredUpdateMutation<TItem>,
+): TItem {
+	return { ...m.original, ...m.changes } as TItem;
+}
+
+/**
+ * Write-behind queue for local mutations: coalesces by persist key and flushes to a
+ * {@link GenericSyncBackend} on an interval or when {@link flush} is called explicitly.
+ */
+export class DeferredWriteQueue<TItem extends object> {
+	readonly #backend: GenericSyncBackend<TItem>;
+	readonly #getPersistKey: (item: TItem) => string;
+	readonly #flushIntervalMs: number;
+	#pending = new Map<string, PendingRow<TItem>>();
+	#intervalId: ReturnType<typeof setInterval> | null = null;
+	#flushTail: Promise<void> = Promise.resolve();
+	#disposed = false;
+
+	constructor(options: {
+		backend: GenericSyncBackend<TItem>;
+		getPersistKey: (item: TItem) => string;
+		flushIntervalMs?: number;
+	}) {
+		this.#backend = options.backend;
+		this.#getPersistKey = options.getPersistKey;
+		this.#flushIntervalMs = options.flushIntervalMs ?? 100;
+
+		if (typeof globalThis !== "undefined") {
+			globalThis.addEventListener?.("beforeunload", this.#onBeforeUnload);
+			globalThis.addEventListener?.(
+				"visibilitychange",
+				this.#onVisibilityChange,
+			);
+		}
+
+		this.#intervalId = setInterval(() => {
+			void this.flush();
+		}, this.#flushIntervalMs);
+	}
+
+	#onBeforeUnload = (): void => {
+		void this.flush();
+	};
+
+	#onVisibilityChange = (): void => {
+		const doc = (
+			globalThis as typeof globalThis & {
+				document?: { visibilityState?: string };
+			}
+		).document;
+		if (doc?.visibilityState === "hidden") {
+			void this.flush();
+		}
+	};
+
+	enqueueInsert(items: TItem[]): void {
+		if (this.#disposed || items.length === 0) return;
+		for (const item of items) {
+			const key = this.#getPersistKey(item);
+			const cur = this.#pending.get(key);
+			if (cur?.kind === "delete") {
+				this.#pending.set(key, {
+					kind: "row",
+					value: item,
+					insertedOnly: true,
+				});
+				continue;
+			}
+			if (cur?.kind === "row" && !cur.insertedOnly) {
+				this.#pending.set(key, {
+					kind: "row",
+					value: item,
+					insertedOnly: false,
+				});
+				continue;
+			}
+			this.#pending.set(key, { kind: "row", value: item, insertedOnly: true });
+		}
+	}
+
+	enqueueUpdate(mutations: DeferredUpdateMutation<TItem>[]): void {
+		if (this.#disposed || mutations.length === 0) return;
+		for (const m of mutations) {
+			const key = m.key;
+			const value = mergeUpdate(m);
+			const cur = this.#pending.get(key);
+			if (cur?.kind === "delete") {
+				this.#pending.set(key, { kind: "row", value, insertedOnly: false });
+				continue;
+			}
+			if (cur?.kind === "row") {
+				this.#pending.set(key, {
+					kind: "row",
+					value,
+					insertedOnly: cur.insertedOnly,
+				});
+				continue;
+			}
+			this.#pending.set(key, { kind: "row", value, insertedOnly: false });
+		}
+	}
+
+	enqueueDelete(mutations: DeferredDeleteMutation<TItem>[]): void {
+		if (this.#disposed || mutations.length === 0) return;
+		for (const m of mutations) {
+			this.#pending.set(m.key, { kind: "delete" });
+		}
+	}
+
+	/**
+	 * Drains pending ops into the backend. Serialized so concurrent flushes chain.
+	 */
+	flush(): Promise<void> {
+		this.#flushTail = this.#flushTail
+			.catch(() => {})
+			.then(() => this.#flushImpl());
+		return this.#flushTail;
+	}
+
+	async #flushImpl(): Promise<void> {
+		if (this.#pending.size === 0) return;
+		const entries = [...this.#pending.entries()];
+		this.#pending.clear();
+
+		const deletePayload: DeferredDeleteMutation<TItem>[] = [];
+		const toInsert: TItem[] = [];
+		const toUpsert: TItem[] = [];
+
+		for (const [key, op] of entries) {
+			if (op.kind === "delete") {
+				const id =
+					Number.isFinite(Number(key)) && String(Number(key)) === key
+						? Number(key)
+						: key;
+				const stub = { id } as TItem;
+				deletePayload.push({
+					key,
+					modified: stub,
+					original: stub,
+				});
+			} else if (op.insertedOnly) {
+				toInsert.push(op.value);
+			} else {
+				toUpsert.push(op.value);
+			}
+		}
+
+		if (deletePayload.length > 0) {
+			await this.#backend.handleDelete(deletePayload);
+		}
+		if (toInsert.length > 0) {
+			await this.#backend.handleInsert(toInsert);
+		}
+		if (toUpsert.length > 0) {
+			if (this.#backend.handleBatchPut !== undefined) {
+				await this.#backend.handleBatchPut(toUpsert);
+			} else {
+				await this.#backend.handleUpdate(
+					toUpsert.map((value) => ({
+						key: this.#getPersistKey(value),
+						changes: value as Partial<TItem>,
+						original: value,
+					})),
+				);
+			}
+		}
+	}
+
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		if (this.#intervalId !== null) {
+			clearInterval(this.#intervalId);
+			this.#intervalId = null;
+		}
+		globalThis.removeEventListener?.("beforeunload", this.#onBeforeUnload);
+		globalThis.removeEventListener?.(
+			"visibilitychange",
+			this.#onVisibilityChange,
+		);
+		void this.flush();
+	}
+}

package/src/generic-sync.ts

@@ -1,4 +1,9 @@
-import type { CollectionUtils, SyncMessage } from "./sync-types";
+import type {
+	CollectionUtils,
+	ReceiveSyncDurableOp,
+	SyncMessage,
+} from "./sync-types";
+import { DeferredWriteQueue } from "./deferred-write-queue";
 import { exhaustiveGuard } from "@firtoz/maybe-error";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type {
@@ -20,10 +25,21 @@ export const USE_DEDUPE = false as boolean;
 /**
  * Base configuration for sync lifecycle management (generic, no Drizzle dependency).
  */
-export interface GenericBaseSyncConfig {
+export interface GenericBaseSyncConfig<TItem extends object = object> {
 	readyPromise: Promise<void>;
 	syncMode?: SyncMode;
 	debug?: boolean;
+	/**
+	 * Row key for durable storage when applying {@link CollectionUtils.receiveSync} updates.
+	 * If omitted, `id` on the item (string or number) is used.
+	 */
+	getSyncPersistKey?: (item: TItem) => string;
+	/**
+	 * When set, local `onInsert` / `onUpdate` / `onDelete` confirm TanStack sync state immediately
+	 * and enqueue durable backend writes (coalesced, flushed on an interval). `receiveSync`,
+	 * `loadSubset`, and `truncate` flush the queue first so reads stay consistent.
+	 */
+	deferLocalPersistence?: boolean | { flushIntervalMs?: number };
 }
 
 /**
@@ -48,6 +64,18 @@ export interface GenericSyncBackend<TItem extends object> {
 		}>,
 	) => Promise<void>;
 	handleTruncate?: () => Promise<void>;
+	/**
+	 * When set, {@link CollectionUtils.receiveSync} persists an entire message batch with one call
+	 * (e.g. one SQLite transaction) instead of awaiting {@link handleInsert}/handleUpdate per
+	 * message. TanStack `syncWrite`/`syncTruncate` still run once per message in order.
+	 */
+	applyReceiveSyncDurableWrites?: (
+		ops: ReceiveSyncDurableOp<TItem>[],
+	) => Promise<void>;
+	/**
+	 * Optional batch upsert for deferred local persistence flushes (e.g. IndexedDB `put` in one tx).
+	 */
+	handleBatchPut?: (items: Array<TItem>) => Promise<void>;
 }
 
 /**
@@ -81,7 +109,7 @@ export type GenericSyncFunctionResult<TItem extends object> = {
  * Generic version -- no Drizzle dependency.
  */
 export function createGenericSyncFunction<TItem extends object>(
-	config: GenericBaseSyncConfig,
+	config: GenericBaseSyncConfig<TItem>,
 	backend: GenericSyncBackend<TItem>,
 ): GenericSyncFunctionResult<TItem> {
 	type CollectionType = CollectionConfig<
@@ -101,6 +129,57 @@ export function createGenericSyncFunction<TItem extends object>(
 		| null = null;
 	let syncCommit: (() => void) | null = null;
 	let syncTruncate: (() => void) | null = null;
+	/** Resolves when eager `initialSync` has finished (or immediately in on-demand mode). Used so `receiveSync` cannot interleave with initial inserts. */
+	let initialSyncDone: Promise<void> | null = null;
+	/**
+	 * TanStack DB allows only one pending sync transaction per collection. Every path that calls
+	 * `begin`/`commit` — `initialSync`, `loadSubset`, `onInsert`/`onUpdate`/`onDelete`, `receiveSync`,
+	 * and `truncate` — must run through this queue so async backends (e.g. SQLite WASM) cannot
+	 * leave a transaction open across an `await` while another path starts a second transaction.
+	 */
+	let syncLayerSerial: Promise<void> = Promise.resolve();
+
+	const enqueueSyncLayer = (run: () => void | Promise<void>): Promise<void> => {
+		const next = syncLayerSerial.catch(() => {}).then(run);
+		syncLayerSerial = next;
+		return next;
+	};
+
+	function resolveDeferLocalPersistence(
+		opts: GenericBaseSyncConfig<TItem>["deferLocalPersistence"],
+	): { enabled: boolean; flushIntervalMs: number } {
+		if (opts === true) return { enabled: true, flushIntervalMs: 100 };
+		if (typeof opts === "object" && opts !== null) {
+			return { enabled: true, flushIntervalMs: opts.flushIntervalMs ?? 100 };
+		}
+		return { enabled: false, flushIntervalMs: 100 };
+	}
+
+	const deferOpts = resolveDeferLocalPersistence(config.deferLocalPersistence);
+
+	const resolveDeferredPersistKey = (item: TItem): string => {
+		if (config.getSyncPersistKey !== undefined) {
+			return config.getSyncPersistKey(item);
+		}
+		if (item !== null && typeof item === "object" && "id" in item) {
+			const id = (item as { id: unknown }).id;
+			if (typeof id === "string" || typeof id === "number") {
+				return String(id);
+			}
+		}
+		throw new Error(
+			"[deferLocalPersistence] Persist key missing: set GenericBaseSyncConfig.getSyncPersistKey or use items with string/number `id`",
+		);
+	};
+
+	let deferQueue: DeferredWriteQueue<TItem> | null = null;
+	if (deferOpts.enabled) {
+		deferQueue = new DeferredWriteQueue({
+			backend,
+			getPersistKey: resolveDeferredPersistKey,
+			flushIntervalMs: deferOpts.flushIntervalMs,
+		});
+	}
 
 	const syncFn: SyncConfig<TItem, string>["sync"] = (params) => {
 		const { begin, write, commit, markReady, truncate } = params;
@@ -111,88 +190,156 @@ export function createGenericSyncFunction<TItem extends object>(
 		syncTruncate = truncate;
 
 		const initialSync = async () => {
-			await config.readyPromise;
+			await enqueueSyncLayer(async () => {
+				await config.readyPromise;
 
-			try {
-				const items = await backend.initialLoad();
+				try {
+					const items = await backend.initialLoad();
 
-				begin();
+					begin();
 
-				for (const item of items) {
-					write({
-						type: "insert",
-						value: item,
-					});
-				}
+					for (const item of items) {
+						write({
+							type: "insert",
+							value: item,
+						});
+					}
 
-				commit();
-			} finally {
-				markReady();
-			}
+					commit();
+				} finally {
+					markReady();
+				}
+			});
 		};
 
 		if (config.syncMode === "eager" || !config.syncMode) {
-			initialSync();
+			initialSyncDone = initialSync();
 		} else {
 			markReady();
+			initialSyncDone = Promise.resolve();
 		}
 
 		insertListener = async (params) => {
-			const results = await backend.handleInsert(
-				params.transaction.mutations.map((m) => m.modified),
-			);
-
-			begin();
-			for (const result of results) {
-				write({
-					type: "insert",
-					value: result,
-				});
-			}
-			commit();
+			await enqueueSyncLayer(async () => {
+				const items = params.transaction.mutations.map((m) => m.modified);
+				if (deferQueue !== null) {
+					begin();
+					for (const item of items) {
+						write({
+							type: "insert",
+							value: item,
+						});
+					}
+					commit();
+					deferQueue.enqueueInsert(items);
+					return;
+				}
+
+				const results = await backend.handleInsert(items);
+
+				begin();
+				for (const result of results) {
+					write({
+						type: "insert",
+						value: result,
+					});
+				}
+				commit();
+			});
 		};
 
 		updateListener = async (params) => {
-			const results = await backend.handleUpdate(params.transaction.mutations);
-
-			begin();
-			for (const result of results) {
-				write({
-					type: "update",
-					value: result,
-				});
-			}
-			commit();
+			await enqueueSyncLayer(async () => {
+				if (deferQueue !== null) {
+					const mutations = params.transaction.mutations.map((m) => ({
+						key: String(m.key),
+						changes: m.changes as Partial<TItem>,
+						original: m.original as TItem,
+					}));
+					const results = mutations.map(
+						(m) => ({ ...m.original, ...m.changes }) as TItem,
+					);
+					begin();
+					for (const result of results) {
+						write({
+							type: "update",
+							value: result,
+						});
+					}
+					commit();
+					deferQueue.enqueueUpdate(mutations);
+					return;
+				}
+
+				const results = await backend.handleUpdate(
+					params.transaction.mutations,
+				);
+
+				begin();
+				for (const result of results) {
+					write({
+						type: "update",
+						value: result,
+					});
+				}
+				commit();
+			});
 		};
 
 		deleteListener = async (params) => {
-			await backend.handleDelete(params.transaction.mutations);
-
-			begin();
-			for (const item of params.transaction.mutations) {
-				write({
-					type: "delete",
-					value: item.modified,
-				});
-			}
-			commit();
+			await enqueueSyncLayer(async () => {
+				if (deferQueue !== null) {
+					const mutations = params.transaction.mutations.map((m) => ({
+						key: String(m.key),
+						modified: m.modified as TItem,
+						original: m.original as TItem,
+					}));
+					begin();
+					for (const item of mutations) {
+						write({
+							type: "delete",
+							value: item.modified,
+						});
+					}
+					commit();
+					deferQueue.enqueueDelete(mutations);
+					return;
+				}
+
+				await backend.handleDelete(params.transaction.mutations);
+
+				begin();
+				for (const item of params.transaction.mutations) {
+					write({
+						type: "delete",
+						value: item.modified,
+					});
+				}
+				commit();
+			});
 		};
 
 		const loadSubset = async (options: LoadSubsetOptions) => {
-			await config.readyPromise;
+			await enqueueSyncLayer(async () => {
+				await config.readyPromise;
 
-			const items = await backend.loadSubset(options);
+				if (deferQueue !== null) {
+					await deferQueue.flush();
+				}
 
-			begin();
+				const items = await backend.loadSubset(options);
 
-			for (const item of items) {
-				write({
-					type: "insert",
-					value: item,
-				});
-			}
+				begin();
+
+				for (const item of items) {
+					write({
+						type: "insert",
+						value: item,
+					});
+				}
 
-			commit();
+				commit();
+			});
 		};
 
 		let loadSubsetDedupe: DeduplicatedLoadSubset | null = null;
@@ -204,6 +351,8 @@ export function createGenericSyncFunction<TItem extends object>(
 
 		return {
 			cleanup: () => {
+				deferQueue?.dispose();
+				deferQueue = null;
 				insertListener = undefined;
 				updateListener = undefined;
 				deleteListener = undefined;
@@ -213,45 +362,179 @@ export function createGenericSyncFunction<TItem extends object>(
 		} satisfies SyncConfigRes;
 	};
 
-	const receiveSync = async (messages: SyncMessage<TItem>[]) => {
-		if (messages.length === 0) return;
-		if (!syncBegin || !syncWrite || !syncCommit || !syncTruncate) {
-			if (config.debug) {
-				console.warn(
-					"[receiveSync] Sync functions not initialized yet - messages will be dropped",
-					messages.length,
-				);
+	const resolveReceiveSyncPersistKey = (item: TItem): string => {
+		if (config.getSyncPersistKey !== undefined) {
+			return config.getSyncPersistKey(item);
+		}
+		if (item !== null && typeof item === "object" && "id" in item) {
+			const id = (item as { id: unknown }).id;
+			if (typeof id === "string" || typeof id === "number") {
+				return String(id);
 			}
-			return;
 		}
-		syncBegin();
+		throw new Error(
+			"[receiveSync] Persist key missing: set GenericBaseSyncConfig.getSyncPersistKey or use items with string/number `id`",
+		);
+	};
+
+	const shallowRecordDiff = (previous: TItem, next: TItem): Partial<TItem> => {
+		const out: Partial<TItem> = {};
+		if (
+			previous !== null &&
+			typeof previous === "object" &&
+			next !== null &&
+			typeof next === "object"
+		) {
+			const prevRec = previous as Record<string, unknown>;
+			const nextRec = next as Record<string, unknown>;
+			for (const k of Object.keys(nextRec)) {
+				if (prevRec[k] !== nextRec[k]) {
+					(out as Record<string, unknown>)[k] = nextRec[k];
+				}
+			}
+		}
+		return out;
+	};
+
+	const toReceiveSyncDurableOps = (
+		messages: SyncMessage<TItem>[],
+	): ReceiveSyncDurableOp<TItem>[] => {
+		const out: ReceiveSyncDurableOp<TItem>[] = [];
 		for (const msg of messages) {
 			switch (msg.type) {
 				case "insert":
-					syncWrite({ type: "insert", value: msg.value });
+					out.push({ type: "insert", value: msg.value });
 					break;
 				case "update":
-					syncWrite({ type: "update", value: msg.value });
+					out.push({
+						type: "update",
+						key: resolveReceiveSyncPersistKey(msg.value),
+						changes: shallowRecordDiff(
+							msg.previousValue,
+							msg.value,
+						) as Partial<TItem>,
+						original: msg.previousValue,
+					});
 					break;
 				case "delete":
-					syncWrite({
-						type: "delete",
-						value: { id: msg.key } as TItem,
-					});
+					out.push({ type: "delete", key: String(msg.key) });
 					break;
 				case "truncate":
-					syncTruncate();
+					out.push({ type: "truncate" });
 					break;
 				default:
 					exhaustiveGuard(msg);
 			}
 		}
-		syncCommit();
+		return out;
+	};
+
+	const receiveSync = async (messages: SyncMessage<TItem>[]) => {
+		if (messages.length === 0) return;
+
+		await enqueueSyncLayer(async () => {
+			if (initialSyncDone) {
+				await initialSyncDone;
+			}
+			if (!syncBegin || !syncWrite || !syncCommit || !syncTruncate) {
+				if (config.debug) {
+					console.warn(
+						"[receiveSync] Sync functions not initialized yet - messages will be dropped",
+						messages.length,
+					);
+				}
+				return;
+			}
+			if (deferQueue !== null) {
+				await deferQueue.flush();
+			}
+			syncBegin();
+
+			try {
+				const applyBatch = backend.applyReceiveSyncDurableWrites;
+				if (applyBatch !== undefined) {
+					await applyBatch(toReceiveSyncDurableOps(messages));
+					for (const msg of messages) {
+						switch (msg.type) {
+							case "insert":
+								syncWrite({ type: "insert", value: msg.value });
+								break;
+							case "update":
+								syncWrite({ type: "update", value: msg.value });
+								break;
+							case "delete":
+								syncWrite({
+									type: "delete",
+									value: { id: msg.key } as TItem,
+								});
+								break;
+							case "truncate":
+								syncTruncate();
+								break;
+							default:
+								exhaustiveGuard(msg);
+						}
+					}
+				} else {
+					for (const msg of messages) {
+						switch (msg.type) {
+							case "insert":
+								await backend.handleInsert([msg.value]);
+								syncWrite({ type: "insert", value: msg.value });
+								break;
+							case "update": {
+								const key = resolveReceiveSyncPersistKey(msg.value);
+								await backend.handleUpdate([
+									{
+										key,
+										changes: shallowRecordDiff(
+											msg.previousValue,
+											msg.value,
+										) as Partial<TItem>,
+										original: msg.previousValue,
+									},
+								]);
+								syncWrite({ type: "update", value: msg.value });
+								break;
+							}
+							case "delete":
+								await backend.handleDelete([
+									{
+										key: String(msg.key),
+										modified: { id: msg.key } as TItem,
+										original: { id: msg.key } as TItem,
+									},
+								]);
+								syncWrite({
+									type: "delete",
+									value: { id: msg.key } as TItem,
+								});
+								break;
+							case "truncate":
+								if (backend.handleTruncate) {
+									await backend.handleTruncate();
+								}
+								syncTruncate();
+								break;
+							default:
+								exhaustiveGuard(msg);
+						}
+					}
+				}
+			} catch (err) {
+				console.error(
+					"[receiveSync] error during sync writes, committing partial batch to avoid leaving transaction open",
+					err,
+				);
+			}
+			syncCommit();
+		});
 	};
 
 	const utils: CollectionUtils<TItem> = {
 		truncate: async () => {
-			if (!backend.handleTruncate) {
+			const handleTruncate = backend.handleTruncate;
+			if (!handleTruncate) {
 				throw new Error("Truncate not supported by this backend");
 			}
 			if (!syncBegin || !syncTruncate || !syncCommit) {
@@ -259,10 +542,23 @@ export function createGenericSyncFunction<TItem extends object>(
 					"Sync functions not initialized - sync function may not have been called yet",
 				);
 			}
-			await backend.handleTruncate();
-			syncBegin();
-			syncTruncate();
-			syncCommit();
+			await enqueueSyncLayer(async () => {
+				if (deferQueue !== null) {
+					await deferQueue.flush();
+				}
+				await handleTruncate();
+				const begin = syncBegin;
+				const trunc = syncTruncate;
+				const commit = syncCommit;
+				if (!begin || !trunc || !commit) {
+					throw new Error(
+						"Sync functions not initialized - sync function may not have been called yet",
+					);
+				}
+				begin();
+				trunc();
+				commit();
+			});
 		},
 		receiveSync,
 	};
@@ -332,8 +628,8 @@ export function createGenericCollectionConfig<
 	CollectionConfig<
 		TItem,
 		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
+		TSchema,
+		CollectionUtils<InferSchemaOutput<TSchema>>
 	>,
 	"utils"
 > & {

package/src/index.ts

@@ -2,6 +2,7 @@ export type {
 	CollectionUtils,
 	ExternalSyncEvent,
 	ExternalSyncHandler,
+	ReceiveSyncDurableOp,
 	SyncMessage,
 } from "./sync-types";
 export {
@@ -20,3 +21,8 @@ export {
 	type GenericSyncBackend,
 	type GenericSyncFunctionResult,
 } from "./generic-sync";
+export {
+	DeferredWriteQueue,
+	type DeferredDeleteMutation,
+	type DeferredUpdateMutation,
+} from "./deferred-write-queue";

package/src/memoryCollection.ts

@@ -46,10 +46,27 @@ export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 	type TItem = InferSchemaOutput<TSchema>;
 	type TKey = string | number;
 	let syncParams: Parameters<SyncConfig<TItem>["sync"]>[0] | null = null;
+	/** Batches from `receiveSync` that arrived before TanStack called `sync`. */
+	const pendingReceiveSyncBatches: SyncMessage<TItem, TKey>[][] = [];
+	/**
+	 * One TanStack sync transaction at a time: `receiveSync`, local mutations, and `truncate` all
+	 * call `begin`/`commit` — overlapping calls cause SyncTransactionAlreadyCommittedWriteError.
+	 */
+	let syncWriteChain: Promise<void> = Promise.resolve();
+
+	const enqueueSyncWrite = async (fn: () => void): Promise<void> => {
+		const next = syncWriteChain.catch(() => {}).then(fn);
+		syncWriteChain = next;
+		await next;
+	};
 
 	const sync: SyncConfig<TItem>["sync"] = (params) => {
 		syncParams = params;
 		params.markReady();
+		for (const batch of pendingReceiveSyncBatches) {
+			writeChanges(batch);
+		}
+		pendingReceiveSyncBatches.length = 0;
 		return () => {};
 	};
 
@@ -88,7 +105,9 @@ export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 		for (const mutation of params.transaction.mutations) {
 			writes.push({ type: "insert", value: mutation.modified });
 		}
-		writeChanges(writes);
+		await enqueueSyncWrite(() => {
+			writeChanges(writes);
+		});
 		config.onBroadcast?.(writes);
 	};
 
@@ -101,7 +120,9 @@ export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 				previousValue: mutation.original,
 			});
 		}
-		writeChanges(writes);
+		await enqueueSyncWrite(() => {
+			writeChanges(writes);
+		});
 		config.onBroadcast?.(writes);
 	};
 
@@ -110,22 +131,36 @@ export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 		for (const mutation of params.transaction.mutations) {
 			writes.push({ type: "delete", key: mutation.key as TKey });
 		}
-		writeChanges(writes);
+		await enqueueSyncWrite(() => {
+			writeChanges(writes);
+		});
 		config.onBroadcast?.(writes);
 	};
 
 	const truncate = async () => {
 		if (!syncParams) {
-			throw new Error("Sync parameters not initialized");
+			// TanStack may not have invoked `sync` yet (e.g. first paint / effect). Nothing to clear.
+			pendingReceiveSyncBatches.length = 0;
+			return;
 		}
-		syncParams.begin();
-		syncParams.truncate();
-		syncParams.commit();
+		await enqueueSyncWrite(() => {
+			const p = syncParams;
+			if (!p) return;
+			p.begin();
+			p.truncate();
+			p.commit();
+		});
 	};
 
 	const receiveSync = async (messages: SyncMessage<TItem, TKey>[]) => {
 		if (messages.length === 0) return;
-		writeChanges(messages);
+		if (!syncParams) {
+			pendingReceiveSyncBatches.push(messages);
+			return;
+		}
+		await enqueueSyncWrite(() => {
+			writeChanges(messages);
+		});
 	};
 
 	return {

package/src/sync-types.ts

@@ -15,6 +15,22 @@ export type SyncMessage<
 	| { type: "delete"; key: TKey }
 	| { type: "truncate" };
 
+/**
+ * Normalized durable ops for a {@link SyncMessage} batch. SQLite-style backends can implement
+ * `GenericSyncBackend.applyReceiveSyncDurableWrites` to persist the whole batch in one store
+ * transaction instead of one transaction per message.
+ */
+export type ReceiveSyncDurableOp<TItem extends object> =
+	| { type: "insert"; value: TItem }
+	| {
+			type: "update";
+			key: string;
+			changes: Partial<TItem>;
+			original: TItem;
+	  }
+	| { type: "delete"; key: string }
+	| { type: "truncate" };
+
 /**
  * External sync event (batched). Used internally by the sync layer.
  */