@lsync/client 0.0.2 → 0.0.3

package/dist/index.mjs

@@ -1,7 +1,5 @@
+import { ProtocolError, parseServerMessage, sendClientMessage } from "@lsync/transport";
 import { createCollection } from "@tanstack/db";
-import { createTRPCProxyClient } from "@trpc/client";
-import { parseServerMessage, sendClientRpcRequest } from "@lsync/transport";
-import { observable } from "@trpc/server/observable";
 //#region src/batch.ts
 function createBatch(collection, clientId, transaction) {
 	return { updates: transaction.mutations.map((mutation) => toUpdate(collection, clientId, mutation)) };
@@ -44,42 +42,14 @@ function toChangeMessage(update, existing) {
 	};
 }
 //#endregion
-//#region src/collection-path.ts
-function collectionScope$1(path, params) {
-	return `/${collectionPathSegments(path).map((segment) => segmentValue(segment, params)).map(normalizeSegment$1).join("/")}/`;
-}
-function firstNewPathParam(childPath, parentPath) {
-	if (!childPath) return void 0;
-	const parentParams = new Set(pathParams(parentPath));
-	return pathParams(childPath).find((param) => !parentParams.has(param));
-}
-function collectionPathSegments(path) {
-	return path.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
-}
-function collectionPathParamName(segment) {
-	return segment.match(/^\{([A-Za-z_][A-Za-z0-9_]*)\}$/)?.[1] ?? segment.match(/^:([A-Za-z_][A-Za-z0-9_]*)$/)?.[1];
-}
-function isCollectionPathParam(segment) {
-	return collectionPathParamName(segment) !== void 0;
-}
-function segmentValue(segment, params) {
-	const param = collectionPathParamName(segment);
-	if (!param) return segment;
-	const value = params[param];
-	if (value === void 0) throw new Error(`Missing collection path parameter: ${param}`);
-	return String(value);
-}
-function pathParams(path) {
-	return collectionPathSegments(path).flatMap((segment) => {
-		const param = collectionPathParamName(segment);
-		return param ? [param] : [];
-	});
-}
-function normalizeSegment$1(segment) {
-	return encodeURIComponent(decodeURIComponent(segment));
-}
-//#endregion
 //#region src/client-rpc.ts
