@lovrozagar/flare 0.1.0

package/src/state-parser/index.ts

@@ -0,0 +1,266 @@
+import type { HeadConfig } from "../route-builder/types.ts";
+import type { FlareMatchState, FlareState } from "../ssr/index.tsx";
+import type { SearchParams } from "../url/index.ts";
+
+export type { FlareState, FlareMatchState };
+
+export interface DeferredMarker {
+	__deferred: true;
+	key: string;
+}
+
+export interface HydratedMatch {
+	errorName?: string;
+	headConfig?: HeadConfig;
+	loaderData: unknown;
+	matchId: string;
+	preloaderContext?: Record<string, unknown>;
+	virtualPath: string;
+}
+
+export interface ParseResult {
+	matches: HydratedMatch[];
+	params: Record<string, string | string[]>;
+	pathname: string;
+	resolvers: Map<string, DeferredResolver>;
+	search: SearchParams;
+}
+
+export interface DeferredResolver {
+	reject: (error: Error) => void;
+	resolve: (data: unknown) => void;
+}
+
+export function parseFlareState(raw: unknown): FlareState | null {
+	if (raw === null || raw === undefined || typeof raw !== "object") return null;
+
+	const obj = raw as Record<string, unknown>;
+	if (
+		typeof obj.c !== "object" ||
+		obj.c === null ||
+		!Array.isArray(obj.m) ||
+		typeof obj.p !== "string" ||
+		typeof obj.r !== "object" ||
+		obj.r === null ||
+		typeof obj.s !== "object" ||
+		obj.s === null
+	) {
+		return null;
+	}
+
+	return raw as FlareState;
+}
+
+export function isDeferredMarker(value: unknown): value is DeferredMarker {
+	if (value === null || value === undefined || typeof value !== "object") return false;
+	const obj = value as Record<string, unknown>;
+	return obj.__deferred === true && "key" in obj && typeof obj.key === "string";
+}
+
+export function hydrateLoaderData(matchId: string, data: unknown, resolvers: Map<string, DeferredResolver>): unknown {
+	if (data === null || data === undefined) return data;
+	if (typeof data !== "object") return data;
+
+	if (isDeferredMarker(data)) {
+		let resolveFn: (d: unknown) => void = () => {};
+		let rejectFn: (e: Error) => void = () => {};
+		const promise = new Promise<unknown>((resolve, reject) => {
+			resolveFn = resolve;
+			rejectFn = reject;
+		});
+		resolvers.set(`${matchId}:${data.key}`, { reject: rejectFn, resolve: resolveFn });
+		return { __deferred: true, __key: data.key, promise };
+	}
+
+	if (Array.isArray(data)) {
+		return data.map((item) => hydrateLoaderData(matchId, item, resolvers));
+	}
+
+	const obj = data as Record<string, unknown>;
+	const result: Record<string, unknown> = Object.create(null);
+	for (const key of Object.keys(obj)) {
+		if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+		result[key] = hydrateLoaderData(matchId, obj[key], resolvers);
+	}
+	return result;
+}
+
+/**
+ * Register `self.__flare_r(resolverKey, data)` global so streamed `<script>` tags
+ * from SSR deferred resolution can resolve hydrated promise shells.
+ */
+declare global {
+	var __flare_q:
+		| Array<[string, unknown, boolean?]>
+		| { push: (entry: [string, unknown, boolean?]) => number }
+		| undefined;
+	var __flare_qc: Array<[unknown]> | { push: (entry: [unknown]) => number } | undefined;
+	var __flare_r: ((key: string, data: unknown) => void) | undefined;
+	var __flare_re: ((key: string, message: string) => void) | undefined;
+}
+
+/*
+ * Multi-instance registry: supports multiple Flare apps hydrating on the same page.
+ * Each call to installDeferredResolver registers its resolver map. The global
+ * __flare_r/__flare_re/__flare_q search ALL active maps when resolving a key.
+ * Globals are only cleaned when every active map is drained AND no pending entries remain.
+ */
+const activeInstances = new Set<Map<string, DeferredResolver>>();
+const pendingEntries: Array<[string, unknown, boolean?]> = [];
+
+function resolveOrBuffer(key: string, data: unknown, isError: boolean): void {
+	for (const m of activeInstances) {
+		const resolver = m.get(key);
+		if (resolver) {
+			if (isError) {
+				resolver.reject(new Error(data as string));
+			} else {
+				resolver.resolve(data);
+			}
+			m.delete(key);
+			return;
+		}
+	}
+	pendingEntries.push(isError ? [key, data, true] : [key, data]);
+}
+
+function cleanupIfAllEmpty(): void {
+	if (pendingEntries.length > 0) return;
+	for (const m of activeInstances) {
+		if (m.size > 0) return;
+	}
+	globalThis.__flare_r = undefined;
+	globalThis.__flare_re = undefined;
+	globalThis.__flare_q = undefined;
+	activeInstances.clear();
+}
+
+/**
+ * Drain buffered deferred chunks from SSR streamed `<script>` tags,
+ * then install live resolver for any late-arriving chunks.
+ *
+ * SSR scripts push `[key, data]` (or `[key, msg, true]` for errors)
+ * into `self.__flare_q` array. This function drains them, then replaces
+ * the array push with a direct resolver so future chunks resolve immediately.
+ *
+ * Safe for multiple Flare instances on the same page — resolvers compose
+ * rather than overwrite, and globals are only cleaned when all are drained.
+ */
+export function installDeferredResolver(resolvers: Map<string, DeferredResolver>): void {
+	if (typeof globalThis === "undefined") return;
+
+	/* Reset registry if globals were cleaned externally (e.g. tests) */
+	if (!globalThis.__flare_r && activeInstances.size > 0) {
+		activeInstances.clear();
+		pendingEntries.length = 0;
+	}
+
+	activeInstances.add(resolvers);
+
+	/* Drain any buffered entries from SSR script tags */
+	const queue = globalThis.__flare_q;
+	if (Array.isArray(queue)) {
+		for (const entry of queue) {
+			resolveOrBuffer(entry[0], entry[1], Boolean(entry[2]));
+		}
+	}
+
+	/* Drain pending entries — new instance may have matching resolvers */
+	if (pendingEntries.length > 0) {
+		const pending = [...pendingEntries];
+		pendingEntries.length = 0;
+		for (const entry of pending) {
+			resolveOrBuffer(entry[0], entry[1], Boolean(entry[2]));
+		}
+	}
+
+	/* Install live resolvers for chunks that stream after hydration */
+	globalThis.__flare_r = (key: string, data: unknown) => {
+		resolveOrBuffer(key, data, false);
+		cleanupIfAllEmpty();
+	};
+	globalThis.__flare_re = (key: string, message: string) => {
+		resolveOrBuffer(key, message, true);
+		cleanupIfAllEmpty();
+	};
+
+	/*
+	 * Trap __flare_q so late-arriving SSR script pushes resolve immediately.
+	 * SSR scripts do `(self.__flare_q=self.__flare_q||[]).push([...])` — after
+	 * drain, new pushes must route through the live resolver, not the array.
+	 */
+	globalThis.__flare_q = {
+		push(entry: [string, unknown, boolean?]) {
+			resolveOrBuffer(entry[0], entry[1], Boolean(entry[2]));
+			cleanupIfAllEmpty();
+			return 0;
+		},
+	};
+
+	/* If no resolvers needed (all data was instant), clean up immediately */
+	cleanupIfAllEmpty();
+}
+
+/**
+ * Drain buffered deferred QC entries from SSR streamed `<script>` tags,
+ * then install live proxy for late-arriving entries.
+ *
+ * SSR scripts push `[{data, key, staleTime?}]` into `self.__flare_qc` array.
+ * This function drains them, then replaces the array with a push-proxy
+ * so future scripts hydrate immediately.
+ */
+export function installQueryCacheResolver(queryClient: unknown): void {
+	if (typeof globalThis === "undefined") return;
+
+	const qc = queryClient as {
+		setQueryData: (key: unknown[], data: unknown) => void;
+		setQueryDefaults: (key: unknown[], defaults: { staleTime: number }) => void;
+	};
+
+	function applyEntry(entry: unknown): void {
+		if (typeof entry !== "object" || entry === null) return;
+		const e = entry as { data: unknown; key: unknown[]; staleTime?: number };
+		if (!Array.isArray(e.key)) return;
+		qc.setQueryData(e.key, e.data);
+		if (typeof e.staleTime === "number" && Number.isFinite(e.staleTime) && e.staleTime >= 0) {
+			qc.setQueryDefaults(e.key, { staleTime: e.staleTime });
+		}
+	}
+
+	/* Drain any buffered entries from SSR script tags */
+	const queue = globalThis.__flare_qc;
+	if (Array.isArray(queue)) {
+		for (const entry of queue) {
+			applyEntry(entry[0]);
+		}
+	}
+
+	/* Install push-proxy for late-arriving SSR scripts */
+	globalThis.__flare_qc = {
+		push(entry: [unknown]) {
+			applyEntry(entry[0]);
+			return 0;
+		},
+	};
+}
+
+export function hydrateFlareState(state: FlareState): ParseResult {
+	const resolvers = new Map<string, DeferredResolver>();
+
+	const matches: HydratedMatch[] = state.m.map((match) => ({
+		errorName: match.x,
+		headConfig: match.h,
+		loaderData: hydrateLoaderData(match.i, match.d, resolvers),
+		matchId: match.i,
+		preloaderContext: match.p,
+		virtualPath: match.v,
+	}));
+
+	return {
+		matches,
+		params: state.r,
+		pathname: state.p,
+		resolvers,
+		search: state.s,
+	};
+}

