@lovrozagar/flare 0.1.0

package/src/server-fn-query.ts

@@ -0,0 +1,169 @@
+/**
+ * Client-safe query/mutation option helpers for server functions.
+ * This module must NOT import from ./server-fn/index.ts or ./server-context
+ * to avoid pulling in node:async_hooks on the client.
+ */
+
+export interface PiggybackedQuery {
+	data: unknown;
+	key: unknown[];
+}
+
+interface ServerFnRegistration {
+	id?: string;
+	method?: string;
+	name: string;
+}
+
+interface ServerFnLike<TInput, TOutput> {
+	(input: TInput): Promise<TOutput>;
+	_registration?: ServerFnRegistration;
+}
+
+interface QueryClientLike {
+	invalidateQueries(options: { queryKey: unknown[] }): Promise<void>;
+	setQueryData(key: unknown[], data: unknown): unknown;
+}
+
+interface ServerFnQueryConfig<TInput> {
+	input?: TInput;
+	onRevalidate?: (tags: string[]) => void;
+	queryClient?: QueryClientLike;
+	queryKey?: unknown[];
+	staleTime?: number;
+}
+
+export function serverFnQueryOptions<TInput, TOutput>(
+	serverFn: ServerFnLike<TInput, TOutput>,
+	config?: ServerFnQueryConfig<TInput>,
+): { queryFn: () => Promise<TOutput>; queryKey: unknown[]; staleTime?: number } {
+	const reg = serverFn._registration;
+	const name = reg?.name ?? "unknown";
+	const id = reg?.id ?? name;
+	const queryKey = config?.queryKey ?? [name, config?.input];
+
+	return {
+		queryFn: async () => {
+			if (typeof window === "undefined") {
+				return serverFn(config?.input as TInput);
+			}
+
+			const url = `/_fn/${id}/${name}`;
+			const method = reg?.method ?? "post";
+
+			const res =
+				method === "get"
+					? await fetch(
+							config?.input !== undefined
+								? `${url}?${new URLSearchParams(config.input as Record<string, string>)}`
+								: url,
+						)
+					: await fetch(url, {
+							body: config?.input !== undefined ? JSON.stringify(config.input) : undefined,
+							headers: { "content-type": "application/json" },
+							method: "POST",
+						});
+
+			if (!res.ok) {
+				const body: unknown = await res.json().catch(() => null);
+				const errMsg =
+					typeof body === "object" && body !== null && "message" in body
+						? String((body as Record<string, unknown>).message)
+						: `Request failed (${res.status})`;
+				throw new Error(`Server function request failed: ${errMsg}`);
+			}
+
+			const json = (await res.json()) as {
+				data: TOutput;
+				queries?: Array<{ data: unknown; key: unknown[] }>;
+				revalidatedTags?: string[];
+			};
+
+			if (json.queries && config?.queryClient) {
+				for (const q of json.queries) {
+					if (Array.isArray(q.key)) {
+						config.queryClient.setQueryData(q.key, q.data);
+					}
+				}
+			}
+
+			if (json.revalidatedTags && json.revalidatedTags.length > 0 && config?.onRevalidate) {
+				config.onRevalidate(json.revalidatedTags);
+			}
+
+			return json.data;
+		},
+		queryKey,
+		staleTime: config?.staleTime,
+	};
+}
+
+interface ServerFnMutationConfig {
+	invalidates?: unknown[][];
+	onRevalidate?: (tags: string[]) => void;
+	queryClient?: QueryClientLike;
+}
+
+export function serverFnMutationOptions<TInput, TOutput>(
+	serverFn: ServerFnLike<TInput, TOutput>,
+	config?: ServerFnMutationConfig,
+): {
+	mutationFn: (input: TInput) => Promise<TOutput>;
+	onSuccess?: () => void;
+} {
+	const reg = serverFn._registration;
+	const name = reg?.name ?? "unknown";
+	const id = reg?.id ?? name;
+
+	return {
+		mutationFn: async (input: TInput) => {
+			if (typeof window === "undefined") {
+				return serverFn(input);
+			}
+
+			const url = `/_fn/${id}/${name}`;
+			const res = await fetch(url, {
+				body: input !== undefined ? JSON.stringify(input) : undefined,
+				headers: { "content-type": "application/json" },
+				method: "POST",
+			});
+
+			if (!res.ok) {
+				const body: unknown = await res.json().catch(() => null);
+				const errMsg =
+					typeof body === "object" && body !== null && "message" in body
+						? String((body as Record<string, unknown>).message)
+						: `Request failed (${res.status})`;
+				throw new Error(`Server function request failed: ${errMsg}`);
+			}
+
+			const json = (await res.json()) as {
+				data: TOutput;
+				queries?: Array<{ data: unknown; key: unknown[] }>;
+				revalidatedTags?: string[];
+			};
+
+			if (json.queries && config?.queryClient) {
+				for (const q of json.queries) {
+					if (Array.isArray(q.key)) {
+						config.queryClient.setQueryData(q.key, q.data);
+					}
+				}
+			}
+
+			if (json.revalidatedTags && json.revalidatedTags.length > 0 && config?.onRevalidate) {
+				config.onRevalidate(json.revalidatedTags);
+			}
+
+			return json.data;
+		},
+		onSuccess:
+			config?.invalidates && config.queryClient
+				? () => {
+						for (const key of config.invalidates ?? []) {
+							void config.queryClient?.invalidateQueries({ queryKey: key });
+						}
+					}
+				: undefined,
+	};
+}

