@lovrozagar/flare 0.1.1 → 0.2.0

package/src/navigation/types.ts

@@ -1,4 +1,4 @@
-import type { JSX } from "solid-js";
+import type { JSX } from "@solidjs/web";
 import type {
 	ClientErrorRenderProps,
 	ClientNotFoundRenderProps,
@@ -29,6 +29,11 @@ export interface LoadedRouteModule {
 	errorRender?: (props: ClientErrorRenderProps) => JSX.Element;
 	notFoundRender?: (props: ClientNotFoundRenderProps) => JSX.Element;
 	cache?: {
+		cdn?:
+			| {
+					tags?: string[] | ((ctx: { params: Record<string, string | string[]> }) => string[]);
+			  }
+			| false;
 		client?:
 			| {
 					cacheDeferred?: boolean;
@@ -38,6 +43,11 @@ export interface LoadedRouteModule {
 					staleTime?: number;
 			  }
 			| false;
+		ssr?:
+			| {
+					tags?: string[] | ((ctx: { params: Record<string, string | string[]> }) => string[]);
+			  }
+			| false;
 	};
 	render: (props: RenderProps) => JSX.Element;
 	unauthenticatedRender?: (props: ClientUnauthenticatedRenderProps) => JSX.Element;

package/src/navigation-progress/index.tsx

@@ -1,5 +1,6 @@
-import { createEffect, type JSX, onCleanup, useContext } from "solid-js";
-import { isServer } from "solid-js/web";
+import { createEffect, useContext } from "solid-js";
+import type { JSX } from "@solidjs/web";
+import { isServer } from "@solidjs/web";
 import { RouterContext } from "../outlet/index.tsx";
 
 export interface NavigationProgressProps {
@@ -179,20 +180,20 @@ export function NavigationProgress(props: NavigationProgressProps): JSX.Element
 	const ctx = useContext(RouterContext);
 
 	if (!isServer && ctx) {
-		createEffect(() => {
-			const phase = ctx.navigationPhase();
-
-			if (phase === "loading") {
-				clearTimers();
-				start();
-			} else if (phase === "idle" && status !== null) {
-				handleComplete();
-			} else if (phase === "transitioning" && status !== null) {
-				handleComplete();
-			}
-		});
-
-		onCleanup(clearTimers);
+		createEffect(
+			() => ctx.navigationPhase(),
+			(phase) => {
+				if (phase === "loading") {
+					clearTimers();
+					start();
+				} else if (phase === "idle" && status !== null) {
+					handleComplete();
+				} else if (phase === "transitioning" && status !== null) {
+					handleComplete();
+				}
+				return clearTimers;
+			},
+		);
 	}
 
 	const barColor = (): string => props.color ?? "currentColor";

package/src/ndjson-client/index.ts

@@ -1,5 +1,6 @@
 import { NotFoundError, RedirectResponse, UnauthenticatedError, UnauthorizedError } from "../errors/index.ts";
 import { warn } from "../logger.ts";
+import { HEADER_DATA, HEADER_FLAG, HEADER_PREFETCH, HEADER_STALE } from "../protocol.ts";
 import type { HeadConfig } from "../route-builder/types.ts";
 import type { DeferredResolver } from "../state-parser/index.ts";
 import { hydrateLoaderData } from "../state-parser/index.ts";
@@ -8,9 +9,13 @@ const MAX_LINE_BYTES = 5 * 1024 * 1024;
 const MAX_MESSAGES = 10_000;
 
 export interface NDJSONFetchOptions {
+	/** Match ids whose prefetch `l` shell is already committed — skip hydrate, stream `c` into `resolvers`. */
+	keepMatchIds?: Iterable<string>;
 	matchIds?: string[];
 	prefetch?: boolean;
 	queryClient?: unknown;
+	/** Pre-seeded deferred resolvers (hydrated prefetch shell). */
+	resolvers?: Map<string, DeferredResolver>;
 	signal?: AbortSignal;
 	url: string;
 }
@@ -18,12 +23,15 @@ export interface NDJSONFetchOptions {
 export interface NDJSONFetchResult {
 	matches: FetchedMatch[];
 	perRouteHeads: PerRouteHead[];
+	status?: number;
 	success: boolean;
 }
 
 export interface FetchedMatch {
 	error?: Error;
 	hasDeferredMarkers?: boolean;
+	/** Enter `l` for a match whose prefetch shell is already on screen — do not replace loaderData. */
+	keepShell?: boolean;
 	loaderData: unknown;
 	matchId: string;
 	preloaderContext?: Record<string, unknown>;
@@ -94,15 +102,29 @@ function forwardServerLog(msg: NDJSONMessage): void {
 	}
 }
 
+/** Hydrate `t:"q"` entries unless the navigation that started this hop has aborted. */
+export function applyQueryCacheHydration(queryClient: unknown, entries: unknown, signal?: AbortSignal): void {
+	if (signal?.aborted) return;
+	void import("../query-client")
+		.then(({ hydrateQueryCache }) => {
+			if (signal?.aborted) return;
+			hydrateQueryCache(
+				queryClient as Parameters<typeof hydrateQueryCache>[0],
+				entries as Parameters<typeof hydrateQueryCache>[1],
+			);
+		})
+		.catch(() => {});
+}
+
 export async function fetchNDJSON(options: NDJSONFetchOptions): Promise<NDJSONFetchResult> {
-	const headers: Record<string, string> = { "x-d": "1" };
+	const headers: Record<string, string> = { [HEADER_DATA]: HEADER_FLAG };
 
 	if (options.matchIds) {
-		headers["x-m"] = options.matchIds.join(",");
+		headers[HEADER_STALE] = options.matchIds.join(",");
 	}
 
 	if (options.prefetch) {
-		headers["x-p"] = "1";
+		headers[HEADER_PREFETCH] = HEADER_FLAG;
 	}
 
 	const response = await fetch(options.url, {
@@ -116,12 +138,13 @@ export async function fetchNDJSON(options: NDJSONFetchOptions): Promise<NDJSONFe
 	 * body makes retry() rebuild matches from a cache that never stored the
 	 * pipeline error, so the error UI cannot recover. */
 	if (!response.ok && !isNdjson) {
-		return { matches: [], perRouteHeads: [], success: false };
+		return { matches: [], perRouteHeads: [], status: response.status, success: false };
 	}
 
 	const matches: FetchedMatch[] = [];
 	const perRouteHeads: PerRouteHead[] = [];
-	const deferredResolvers = new Map<string, DeferredResolver>();
+	const deferredResolvers = options.resolvers ?? new Map<string, DeferredResolver>();
+	const keepMatchIds = new Set(options.keepMatchIds ?? []);
 
 	let loadersReadyResolve: () => void = () => {};
 	let loadersReadyResolved = false;
@@ -168,20 +191,29 @@ export async function fetchNDJSON(options: NDJSONFetchOptions): Promise<NDJSONFe
 			}
 
 			case "l": {
-				if (options.prefetch) {
+				const matchId = msg.m ?? "";
+				if (keepMatchIds.has(matchId)) {
+					matches.push({
+						hasDeferredMarkers: true,
+						keepShell: true,
+						loaderData: msg.d,
+						matchId,
+						preloaderContext: msg.p,
+					});
+				} else if (options.prefetch) {
 					matches.push({
 						hasDeferredMarkers: containsDeferredMarkers(msg.d) || undefined,
 						loaderData: msg.d,
-						matchId: msg.m ?? "",
+						matchId,
 						preloaderContext: msg.p,
 					});
 				} else {
 					const sizeBefore = deferredResolvers.size;
-					const hydrated = hydrateLoaderData(msg.m ?? "", msg.d, deferredResolvers);
+					const hydrated = hydrateLoaderData(matchId, msg.d, deferredResolvers);
 					matches.push({
 						hasDeferredMarkers: deferredResolvers.size > sizeBefore || undefined,
 						loaderData: hydrated,
-						matchId: msg.m ?? "",
+						matchId,
 						preloaderContext: msg.p,
 					});
 				}
@@ -246,14 +278,7 @@ export async function fetchNDJSON(options: NDJSONFetchOptions): Promise<NDJSONFe
 
 			case "q": {
 				if (options.queryClient && Array.isArray(msg.d)) {
-					import("../query-client")
-						.then(({ hydrateQueryCache }) => {
-							hydrateQueryCache(
-								options.queryClient as Parameters<typeof hydrateQueryCache>[0],
-								msg.d as Parameters<typeof hydrateQueryCache>[1],
-							);
-						})
-						.catch(() => {});
+					applyQueryCacheHydration(options.queryClient, msg.d, options.signal);
 				}
 				break;
 			}

package/src/ndjson-server/index.ts

@@ -6,10 +6,27 @@ import type { HeadConfig } from "../route-builder/types.ts";
 import type { ServerLogEntry } from "@lovrozagar/flare/server-context";
 
 export interface NDJSONResponseConfig {
+	abortController?: AbortController;
 	deferContexts: Map<string, DeferContext>;
 	matches: PipelineMatch[];
 	queryClient?: unknown;
 	serverLogs?: ServerLogEntry[];
+	status?: number;
+}
+
+export function followAbortSignal(controller: AbortController, signal: AbortSignal | undefined): void {
+	if (!signal) return;
+	if (signal.aborted) {
+		controller.abort();
+		return;
+	}
+	signal.addEventListener(
+		"abort",
+		() => {
+			if (!controller.signal.aborted) controller.abort();
+		},
+		{ once: true },
+	);
 }
 
 const NDJSON_HEADERS = {
@@ -190,16 +207,44 @@ export function createNDJSONResponse(config: NDJSONResponseConfig): Response {
 	for (const l of lines) {
 		body += `${l}\n`;
 	}
-	return new Response(body, { headers: NDJSON_HEADERS, status: 200 });
+	return new Response(body, { headers: NDJSON_HEADERS, status: config.status ?? 200 });
+}
+
+export function createErrorNDJSONResponse(error: Error, status?: number): Response {
+	const http =
+		status ??
+		(error.name === "UnauthenticatedError"
+			? 401
+			: error.name === "UnauthorizedError"
+				? 403
+				: error.name === "NotFoundError"
+					? 404
+					: 500);
+	const lines = [formatErrorMessage("", error), formatReadyMessage(), formatDoneMessage()];
+	let body = "";
+	for (const l of lines) {
+		body += `${l}\n`;
+	}
+	return new Response(body, { headers: NDJSON_HEADERS, status: http });
 }
 
 export function createStreamingNDJSONResponse(config: NDJSONResponseConfig): Response {
 	const { deferContexts, matches } = config;
+	let cancelled = false;
 
 	const stream = new ReadableStream({
+		cancel() {
+			cancelled = true;
+			if (config.abortController && !config.abortController.signal.aborted) {
+				config.abortController.abort();
+			}
+		},
 		async start(controller) {
 			const encoder = new TextEncoder();
-			const enqueue = (msg: string) => controller.enqueue(encoder.encode(`${msg}\n`));
+			const enqueue = (msg: string) => {
+				if (cancelled) return;
+				controller.enqueue(encoder.encode(`${msg}\n`));
+			};
 
 			/* 0. Server log messages */
 			if (config.serverLogs) {
@@ -227,14 +272,6 @@ export function createStreamingNDJSONResponse(config: NDJSONResponseConfig): Res
 			/* 3. Ready */
 			enqueue(formatReadyMessage());
 
-			/* Install QC tracking for deferred callbacks */
-			let trackedQC: { drain(): Array<{ data: unknown; key: unknown[]; staleTime?: number }> } | undefined;
-			if (config.queryClient) {
-				const { createTrackedQueryClient } = await import("../query-client");
-				const typed = config.queryClient as Parameters<typeof createTrackedQueryClient>[0];
-				trackedQC = createTrackedQueryClient(typed);
-			}
-
 			/* 4. Stream deferred chunks */
 			const entries: DeferredEntry[] = [];
 			for (const ctx of deferContexts.values()) {
@@ -242,25 +279,37 @@ export function createStreamingNDJSONResponse(config: NDJSONResponseConfig): Res
 					entries.push(e);
 				}
 			}
-			await Promise.allSettled(
-				entries.map(async (entry) => {
-					try {
-						const data = await entry.promise;
-						enqueue(formatChunkMessage(entry.matchId, entry.key, data));
-					} catch (e) {
-						const err = e instanceof Error ? e : new Error(String(e));
-						enqueue(formatErrorMessage(entry.matchId, err, entry.key));
-					}
-
-					/* Drain QC delta entries accumulated during this deferred resolve */
-					if (trackedQC) {
-						const qcEntries = trackedQC.drain();
-						if (qcEntries.length > 0) {
-							enqueue(formatQueryCacheMessage(qcEntries));
+
+			const streamDeferred = async (trackedQC?: {
+				drain(): Array<{ data: unknown; key: unknown[]; staleTime?: number }>;
+			}) => {
+				await Promise.allSettled(
+					entries.map(async (entry) => {
+						try {
+							const data = await entry.promise;
+							enqueue(formatChunkMessage(entry.matchId, entry.key, data));
+						} catch (e) {
+							const err = e instanceof Error ? e : new Error(String(e));
+							enqueue(formatErrorMessage(entry.matchId, err, entry.key));
 						}
-					}
-				}),
-			);
+
+						if (trackedQC) {
+							const qcEntries = trackedQC.drain();
+							if (qcEntries.length > 0) {
+								enqueue(formatQueryCacheMessage(qcEntries));
+							}
+						}
+					}),
+				);
+			};
+
+			if (config.queryClient) {
+				const { withTrackedQueryClient } = await import("../query-client");
+				const typed = config.queryClient as Parameters<typeof withTrackedQueryClient>[0];
+				await withTrackedQueryClient(typed, streamDeferred);
+			} else {
+				await streamDeferred();
+			}
 
 			/* 5. Done */
 			enqueue(formatDoneMessage());
@@ -268,7 +317,7 @@ export function createStreamingNDJSONResponse(config: NDJSONResponseConfig): Res
 		},
 	});
 
-	return new Response(stream, { headers: NDJSON_HEADERS, status: 200 });
+	return new Response(stream, { headers: NDJSON_HEADERS, status: config.status ?? 200 });
 }
 
 export function createRedirectNDJSONResponse(redirect: RedirectResponse): Response {