@askrjs/askr 0.3.0 → 0.4.0

package/dist/query-registry-WMCN0BJL.js

@@ -0,0 +1,320 @@
+import { a as getDefaultDataRuntime, d as writePrefetchedQueryData, i as findDataRuntimeState, t as createDataRuntime } from "./data-runtime-C1bFAlba.js";
+//#region src/common/deferred-value.ts
+const DEFERRED_VALUE = Symbol.for("@askrjs/askr/deferred-value");
+const DEFERRED_BOUNDARY = Symbol.for("@askrjs/askr/deferred-boundary");
+/** Wrap a promise as a {@link Deferred} value that tracks its settled state and result. */
+function defer(promise) {
+	let state = "pending";
+	let value;
+	let error;
+	const normalized = Promise.resolve(promise);
+	normalized.then((resolved) => {
+		state = "fulfilled";
+		value = resolved;
+	}, (reason) => {
+		state = "rejected";
+		error = reason;
+	});
+	return Object.freeze(Object.defineProperties({}, {
+		state: {
+			enumerable: true,
+			get: () => state
+		},
+		value: {
+			enumerable: true,
+			get: () => value
+		},
+		error: {
+			enumerable: true,
+			get: () => error
+		},
+		promise: { value: normalized },
+		[DEFERRED_VALUE]: { value: true }
+	}));
+}
+/** Check whether `value` is a {@link Deferred} produced by {@link defer}. */
+function isDeferred(value) {
+	if (!value || typeof value !== "object") return false;
+	const marker = Object.getOwnPropertyDescriptor(value, DEFERRED_VALUE);
+	return Boolean(marker && "value" in marker && marker.value === true);
+}
+/** @internal Reconstruct settled server data without importing deferred rendering. */
+function reviveDeferredValue(state, value, error) {
+	const promise = state === "fulfilled" ? Promise.resolve(value) : Promise.reject(error);
+	if (state === "rejected") promise.catch(() => void 0);
+	return Object.freeze(Object.defineProperties({}, {
+		state: {
+			enumerable: true,
+			value: state
+		},
+		value: {
+			enumerable: true,
+			value
+		},
+		error: {
+			enumerable: true,
+			value: error
+		},
+		promise: { value: promise },
+		[DEFERRED_VALUE]: { value: true }
+	}));
+}
+//#endregion
+//#region src/common/json-transport.ts
+/** Diagnostic path for an own property of the value at `parent`. */
+function jsonTransportPropertyPath(parent, key) {
+	if (/^(?:0|[1-9]\d*)$/.test(key)) return `${parent}[${key}]`;
+	if (/^[A-Za-z_$][\w$]*$/.test(key)) return `${parent}.${key}`;
+	return `${parent}[${JSON.stringify(key)}]`;
+}
+/** Format a diagnostic path only when a value actually fails. */
+function pathOf(frame, key) {
+	const keys = key === void 0 ? [] : [key];
+	for (let at = frame; at.p; at = at.p) keys.push(at.k);
+	let path = "$";
+	for (let index = keys.length - 1; index >= 0; index -= 1) path = jsonTransportPropertyPath(path, keys[index]);
+	return path;
+}
+function primitiveReason(value) {
+	switch (typeof value) {
+		case "number": return Number.isFinite(value) ? void 0 : "non-finite numbers are not supported";
+		case "undefined": return "undefined is not supported";
+		case "bigint": return "bigint is not supported";
+		case "symbol": return "symbols are not supported";
+		case "function": return "functions are not supported";
+	}
+}
+function objectLabel(value) {
+	if (value instanceof Date) return "Date";
+	if (value instanceof Map) return "Map";
+	if (value instanceof Set) return "Set";
+	const constructor = value.constructor;
+	return typeof constructor === "function" && constructor.name ? constructor.name : "class instance";
+}
+/**
+* Validate that `value` survives the hydration JSON transport unchanged:
+* `null`, strings, booleans, finite numbers, dense arrays, plain objects, and
+* framework deferred values. Anything `JSON.stringify()` would drop, coerce, or
+* reject (undefined, functions, bigint, `Date`, `Map`, class instances, cycles,
+* and so on) throws a `TypeError` naming `subject` and the value's path, then
+* `hint`. Accessors are rejected without being invoked. The walk is
+* iterative, so nesting depth is bounded by memory rather than the call
+* stack, and paths are formatted only on failure.
+*/
+function validateJsonTransportValue(value, subject, hint) {
+	const fail = (path, reason) => {
+		throw new TypeError(`[Askr] ${subject} at "${path}" is not JSON transport-safe: ${reason}. ${hint}`);
+	};
+	const stack = [];
+	const ancestors = /* @__PURE__ */ new Set();
+	const visit = (child, parent, key) => {
+		const reason = primitiveReason(child);
+		if (reason) fail(parent ? pathOf(parent, key) : "$", reason);
+		if (child !== null && typeof child === "object") stack.push({
+			o: child,
+			p: parent,
+			k: key,
+			seen: false
+		});
+	};
+	visit(value, void 0, "");
+	while (stack.length > 0) {
+		const frame = stack[stack.length - 1];
+		const object = frame.o;
+		if (frame.seen) {
+			stack.pop();
+			ancestors.delete(object);
+			continue;
+		}
+		if (ancestors.has(object)) fail(pathOf(frame), "cyclic references are not supported");
+		frame.seen = true;
+		ancestors.add(object);
+		const hasSymbols = Object.getOwnPropertySymbols(object).length > 0;
+		if (hasSymbols && isDeferred(object)) {
+			if (object.state === "fulfilled") visit(object.value, frame, "value");
+			continue;
+		}
+		const array = Array.isArray(object) ? object : void 0;
+		if (!array) {
+			const prototype = Object.getPrototypeOf(object);
+			if (prototype !== Object.prototype && prototype !== null) fail(pathOf(frame), `${objectLabel(object)} instances are not supported; use a plain object`);
+		}
+		if (hasSymbols) fail(pathOf(frame), "symbol-keyed properties are not supported");
+		const keys = Object.keys(object);
+		let named = false;
+		if (array) {
+			const length = array.length;
+			if (keys.length !== length || length > 0 && keys[length - 1] !== String(length - 1)) {
+				for (let index = 0; index < length; index += 1) if (!(index in array)) fail(pathOf(frame, String(index)), "sparse arrays are not supported");
+				named = true;
+			}
+		}
+		const names = Object.getOwnPropertyNames(object);
+		if (names.length !== keys.length + (array ? 1 : 0)) {
+			for (const name of names) if (!(array && name === "length") && !keys.includes(name)) fail(pathOf(frame, name), "non-enumerable properties are not supported");
+		}
+		const firstChild = stack.length;
+		for (const key of keys) {
+			const descriptor = Object.getOwnPropertyDescriptor(object, key);
+			if (!("value" in descriptor)) fail(pathOf(frame, key), "accessors are not supported");
+			if (named && (!/^(?:0|[1-9]\d*)$/.test(key) || Number(key) >= array.length)) fail(pathOf(frame, key), "named array properties are not supported");
+			visit(descriptor.value, frame, key);
+		}
+		for (let low = firstChild, high = stack.length - 1; low < high;) {
+			const child = stack[low];
+			stack[low++] = stack[high];
+			stack[high--] = child;
+		}
+	}
+}
+//#endregion
+//#region src/common/telemetry.ts
+function withTelemetry(span, fields, work) {
+	return span ? span(fields, work) : work();
+}
+//#endregion
+//#region src/data/query-registry.ts
+/** Pair a {@link QueryDefinition} with the server-side handler that resolves it. */
+function serveQuery(query, handler) {
+	return Object.freeze({
+		query,
+		handler
+	});
+}
+/** Build a {@link ServerQueryRegistry} from one or more {@link serveQuery} entries. */
+function defineServerQueries(...entries) {
+	const frozenEntries = Object.freeze([...entries]);
+	const handlers = new Map(entries.map((entry) => [entry.query, entry.handler]));
+	return Object.freeze({
+		entries: frozenEntries,
+		get(query) {
+			return handlers.get(query);
+		}
+	});
+}
+/** Freeze and return a reusable {@link QueryDefinition}. */
+function defineQuery(definition) {
+	return Object.freeze({ ...definition });
+}
+/**
+* Throw when query data cannot cross the hydration JSON transport unchanged.
+* SSR preloads check before anything streams; dehydration checks again.
+*/
+function assertQueryDataTransportSafe(key, value) {
+	validateJsonTransportValue(value, `Query data for key ${JSON.stringify(key)}`, "Return JSON-compatible query data.");
+}
+/**
+* Settle with `promise`, or reject with the reason of the first of `signals`
+* to abort.
+*/
+function raceAbort(promise, signals) {
+	return new Promise((resolve, reject) => {
+		const abort = () => reject(signals.find((each) => each.aborted).reason);
+		for (const each of signals) {
+			if (each.aborted) abort();
+			each.addEventListener("abort", abort);
+		}
+		promise.then(resolve, reject).finally(() => {
+			for (const each of signals) each.removeEventListener("abort", abort);
+		});
+	});
+}
+/**
+* Create a {@link QueryPrefetchContext} for prefetching query data ahead of
+* render, e.g. during SSR route resolution.
+*/
+function createQueryPrefetchContext(options = {}) {
+	const runtime = options.runtime ?? (options.mode === "spa" ? getDefaultDataRuntime() : createDataRuntime());
+	const signal = options.signal ?? new AbortController().signal;
+	const storePrefetchedValue = (key, value) => {
+		if (signal.aborted) return false;
+		if (runtime.queryCache.has(key)) return true;
+		const runtimeState = options.mode !== "ssr" && typeof window !== "undefined" ? findDataRuntimeState(runtime) : void 0;
+		if (runtimeState) writePrefetchedQueryData(runtimeState, key, value);
+		else {
+			if (options.mode === "ssr") assertQueryDataTransportSafe(key, value);
+			runtime.queryData.set(key, value);
+		}
+		return true;
+	};
+	return {
+		runtime,
+		request: options.request,
+		signal,
+		mode: options.mode ?? "spa",
+		async prefetch(query, input) {
+			return withTelemetry(options.telemetry?.queryPrefetch, {}, async () => {
+				const key = query.key(input);
+				if (runtime.queryCache.has(key) || runtime.queryData.has(key)) return true;
+				const handler = options.mode === "ssr" ? options.registry?.get(query) : void 0;
+				if (options.mode === "ssr" && !handler) return false;
+				const inflight = findDataRuntimeState(runtime)?.prefetches ?? /* @__PURE__ */ new Map();
+				for (;;) {
+					let pending = inflight.get(key);
+					const joined = pending !== void 0 && !(pending.signal.aborted && !signal.aborted);
+					if (!joined) {
+						let promise;
+						try {
+							promise = Promise.resolve(handler ? handler({
+								input,
+								request: options.request,
+								signal
+							}) : query.fetch(input, { signal }));
+						} catch (error) {
+							promise = Promise.reject(error);
+						}
+						pending = {
+							signal,
+							promise,
+							waiters: 0
+						};
+						inflight.set(key, pending);
+					}
+					const current = pending;
+					current.waiters += 1;
+					try {
+						let value;
+						try {
+							value = await (joined ? raceAbort(current.promise, [signal, current.signal]) : current.promise);
+						} catch (error) {
+							if (current.signal.aborted && !signal.aborted) continue;
+							throw error;
+						}
+						return !current.invalidated && storePrefetchedValue(key, value);
+					} finally {
+						current.waiters -= 1;
+						if (current.waiters === 0 && inflight.get(key) === current) inflight.delete(key);
+					}
+				}
+			});
+		}
+	};
+}
+/** Prefetch `query` with `input` into a {@link QueryPrefetchContext}'s runtime. */
+async function prefetchQuery(context, query, input) {
+	return context.prefetch(query, input);
+}
+/**
+* Extract a runtime's cached query data into a JSON-serializable snapshot.
+* Throws a `TypeError` naming the key and path of any value that would not
+* survive JSON transport unchanged (for example a `Date`, `Map`, or bigint).
+*/
+function dehydrateDataRuntime(runtime) {
+	const result = {};
+	for (const [key, value] of runtime.queryData) {
+		assertQueryDataTransportSafe(key, value);
+		result[key] = value;
+	}
+	return result;
+}
+/** Load a {@link dehydrateDataRuntime} snapshot back into a runtime's query cache. */
+function hydrateDataRuntime(runtime, data) {
+	if (!data || typeof data !== "object" || Array.isArray(data)) return;
+	const runtimeState = findDataRuntimeState(runtime);
+	for (const [key, value] of Object.entries(data)) {
+		runtimeState?.unreadPrefetches.delete(key);
+		runtime.queryData.set(key, value);
+	}
+}
+//#endregion
+export { hydrateDataRuntime as a, withTelemetry as c, DEFERRED_BOUNDARY as d, defer as f, dehydrateDataRuntime as i, jsonTransportPropertyPath as l, reviveDeferredValue as m, defineQuery as n, prefetchQuery as o, isDeferred as p, defineServerQueries as r, serveQuery as s, createQueryPrefetchContext as t, validateJsonTransportValue as u };