+function rejectPending(pending, error) {
+	const requests = [...pending.values()];
+	pending.clear();
+	for (const request of requests) try {
+		request.reject(error);
+	} catch {}
+}
 function takePending(pending, id) {
 	if (id === null || id === void 0) return;
 	const key = String(id);
@@ -87,45 +57,10 @@ function takePending(pending, id) {
 	pending.delete(key);
 	return request;
 }
-function requestForOperation(id, op) {
-	if (op.type === "mutation" && op.path === "push") return {
-		id,
-		method: "mutation",
-		params: {
-			path: "push",
-			input: { json: op.input }
-		}
-	};
-	if (op.type === "query" && op.path === "read") return {
-		id,
-		method: "query",
-		params: {
-			path: "read",
-			input: { json: op.input }
-		}
-	};
-	if (op.type === "query" && op.path === "changes") return {
-		id,
-		method: "query",
-		params: {
-			path: "changes",
-			input: { json: op.input }
-		}
-	};
-	if (op.type === "mutation" && op.path === "api") return {
-		id,
-		method: "mutation",
-		params: {
-			path: "api",
-			input: { json: op.input }
-		}
-	};
-	throw new Error(`Unsupported operation: ${op.type}.${op.path}`);
-}
-function collectionScope(collection) {
-	return `/${collection.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean).map(normalizeSegment).join("/")}/`;
+function collectionScope$1(collection) {
+	return `/${collection.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean).map(normalizeSegment$1).join("/")}/`;
 }
-function normalizeSegment(segment) {
+function normalizeSegment$1(segment) {
 	return encodeURIComponent(decodeURIComponent(segment));
 }
 //#endregion
@@ -137,13 +72,15 @@ var ClientSubscriptions = class {
 		this.controls = controls;
 	}
 	subscribe(collection, listener) {
-		const key = collectionScope(collection);
+		const key = collectionScope$1(collection);
 		let entry = this.subscriptions.get(key);
 		const shouldSubscribe = !entry;
 		if (!entry) {
 			entry = {
 				collection: key,
+				disconnectListeners: /* @__PURE__ */ new Set(),
 				listeners: /* @__PURE__ */ new Set(),
+				reconnectListeners: /* @__PURE__ */ new Set(),
 				ready: Promise.resolve()
 			};
 			this.subscriptions.set(key, entry);
@@ -152,9 +89,20 @@ var ClientSubscriptions = class {
 		if (shouldSubscribe) entry.ready = this.start(entry);
 		return {
 			ready: entry.ready,
+			onDisconnect: (next) => addLifecycleListener(entry.disconnectListeners, next),
+			onReconnect: (next) => addLifecycleListener(entry.reconnectListeners, next),
 			unsubscribe: () => this.unsubscribe(key, listener)
 		};
 	}
+	get hasSubscriptions() {
+		return this.subscriptions.size > 0;
+	}
+	disconnected() {
+		for (const entry of this.subscriptions.values()) for (const listener of entry.disconnectListeners) listener();
+	}
+	reconnected() {
+		for (const entry of this.subscriptions.values()) for (const listener of entry.reconnectListeners) listener();
+	}
 	async replay(ws) {
 		await Promise.all([...this.subscriptions.values()].map((entry) => this.subscribeOnSocket(ws, entry)));
 	}
@@ -162,20 +110,20 @@ var ClientSubscriptions = class {
 		const updatesByCollection = /* @__PURE__ */ new Map();
 		const invalidationsByCollection = /* @__PURE__ */ new Map();
 		for (const update of broadcast.updates) {
-			const collection = collectionScope(update.collection);
+			const collection = collectionScope$1(update.collection);
 			const updates = updatesByCollection.get(collection) ?? [];
 			updates.push(update);
 			updatesByCollection.set(collection, updates);
 		}
 		for (const invalidation of broadcast.invalidations ?? []) {
-			const collection = collectionScope(invalidation.collection);
+			const collection = collectionScope$1(invalidation.collection);
 			const invalidations = invalidationsByCollection.get(collection) ?? [];
 			invalidations.push(invalidation);
 			invalidationsByCollection.set(collection, invalidations);
 		}
 		for (const entry of this.subscriptions.values()) {
-			const updates = updatesByCollection.get(collectionScope(entry.collection));
-			const invalidations = invalidationsByCollection.get(collectionScope(entry.collection));
+			const updates = updatesByCollection.get(collectionScope$1(entry.collection));
+			const invalidations = invalidationsByCollection.get(collectionScope$1(entry.collection));
 			if ((!updates || updates.length === 0) && (!invalidations || invalidations.length === 0)) continue;
 			const scopedBroadcast = {
 				...broadcast,
@@ -190,7 +138,7 @@ var ClientSubscriptions = class {
 		return socket?.readyState === WebSocket.OPEN ? this.subscribeOnSocket(socket, entry) : this.controls.open().then(() => void 0);
 	}
 	async subscribeOnSocket(ws, entry) {
-		if (this.subscriptions.get(collectionScope(entry.collection)) !== entry) return;
+		if (this.subscriptions.get(collectionScope$1(entry.collection)) !== entry) return;
 		entry.collection = (await this.controls.send(ws, "subscribe", entry.collection)).collection;
 	}
 	unsubscribe(key, listener) {
@@ -200,164 +148,472 @@ var ClientSubscriptions = class {
 		if (entry.listeners.size > 0) return;
 		this.subscriptions.delete(key);
 		const socket = this.controls.currentSocket();
-		if (socket?.readyState === WebSocket.OPEN) this.controls.send(socket, "unsubscribe", entry.collection);
+		if (socket?.readyState === WebSocket.OPEN) this.controls.send(socket, "unsubscribe", entry.collection).catch(() => void 0);
 	}
 };
+function addLifecycleListener(listeners, listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
 //#endregion
-//#region src/client.ts
+//#region src/client-reconnect.ts
+var ConnectionClosedError = class extends Error {
+	constructor(message = "Sync WebSocket closed before the request completed") {
+		super(message);
+		this.name = "ConnectionClosedError";
+	}
+};
+var RequestTimeoutError = class extends Error {
+	constructor() {
+		super("Sync RPC request timed out");
+		this.name = "RequestTimeoutError";
+	}
+};
+function reconnectPolicy(option) {
+	const input = typeof option === "object" ? option : {};
+	return {
+		enabled: option !== false,
+		initialDelayMs: input.initialDelayMs ?? 100,
+		maxDelayMs: input.maxDelayMs ?? 5e3,
+		multiplier: input.multiplier ?? 2,
+		maxAttempts: input.maxAttempts ?? 5
+	};
+}
+function reconnectDelay(policy, attempt) {
+	return Math.min(policy.initialDelayMs * policy.multiplier ** attempt, policy.maxDelayMs);
+}
+function wait(delayMs) {
+	return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function retryableMutationError(error) {
+	if (error instanceof ConnectionClosedError || error instanceof RequestTimeoutError) return true;
+	if (typeof error !== "object" || error === null || !("cause" in error)) return false;
+	return retryableMutationError(error.cause);
+}
+//#endregion
+//#region src/client-shared.ts
 const sharedClients = /* @__PURE__ */ new Map();
+function acquireSharedClient(options) {
+	const key = sharedClientKey(options);
+	let entry = sharedClients.get(key);
+	if (!entry) {
+		entry = {
+			client: createClient(options),
+			refs: 0
+		};
+		sharedClients.set(key, entry);
+	}
+	entry.refs += 1;
+	let released = false;
+	const release = () => {
+		if (released) return;
+		released = true;
+		entry.refs -= 1;
+		if (entry.refs === 0 && sharedClients.get(key) === entry) {
+			sharedClients.delete(key);
+			entry.client.close();
+		}
+	};
+	return {
+		client: entry.client,
+		release,
+		[Symbol.dispose]: release
+	};
+}
+function sharedClientKey(options) {
+	const url = new URL(options.url);
+	url.searchParams.delete("clientId");
+	const reconnect = typeof options.reconnect === "object" ? JSON.stringify(options.reconnect) : options.reconnect;
+	return [
+		url,
+		options.clientId,
+		reconnect,
+		options.connectionTimeoutMs,
+		options.requestTimeoutMs
+	].join("\0");
+}
+//#endregion
+//#region src/client.ts
 function createClient(options) {
 	const clientId = options.clientId ?? crypto.randomUUID();
 	const pending = /* @__PURE__ */ new Map();
+	const reconnect = reconnectPolicy(options.reconnect);
+	const connectionTimeoutMs = options.connectionTimeoutMs ?? 1e4;
+	const requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
 	let nextId = 1;
 	let socket;
 	let connectPromise;
+	let reconnectTimer;
+	let closed = false;
+	let hasOpened = false;
 	let subscriptions;
 	const open = async () => {
+		if (closed) throw new ConnectionClosedError("Sync client is closed");
 		if (socket?.readyState === WebSocket.OPEN) return socket;
 		if (connectPromise) return connectPromise;
-		connectPromise = new Promise((resolve, reject) => {
+		const connect = async () => {
+			const attempts = reconnect.enabled ? reconnect.maxAttempts : 1;
+			let lastError;
+			for (let attempt = 0; attempt < attempts; attempt += 1) try {
+				return await connectOnce();
+			} catch (error) {
+				lastError = error;
+				if (attempt + 1 < attempts) await wait(reconnectDelay(reconnect, attempt));
+			}
+			throw lastError;
+		};
+		const connectOnce = () => new Promise((resolve, reject) => {
 			const url = new URL(options.url);
 			url.searchParams.set("clientId", clientId);
 			const ws = new WebSocket(url);
 			ws.binaryType = "arraybuffer";
+			let opened = false;
+			const connectionTimer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`Sync WebSocket connection timed out after ${connectionTimeoutMs}ms`));
+				ws.close();
+			}, connectionTimeoutMs);
 			ws.addEventListener("open", () => {
+				opened = true;
+				clearTimeout(connectionTimer);
 				socket = ws;
 				subscriptions.replay(ws).then(() => {
-					connectPromise = void 0;
+					if (hasOpened) subscriptions.reconnected();
+					hasOpened = true;
 					resolve(ws);
 				}).catch((error) => {
-					connectPromise = void 0;
 					reject(error);
+					ws.close();
 				});
 			});
 			ws.addEventListener("message", (event) => {
 				const message = parseServerMessage(event.data);
-				if ("method" in message) {
-					subscriptions.dispatch(message.params.input.json);
+				if (message.type === "updates") {
+					subscriptions.dispatch(message.payload);
 					return;
 				}
-				if ("error" in message) {
-					const request = takePending(pending, message.id);
-					if (!request) return;
-					request.reject(new Error(message.error.message));
+				if (message.type === "error") {
+					takePending(pending, message.id)?.reject(new ProtocolError(message.error));
 					return;
 				}
-				const request = takePending(pending, message.id);
-				if (!request) return;
-				request.resolve(message.result.data.json);
+				takePending(pending, message.id)?.resolve(message.payload);
 			});
 			ws.addEventListener("close", () => {
-				socket = void 0;
-				connectPromise = void 0;
+				clearTimeout(connectionTimer);
+				if (socket === ws) {
+					socket = void 0;
+					rejectPending(pending, new ConnectionClosedError());
+					subscriptions.disconnected();
+					scheduleReconnect();
+				}
+				if (!opened) reject(/* @__PURE__ */ new Error("Unable to open sync WebSocket"));
 			});
 			ws.addEventListener("error", () => {
+				clearTimeout(connectionTimer);
 				reject(/* @__PURE__ */ new Error("Unable to open sync WebSocket"));
 			});
 		});
+		connectPromise = connect().finally(() => {
+			connectPromise = void 0;
+		});
 		return connectPromise;
 	};
+	function scheduleReconnect() {
+		if (closed || connectPromise || !reconnect.enabled || !subscriptions.hasSubscriptions || reconnectTimer) return;
+		reconnectTimer = setTimeout(() => {
+			reconnectTimer = void 0;
+			open().catch(() => scheduleReconnect());
+		}, reconnect.initialDelayMs);
+	}
 	const sendRequest = (ws, request) => {
 		return new Promise((resolve, reject) => {
 			const id = request.id;
-			if (id === null || id === void 0) {
-				reject(/* @__PURE__ */ new Error("RPC request requires an id"));
-				return;
-			}
+			const timeout = setTimeout(() => {
+				takePending(pending, id)?.reject(new RequestTimeoutError());
+			}, requestTimeoutMs);
 			pending.set(String(id), {
-				resolve: (value) => resolve(value),
-				reject
+				resolve: (value) => {
+					clearTimeout(timeout);
+					resolve(value);
+				},
+				reject: (error) => {
+					clearTimeout(timeout);
+					reject(error);
+				}
 			});
 			try {
-				sendClientRpcRequest(ws, request);
+				sendClientMessage(ws, request);
 			} catch (error) {
-				pending.delete(String(id));
-				reject(error);
+				takePending(pending, id)?.reject(error instanceof Error ? error : new Error(String(error)));
 			}
 		});
 	};
-	const sendSubscriptionControl = async (ws, method, collection) => {
-		const id = String(nextId++);
-		return sendRequest(ws, {
-			id,
-			method,
-			params: { input: { json: { collection } } }
-		});
-	};
+	const sendSubscriptionControl = async (ws, method, collection) => sendRequest(ws, {
+		version: 1,
+		id: String(nextId++),
+		type: method,
+		input: { collection }
+	});
 	subscriptions = new ClientSubscriptions({
 		currentSocket: () => socket,
 		open,
 		send: sendSubscriptionControl
 	});
-	const link = () => {
-		return ({ op }) => observable((observer) => {
-			let cancelled = false;
-			open().then((ws) => {
-				if (cancelled) return;
-				const id = String(nextId++);
-				sendRequest(ws, requestForOperation(id, op)).then((value) => {
-					observer.next({ result: { data: value } });
-					observer.complete();
-				}).catch((error) => observer.error(error));
-			}).catch((error) => observer.error(error));
-			return () => {
-				cancelled = true;
-			};
-		});
-	};
-	const trpc = createTRPCProxyClient({ links: [link] });
+	const sendPush = (batch) => open().then((ws) => sendRequest(ws, {
+		version: 1,
+		id: String(nextId++),
+		type: "push",
+		input: batch
+	}));
 	return {
 		clientId,
-		push: (batch) => trpc.push.mutate(batch),
-		read: (query) => trpc.read.query(query),
-		changes: (query) => trpc.changes.query(query),
-		call: (path, ...args) => {
+		push: async (batch) => {
+			const attempts = reconnect.enabled ? reconnect.maxAttempts : 1;
+			for (let attempt = 0;; attempt += 1) try {
+				return await sendPush(batch);
+			} catch (error) {
+				if (!retryableMutationError(error) || attempt + 1 >= attempts) throw error;
+				await wait(reconnectDelay(reconnect, attempt));
+			}
+		},
+		read: async (query) => {
+			const ws = await open();
+			return sendRequest(ws, {
+				version: 1,
+				id: String(nextId++),
+				type: "read",
+				input: query
+			});
+		},
+		changes: async (query) => {
+			const ws = await open();
+			return sendRequest(ws, {
+				version: 1,
+				id: String(nextId++),
+				type: "changes",
+				input: query
+			});
+		},
+		call: async (path, ...args) => {
 			const [input] = args;
 			const call = input === void 0 ? { path } : {
 				path,
 				input
 			};
-			return trpc.api.mutate(call);
+			const ws = await open();
+			return sendRequest(ws, {
+				version: 1,
+				id: String(nextId++),
+				type: "api",
+				input: call
+			});
 		},
 		subscribe: (collection, listener) => subscriptions.subscribe(collection, listener),
 		close() {
+			closed = true;
+			if (reconnectTimer) clearTimeout(reconnectTimer);
+			rejectPending(pending, new ConnectionClosedError("Sync client was closed"));
 			socket?.close();
 			socket = void 0;
 		}
 	};
 }
-function acquireSharedClient(options) {
-	const key = sharedClientKey(options);
-	let entry = sharedClients.get(key);
-	if (!entry) {
-		entry = {
-			client: createClient({
-				url: options.url,
-				...options.clientId ? { clientId: options.clientId } : {}
-			}),
-			refs: 0
-		};
-		sharedClients.set(key, entry);
+//#endregion
+//#region src/subsets.ts
+var SubsetTracker = class {
+	getKey;
+	subsets = /* @__PURE__ */ new Map();
+	keyRefs = /* @__PURE__ */ new Map();
+	constructor(getKey) {
+		this.getKey = getKey;
 	}
-	entry.refs += 1;
-	let released = false;
-	return {
-		client: entry.client,
-		release() {
-			if (released) return;
-			released = true;
-			entry.refs -= 1;
-			if (entry.refs === 0 && sharedClients.get(key) === entry) {
-				sharedClients.delete(key);
-				entry.client.close();
+	replace(subsetId, rows, filters, predicate) {
+		const previous = this.subsets.get(subsetId);
+		const refs = previous?.refs ?? 0;
+		if (previous) this.releaseKeys(previous.keys);
+		const keys = new Set(rows.map((row) => this.getKey(row)));
+		this.addKeys(keys);
+		this.subsets.set(subsetId, {
+			filters,
+			keys,
+			loaded: true,
+			...predicate ? { predicate } : {},
+			refs
+		});
+		const removed = [];
+		previous?.keys.forEach((key) => {
+			if (!keys.has(key) && !this.keyRefs.has(key)) removed.push(key);
+		});
+		return removed;
+	}
+	retain(subsetId) {
+		const subset = this.subsets.get(subsetId);
+		if (subset) {
+			subset.refs += 1;
+			return { loaded: subset.loaded };
+		}
+		this.subsets.set(subsetId, {
+			filters: [],
+			keys: /* @__PURE__ */ new Set(),
+			loaded: false,
+			refs: 1
+		});
+		return { loaded: false };
+	}
+	trackRow(row) {
+		const result = this.reconcileRow(row);
+		return result.before || result.after;
+	}
+	reconcileRow(row) {
+		const key = this.getKey(row);
+		let before = false;
+		this.subsets.forEach((subset) => {
+			const had = subset.keys.has(key);
+			before ||= had;
+			if (matchesSubset(row, subset)) {
+				if (!had) {
+					subset.keys.add(key);
+					this.keyRefs.set(key, (this.keyRefs.get(key) ?? 0) + 1);
+				}
+				return;
+			}
+			if (had) {
+				subset.keys.delete(key);
+				this.releaseKey(key);
 			}
+		});
+		return {
+			before,
+			after: this.keyRefs.has(key)
+		};
+	}
+	deleteKey(key) {
+		if (!this.keyRefs.has(key)) return false;
+		this.subsets.forEach((subset) => {
+			subset.keys.delete(key);
+		});
+		this.keyRefs.delete(key);
+		return true;
+	}
+	release(subsetId, retain = false) {
+		const subset = this.subsets.get(subsetId);
+		if (!subset) return [];
+		subset.refs -= 1;
+		if (subset.refs > 0) return [];
+		subset.refs = 0;
+		if (retain) return [];
+		return this.expire(subsetId);
+	}
+	expire(subsetId) {
+		const subset = this.subsets.get(subsetId);
+		if (!subset || subset.refs > 0) return [];
+		this.subsets.delete(subsetId);
+		return this.releaseKeys(subset.keys);
+	}
+	clear() {
+		const keys = [...this.keyRefs.keys()];
+		this.subsets.clear();
+		this.keyRefs.clear();
+		return keys;
+	}
+	addKeys(keys) {
+		keys.forEach((key) => {
+			this.keyRefs.set(key, (this.keyRefs.get(key) ?? 0) + 1);
+		});
+	}
+	releaseKeys(keys) {
+		const removed = [];
+		keys.forEach((key) => {
+			if (this.releaseKey(key)) removed.push(key);
+		});
+		return removed;
+	}
+	releaseKey(key) {
+		const refs = (this.keyRefs.get(key) ?? 0) - 1;
+		if (refs <= 0) {
+			this.keyRefs.delete(key);
+			return true;
 		}
-	};
+		this.keyRefs.set(key, refs);
+		return false;
+	}
+};
+function writeRows(collection, rows, getKey, write) {
+	for (const row of rows) {
+		const key = getKey(row);
+		write({
+			type: collection.has(key) ? "update" : "insert",
+			key,
+			value: row
+		});
+	}
 }
-function sharedClientKey(options) {
-	const url = new URL(options.url);
-	url.searchParams.delete("clientId");
-	return `${url.toString()}\0${options.clientId ?? ""}`;
+function matchesFilters(row, filters) {
+	return filters.every((filter) => matchesFilter(row, filter));
+}
+function matchesSubset(row, subset) {
+	return matchesFilters(row, subset.filters) && matchesPredicate(row, subset.predicate);
+}
+function matchesPredicate(row, predicate) {
+	if (!predicate) return true;
+	if (predicate.type === "comparison") return matchesFilter(row, predicate);
+	if (predicate.type === "and") return predicate.predicates.every((child) => matchesPredicate(row, child));
+	return predicate.predicates.some((child) => matchesPredicate(row, child));
+}
+function matchesFilter(row, filter) {
+	const value = valueAtPath(row, filter.field);
+	switch (filter.op) {
+		case "eq": return value === filter.value;
+		case "ne": return value !== filter.value;
+		case "gt": return compareValues(value, filter.value, (left, right) => left > right);
+		case "gte": return compareValues(value, filter.value, (left, right) => left >= right);
+		case "lt": return compareValues(value, filter.value, (left, right) => left < right);
+		case "lte": return compareValues(value, filter.value, (left, right) => left <= right);
+		case "in": return Array.isArray(filter.value) && filter.value.includes(value);
+	}
+	return false;
+}
+function compareValues(left, right, compare) {
+	if (typeof left === "number" && typeof right === "number") return compare(left, right);
+	if (typeof left === "string" && typeof right === "string") return compare(left, right);
+	return false;
+}
+function valueAtPath(row, field) {
+	return field.split(".").reduce((value, segment) => {
+		if (typeof value !== "object" || value === null) return;
+		return value[segment];
+	}, row);
+}
+//#endregion
+//#region src/collection-broadcast.ts
+function applyCollectionBroadcast(options) {
+	if ((options.broadcast.invalidations ?? []).length > 0 && options.syncMode === "on-demand") options.deleteKeys(options.subsets.clear());
+	const changes = options.broadcast.updates.flatMap((update) => {
+		if (collectionScope$1(update.collection) !== collectionScope$1(options.collectionName)) return [];
+		const ownUpdate = update.clientId === options.clientId;
+		if (options.ignoreOwnUpdates && ownUpdate) return [];
+		if (options.syncMode !== "on-demand") return [toChangeMessage(update, options.collection.has(update.key))];
+		const key = update.key;
+		const exists = options.collection.has(key);
+		if (update.type === "delete") {
+			options.subsets.deleteKey(key);
+			return exists ? [{
+				type: "delete",
+				key
+			}] : [];
+		}
+		const current = options.collection.get(key);
+		const row = update.type === "update" && current ? {
+			...current,
+			...update.value
+		} : update.value;
+		const tracked = options.subsets.reconcileRow(row);
+		return ownUpdate || exists || tracked.after ? [toChangeMessage(update, exists)] : [];
+	});
+	if (changes.length === 0) return [];
+	options.begin();
+	for (const change of changes) options.write(change);
+	options.commit();
+	return changes;
 }
 //#endregion
 //#region src/read-query.ts
@@ -507,170 +763,292 @@ function isValExpression(value) {
 	return isExpression(value) && value.type === "val";
 }
 //#endregion
-//#region src/subsets.ts
-var SubsetTracker = class {
-	getKey;
-	subsets = /* @__PURE__ */ new Map();
-	keyRefs = /* @__PURE__ */ new Map();
-	constructor(getKey) {
-		this.getKey = getKey;
-	}
-	replace(subsetId, rows, filters, predicate) {
-		const previous = this.subsets.get(subsetId);
-		const refs = previous?.refs ?? 0;
-		if (previous) this.releaseKeys(previous.keys);
-		const keys = new Set(rows.map((row) => this.getKey(row)));
-		this.addKeys(keys);
-		this.subsets.set(subsetId, {
-			filters,
-			keys,
-			loaded: true,
-			...predicate ? { predicate } : {},
-			refs
+//#region src/initial-sync.ts
+const DEFAULT_MAX_SYNC_ROWS = 1e4;
+const MAX_READ_ROWS = 1e3;
+async function readInitialSyncRows(client, query, maxSyncRows) {
+	if (query.limit !== void 0 || query.cursor) return (await client.read(query)).rows;
+	const maximum = maxSyncRows ?? 1e4;
+	if (maximum !== false && (!Number.isInteger(maximum) || maximum <= 0)) throw new Error("maxSyncRows must be a positive integer or false");
+	const rows = [];
+	const baseOffset = query.offset ?? 0;
+	while (maximum === false || rows.length <= maximum) {
+		const remaining = maximum === false ? MAX_READ_ROWS : maximum + 1 - rows.length;
+		const limit = Math.min(MAX_READ_ROWS, remaining);
+		const page = await client.read({
+			...query,
+			limit,
+			offset: baseOffset + rows.length
 		});
-		const removed = [];
-		previous?.keys.forEach((key) => {
-			if (!keys.has(key) && !this.keyRefs.has(key)) removed.push(key);
+		rows.push(...page.rows);
+		if (page.rows.length < limit) return rows;
+	}
+	throw new Error(`Collection ${query.collection} exceeds the initial sync limit of ${maximum} rows; use syncMode: "on-demand" or maxSyncRows: false`);
+}
+//#endregion
+//#region src/sync-session.ts
+var SyncSession = class {
+	options;
+	buffered = [];
+	cursor = 0;
+	disconnectCleanup;
+	reconnectCleanup;
+	queue = Promise.resolve();
+	subscription;
+	_state = "idle";
+	constructor(options) {
+		this.options = options;
+	}
+	get state() {
+		return this._state;
+	}
+	start() {
+		if (this._state !== "idle") return this.queue;
+		this._state = "subscribing";
+		this.subscription = this.options.client.subscribe(this.options.collection, (broadcast) => {
+			this.receive(broadcast);
 		});
-		return removed;
+		this.disconnectCleanup = this.subscription.onDisconnect?.(() => this.disconnected());
+		this.reconnectCleanup = this.subscription.onReconnect?.(() => this.reconnected());
+		this.queue = this.initialize();
+		return this.queue;
 	}
-	retain(subsetId) {
-		const subset = this.subsets.get(subsetId);
-		if (subset) {
-			subset.refs += 1;
-			return { loaded: subset.loaded };
+	stop() {
+		this._state = "stopped";
+		this.buffered = [];
+		this.disconnectCleanup?.();
+		this.reconnectCleanup?.();
+		this.subscription?.unsubscribe();
+	}
+	async initialize() {
+		if (this.options.hydrate) {
+			await this.options.hydrate();
+			if (this.isStopped()) return;
+			this.options.hydrated?.();
 		}
-		this.subsets.set(subsetId, {
-			filters: [],
-			keys: /* @__PURE__ */ new Set(),
-			loaded: false,
-			refs: 1
-		});
-		return { loaded: false };
+		await this.subscription?.ready;
+		if (this.isStopped()) return;
+		const established = await this.options.client.changes({ collections: {} });
+		this._state = "loading";
+		await this.options.initialize();
+		this.cursor = established.watermark;
+		this.flush();
+		this.markSynchronized();
 	}
-	trackRow(row) {
-		const result = this.reconcileRow(row);
-		return result.before || result.after;
+	receive(broadcast) {
+		if (this._state !== "synchronized") {
+			this.buffered.push(broadcast);
+			return;
+		}
+		this.applyBroadcast(broadcast);
 	}
-	reconcileRow(row) {
-		const key = this.getKey(row);
-		let before = false;
-		this.subsets.forEach((subset) => {
-			const had = subset.keys.has(key);
-			before ||= had;
-			if (matchesSubset(row, subset)) {
-				if (!had) {
-					subset.keys.add(key);
-					this.keyRefs.set(key, (this.keyRefs.get(key) ?? 0) + 1);
-				}
-				return;
-			}
-			if (had) {
-				subset.keys.delete(key);
-				this.releaseKey(key);
+	disconnected() {
+		if (this._state === "stopped") return;
+		this._state = "disconnected";
+	}
+	reconnected() {
+		if (this._state === "stopped") return;
+		this.queue = this.queue.catch(() => void 0).then(() => this.recover());
+	}
+	async recover() {
+		this._state = "catching-up";
+		while (!this.isStopped()) {
+			const result = await this.options.client.changes({
+				collections: { [this.options.collection]: this.cursor },
+				limit: 1e3
+			});
+			if (result.type === "resyncRequired") {
+				this._state = "resyncing";
+				await this.options.resync();
+				this.cursor = result.watermark;
+				break;
 			}
+			if (result.updates.length > 0) this.applyUpdates(result.updates, result.watermark);
+			const nextCursor = result.cursors?.[this.options.collection] ?? visibleCursor(result.updates);
+			if (result.hasMore && nextCursor <= this.cursor) throw new Error(`Sync history cursor did not advance for ${this.options.collection}`);
+			this.cursor = result.hasMore ? Math.max(this.cursor, nextCursor) : Math.max(this.cursor, result.watermark);
+			if (!result.hasMore) break;
+		}
+		if (this.isStopped()) return;
+		this.flush();
+		this.markSynchronized();
+	}
+	flush() {
+		const broadcasts = this.buffered.sort((left, right) => left.watermark - right.watermark);
+		this.buffered = [];
+		for (const broadcast of broadcasts) this.applyBroadcast(broadcast);
+	}
+	applyBroadcast(broadcast) {
+		if (broadcast.watermark <= this.cursor) return;
+		const updates = broadcast.updates.filter((update) => update.sequence > this.cursor);
+		this.options.apply({
+			...broadcast,
+			updates
 		});
-		return {
-			before,
-			after: this.keyRefs.has(key)
-		};
+		this.cursor = Math.max(this.cursor, broadcast.watermark);
 	}
-	deleteKey(key) {
-		if (!this.keyRefs.has(key)) return false;
-		this.subsets.forEach((subset) => {
-			subset.keys.delete(key);
+	applyUpdates(updates, watermark) {
+		this.options.apply({
+			type: "updates",
+			shardId: "history",
+			updates,
+			watermark
 		});
-		this.keyRefs.delete(key);
-		return true;
 	}
-	release(subsetId, retain = false) {
-		const subset = this.subsets.get(subsetId);
-		if (!subset) return [];
-		subset.refs -= 1;
-		if (subset.refs > 0) return [];
-		subset.refs = 0;
-		if (retain) return [];
-		return this.expire(subsetId);
+	markSynchronized() {
+		this._state = "synchronized";
+		this.options.synchronized();
 	}
-	expire(subsetId) {
-		const subset = this.subsets.get(subsetId);
-		if (!subset || subset.refs > 0) return [];
-		this.subsets.delete(subsetId);
-		return this.releaseKeys(subset.keys);
+	isStopped() {
+		return this._state === "stopped";
 	}
-	clear() {
-		const keys = [...this.keyRefs.keys()];
-		this.subsets.clear();
-		this.keyRefs.clear();
-		return keys;
+};
+function visibleCursor(updates) {
+	return updates.reduce((cursor, update) => Math.max(cursor, update.sequence), 0);
+}
+//#endregion
+//#region src/offline-cache.ts
+const databaseVersion = 1;
+const rowStore = "collectionRows";
+const collectionIndex = "byCollection";
+function createOfflineCache(option, id, getKey) {
+	if (!option) return void 0;
+	if (!id) throw new Error("collectionOptions requires a stable id when offline is enabled");
+	if (!globalThis.indexedDB) throw new Error("IndexedDB is unavailable; offline collections must be created in a browser");
+	const options = option === true ? {} : option;
+	const collectionId = `${id}\0${options.cacheVersion ?? 1}`;
+	return new IndexedDBOfflineCache(globalThis.indexedDB, options.databaseName ?? "lsync", collectionId, getKey);
+}
+var IndexedDBOfflineCache = class {
+	collectionId;
+	getKey;
+	database;
+	queue = Promise.resolve();
+	constructor(factory, databaseName, collectionId, getKey) {
+		this.collectionId = collectionId;
+		this.getKey = getKey;
+		this.database = openDatabase(factory, databaseName);
 	}
-	addKeys(keys) {
-		keys.forEach((key) => {
-			this.keyRefs.set(key, (this.keyRefs.get(key) ?? 0) + 1);
+	async load() {
+		await this.queue;
+		return (await requestResult((await this.database).transaction(rowStore, "readonly").objectStore(rowStore).index(collectionIndex).getAll(this.collectionId))).map((record) => record.value);
+	}
+	put(rows) {
+		if (rows.length === 0) return this.queue;
+		return this.enqueue(async () => {
+			const transaction = (await this.database).transaction(rowStore, "readwrite");
+			const store = transaction.objectStore(rowStore);
+			for (const row of rows) store.put(this.record(row));
+			await transactionComplete(transaction);
 		});
 	}
-	releaseKeys(keys) {
-		const removed = [];
-		keys.forEach((key) => {
-			if (this.releaseKey(key)) removed.push(key);
+	delete(keys) {
+		if (keys.length === 0) return this.queue;
+		return this.enqueue(async () => {
+			const transaction = (await this.database).transaction(rowStore, "readwrite");
+			const store = transaction.objectStore(rowStore);
+			for (const key of keys) store.delete([this.collectionId, key]);
+			await transactionComplete(transaction);
 		});
-		return removed;
 	}
-	releaseKey(key) {
-		const refs = (this.keyRefs.get(key) ?? 0) - 1;
-		if (refs <= 0) {
-			this.keyRefs.delete(key);
-			return true;
-		}
-		this.keyRefs.set(key, refs);
-		return false;
+	replace(rows) {
+		return this.enqueue(async () => {
+			const transaction = (await this.database).transaction(rowStore, "readwrite");
+			const store = transaction.objectStore(rowStore);
+			await deleteCollectionRows(store.index(collectionIndex), this.collectionId);
+			for (const row of rows) store.put(this.record(row));
+			await transactionComplete(transaction);
+		});
 	}
-};
-function writeRows(collection, rows, getKey, write) {
-	for (const row of rows) {
-		const key = getKey(row);
-		write({
-			type: collection.has(key) ? "update" : "insert",
-			key,
+	record(row) {
+		return {
+			collectionId: this.collectionId,
+			key: this.getKey(row),
 			value: row
-		});
+		};
+	}
+	enqueue(operation) {
+		const result = this.queue.then(operation);
+		this.queue = result.catch(() => void 0);
+		return result;
 	}
+};
+function openDatabase(factory, name) {
+	return new Promise((resolve, reject) => {
+		const request = factory.open(name, databaseVersion);
+		request.onupgradeneeded = () => {
+			request.result.createObjectStore(rowStore, { keyPath: ["collectionId", "key"] }).createIndex(collectionIndex, "collectionId");
+		};
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+		request.onblocked = () => reject(/* @__PURE__ */ new Error(`IndexedDB database ${name} is blocked`));
+	});
 }
-function matchesFilters(row, filters) {
-	return filters.every((filter) => matchesFilter(row, filter));
+function deleteCollectionRows(index, id) {
+	return new Promise((resolve, reject) => {
+		const request = index.openKeyCursor(id);
+		request.onsuccess = () => {
+			const cursor = request.result;
+			if (!cursor) {
+				resolve();
+				return;
+			}
+			index.objectStore.delete(cursor.primaryKey);
+			cursor.continue();
+		};
+		request.onerror = () => reject(request.error);
+	});
 }
-function matchesSubset(row, subset) {
-	return matchesFilters(row, subset.filters) && matchesPredicate(row, subset.predicate);
+function requestResult(request) {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
 }
-function matchesPredicate(row, predicate) {
-	if (!predicate) return true;
-	if (predicate.type === "comparison") return matchesFilter(row, predicate);
-	if (predicate.type === "and") return predicate.predicates.every((child) => matchesPredicate(row, child));
-	return predicate.predicates.some((child) => matchesPredicate(row, child));
+function transactionComplete(transaction) {
+	return new Promise((resolve, reject) => {
+		transaction.oncomplete = () => resolve();
+		transaction.onerror = () => reject(transaction.error);
+		transaction.onabort = () => reject(transaction.error);
+	});
 }
-function matchesFilter(row, filter) {
-	const value = valueAtPath(row, filter.field);
-	switch (filter.op) {
-		case "eq": return value === filter.value;
-		case "ne": return value !== filter.value;
-		case "gt": return compareValues(value, filter.value, (left, right) => left > right);
-		case "gte": return compareValues(value, filter.value, (left, right) => left >= right);
-		case "lt": return compareValues(value, filter.value, (left, right) => left < right);
-		case "lte": return compareValues(value, filter.value, (left, right) => left <= right);
-		case "in": return Array.isArray(filter.value) && filter.value.includes(value);
+//#endregion
+//#region src/offline-sync.ts
+function persistChanges(offline, changes, collection, getKey) {
+	if (!offline) return;
+	const rows = [];
+	const deletedKeys = [];
+	for (const change of changes) {
+		if (change.type === "delete") {
+			deletedKeys.push(change.key);
+			continue;
+		}
+		const row = collection.get(getKey(change.value));
+		if (row) rows.push(row);
 	}
-	return false;
+	offline.put(rows);
+	offline.delete(deletedKeys);
 }
-function compareValues(left, right, compare) {
-	if (typeof left === "number" && typeof right === "number") return compare(left, right);
-	if (typeof left === "string" && typeof right === "string") return compare(left, right);
-	return false;
+function persistTransaction(offline, transaction) {
+	if (!offline) return;
+	const rows = [];
+	const deletedKeys = [];
+	for (const mutation of transaction.mutations) if (mutation.type === "delete") deletedKeys.push(mutation.key);
+	else rows.push(mutation.modified);
+	offline.put(rows);
+	offline.delete(deletedKeys);
 }
-function valueAtPath(row, field) {
-	return field.split(".").reduce((value, segment) => {
-		if (typeof value !== "object" || value === null) return;
-		return value[segment];
-	}, row);
+//#endregion
+//#region src/local-transaction.ts
+function trackLocalTransaction(subsets, syncMode, transaction) {
+	if (syncMode !== "on-demand" || !subsets) return;
+	for (const mutation of transaction.mutations) {
+		if (mutation.type === "delete") {
+			subsets.deleteKey(mutation.key);
+			continue;
+		}
+		subsets.reconcileRow(mutation.modified);
+	}
 }
 //#endregion
 //#region src/collection.ts
@@ -678,6 +1056,9 @@ function collectionOptions(options) {
 	let lease;
 	let client = options.client;
 	let activeSubsets;
+	if (options.offline && options.syncMode === "on-demand") throw new Error("IndexedDB offline caching currently requires eager sync mode");
+	if (options.offline && options.read === false) throw new Error("IndexedDB offline caching requires an initial collection read");
+	const offline = createOfflineCache(options.offline, options.id, options.getKey);
 	if (!client) {
 		if (!options.url) throw new Error("collectionOptions requires either client or url");
 		lease = acquireSharedClient({
@@ -696,11 +1077,12 @@ function collectionOptions(options) {
 		...options.defaultIndexType !== void 0 ? { defaultIndexType: options.defaultIndexType } : {},
 		getKey: options.getKey,
 		sync: {
-			sync: ({ begin, write, commit, markReady, collection }) => {
+			sync: ({ begin, write, commit, markReady, truncate, collection }) => {
 				const subsets = new SubsetTracker(options.getKey);
 				activeSubsets = subsets;
 				const subsetGcTime = options.gcTime ?? 3e5;
 				const retentionTimers = /* @__PURE__ */ new Map();
+				const subsetQueries = /* @__PURE__ */ new Map();
 				const deleteKeys = (keys) => {
 					if (keys.length === 0) return;
 					begin();
@@ -709,6 +1091,7 @@ function collectionOptions(options) {
 						key
 					});
 					commit();
+					offline?.delete(keys);
 				};
 				const cancelRetention = (id) => {
 					const timer = retentionTimers.get(id);
@@ -725,47 +1108,86 @@ function collectionOptions(options) {
 					cancelRetention(id);
 					retentionTimers.set(id, setTimeout(() => {
 						retentionTimers.delete(id);
+						subsetQueries.delete(id);
 						deleteKeys(subsets.expire(id));
 					}, subsetGcTime));
 				};
-				const subscription = client.subscribe(options.collection, (broadcast) => {
-					if ((broadcast.invalidations ?? []).length > 0 && options.syncMode === "on-demand") deleteKeys(subsets.clear());
-					const changes = broadcast.updates.flatMap((update) => {
-						if (update.collection !== options.collection) return [];
-						const ownUpdate = update.clientId === client.clientId;
-						if ((options.ignoreOwnUpdates ?? false) && ownUpdate) return [];
-						if (options.syncMode !== "on-demand") return [toChangeMessage(update, collection.has(update.key))];
-						const key = update.key;
-						const exists = collection.has(key);
-						if (update.type === "delete") {
-							subsets.deleteKey(key);
-							return exists ? [{
-								type: "delete",
-								key
-							}] : [];
-						}
-						const current = collection.get(key);
-						const row = update.type === "update" && current ? {
-							...current,
-							...update.value
-						} : update.value;
-						const tracked = subsets.reconcileRow(row);
-						if (ownUpdate || exists || tracked.after) return [toChangeMessage(update, exists)];
-						return [];
-					});
-					if (changes.length === 0) return;
-					begin();
-					for (const change of changes) write(change);
-					commit();
+				const initialQuery = initialReadQuery(options.collection, options.read);
+				const loadEager = async (replace = false) => {
+					if (!initialQuery) return;
+					const rows = await readInitialSyncRows(client, initialQuery, options.maxSyncRows);
+					if (replace) truncate();
+					if (rows.length > 0) {
+						begin();
+						writeRows(collection, rows, options.getKey, write);
+						commit();
+					}
+					if (replace) await offline?.replace(rows);
+					else await offline?.put(rows);
+				};
+				const reloadSubsets = async () => {
+					for (const [id, query] of subsetQueries) {
+						const result = await client.read(query);
+						const removedKeys = subsets.replace(id, result.rows, query.filters ?? [], query.predicate);
+						begin();
+						writeRows(collection, result.rows, options.getKey, write);
+						for (const key of removedKeys) write({
+							type: "delete",
+							key
+						});
+						commit();
+						await offline?.put(result.rows);
+						await offline?.delete(removedKeys);
+					}
+				};
+				let markedReady = false;
+				const markCollectionReady = () => {
+					if (!markedReady) markReady();
+					markedReady = true;
+				};
+				const session = new SyncSession({
+					client,
+					collection: options.collection,
+					initialize: () => options.syncMode === "on-demand" ? Promise.resolve() : loadEager(offline !== void 0),
+					resync: () => options.syncMode === "on-demand" ? reloadSubsets() : loadEager(true),
+					apply: (broadcast) => {
+						const changes = applyCollectionBroadcast({
+							broadcast,
+							collectionName: options.collection,
+							clientId: client.clientId,
+							ignoreOwnUpdates: options.ignoreOwnUpdates ?? false,
+							syncMode: options.syncMode === "on-demand" ? "on-demand" : "eager",
+							collection,
+							subsets,
+							begin,
+							write,
+							commit,
+							deleteKeys
+						});
+						persistChanges(offline, changes, collection, options.getKey);
+					},
+					...offline ? {
+						hydrate: async () => {
+							const rows = await offline.load();
+							if (rows.length === 0) return;
+							begin();
+							writeRows(collection, rows, options.getKey, write);
+							commit();
+						},
+						hydrated: markCollectionReady
+					} : {},
+					synchronized: markCollectionReady
 				});
+				session.start();
 				const readSubset = (subsetOptions) => {
 					const id = subsetId(subsetOptions);
 					cancelRetention(id);
 					if (subsets.retain(id).loaded) return true;
 					return (async () => {
 						const query = readQueryForSubset(options.collection, options.read === false ? void 0 : options.read, subsetOptions);
-						await subscription.ready;
+						await session.start();
 						const result = await client.read(query);
+						subsetQueries.set(id, query);
 						const removedKeys = subsets.replace(id, result.rows, query.filters ?? [], query.predicate);
 						begin();
 						writeRows(collection, result.rows, options.getKey, write);
@@ -779,71 +1201,89 @@ function collectionOptions(options) {
 						throw error;
 					});
 				};
-				if (options.syncMode === "on-demand") {
-					markReady();
-					return {
-						loadSubset: readSubset,
-						unloadSubset: (subsetOptions) => {
-							const id = subsetId(subsetOptions);
-							const removedKeys = subsets.release(id, subsetGcTime !== 0);
-							deleteKeys(removedKeys);
-							if (removedKeys.length === 0) scheduleRetention(id);
-						},
-						cleanup: () => {
-							retentionTimers.forEach((timer) => {
-								clearTimeout(timer);
-							});
-							retentionTimers.clear();
-							subsets.clear();
-							if (activeSubsets === subsets) activeSubsets = void 0;
-							subscription.unsubscribe();
-							lease?.release();
-						}
-					};
-				}
-				const initialQuery = initialReadQuery(options.collection, options.read);
-				if (!initialQuery) subscription.ready.then(() => {
-					markReady();
-				});
-				else subscription.ready.then(() => client.read(initialQuery)).then((result) => {
-					if (result.rows.length > 0) {
-						begin();
-						writeRows(collection, result.rows, options.getKey, write);
-						commit();
+				if (options.syncMode === "on-demand") return {
+					loadSubset: readSubset,
+					unloadSubset: (subsetOptions) => {
+						const id = subsetId(subsetOptions);
+						const removedKeys = subsets.release(id, subsetGcTime !== 0);
+						deleteKeys(removedKeys);
+						if (removedKeys.length === 0) scheduleRetention(id);
+						else subsetQueries.delete(id);
+					},
+					cleanup: () => {
+						retentionTimers.forEach((timer) => {
+							clearTimeout(timer);
+						});
+						retentionTimers.clear();
+						subsetQueries.clear();
+						subsets.clear();
+						if (activeSubsets === subsets) activeSubsets = void 0;
+						session.stop();
+						lease?.[Symbol.dispose]();
 					}
-					markReady();
-				});
+				};
 				return () => {
 					if (activeSubsets === subsets) activeSubsets = void 0;
-					subscription.unsubscribe();
-					lease?.release();
+					session.stop();
+					lease?.[Symbol.dispose]();
 				};
 			},
 			rowUpdateMode: "partial"
 		},
 		onInsert: async ({ transaction }) => {
 			trackLocalTransaction(activeSubsets, options.syncMode, transaction);
-			return client.push(createBatch(options.collection, client.clientId, transaction));
+			const result = await client.push(createBatch(options.collection, client.clientId, transaction));
+			persistTransaction(offline, transaction);
+			return result;
 		},
 		onUpdate: async ({ transaction }) => {
 			trackLocalTransaction(activeSubsets, options.syncMode, transaction);
-			return client.push(createBatch(options.collection, client.clientId, transaction));
+			const result = await client.push(createBatch(options.collection, client.clientId, transaction));
+			persistTransaction(offline, transaction);
+			return result;
 		},
 		onDelete: async ({ transaction }) => {
 			trackLocalTransaction(activeSubsets, options.syncMode, transaction);
-			return client.push(createBatch(options.collection, client.clientId, transaction));
+			const result = await client.push(createBatch(options.collection, client.clientId, transaction));
+			persistTransaction(offline, transaction);
+			return result;
 		}
 	};
 }
-function trackLocalTransaction(subsets, syncMode, transaction) {
-	if (syncMode !== "on-demand" || !subsets) return;
-	for (const mutation of transaction.mutations) {
-		if (mutation.type === "delete") {
-			subsets.deleteKey(mutation.key);
-			continue;
-		}
-		subsets.reconcileRow(mutation.modified);
-	}
+//#endregion
+//#region src/collection-path.ts
+function collectionScope(path, params) {
+	return `/${collectionPathSegments(path).map((segment) => segmentValue(segment, params)).map(normalizeSegment).join("/")}/`;
+}
+function firstNewPathParam(childPath, parentPath) {
+	if (!childPath) return void 0;
+	const parentParams = new Set(pathParams(parentPath));
+	return pathParams(childPath).find((param) => !parentParams.has(param));
+}
+function collectionPathSegments(path) {
+	return path.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+}
+function collectionPathParamName(segment) {
+	return segment.match(/^\{([A-Za-z_][A-Za-z0-9_]*)\}$/)?.[1] ?? segment.match(/^:([A-Za-z_][A-Za-z0-9_]*)$/)?.[1];
+}
+function isCollectionPathParam(segment) {
+	return collectionPathParamName(segment) !== void 0;
+}
+function segmentValue(segment, params) {
+	const param = collectionPathParamName(segment);
+	if (!param) return segment;
+	const value = params[param];
+	if (value === void 0) throw new Error(`Missing collection path parameter: ${param}`);
+	return String(value);
+}
+function pathParams(path) {
+	return collectionPathSegments(path).flatMap((segment) => {
+		const param = collectionPathParamName(segment);
+		return param ? [param] : [];
+	});
+}
+function normalizeSegment(segment) {
+	return encodeURIComponent(decodeURIComponent(segment));
 }
 //#endregion
 //#region src/collection-api.ts
@@ -851,12 +1291,53 @@ function defaultCollectionApiPath(path, name) {
 	const prefix = collectionPathSegments(path).filter((segment) => !isCollectionPathParam(segment)).join(".");
 	return prefix ? `${prefix}.${name}` : name;
 }
+var CollectionCache = class extends Map {
+	maxSize;
+	constructor(maxSize) {
+		super();
+		this.maxSize = normalizeMaxSize(maxSize);
+	}
+	touch(key, entry) {
+		this.delete(key);
+		this.set(key, entry);
+	}
+	evictInactive(protectedKey) {
+		while (this.size > this.maxSize) {
+			const candidate = [...this.entries()].find(([key, entry]) => key !== protectedKey && entry.collection.subscriberCount === 0 && entry.collection.status !== "loading");
+			if (!candidate) return;
+			this.delete(candidate[0]);
+			cleanupCollection(candidate[1].collection).catch(() => {});
+		}
+	}
+	async dispose() {
+		const entries = [...this.values()];
+		this.clear();
+		await Promise.all(entries.map(({ collection }) => cleanupCollection(collection)));
+	}
+};
+async function cleanupCollection(collection) {
+	if (collection.status === "loading") try {
+		await collection.preload();
+	} catch {}
+	if (collection.status !== "cleaned-up") await collection.cleanup();
+}
+function normalizeMaxSize(maxSize) {
+	if (maxSize === void 0) return 32;
+	if (!Number.isInteger(maxSize) || maxSize < 1) throw new Error("maxCachedCollections must be a positive integer");
+	return maxSize;
+}
+//#endregion
+//#region src/collection-type-config.ts
+function collectionConfig(options) {
+	const { api, children, id, maxCachedCollections, name, parentParam, path, ...config } = options;
+	return config;
+}
 //#endregion
 //#region src/collection-type.ts
 function createCollectionTypeFromOptions(options) {
 	const connection = connectionFrom(options);
 	if (!connection) throw new Error("CollectionTypes.builder requires either client or url");
-	return new CollectionTypeManager(options, connection, {}, /* @__PURE__ */ new Map()).api();
+	return new CollectionTypeManager(options, connection, {}, new CollectionCache(options.maxCachedCollections)).api();
 }
 var CollectionTypeManager = class CollectionTypeManager {
 	options;
@@ -873,6 +1354,7 @@ var CollectionTypeManager = class CollectionTypeManager {
 		return withChildren(withApiMethods({
 			all: (params = {}) => this.all(params),
 			delete: (...args) => this.all({}).delete(...args),
+			dispose: () => this.dispose(),
 			insert: (...args) => this.all({}).insert(...args),
 			with: (params) => this.with(params),
 			withId: (id, childParam) => this.withId(id, childParam),
@@ -881,7 +1363,7 @@ var CollectionTypeManager = class CollectionTypeManager {
 		}, this.apiMethods()), this.childManagers(this.params));
 	}
 	all(params) {
-		const scope = collectionScope$1(this.options.path, {
+		const scope = collectionScope(this.options.path, {
 			...this.params,
 			...params
 		});
@@ -890,6 +1372,8 @@ var CollectionTypeManager = class CollectionTypeManager {
 		if (existing) {
 			existing.usage.accessCount += 1;
 			existing.usage.lastAccessedAt = Date.now();
+			this.cache.touch(key, existing);
+			this.cache.evictInactive(key);
 			return existing.collection;
 		}
 		const id = collectionId(this.options.id, this.options.path, scope);
@@ -911,6 +1395,7 @@ var CollectionTypeManager = class CollectionTypeManager {
 			collection,
 			usage
 		});
+		this.cache.evictInactive(key);
 		return collection;
 	}
 	with(params) {
@@ -930,12 +1415,15 @@ var CollectionTypeManager = class CollectionTypeManager {
 	usage() {
 		return [...this.cache.values()].map((entry) => ({ ...entry.usage }));
 	}
+	async dispose() {
+		await this.cache.dispose();
+	}
 	apiMethods() {
 		return Object.fromEntries(Object.entries(this.options.api ?? {}).map(([name, method]) => [name, (...args) => this.callApi(name, method, args[0])]));
 	}
 	async callApi(name, method, input) {
 		if (method.handler) {
-			const scope = collectionScope$1(this.options.path, this.params);
+			const scope = collectionScope(this.options.path, this.params);
 			return method.handler({
 				input,
 				collection: this.all({}),
@@ -949,7 +1437,7 @@ var CollectionTypeManager = class CollectionTypeManager {
 		try {
 			return await client.call(path, input);
 		} finally {
-			lease?.release();
+			lease?.[Symbol.dispose]();
 		}
 	}
 	childManagers(params) {
@@ -964,10 +1452,6 @@ var CollectionTypeManager = class CollectionTypeManager {
 		} : this.params;
 	}
 };
-function collectionConfig(options) {
-	const { api, children, id, name, parentParam, path, ...config } = options;
-	return config;
-}
 function withChildren(target, children) {
 	return Object.assign(target, children);
 }
@@ -1038,6 +1522,24 @@ var ClientCollectionBuilder = class ClientCollectionBuilder {
 			syncMode
 		});
 	}
+	maxSyncRows(maxSyncRows) {
+		return new ClientCollectionBuilder({
+			...this.override,
+			maxSyncRows
+		});
+	}
+	offline(options = true) {
+		return new ClientCollectionBuilder({
+			...this.override,
+			offline: options
+		});
+	}
+	maxCachedCollections(maxCachedCollections) {
+		return new ClientCollectionBuilder({
+			...this.override,
+			maxCachedCollections
+		});
+	}
 	index(autoIndex, defaultIndexType) {
 		return new ClientCollectionBuilder({
 			...this.override,
@@ -1067,6 +1569,6 @@ function collectionOptionsFromDefinition(definition, dotPath, overrides) {
 	};
 }
 //#endregion
-export { collectionTypesFrom, createBatch, toChangeMessage };
+export { DEFAULT_MAX_SYNC_ROWS, collectionOptions, collectionTypesFrom, createBatch, createClient, toChangeMessage };
 
 //# sourceMappingURL=index.mjs.map