@lsync/client 0.0.1

package/dist/index.mjs

@@ -0,0 +1,1206 @@
+import { createTRPCProxyClient } from "@trpc/client";
+import { parseServerMessage, sendClientRpcRequest } from "@lsync/transport";
+import { observable } from "@trpc/server/observable";
+import { createCollection } from "@tanstack/db";
+//#region src/batch.ts
+function createBatch(collection, clientId, transaction) {
+	return { updates: transaction.mutations.map((mutation) => toUpdate(collection, clientId, mutation)) };
+}
+function toUpdate(collection, clientId, mutation) {
+	const base = {
+		id: mutation.mutationId,
+		collection,
+		key: mutation.key,
+		type: mutation.type,
+		clientId,
+		createdAt: mutation.createdAt.getTime()
+	};
+	if (mutation.type === "delete") return {
+		...base,
+		type: "delete",
+		previousValue: mutation.original
+	};
+	if (mutation.type === "update") return {
+		...base,
+		type: "update",
+		value: mutation.modified,
+		previousValue: mutation.original
+	};
+	return {
+		...base,
+		type: "insert",
+		value: mutation.modified
+	};
+}
+function toChangeMessage(update, existing) {
+	if (update.type === "delete") return {
+		type: "delete",
+		key: update.key
+	};
+	return {
+		type: update.type === "update" && existing === false ? "insert" : update.type === "insert" && existing === true ? "update" : update.type,
+		key: update.key,
+		value: update.value
+	};
+}
+//#endregion
+//#region src/client-rpc.ts
+function takePending(pending, id) {
+	if (id === null || id === void 0) return;
+	const key = String(id);
+	const request = pending.get(key);
+	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$1(collection) {
+	return `/${collection.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean).map(normalizeSegment$1).join("/")}/`;
+}
+function normalizeSegment$1(segment) {
+	return encodeURIComponent(decodeURIComponent(segment));
+}
+//#endregion
+//#region src/client-subscriptions.ts
+var ClientSubscriptions = class {
+	controls;
+	subscriptions = /* @__PURE__ */ new Map();
+	constructor(controls) {
+		this.controls = controls;
+	}
+	subscribe(collection, listener) {
+		const key = collectionScope$1(collection);
+		let entry = this.subscriptions.get(key);
+		const shouldSubscribe = !entry;
+		if (!entry) {
+			entry = {
+				collection: key,
+				listeners: /* @__PURE__ */ new Set(),
+				ready: Promise.resolve()
+			};
+			this.subscriptions.set(key, entry);
+		}
+		entry.listeners.add(listener);
+		if (shouldSubscribe) entry.ready = this.start(entry);
+		return {
+			ready: entry.ready,
+			unsubscribe: () => this.unsubscribe(key, listener)
+		};
+	}
+	async replay(ws) {
+		await Promise.all([...this.subscriptions.values()].map((entry) => this.subscribeOnSocket(ws, entry)));
+	}
+	dispatch(broadcast) {
+		const updatesByCollection = /* @__PURE__ */ new Map();
+		const invalidationsByCollection = /* @__PURE__ */ new Map();
+		for (const update of broadcast.updates) {
+			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$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$1(entry.collection));
+			const invalidations = invalidationsByCollection.get(collectionScope$1(entry.collection));
+			if ((!updates || updates.length === 0) && (!invalidations || invalidations.length === 0)) continue;
+			const scopedBroadcast = {
+				...broadcast,
+				...invalidations ? { invalidations } : {},
+				updates: updates ?? []
+			};
+			for (const listener of entry.listeners) listener(scopedBroadcast);
+		}
+	}
+	start(entry) {
+		const socket = this.controls.currentSocket();
+		return socket?.readyState === WebSocket.OPEN ? this.subscribeOnSocket(socket, entry) : this.controls.open().then(() => void 0);
+	}
+	async subscribeOnSocket(ws, entry) {
+		if (this.subscriptions.get(collectionScope$1(entry.collection)) !== entry) return;
+		entry.collection = (await this.controls.send(ws, "subscribe", entry.collection)).collection;
+	}
+	unsubscribe(key, listener) {
+		const entry = this.subscriptions.get(key);
+		if (!entry) return;
+		entry.listeners.delete(listener);
+		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);
+	}
+};
+//#endregion
+//#region src/client.ts
+const sharedClients = /* @__PURE__ */ new Map();
+function createClient(options) {
+	const clientId = options.clientId ?? crypto.randomUUID();
+	const pending = /* @__PURE__ */ new Map();
+	let nextId = 1;
+	let socket;
+	let connectPromise;
+	let subscriptions;
+	const open = async () => {
+		if (socket?.readyState === WebSocket.OPEN) return socket;
+		if (connectPromise) return connectPromise;
+		connectPromise = new Promise((resolve, reject) => {
+			const url = new URL(options.url);
+			url.searchParams.set("clientId", clientId);
+			const ws = new WebSocket(url);
+			ws.binaryType = "arraybuffer";
+			ws.addEventListener("open", () => {
+				socket = ws;
+				subscriptions.replay(ws).then(() => {
+					connectPromise = void 0;
+					resolve(ws);
+				}).catch((error) => {
+					connectPromise = void 0;
+					reject(error);
+				});
+			});
+			ws.addEventListener("message", (event) => {
+				const message = parseServerMessage(event.data);
+				if ("method" in message) {
+					subscriptions.dispatch(message.params.input.json);
+					return;
+				}
+				if ("error" in message) {
+					const request = takePending(pending, message.id);
+					if (!request) return;
+					request.reject(new Error(message.error.message));
+					return;
+				}
+				const request = takePending(pending, message.id);
+				if (!request) return;
+				request.resolve(message.result.data.json);
+			});
+			ws.addEventListener("close", () => {
+				socket = void 0;
+				connectPromise = void 0;
+			});
+			ws.addEventListener("error", () => {
+				reject(/* @__PURE__ */ new Error("Unable to open sync WebSocket"));
+			});
+		});
+		return connectPromise;
+	};
+	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;
+			}
+			pending.set(String(id), {
+				resolve: (value) => resolve(value),
+				reject
+			});
+			try {
+				sendClientRpcRequest(ws, request);
+			} catch (error) {
+				pending.delete(String(id));
+				reject(error);
+			}
+		});
+	};
+	const sendSubscriptionControl = async (ws, method, collection) => {
+		const id = String(nextId++);
+		return sendRequest(ws, {
+			id,
+			method,
+			params: { input: { json: { 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] });
+	return {
+		clientId,
+		push: (batch) => trpc.push.mutate(batch),
+		read: (query) => trpc.read.query(query),
+		changes: (query) => trpc.changes.query(query),
+		call: (path, ...args) => {
+			const [input] = args;
+			const call = input === void 0 ? { path } : {
+				path,
+				input
+			};
+			return trpc.api.mutate(call);
+		},
+		subscribe: (collection, listener) => subscriptions.subscribe(collection, listener),
+		close() {
+			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);
+	}
+	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();
+			}
+		}
+	};
+}
+function sharedClientKey(options) {
+	const url = new URL(options.url);
+	url.searchParams.delete("clientId");
+	return `${url.toString()}\0${options.clientId ?? ""}`;
+}
+//#endregion
+//#region src/read-query.ts
+function initialReadQuery(collection, read) {
+	if (read === false) return;
+	return {
+		collection,
+		...read
+	};
+}
+function subsetId(options) {
+	return JSON.stringify({
+		cursor: options.cursor ? {
+			whereCurrent: toReadPredicate(options.cursor.whereCurrent),
+			whereFrom: toReadPredicate(options.cursor.whereFrom)
+		} : void 0,
+		predicate: options.where ? toReadPredicate(options.where) : void 0,
+		limit: options.limit,
+		offset: options.offset,
+		orderBy: toReadOrderByList(options.orderBy)
+	});
+}
+function readQueryForSubset(collection, baseRead, options) {
+	const query = {
+		collection,
+		...baseRead,
+		filters: [...baseRead?.filters ?? []]
+	};
+	const predicate = combinePredicates(baseRead?.predicate, options.where ? toReadPredicate(options.where) : void 0);
+	if (predicate) query.predicate = predicate;
+	const limit = options.limit ?? baseRead?.limit;
+	if (limit !== void 0) query.limit = limit;
+	const offset = options.cursor ? void 0 : options.offset ?? baseRead?.offset;
+	if (offset !== void 0) query.offset = offset;
+	const subsetOrderBy = toReadOrderByList(options.orderBy);
+	const orderBy = subsetOrderBy.length > 0 ? subsetOrderBy : baseRead?.orderBy;
+	if (orderBy) query.orderBy = orderBy;
+	if (options.cursor) query.cursor = {
+		whereCurrent: toReadPredicate(options.cursor.whereCurrent),
+		whereFrom: toReadPredicate(options.cursor.whereFrom),
+		...options.cursor.lastKey !== void 0 ? { lastKey: options.cursor.lastKey } : {}
+	};
+	return query;
+}
+function combinePredicates(left, right) {
+	if (!left) return right;
+	if (!right) return left;
+	return {
+		type: "and",
+		predicates: [left, right]
+	};
+}
+function toReadPredicate(expression) {
+	const unwrapped = unwrapExpression(expression);
+	if (!isFuncExpression(unwrapped)) throw new Error("On-demand cursor predicates must be function expressions");
+	if (unwrapped.name === "and" || unwrapped.name === "or") return {
+		type: unwrapped.name,
+		predicates: unwrapped.args.map(toReadPredicate)
+	};
+	if (unwrapped.name === "not") return negatePredicate(toReadPredicate(unwrapped.args[0]));
+	const comparison = comparisonFromExpression(unwrapped);
+	if (!comparison) throw new Error(`Unsupported on-demand cursor operator: ${unwrapped.name}`);
+	return {
+		type: "comparison",
+		...comparison
+	};
+}
+function negatePredicate(predicate) {
+	if (predicate.type === "and" || predicate.type === "or") return {
+		type: predicate.type === "and" ? "or" : "and",
+		predicates: predicate.predicates.map(negatePredicate)
+	};
+	const comparison = predicate;
+	return {
+		...comparison,
+		op: negateOperator(comparison.op)
+	};
+}
+function negateOperator(operator) {
+	switch (operator) {
+		case "eq": return "ne";
+		case "ne": return "eq";
+		case "gt": return "lte";
+		case "gte": return "lt";
+		case "lt": return "gte";
+		case "lte": return "gt";
+		case "in": throw new Error("Unsupported on-demand cursor operator: not(in)");
+		default: throw new Error("Unsupported on-demand cursor operator");
+	}
+}
+function comparisonFromExpression(expression) {
+	const op = toReadFilterOperator(expression.name);
+	const [left, right] = expression.args;
+	if (!op || !isRefExpression(left) || !isValExpression(right)) return;
+	return {
+		field: left.path.join("."),
+		op,
+		value: right.value
+	};
+}
+function toReadOrderByList(orderBy) {
+	return (orderBy ?? []).map((sort) => {
+		const expression = unwrapExpression(sort.expression);
+		if (!isRefExpression(expression)) throw new Error(`On-demand orderBy must be a field reference`);
+		return toReadOrderBy({
+			field: expression.path,
+			direction: sort.compareOptions.direction
+		});
+	});
+}
+function toReadOrderBy(sort) {
+	return {
+		field: sort.field.join("."),
+		direction: sort.direction
+	};
+}
+function toReadFilterOperator(operator) {
+	switch (operator) {
+		case "eq":
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte":
+		case "in": return operator;
+		case "not_eq": return "ne";
+		case "not_gt": return "lte";
+		case "not_gte": return "lt";
+		case "not_lt": return "gte";
+		case "not_lte": return "gt";
+		default: return;
+	}
+}
+function unwrapExpression(value) {
+	if (typeof value === "object" && value !== null && "expression" in value && isExpression(value.expression)) return value.expression;
+	return value;
+}
+function isExpression(value) {
+	return typeof value === "object" && value !== null && "type" in value;
+}
+function isFuncExpression(value) {
+	return isExpression(value) && value.type === "func" && typeof value.name === "string" && Array.isArray(value.args);
+}
+function isRefExpression(value) {
+	return isExpression(value) && value.type === "ref" && Array.isArray(value.path);
+}
+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
+		});
+		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 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.ts
+function collectionOptions(options) {
+	let lease;
+	let client = options.client;
+	let activeSubsets;
+	if (!client) {
+		if (!options.url) throw new Error("collectionOptions requires either client or url");
+		lease = acquireSharedClient({
+			url: options.url,
+			...options.clientId ? { clientId: options.clientId } : {}
+		});
+		client = lease.client;
+	}
+	return {
+		...options.id ? { id: options.id } : {},
+		...options.gcTime !== void 0 ? { gcTime: options.gcTime } : {},
+		...options.schema ? { schema: options.schema } : {},
+		...options.startSync !== void 0 ? { startSync: options.startSync } : {},
+		...options.syncMode ? { syncMode: options.syncMode } : {},
+		...options.autoIndex !== void 0 ? { autoIndex: options.autoIndex } : {},
+		...options.defaultIndexType !== void 0 ? { defaultIndexType: options.defaultIndexType } : {},
+		getKey: options.getKey,
+		sync: {
+			sync: ({ begin, write, commit, markReady, collection }) => {
+				const subsets = new SubsetTracker(options.getKey);
+				activeSubsets = subsets;
+				const subsetGcTime = options.gcTime ?? 3e5;
+				const retentionTimers = /* @__PURE__ */ new Map();
+				const deleteKeys = (keys) => {
+					if (keys.length === 0) return;
+					begin();
+					for (const key of keys) write({
+						type: "delete",
+						key
+					});
+					commit();
+				};
+				const cancelRetention = (id) => {
+					const timer = retentionTimers.get(id);
+					if (!timer) return;
+					clearTimeout(timer);
+					retentionTimers.delete(id);
+				};
+				const scheduleRetention = (id) => {
+					if (!Number.isFinite(subsetGcTime)) return;
+					if (subsetGcTime <= 0) {
+						deleteKeys(subsets.expire(id));
+						return;
+					}
+					cancelRetention(id);
+					retentionTimers.set(id, setTimeout(() => {
+						retentionTimers.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 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;
+						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();
+					})().catch((error) => {
+						deleteKeys(subsets.release(id));
+						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();
+					}
+					markReady();
+				});
+				return () => {
+					if (activeSubsets === subsets) activeSubsets = void 0;
+					subscription.unsubscribe();
+					lease?.release();
+				};
+			},
+			rowUpdateMode: "partial"
+		},
+		onInsert: async ({ transaction }) => {
+			trackLocalTransaction(activeSubsets, options.syncMode, transaction);
+			return client.push(createBatch(options.collection, client.clientId, transaction));
+		},
+		onUpdate: async ({ transaction }) => {
+			trackLocalTransaction(activeSubsets, options.syncMode, transaction);
+			return client.push(createBatch(options.collection, client.clientId, transaction));
+		},
+		onDelete: async ({ transaction }) => {
+			trackLocalTransaction(activeSubsets, options.syncMode, transaction);
+			return client.push(createBatch(options.collection, client.clientId, transaction));
+		}
+	};
+}
+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
+function defaultCollectionApiPath(path, name) {
+	const prefix = collectionPathSegments(path).filter((segment) => !isCollectionPathParam(segment)).join(".");
+	return prefix ? `${prefix}.${name}` : name;
+}
+//#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();
+}
+var CollectionTypeManager = class CollectionTypeManager {
+	options;
+	connection;
+	params;
+	cache;
+	constructor(options, connection, params, cache) {
+		this.options = options;
+		this.connection = connection;
+		this.params = params;
+		this.cache = cache;
+	}
+	api() {
+		return withChildren(withApiMethods({
+			all: (params = {}) => this.all(params),
+			delete: (...args) => this.all({}).delete(...args),
+			insert: (...args) => this.all({}).insert(...args),
+			with: (params) => this.with(params),
+			withId: (id, childParam) => this.withId(id, childParam),
+			update: (...args) => this.all({}).update(...args),
+			usage: () => this.usage()
+		}, this.apiMethods()), this.childManagers(this.params));
+	}
+	all(params) {
+		const scope = collectionScope(this.options.path, {
+			...this.params,
+			...params
+		});
+		const key = `${this.options.path}\n${scope}`;
+		const existing = this.cache.get(key);
+		if (existing) {
+			existing.usage.accessCount += 1;
+			existing.usage.lastAccessedAt = Date.now();
+			return existing.collection;
+		}
+		const id = collectionId(this.options.id, this.options.path, scope);
+		const collection = createCollection(collectionOptions({
+			...collectionConfig(this.options),
+			...this.connection,
+			id,
+			collection: scope
+		}));
+		const usage = {
+			id,
+			path: this.options.path,
+			scope,
+			accessCount: 1,
+			createdAt: Date.now(),
+			lastAccessedAt: Date.now()
+		};
+		this.cache.set(key, {
+			collection,
+			usage
+		});
+		return collection;
+	}
+	with(params) {
+		return new CollectionTypeManager(this.options, this.connection, {
+			...this.params,
+			...params
+		}, this.cache).api();
+	}
+	withId(id, childParam) {
+		return withChildren({
+			all: () => this.all({}),
+			delete: (config) => this.all({}).delete(id, config),
+			get: () => this.all({}).get(id),
+			update: (...args) => this.all({}).update(id, ...args)
+		}, this.childManagers(this.childParams(id, childParam)));
+	}
+	usage() {
+		return [...this.cache.values()].map((entry) => ({ ...entry.usage }));
+	}
+	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(this.options.path, this.params);
+			return method.handler({
+				input,
+				collection: this.all({}),
+				params: this.params,
+				scope
+			});
+		}
+		const path = method.path ?? defaultCollectionApiPath(this.options.path, name);
+		const lease = this.connection.client ? void 0 : acquireSharedClient(this.connection);
+		const client = this.connection.client ?? lease?.client;
+		try {
+			return await client.call(path, input);
+		} finally {
+			lease?.release();
+		}
+	}
+	childManagers(params) {
+		const children = this.options.children ?? {};
+		return Object.fromEntries(Object.entries(children).map(([name, child]) => [name, new CollectionTypeManager(child, connectionFrom(child) ?? this.connection, params, this.cache).api()]));
+	}
+	childParams(id, childParam) {
+		const param = childParam ?? firstChildParam(this.options);
+		return param ? {
+			...this.params,
+			[param]: id
+		} : 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);
+}
+function withApiMethods(target, api) {
+	for (const name of Object.keys(api)) if (name in target) throw new Error(`Collection API method conflicts with existing property: ${name}`);
+	return Object.assign(target, api);
+}
+function connectionFrom(options) {
+	if (options.client) return { client: options.client };
+	if (options.url) return {
+		url: options.url,
+		...options.clientId ? { clientId: options.clientId } : {}
+	};
+}
+function collectionId(id, path, scope) {
+	return typeof id === "function" ? id({
+		path,
+		scope
+	}) : id ?? scope;
+}
+function firstChildParam(options) {
+	const child = Object.values(options.children ?? {})[0];
+	return child?.parentParam ?? firstNewPathParam(child?.path, options.path);
+}
+//#endregion
+//#region src/definition-builder.ts
+function collectionTypesFrom(definitions) {
+	return new DefinitionCollectionTypesBuilder(definitions.collections, {}, void 0);
+}
+var DefinitionCollectionTypesBuilder = class DefinitionCollectionTypesBuilder {
+	definitions;
+	overrides;
+	connection;
+	constructor(definitions, overrides, connection) {
+		this.definitions = definitions;
+		this.overrides = overrides;
+		this.connection = connection;
+	}
+	client(client) {
+		return new DefinitionCollectionTypesBuilder(this.definitions, this.overrides, { client });
+	}
+	url(url, options = {}) {
+		return new DefinitionCollectionTypesBuilder(this.definitions, this.overrides, {
+			url,
+			...options.clientId ? { clientId: options.clientId } : {}
+		});
+	}
+	collection(path, configure) {
+		const override = configure(new ClientCollectionBuilder({})).toOverride();
+		return new DefinitionCollectionTypesBuilder(this.definitions, {
+			...this.overrides,
+			[path]: override
+		}, this.connection);
+	}
+	build() {
+		if (!this.connection) throw new Error("CollectionTypes.from requires either client or url");
+		return Object.fromEntries(Object.entries(this.definitions).map(([name, definition]) => [name, collectionTypeFromDefinition(definition, name, this.overrides, this.connection)]));
+	}
+};
+var ClientCollectionBuilder = class ClientCollectionBuilder {
+	override;
+	constructor(override) {
+		this.override = override;
+	}
+	sync(syncMode) {
+		return new ClientCollectionBuilder({
+			...this.override,
+			syncMode
+		});
+	}
+	index(autoIndex, defaultIndexType) {
+		return new ClientCollectionBuilder({
+			...this.override,
+			autoIndex,
+			...defaultIndexType ? { defaultIndexType } : {}
+		});
+	}
+	toOverride() {
+		return this.override;
+	}
+};
+function collectionTypeFromDefinition(definition, dotPath, overrides, connection) {
+	return createCollectionTypeFromOptions({
+		...collectionOptionsFromDefinition(definition, dotPath, overrides),
+		...connection
+	});
+}
+function collectionOptionsFromDefinition(definition, dotPath, overrides) {
+	return {
+		...overrides[dotPath],
+		name: definition.name,
+		path: definition.path,
+		schema: definition.schema,
+		getKey: (item) => item[definition.key],
+		children: Object.fromEntries(Object.entries(definition.children).map(([name, child]) => [name, collectionOptionsFromDefinition(child, `${dotPath}.${name}`, overrides)])),
+		api: Object.fromEntries(Object.entries(definition.api).map(([name, api]) => [name, api.path ? { path: api.path } : {}]))
+	};
+}
+//#endregion
+//#region src/collection-name.ts
+function rootPathForName(name) {
+	return `/${encodeURIComponent(name)}/`;
+}
+function childPathForName(parentPath, parentParam, name) {
+	return `${parentPath.replace(/\/+$/g, "")}/{${parentParam}}/${encodeURIComponent(name)}/`;
+}
+function parentIdParamForName(name) {
+	return `${name}Id`;
+}
+//#endregion
+//#region src/immutable.ts
+function cloneImmutable(value) {
+	if (Array.isArray(value)) return Object.freeze(value.map(cloneImmutable));
+	if (!isPlainObject(value)) return value;
+	return Object.freeze(Object.fromEntries(Object.entries(value).map(([nestedKey, nestedValue]) => [nestedKey, cloneImmutable(nestedValue)])));
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+//#endregion
+//#region src/collection-type-builder-state.ts
+function freezeBuilderState(state) {
+	return Object.freeze(Object.fromEntries(Object.entries(state).filter(([, value]) => value !== void 0).map(([key, value]) => [key, copyBuilderStateValue(key, value)])));
+}
+function copyBuilderStateValue(key, value) {
+	if (key === "api" && isApiMap(value)) return freezeApiMap(value);
+	if (key === "url" && value instanceof URL) return value.toString();
+	return cloneImmutable(value);
+}
+function freezeApiMap(api) {
+	return Object.freeze(Object.fromEntries(Object.entries(api).map(([name, method]) => [name, freezeApiMethod(method)])));
+}
+function freezeApiMethod(method) {
+	return Object.freeze({ ...method });
+}
+function isApiMap(value) {
+	return typeof value === "object" && value !== null;
+}
+//#endregion
+//#region src/collection-type-builder.ts
+function collectionTypeBuilder() {
+	return new CollectionTypeBuilder({});
+}
+const CollectionTypes = {
+	builder: collectionTypeBuilder,
+	from: collectionTypesFrom
+};
+var CollectionTypeBuilder = class CollectionTypeBuilder {
+	state;
+	constructor(state) {
+		this.state = freezeBuilderState(state);
+	}
+	client(client) {
+		return this.next({
+			client,
+			url: void 0,
+			clientId: void 0
+		});
+	}
+	url(url, options = {}) {
+		return this.next({
+			client: void 0,
+			url,
+			...options.clientId ? { clientId: options.clientId } : {}
+		});
+	}
+	name(name) {
+		return this.next({
+			name,
+			path: rootPathForName(name)
+		});
+	}
+	schema(schema) {
+		return this.next({ schema });
+	}
+	sync(syncMode) {
+		return this.next({ syncMode });
+	}
+	index(autoIndex, defaultIndexType) {
+		return this.next({
+			autoIndex,
+			...defaultIndexType ? { defaultIndexType } : {}
+		});
+	}
+	child(name, configure) {
+		const child = configure(this.childBuilder(name));
+		const children = typeof this.state.children === "object" && this.state.children !== null ? this.state.children : {};
+		return this.next({ children: {
+			...children,
+			[name]: child.state
+		} });
+	}
+	key(getKey) {
+		return this.next({ getKey });
+	}
+	api(name, method) {
+		const entry = typeof method === "function" ? localApiMethod(method) : method ?? {};
+		return this.next({ api: {
+			...this.state.api,
+			[name]: entry
+		} });
+	}
+	build() {
+		if (!this.state.name || !this.state.path) throw new Error("CollectionTypes.builder requires a name");
+		if (!this.state.getKey) throw new Error("CollectionTypes.builder requires a key function");
+		return createCollectionTypeFromOptions(this.state);
+	}
+	next(updates) {
+		return new CollectionTypeBuilder({
+			...this.state,
+			...updates
+		});
+	}
+	childBuilder(name) {
+		if (!this.state.name || !this.state.path) throw new Error("CollectionTypes.builder.child requires a parent name");
+		const parentParam = parentIdParamForName(this.state.name);
+		return new CollectionTypeBuilder({
+			name,
+			parentParam,
+			path: childPathForName(this.state.path, parentParam, name)
+		});
+	}
+};
+function localApiMethod(handler) {
+	return Object.freeze({ handler: ({ input, collection, params, scope }) => handler(input, {
+		collection,
+		params,
+		scope
+	}) });
+}
+//#endregion
+export { CollectionTypeBuilder, CollectionTypes, DefinitionCollectionTypesBuilder, collectionOptions, createBatch, createClient, toChangeMessage };
+
+//# sourceMappingURL=index.mjs.map