@happyvertical/smrt-web 0.43.1 → 0.43.3

package/AGENTS.md

@@ -41,6 +41,7 @@ module you are editing. This file keeps what holds in every module.
 | `webmcp.ts` | framework-agnostic WebMCP registrar; registers generated collection tools and routes mutations through shared smrt-web cache state | — |
 | `persistence/` + `update-state.ts` | the read-cache rehydrate capability and the framework-free `updateAvailable` primitive (bundle + contract signals) | [agents/version-persistence.md](agents/version-persistence.md) |
 | `data-query.ts` | dependency-free browser mirror and defensive response normalizer for the canonical bounded data-query envelope (#2444) | — |
+| `remote-query.ts` | query-shaped remote pages over a `SmrtWebCollection`, with keyed stale cache, execution modes, cancellation/latest-query-wins, and optional query-scoped live subscriptions (#2445) | — |
 
 ## The engine-absorption boundary (ratified conditions, #1761)
 

package/README.md

@@ -9,6 +9,12 @@ Use it for browser-side collection state, shared request deduplication, offline
 writes, persisted read caches, and live invalidation. Svelte bindings live in
 [`@happyvertical/smrt-svelte/web`](../smrt-svelte/README.md).
 
+Query-backed surfaces can use `createSmrtWebQuery(collection, transport)` to
+fetch one canonical bounded page. Visible runs update state; `background`,
+`prefetch`, and `silent` runs stay out of visible state. The controller keeps
+stale rows available while refreshing, cancels superseded visible runs, and can
+attach a query-scoped live subscription.
+
 ## Installation
 
 ```bash
@@ -119,6 +125,7 @@ core.
 | Group | Main exports |
 | --- | --- |
 | Collections | `createSmrtCollection`, `createSmrtWebClient`, `newLocalId` |
+| Remote queries | `createSmrtWebQuery`, `SmrtWebQueryTransport` |
 | HTTP | `createDefinitionFetchers`, `unwrapListResult`, `unwrapItemResult` |
 | Offline | `offlineOutbox`, `getOutboxHandle` |
 | Persistence | `persistCollection`, `wipeDurableStore` |

package/dist/chunks/{src-CDdW9uYx.js → src-D9RvoJSQ.js}

@@ -1343,6 +1343,425 @@ function persistCollection(config) {
 	};
 }
 //#endregion
+//#region src/remote-query.ts
+function canonicalize(value) {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (value && typeof value === "object") {
+		const record = value;
+		return Object.fromEntries(Object.keys(record).sort().map((key) => [key, canonicalize(record[key])]));
+	}
+	return value;
+}
+function keyFor(request) {
+	const { requestId: _requestId, ...semantic } = request;
+	return JSON.stringify(canonicalize(semantic));
+}
+function rebindRequestId(result, request) {
+	return result.requestId === request.requestId ? result : {
+		...result,
+		requestId: request.requestId
+	};
+}
+function abortError() {
+	if (typeof DOMException !== "undefined") return new DOMException("The operation was aborted", "AbortError");
+	const error = /* @__PURE__ */ new Error("The operation was aborted");
+	error.name = "AbortError";
+	return error;
+}
+function isAbort(error) {
+	return !!error && typeof error === "object" && error.name === "AbortError";
+}
+function pageOf(result) {
+	if (!result.page) return void 0;
+	return result.page.kind === "offset" ? { ...result.page } : { ...result.page };
+}
+function createSmrtWebQuery(_collection, transport, options = {}) {
+	const staleTimeMs = options.staleTimeMs ?? 3e4;
+	const cache = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	const latestSuccessfulFlight = /* @__PURE__ */ new Map();
+	let flightSequence = 0;
+	const listeners = /* @__PURE__ */ new Set();
+	let request;
+	let visibleController;
+	const runControllers = /* @__PURE__ */ new Set();
+	let generation = 0;
+	let live;
+	let liveIntent;
+	let liveGeneration = 0;
+	let disposed = false;
+	let state = {
+		rows: [],
+		page: void 0,
+		total: void 0,
+		loading: false,
+		refreshing: false,
+		stale: false,
+		error: null,
+		lastUpdated: void 0,
+		result: void 0
+	};
+	const publish = (next) => {
+		state = next;
+		for (const listener of listeners) listener(state);
+	};
+	const cached = (key) => cache.get(key);
+	const cacheSuccess = (key, result, sequence, updatedAt = Date.now()) => {
+		if (disposed) return false;
+		const latest = latestSuccessfulFlight.get(key);
+		if (latest === void 0 || sequence > latest) {
+			latestSuccessfulFlight.set(key, sequence);
+			cache.set(key, {
+				result,
+				updatedAt
+			});
+			return true;
+		}
+		return false;
+	};
+	const apply = (result, candidate, updatedAt = Date.now(), successSequence) => {
+		if (successSequence !== void 0 && !cacheSuccess(keyFor(candidate), result, successSequence, updatedAt)) return;
+		publish({
+			rows: result.rows,
+			page: pageOf(result),
+			total: result.total,
+			loading: false,
+			refreshing: false,
+			stale: result.freshness.state === "stale",
+			error: null,
+			lastUpdated: updatedAt,
+			result
+		});
+	};
+	const runTransport = async (candidate, controller) => {
+		runControllers.add(controller);
+		try {
+			const result = await executeSmrtWebDataQuery(transport, candidate, { signal: controller.signal });
+			if (controller.signal.aborted) throw abortError();
+			return result;
+		} catch (error) {
+			if (controller.signal.aborted) throw abortError();
+			throw error;
+		} finally {
+			runControllers.delete(controller);
+		}
+	};
+	const execute = async (candidate, runOptions = {}) => {
+		if (disposed) throw abortError();
+		const mode = runOptions.mode ?? "visible";
+		const key = keyFor(candidate);
+		if (runOptions.signal?.aborted || (runOptions.deadlineMs ?? 1) <= 0) throw abortError();
+		const rebindIntent = mode === "visible" && liveIntent?.active && (!live || request !== void 0 && keyFor(request) !== key) ? liveIntent : void 0;
+		const entry = cached(key);
+		const fresh = entry !== void 0 && Date.now() - entry.updatedAt < staleTimeMs;
+		if (mode !== "visible" && !runOptions.force && fresh) return rebindRequestId(entry.result, candidate);
+		if (mode === "visible" && !runOptions.force && fresh) {
+			generation += 1;
+			visibleController?.abort(abortError());
+			if (disposed) throw abortError();
+			visibleController = void 0;
+			request = candidate;
+			if (rebindIntent) live?.disconnect();
+			const result = rebindRequestId(entry.result, candidate);
+			apply(result, candidate, entry.updatedAt);
+			if (disposed) throw abortError();
+			if (rebindIntent?.active && !live) resumeLive(rebindIntent);
+			return result;
+		}
+		if (mode === "visible") {
+			generation += 1;
+			visibleController?.abort(abortError());
+			if (disposed) throw abortError();
+			const invocationController = new AbortController();
+			visibleController = invocationController;
+			request = candidate;
+			if (rebindIntent) live?.disconnect();
+			const current = generation;
+			const signal = runOptions.signal;
+			let removeCallerAbort;
+			if (signal?.aborted) invocationController.abort(signal.reason);
+			else if (signal) {
+				const abortCaller = () => invocationController.abort(signal.reason);
+				signal.addEventListener("abort", abortCaller, { once: true });
+				removeCallerAbort = () => signal.removeEventListener("abort", abortCaller);
+			}
+			if (entry) {
+				const cachedResult = rebindRequestId(entry.result, candidate);
+				publish({
+					rows: cachedResult.rows,
+					page: pageOf(cachedResult),
+					total: cachedResult.total,
+					loading: false,
+					refreshing: true,
+					stale: true,
+					error: null,
+					lastUpdated: entry.updatedAt,
+					result: cachedResult
+				});
+			} else publish({
+				...state,
+				loading: true,
+				refreshing: false,
+				stale: false,
+				error: null
+			});
+			runOptions = {
+				...runOptions,
+				signal: invocationController.signal,
+				force: true
+			};
+			try {
+				if (disposed) throw abortError();
+				const result = await runShared(candidate, key, runOptions);
+				if (current === generation) {
+					if (cached(key)?.result === result) apply(result, candidate);
+					else publish({
+						...state,
+						loading: false,
+						refreshing: false
+					});
+					if (rebindIntent?.active && !live) resumeLive(rebindIntent);
+				}
+				return result;
+			} catch (error) {
+				if (current === generation) if (isAbort(error)) publish({
+					...state,
+					loading: false,
+					refreshing: false
+				});
+				else publish({
+					...state,
+					loading: false,
+					refreshing: false,
+					stale: entry !== void 0,
+					error
+				});
+				throw error;
+			} finally {
+				removeCallerAbort?.();
+				if (visibleController === invocationController) visibleController = void 0;
+			}
+		}
+		return runShared(candidate, key, runOptions);
+	};
+	const waitForFlight = (flight, key, candidate, runOptions) => {
+		if (runOptions.signal?.aborted || (runOptions.deadlineMs ?? 1) <= 0) return Promise.reject(abortError());
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			const settle = () => {
+				if (settled) return;
+				settled = true;
+				flight.waiters -= 1;
+				if (timer) clearTimeout(timer);
+				runOptions.signal?.removeEventListener("abort", cancel);
+			};
+			const cancel = () => {
+				if (settled) return;
+				settle();
+				if (flight.waiters === 0 && !flight.settled) {
+					flight.controller.abort(abortError());
+					if (inFlight.get(key) === flight) inFlight.delete(key);
+				}
+				reject(abortError());
+			};
+			const timer = runOptions.deadlineMs === void 0 ? void 0 : setTimeout(cancel, runOptions.deadlineMs);
+			flight.waiters += 1;
+			runOptions.signal?.addEventListener("abort", cancel, { once: true });
+			flight.promise.then((result) => {
+				if (settled) return;
+				settle();
+				resolve(rebindRequestId(result, candidate));
+			}, (error) => {
+				if (settled) return;
+				settle();
+				reject(error);
+			});
+		});
+	};
+	const runShared = async (candidate, key, runOptions) => {
+		if (runOptions.signal?.aborted || (runOptions.deadlineMs ?? 1) <= 0) throw abortError();
+		if (!runOptions.force) {
+			const existing = inFlight.get(key);
+			if (existing) return waitForFlight(existing, key, candidate, runOptions);
+		}
+		const flight = ++flightSequence;
+		const controller = new AbortController();
+		const running = runTransport(candidate, controller).then((result) => {
+			if (controller.signal.aborted) throw abortError();
+			cacheSuccess(key, result, flight);
+			return result;
+		});
+		const shared = {
+			controller,
+			promise: running,
+			waiters: 0,
+			settled: false
+		};
+		inFlight.set(key, shared);
+		running.then(() => {
+			shared.settled = true;
+			if (inFlight.get(key) === shared) inFlight.delete(key);
+		}, () => {
+			shared.settled = true;
+			if (inFlight.get(key) === shared) inFlight.delete(key);
+		});
+		return waitForFlight(shared, key, candidate, runOptions);
+	};
+	const refresh = (refreshOptions = {}) => {
+		if (!request) return Promise.resolve(void 0);
+		return execute(request, {
+			...refreshOptions,
+			mode: "visible",
+			force: true
+		});
+	};
+	const startLive = (intent) => {
+		if (disposed || !intent.active || !request || !transport.subscribe) return void 0;
+		const candidate = request;
+		const currentGeneration = ++liveGeneration;
+		const controller = new AbortController();
+		let connected = true;
+		let subscription;
+		let handle;
+		const disconnect = () => {
+			if (!connected) return;
+			connected = false;
+			controller.abort();
+			subscription.unsubscribe();
+			if (live === handle) live = void 0;
+		};
+		const unsubscribe = () => {
+			if (!intent.active) return;
+			intent.active = false;
+			disconnect();
+			if (liveIntent === intent) liveIntent = void 0;
+			if (live?.intent === intent) live.disconnect();
+		};
+		const reconnect = () => {
+			if (!intent.active || disposed) return;
+			if (!connected) {
+				if (live?.intent === intent) live.reconnect();
+				return;
+			}
+			if (currentGeneration !== liveGeneration) return;
+			disconnect();
+			const reconnectRequest = request;
+			if (!reconnectRequest || keyFor(reconnectRequest) !== keyFor(candidate)) return;
+			execute(reconnectRequest, {
+				mode: "visible",
+				force: true
+			}).catch(() => void 0).finally(() => {
+				if (intent.active && !disposed && liveIntent === intent && !live && request && keyFor(request) === keyFor(candidate)) resumeLive(intent);
+			});
+		};
+		handle = {
+			intent,
+			disconnect,
+			unsubscribe,
+			reconnect
+		};
+		subscription = transport.subscribe(candidate, (raw) => {
+			if (!connected || !intent.active || disposed || currentGeneration !== liveGeneration || controller.signal.aborted) return;
+			const liveFlight = ++flightSequence;
+			(async () => {
+				const result = await executeSmrtWebDataQuery({ query: async () => raw }, candidate);
+				if (connected && intent.active && !disposed && currentGeneration === liveGeneration && request && keyFor(request) === keyFor(candidate)) apply(rebindRequestId(result, request), request, Date.now(), liveFlight);
+			})().catch((error) => {
+				const latestSuccessful = latestSuccessfulFlight.get(keyFor(candidate));
+				if (!isAbort(error) && connected && intent.active && !disposed && currentGeneration === liveGeneration && request && keyFor(request) === keyFor(candidate) && (latestSuccessful === void 0 || liveFlight > latestSuccessful)) publish({
+					...state,
+					error
+				});
+			});
+		}, { signal: controller.signal });
+		if (disposed || !intent.active) {
+			disconnect();
+			return;
+		}
+		live = handle;
+		return handle;
+	};
+	const clearLiveIntent = (intent) => {
+		intent.active = false;
+		if (liveIntent === intent) liveIntent = void 0;
+	};
+	const resumeLive = (intent) => {
+		try {
+			startLive(intent);
+		} catch (error) {
+			clearLiveIntent(intent);
+			if (!disposed) publish({
+				...state,
+				error
+			});
+		}
+	};
+	const subscribeLive = () => {
+		if (disposed || !request || !transport.subscribe) return void 0;
+		if (liveIntent) {
+			liveIntent.active = false;
+			live?.disconnect();
+		}
+		const intent = { active: true };
+		liveIntent = intent;
+		try {
+			return startLive(intent);
+		} catch (error) {
+			clearLiveIntent(intent);
+			throw error;
+		}
+	};
+	return {
+		get state() {
+			return state;
+		},
+		get request() {
+			return request;
+		},
+		execute,
+		refresh,
+		retry: () => refresh(),
+		subscribe(listener) {
+			listeners.add(listener);
+			listener(state);
+			return () => listeners.delete(listener);
+		},
+		subscribeLive,
+		invalidate() {
+			if (!request) return;
+			const key = keyFor(request);
+			const entry = cache.get(key);
+			latestSuccessfulFlight.set(key, ++flightSequence);
+			if (entry) cache.set(key, {
+				...entry,
+				updatedAt: 0
+			});
+			publish({
+				...state,
+				loading: false,
+				refreshing: false,
+				stale: true
+			});
+		},
+		dispose() {
+			disposed = true;
+			generation += 1;
+			liveGeneration += 1;
+			visibleController?.abort(abortError());
+			for (const controller of runControllers) controller.abort(abortError());
+			if (liveIntent) liveIntent.active = false;
+			live?.disconnect();
+			live = void 0;
+			liveIntent = void 0;
+			request = void 0;
+			listeners.clear();
+			cache.clear();
+			latestSuccessfulFlight.clear();
+			inFlight.clear();
+		}
+	};
+}
+//#endregion
 //#region src/sse-client.ts
 var EVENT_SOURCE_CLOSED = 2;
 function defaultEventSourceFactory(url, init) {
@@ -2287,6 +2706,6 @@ function createSmrtCollection(definition, options) {
 	return handle;
 }
 //#endregion
-export { executeSmrtWebDataQuery as A, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES as C, MAX_SMRT_WEB_DATA_QUERY_ROWS as D, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES as E, runWrapMutation as M, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH as O, MAX_SMRT_WEB_DATA_QUERY_FACETS as S, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT as T, offlineOutbox as _, createSmrtWebClient as a, wipeDurableStore as b, unwrapItemResult as c, createUpdateState as d, createSmrtWebEventSubscriber as f, getOutboxHandle as g, persistCollection as h, createSmrtCollection as i, normalizeSmrtWebDataQueryResult as j, MAX_SMRT_WEB_DATA_QUERY_WARNINGS as k, unwrapListResult as l, DEFAULT_PERSIST_DEBOUNCE_MS as m, buildListQuery as n, getEngineCollection as o, liveInvalidation as p, createDefinitionFetchers as r, newLocalId as s, SmrtWebRequestError as t, registerWebMcpTools as u, durableStoreNamespace as v, MAX_SMRT_WEB_DATA_QUERY_OFFSET as w, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS as x, registerDurableResource as y };
+export { MAX_SMRT_WEB_DATA_QUERY_WARNINGS as A, MAX_SMRT_WEB_DATA_QUERY_FACETS as C, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES as D, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT as E, normalizeSmrtWebDataQueryResult as M, runWrapMutation as N, MAX_SMRT_WEB_DATA_QUERY_ROWS as O, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS as S, MAX_SMRT_WEB_DATA_QUERY_OFFSET as T, getOutboxHandle as _, createSmrtWebClient as a, registerDurableResource as b, unwrapItemResult as c, createUpdateState as d, createSmrtWebEventSubscriber as f, persistCollection as g, DEFAULT_PERSIST_DEBOUNCE_MS as h, createSmrtCollection as i, executeSmrtWebDataQuery as j, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH as k, unwrapListResult as l, createSmrtWebQuery as m, buildListQuery as n, getEngineCollection as o, liveInvalidation as p, createDefinitionFetchers as r, newLocalId as s, SmrtWebRequestError as t, registerWebMcpTools as u, offlineOutbox as v, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES as w, wipeDurableStore as x, durableStoreNamespace as y };
 
-//# sourceMappingURL=src-CDdW9uYx.js.map
+//# sourceMappingURL=src-D9RvoJSQ.js.map