package/dist/readable-DFWOsTac.js

@@ -0,0 +1,21 @@
+//#region src/core/reactive/readable.ts
+/**
+* Readables: callables that read a reactive value (`state()` cells and
+* `derive()` results). A function prop or child that returns a readable
+* renders the readable's value.
+*/
+const READABLE = Symbol.for("askr.readable");
+function markReadable(fn) {
+	Object.defineProperty(fn, READABLE, { value: true });
+	return fn;
+}
+function isReadable(value) {
+	return typeof value === "function" && value[READABLE] === true;
+}
+/** Call `fn`; if it returns a readable, read that too. */
+function readValue(fn) {
+	const value = fn();
+	return isReadable(value) ? value() : value;
+}
+//#endregion
+export { readValue as n, markReadable as t };

package/dist/{render-context-B7ohlh6t.js → render-context-DGHnEveC.js}

@@ -21,6 +21,7 @@ function createPageRenderEnvelope(input = {}) {
 	return Object.freeze({
 		version: PAGE_RENDER_ENVELOPE_VERSION,
 		resources: ownedRecord(input.resources),
+		...input.queries ? { queries: ownedRecord(input.queries) } : {},
 		route: input.route,
 		framework: ownedRecord(input.framework)
 	});
@@ -38,18 +39,14 @@ function pageRenderEnvelope(value, fallback = {}) {
 	});
 }
 function replacePageRoute(value, route) {
-	const current = pageRenderEnvelope(value);
 	return createPageRenderEnvelope({
-		resources: current.resources,
-		route,
-		framework: current.framework
+		...pageRenderEnvelope(value),
+		route
 	});
 }
 function withPageFramework(value, framework) {
-	const current = pageRenderEnvelope(value);
 	return createPageRenderEnvelope({
-		resources: current.resources,
-		route: current.route,
+		...pageRenderEnvelope(value),
 		framework
 	});
 }