package/src/store/filesystem.ts

@@ -0,0 +1,131 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { FlareStore, FlareStoreEntry } from "./index.ts";
+
+interface StoredEntry extends FlareStoreEntry {
+	expiresAt?: number;
+}
+
+/**
+ * Encode a store key to a flat filename.
+ * `static:/about` → `static/_about.json`
+ * `flare:_root_/[id]:{"id":"42"}` → `loader/_root___[id]__{"id":"42"}.json`
+ */
+export function keyToPath(key: string): string {
+	let subdir: string;
+	let rest: string;
+
+	if (key.startsWith("static:")) {
+		subdir = "static";
+		rest = key.slice(7);
+	} else if (key.startsWith("cdn:")) {
+		subdir = "cdn";
+		rest = key.slice(4);
+	} else if (key.startsWith("flare:")) {
+		subdir = "loader";
+		rest = key.slice(6);
+	} else {
+		subdir = "other";
+		rest = key;
+	}
+
+	/* flatten slashes and colons to underscores to keep files flat */
+	const encoded = rest.replace(/\//g, "_").replace(/:/g, "__");
+	return `${subdir}/${encoded}.json`;
+}
+
+export function createFileSystemStore(config?: { cacheDir?: string }): FlareStore {
+	const baseDir = config?.cacheDir ?? ".flare/cache";
+
+	function fullPath(key: string): string {
+		return join(baseDir, keyToPath(key));
+	}
+
+	function ensureDir(filePath: string): void {
+		const dir = dirname(filePath);
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+		}
+	}
+
+	function readEntry(filePath: string): StoredEntry | null {
+		try {
+			const raw = readFileSync(filePath, "utf-8");
+			return JSON.parse(raw) as StoredEntry;
+		} catch {
+			return null;
+		}
+	}
+
+	function removeFile(fp: string): void {
+		try {
+			rmSync(fp);
+		} catch {
+			/* file may not exist */
+		}
+	}
+
+	return {
+		delete(key: string): Promise<void> {
+			removeFile(fullPath(key));
+			return Promise.resolve();
+		},
+
+		deleteByKeys(keys: string[]): Promise<void> {
+			for (const key of keys) {
+				removeFile(fullPath(key));
+			}
+			return Promise.resolve();
+		},
+
+		deleteByTags(tags: string[]): Promise<void> {
+			const tagSet = new Set(tags);
+			const subdirs = ["static", "loader", "cdn", "other"];
+			for (const sub of subdirs) {
+				const dir = join(baseDir, sub);
+				if (!existsSync(dir)) continue;
+
+				const files = readdirSync(dir);
+				for (const file of files) {
+					if (!file.endsWith(".json")) continue;
+					const entry = readEntry(join(dir, file));
+					if (entry?.tags?.some((t) => tagSet.has(t))) {
+						removeFile(join(dir, file));
+					}
+				}
+			}
+			return Promise.resolve();
+		},
+
+		get(key: string): Promise<FlareStoreEntry | null> {
+			const fp = fullPath(key);
+			const stored = readEntry(fp);
+			if (!stored) return Promise.resolve(null);
+
+			if (stored.expiresAt !== undefined && Date.now() >= stored.expiresAt) {
+				removeFile(fp);
+				return Promise.resolve(null);
+			}
+
+			const result: FlareStoreEntry = {
+				data: stored.data,
+				storedAt: stored.storedAt,
+			};
+			if (stored.tags) result.tags = stored.tags;
+			return Promise.resolve(result);
+		},
+
+		set(key: string, entry: FlareStoreEntry, ttl?: number): Promise<void> {
+			const fp = fullPath(key);
+			ensureDir(fp);
+
+			const stored: StoredEntry = { ...entry };
+			if (ttl !== undefined) {
+				stored.expiresAt = Date.now() + ttl * 1000;
+			}
+
+			writeFileSync(fp, JSON.stringify(stored));
+			return Promise.resolve();
+		},
+	};
+}

package/src/store/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Unified store — platform-agnostic KV interface for both
+ * loader-data cache and ISR/static page artifacts.
+ *
+ * Key prefixes (`static:`, `flare:`) namespace entry types internally;
+ * users configure a single store adapter.
+ */
+
+export interface FlareStoreEntry {
+	data: unknown;
+	storedAt: number;
+	tags?: string[];
+}
+
+export interface FlareStore {
+	delete(key: string): Promise<void>;
+	deleteByKeys?(keys: string[], callerData?: unknown): Promise<void>;
+	deleteByTags(tags: string[], callerData?: unknown): Promise<void>;
+	get(key: string): Promise<FlareStoreEntry | null>;
+	set(key: string, entry: FlareStoreEntry, ttl?: number): Promise<void>;
+}
+
+/** Internal shape for ISR/static entries stored as `FlareStoreEntry.data` */
+export interface StaticEntryData {
+	etag?: string;
+	headers: Record<string, string>;
+	html: string;
+	ndjson: string;
+}