package/src/server-handler/etag.ts

@@ -0,0 +1,51 @@
+/**
+ * ETag utilities for store-served responses (SSG, ISR, SSR cache hits).
+ * Uses weak ETags because per-request CSP nonce injection changes
+ * the actual bytes while content is semantically identical.
+ */
+
+/** Compute weak ETag from content using SHA-256, truncated to 16 hex chars */
+export async function computeEtag(body: string): Promise<string> {
+	const encoded = new TextEncoder().encode(body);
+	const hash = await crypto.subtle.digest("SHA-256", encoded);
+	const hex = Array.from(new Uint8Array(hash))
+		.slice(0, 8)
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+	return `W/"${hex}"`;
+}
+
+/**
+ * Weak comparison per RFC 9110 section 8.8.3.2.
+ * Strips W/ prefix, compares opaque tags.
+ * Supports comma-separated If-None-Match values and wildcard *.
+ */
+export function weakMatch(ifNoneMatch: string, etag: string): boolean {
+	const trimmed = ifNoneMatch.trim();
+	if (trimmed === "*") return true;
+
+	const etagNorm = etag.trim().replace(/^W\//, "");
+
+	/* Fast path: single value (no comma) avoids split + array allocation */
+	if (!trimmed.includes(",")) {
+		return trimmed.replace(/^W\//, "") === etagNorm;
+	}
+
+	return trimmed.split(",").some((c) => c.trim().replace(/^W\//, "") === etagNorm);
+}
+
+/**
+ * Build Vary header value. Always includes `x-d` (flare's NDJSON protocol header).
+ * Additional values are appended, with deduplication.
+ */
+export function buildVaryHeader(additional?: string[]): string {
+	const values = ["x-d"];
+	if (additional) {
+		for (const v of additional) {
+			if (!values.some((existing) => existing.toLowerCase() === v.toLowerCase())) {
+				values.push(v);
+			}
+		}
+	}
+	return values.join(", ");
+}

package/src/server-handler/headers.ts

@@ -0,0 +1,5 @@
+export type FlareCacheStatus = "HIT" | "MISS" | "STALE";
+export type FlareRenderMode = "ISR" | "SSG" | "SSR";
+
+export const FLARE_CACHE_HEADER = "Flare-Cache" as const;
+export const FLARE_RENDER_HEADER = "Flare-Render" as const;