@@ -69,7 +66,7 @@ function getHydrationRenderUrl(value) {
 	return typeof url === "string" ? url : void 0;
 }
 function isEmptyPageRenderEnvelope(value) {
-	return value.route === void 0 && Object.keys(value.resources).length === 0 && Object.keys(value.framework).length === 0;
+	return value.route === void 0 && Object.keys(value.resources).length === 0 && Object.keys(value.queries ?? {}).length === 0 && Object.keys(value.framework).length === 0;
 }
 //#endregion
 //#region src/common/render-context.ts
@@ -86,6 +83,25 @@ function configureRenderContextProvider(nextProvider) {
 function getActiveRenderContext() {
 	return provider.getRenderContext();
 }
+const deferredBoundaryParents = /* @__PURE__ */ new WeakMap();
+/**
+* Scope deferred boundaries registered in `context` under an already streamed
+* parent boundary, so nested ids (`d:0.0`) never collide with top-level ones.
+*/
+function setDeferredBoundaryParent(context, parentId) {
+	deferredBoundaryParents.set(context, parentId);
+}
+/** Register a pending `Resolve` boundary for streaming and return its deterministic id. */
+function registerDeferredBoundary(context, registration) {
+	const parent = deferredBoundaryParents.get(context);
+	const index = context.deferredBoundaries.length;
+	const id = parent === void 0 ? `d:${index}` : `${parent}.${index}`;
+	context.deferredBoundaries.push({
+		id,
+		...registration
+	});
+	return id;
+}
 /** Register request-local CSS produced during SSR without importing the SSR renderer in clients. */
 function registerSSRStyle(id, cssText) {
 	const context = getActiveRenderContext();
@@ -129,8 +145,8 @@ function isHydrationVerificationRender() {
 	return hydrationVerificationDepth > 0;
 }
 /** @internal Read a server-captured resource branch without invoking its loader. */
-function getResourceVerificationSnapshot(key) {
-	const snapshots = getCurrentRenderData()?.framework[RESOURCE_VERIFICATION_SNAPSHOTS];
+function getResourceVerificationSnapshot(key, framework = getCurrentRenderData()?.framework) {
+	const snapshots = framework?.[RESOURCE_VERIFICATION_SNAPSHOTS];
 	if (!snapshots || typeof snapshots !== "object" || Array.isArray(snapshots)) return null;
 	if (!Object.prototype.hasOwnProperty.call(snapshots, key)) return null;
 	const snapshot = snapshots[key];
@@ -174,4 +190,4 @@ function throwSSRDataMissing() {
 	throw new SSRDataMissingError();
 }
 //#endregion
-export { SSRDataMissingError as C, withPageFramework as S, isEmptyPageRenderEnvelope as _, getResourceVerificationSnapshot as a, replacePageRoute as b, registerSSRStyle as c, stopHydrationRenderPhase as d, stopRenderPhase as f, getHydrationRenderUrl as g, createPageRenderEnvelope as h, getNextRenderKey as i, startHydrationRenderPhase as l, withHydrationVerificationRender as m, getActiveRenderContext as n, isHydrationVerificationRender as o, throwSSRDataMissing as p, getCurrentRenderData as r, recordResourceVerificationSnapshot as s, configureRenderContextProvider as t, startRenderPhase as u, isPageRenderEnvelope as v, withHydrationRenderUrl as x, pageRenderEnvelope as y };
+export { withHydrationRenderUrl as C, replacePageRoute as S, SSRDataMissingError as T, createPageRenderEnvelope as _, getResourceVerificationSnapshot as a, isPageRenderEnvelope as b, registerDeferredBoundary as c, startHydrationRenderPhase as d, startRenderPhase as f, withHydrationVerificationRender as g, throwSSRDataMissing as h, getNextRenderKey as i, registerSSRStyle as l, stopRenderPhase as m, getActiveRenderContext as n, isHydrationVerificationRender as o, stopHydrationRenderPhase as p, getCurrentRenderData as r, recordResourceVerificationSnapshot as s, configureRenderContextProvider as t, setDeferredBoundaryParent as u, getHydrationRenderUrl as v, withPageFramework as w, pageRenderEnvelope as x, isEmptyPageRenderEnvelope as y };