@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/modules/file-routes/domain/index.ts

@@ -0,0 +1,63 @@
+export {
+	isLoaderError,
+	isNotFoundError,
+	LoaderError,
+	loaderErrorBody,
+	NotFoundError,
+	notFound,
+} from "./errors";
+export type { FileRoute, FileRouteMatch, RouteManifest } from "./models";
+export {
+	type ApiRouteContext,
+	type ApiRouteHandler,
+	type ApiRouteModule,
+	type ApiRouteModules,
+	buildRouteManifest,
+	contentMeta,
+	createApiRouteHandler,
+	createLoaderHandler,
+	createRouteActionHandler,
+	DEFER_MARKER,
+	DEFERRED,
+	type DeferOptions,
+	type Deferred,
+	defer,
+	deferAll,
+	deferMarkerKey,
+	deferResolveScript,
+	deferredRegistry,
+	type ExtractParams,
+	expandStaticRoutes,
+	extractDeferred,
+	type GeneratedRoutes,
+	type GeneratedSearch,
+	type GenerateStaticParamsFn,
+	generateApiTypes,
+	generateRouteTypes,
+	type HasParams,
+	href,
+	isDeferred,
+	isLoaderRequest,
+	type LeafMapped,
+	LOADER_ENDPOINT,
+	matchAllFileRoutes,
+	matchFileRoute,
+	materializeDeferred,
+	orderDeferred,
+	type ParamsFor,
+	pathFor,
+	type RouteActionContext,
+	type RouteActionFn,
+	type RouteLoaderFn,
+	type RouteParamsFor,
+	type RoutePath,
+	readDeferredRegistry,
+	relativePath,
+	renderMarkdown,
+	resolveDeferred,
+	route,
+	routePaths,
+	routePattern,
+	runFileRouteLoader,
+	type SearchFor,
+} from "./operations";

package/src/app/modules/file-routes/domain/models/index.ts

@@ -0,0 +1 @@
+export type { FileRoute, FileRouteMatch, RouteManifest } from "./route";

package/src/app/modules/file-routes/domain/models/route.ts

@@ -0,0 +1,38 @@
+/**
+ * File Route Models
+ * Manifest entries produced by scanning the routes directory
+ */
+
+export interface FileRoute {
+	/** URL pattern — "/users/:id", "/blog/*slug", "/" */
+	path: string;
+	/** Page module file (relative to routesDir root) */
+	file: string;
+	/** "api" for *.api.ts endpoints — page routes are the default */
+	kind?: "page" | "api" | "content";
+	/** Layout module files, outermost → innermost */
+	layouts: string[];
+	/** Nearest error boundary module (walked up) */
+	error?: string;
+	/** Nearest loading fallback module (walked up) */
+	loading?: string;
+	/** Nearest not-found module (walked up) */
+	notFound?: string;
+	/** `middleware.ts` convention files, outermost → innermost (dir-scoped) */
+	middleware?: string[];
+	/** Param names extracted from the pattern — ["id"], ["slug"] */
+	params: string[];
+	/** `(.)name` intercepted route — same URL, flagged for modal-style rendering */
+	intercepted?: true;
+	/** `@name` parallel-route slot — renders alongside siblings at the same URL */
+	slot?: string;
+	/** Match specificity — higher wins when patterns overlap */
+	score: number;
+}
+
+export interface FileRouteMatch {
+	route: FileRoute;
+	params: Record<string, string>;
+}
+
+export type RouteManifest = FileRoute[];

package/src/app/modules/file-routes/domain/operations/actions.ts

@@ -0,0 +1,107 @@
+/**
+ * Route Actions
+ * Page modules export `action` — a POST to the route URL runs it
+ * with the request, params and parsed FormData (Next server-action
+ * equivalent without a separate endpoint):
+ *
+ *   // src/routes/login.tsx
+ *   export const action = async ({ form, params }) => {
+ *     await signIn(form.get("user"));
+ *     return new Response(null, { status: 303, headers: { Location: "/" } });
+ *   };
+ */
+
+import type { RouteManifest } from "../models";
+import type { ApiRouteModules } from "./api";
+import { extractDeferred } from "./defer";
+import { runFileRouteLoader } from "./loader";
+import { matchFileRoute } from "./match";
+
+export interface RouteActionContext {
+	request: Request;
+	params: Record<string, string>;
+	/** Parsed form body — empty FormData when the body is not a form */
+	form: FormData;
+}
+
+export type RouteActionFn = (
+	ctx: RouteActionContext,
+) => Response | unknown | Promise<Response | unknown>;
+
+const toResponse = (value: unknown): Response => {
+	if (value instanceof Response) return value;
+	return new Response(JSON.stringify(value), {
+		headers: { "Content-Type": "application/json" },
+	});
+};
+
+/**
+ * Dispatch non-GET page requests to the matched route's `action`
+ * export — returns null when the route has no action
+ */
+export const createRouteActionHandler = (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+): ((request: Request) => Promise<Response | null>) => {
+	const pages = manifest.filter((r) => r.kind !== "api");
+
+	return async (request: Request): Promise<Response | null> => {
+		if (request.method === "GET" || request.method === "HEAD") return null;
+		const { pathname } = new URL(request.url);
+		const match = matchFileRoute(pathname, pages);
+		if (!match) return null;
+
+		const entry = modules[match.route.file] ?? modules[`/${match.route.file}`];
+		if (!entry) return null;
+		const mod = (await Promise.resolve(
+			typeof entry === "function" ? entry() : entry,
+		)) as {
+			action?: RouteActionFn;
+			loader?: (ctx: {
+				request: Request;
+				params: Record<string, string>;
+			}) => unknown | Promise<unknown>;
+		};
+		if (!mod.action) return null;
+
+		let form = new FormData();
+		const type = request.headers.get("content-type") ?? "";
+		if (type.includes("form")) {
+			form = await request.formData();
+		}
+		const response = toResponse(
+			await mod.action({ request, params: match.params, form }),
+		);
+
+		// Single-flight — a mutation response carries the route's
+		// revalidated loader data so the client updates without a
+		// second request (opt-in via the x-sf-flight header)
+		if (request.headers.get("x-sf-flight") && mod.loader) {
+			const data = await runFileRouteLoader(
+				pathname,
+				manifest,
+				modules,
+				request,
+			);
+			const registry = new Map<string, Promise<unknown>>();
+			const marked = extractDeferred(data, registry);
+			const deferred: Record<string, unknown> = {};
+			for (const [k, p] of registry) deferred[k] = await p;
+			const contentType = response.headers.get("Content-Type") ?? "";
+			if (response.ok && contentType.includes("application/json")) {
+				const body = (await response.clone().json()) as object;
+				return Response.json(
+					{
+						...body,
+						__flight: {
+							data: marked,
+							...(Object.keys(deferred).length > 0 ? { deferred } : {}),
+						},
+					},
+					response,
+				);
+			}
+		}
+		return response;
+	};
+};

package/src/app/modules/file-routes/domain/operations/api.ts

@@ -0,0 +1,87 @@
+/**
+ * File API Routes
+ * `*.api.ts` modules inside routesDir export HTTP method handlers:
+ *
+ *   // src/routes/users/[id].api.ts
+ *   export const GET = (req, { params }) =>
+ *     Response.json({ id: params.id });
+ *   export const POST = async (req) => new Response("created", { status: 201 });
+ *   export default (req) => Response.json({ ok: true }); // any method
+ */
+
+import type { RouteManifest } from "../models";
+import { matchFileRoute } from "./match";
+
+export interface ApiRouteContext {
+	params: Record<string, string>;
+}
+
+export type ApiRouteHandler = (
+	request: Request,
+	context: ApiRouteContext,
+) => Response | unknown | Promise<Response | unknown>;
+
+export interface ApiRouteModule {
+	default?: ApiRouteHandler;
+	GET?: ApiRouteHandler;
+	POST?: ApiRouteHandler;
+	PUT?: ApiRouteHandler;
+	PATCH?: ApiRouteHandler;
+	DELETE?: ApiRouteHandler;
+	HEAD?: ApiRouteHandler;
+	OPTIONS?: ApiRouteHandler;
+	[key: string]: unknown;
+}
+
+export type ApiRouteModules = Record<
+	string,
+	ApiRouteModule | Promise<ApiRouteModule> | (() => Promise<ApiRouteModule>)
+>;
+
+const toResponse = (value: unknown): Response => {
+	if (value instanceof Response) return value;
+	return new Response(JSON.stringify(value), {
+		headers: { "Content-Type": "application/json" },
+	});
+};
+
+/**
+ * Match incoming requests against `*.api` manifest entries and dispatch
+ * to the module's method handler — returns null when no api route
+ * matches so the caller can fall through to the render pipeline
+ */
+export const createApiRouteHandler = (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+): ((request: Request) => Promise<Response | null>) => {
+	const apiRoutes = manifest.filter((r) => r.kind === "api");
+
+	return async (request: Request): Promise<Response | null> => {
+		const { pathname } = new URL(request.url);
+		const match = matchFileRoute(pathname, apiRoutes, "api");
+		if (!match) return null;
+
+		const entry = modules[match.route.file] ?? modules[`/${match.route.file}`];
+		if (!entry) return null;
+		const mod = (await Promise.resolve(
+			typeof entry === "function" ? entry() : entry,
+		)) as ApiRouteModule;
+
+		const handler = (mod[request.method] ?? mod.default) as
+			| ApiRouteHandler
+			| undefined;
+		if (!handler) {
+			return new Response(
+				JSON.stringify({
+					error: {
+						code: "METHOD_NOT_ALLOWED",
+						message: `${match.route.path} does not handle ${request.method}`,
+					},
+				}),
+				{ status: 405, headers: { "Content-Type": "application/json" } },
+			);
+		}
+
+		return toResponse(await handler(request, { params: match.params }));
+	};
+};

package/src/app/modules/file-routes/domain/operations/codegen.ts

@@ -0,0 +1,76 @@
+/**
+ * Route Type Codegen
+ * Emits a .d.ts augmenting GeneratedRoutes — written by `solid generate`
+ * so route(), <Link to>, and useParams are typed path-by-path
+ * (the routeTree.gen equivalent)
+ */
+
+import type { RouteManifest } from "../models";
+
+export const generateRouteTypes = (manifest: RouteManifest): string => {
+	const pages = manifest.filter((r) => r.kind !== "api");
+	const entries = pages
+		.map(
+			(r) =>
+				`		${JSON.stringify(r.path)}: ${
+					r.params.length
+						? `{ ${r.params.map((p) => `${JSON.stringify(p)}: string`).join("; ")} }`
+						: "Record<string, never>"
+				};`,
+		)
+		.join("\n");
+	return [
+		"// Generated by `solid generate` — do not edit",
+		'declare module "@wrikka/solid-framework/app" {',
+		"	interface GeneratedRoutes {",
+		entries || "		// no routes",
+		"	}",
+		"}",
+		"export {};",
+		"",
+	].join("\n");
+};
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+
+/**
+ * Api Type Codegen — emits GeneratedApiPaths for api routes so
+ * createApiClient() gets typed paths + methods; methods are detected
+ * statically by scanning each *.api.ts file for method exports
+ */
+export const generateApiTypes = (
+	manifest: RouteManifest,
+	readFile?: (file: string) => string,
+): string => {
+	const apis = manifest.filter((r) => r.kind === "api");
+	const entries = apis
+		.map((r) => {
+			let methods: readonly string[] = HTTP_METHODS;
+			if (readFile) {
+				try {
+					const src = readFile(r.file);
+					const found = HTTP_METHODS.filter((m) =>
+						new RegExp(`export (const|function|async function) ${m}\\b`).test(
+							src,
+						),
+					);
+					if (found.length) methods = found;
+				} catch {
+					// unreadable file — fall back to all methods
+				}
+			}
+			const shape = methods.map((m) => `${m}: unknown`).join("; ");
+			return `		${JSON.stringify(r.path)}: { ${shape} };`;
+		})
+		.join("\n");
+	return [
+		"// Generated by `solid generate` — do not edit",
+		'declare module "@wrikka/solid-framework/app" {',
+		"	interface GeneratedApiPaths {",
+		entries || "		// no api routes",
+		"	}",
+		"}",
+		"export {};",
+		"",
+	].join("\n");
+};

package/src/app/modules/file-routes/domain/operations/content.ts

@@ -0,0 +1,61 @@
+/**
+ * Content routes — `.md` / `.mdx` files map to `kind: "content"`;
+ * `renderMarkdown` turns raw source into an HTML string. Minimal
+ * commonmark subset: headings, bold/italic, code, links, lists, p
+ */
+
+const esc = (s: string): string =>
+	s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const inline = (s: string): string =>
+	esc(s)
+		.replace(/`([^`]+)`/g, "<code>$1</code>")
+		.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+		.replace(/\*([^*]+)\*/g, "<em>$1</em>")
+		.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+export const renderMarkdown = (src: string): string => {
+	const blocks = src.replace(/\r\n/g, "\n").split(/\n{2,}/);
+	const out: string[] = [];
+	for (const block of blocks) {
+		const lines = block.split("\n");
+		const first = lines[0] ?? "";
+		const heading = first.match(/^(#{1,4})\s+(.*)/);
+		if (heading) {
+			out.push(
+				`<h${heading[1].length}>${inline(heading[2])}</h${heading[1].length}>`,
+			);
+			continue;
+		}
+		if (/^\s*```/.test(first)) {
+			out.push(`<pre><code>${esc(lines.slice(1, -1).join("\n"))}</code></pre>`);
+			continue;
+		}
+		if (lines.every((l) => /^\s*[-*]\s+/.test(l))) {
+			out.push(
+				`<ul>${lines
+					.map((l) => `<li>${inline(l.replace(/^\s*[-*]\s+/, ""))}</li>`)
+					.join("")}</ul>`,
+			);
+			continue;
+		}
+		out.push(`<p>${inline(block.replace(/\n/g, " "))}</p>`);
+	}
+	return out.join("\n");
+};
+
+/** Pull title/description out of a markdown doc for head/meta */
+export const contentMeta = (
+	src: string,
+): { title?: string; description?: string } => {
+	const title = src.match(/^#\s+(.+)$/m)?.[1]?.trim();
+	const description = src
+		.split(/\n{2,}/)
+		.map((b) => b.trim())
+		.find((b) => b && !b.startsWith("#") && !b.startsWith("```"))
+		?.slice(0, 160);
+	return {
+		...(title ? { title } : {}),
+		...(description ? { description } : {}),
+	};
+};

package/src/app/modules/file-routes/domain/operations/defer.ts

@@ -0,0 +1,245 @@
+/**
+ * Deferred Loader Values
+ * `defer(promise)` marks a value inside a loader result that resolves
+ * after the shell renders — the SSR pipeline streams a resolve script
+ * per key once the promise settles (stream mode) or awaits all before
+ * serializing hydration (ssr/data-only):
+ *
+ *   export const loader = () => ({
+ *     fast: db.quick(),
+ *     slow: defer(db.slowQuery()),   // streams in later
+ *   });
+ */
+
+import type { Resource } from "solid-js";
+
+export const DEFERRED = Symbol.for("sf.deferred");
+
+export interface Deferred<T> {
+	readonly [DEFERRED]: Promise<T>;
+	/** Stream priority — "high" resolves before "low" */
+	readonly lane?: "high" | "low";
+}
+
+export interface DeferOptions<T> {
+	/** Resolve with `fallback` when the value takes longer than N ms */
+	timeout?: number;
+	fallback?: T;
+	/** Stream priority lane (default "high") */
+	lane?: "high" | "low";
+	/** Retry the promise N times on rejection (attempts, not retries) */
+	retry?: number;
+	/** Abort → resolve with `fallback` when the signal fires */
+	signal?: AbortSignal;
+}
+
+/**
+ * Wrap a promise as a deferred loader value —
+ * `defer(q, { timeout: 3000, fallback: [] })` bounds the wait
+ */
+export const defer = <T>(
+	value: Promise<T> | T | (() => Promise<T>),
+	options?: DeferOptions<T>,
+): Deferred<T> => {
+	const attempt =
+		typeof value === "function" ? (value as () => Promise<T>) : null;
+	let base: Promise<T>;
+	if (attempt && options?.retry) {
+		// retry re-invokes the thunk — `defer(() => q(), { retry: 2 })`
+		base = Array.from({ length: options.retry }).reduce<Promise<T>>(
+			(acc) => acc.catch(attempt),
+			attempt(),
+		);
+	} else {
+		base = Promise.resolve(attempt ? attempt() : (value as Promise<T> | T));
+	}
+	if (options?.signal) {
+		base = Promise.race([
+			base,
+			new Promise<T>((resolve) => {
+				if (options.signal!.aborted) resolve(options.fallback as T);
+				options.signal!.addEventListener("abort", () =>
+					resolve(options.fallback as T),
+				);
+			}),
+		]);
+	}
+	return {
+		[DEFERRED]:
+			options?.timeout === undefined
+				? base
+				: Promise.race([
+						base,
+						new Promise<T>((resolve) =>
+							setTimeout(() => resolve(options.fallback as T), options.timeout),
+						),
+					]),
+		...(options?.lane ? { lane: options.lane } : {}),
+	};
+};
+
+/** Wrap every leaf — `deferAll({ a: q1, b: q2 })` → `{a: Deferred, b: Deferred}` */
+export const deferAll = <T extends Record<string, Promise<unknown> | unknown>>(
+	obj: T,
+	options?: DeferOptions<unknown>,
+): { [K in keyof T]: Deferred<T[K]> } => {
+	const out = {} as { [K in keyof T]: Deferred<T[K]> };
+	for (const k of Object.keys(obj) as (keyof T)[]) {
+		out[k] = defer(obj[k], options as DeferOptions<T[keyof T]>);
+	}
+	return out;
+};
+
+/**
+ * Registry keys in stream order — "low" lane deferreds resolve last
+ * so their `<script>` tags ship after the priority ones
+ */
+export const orderDeferred = (registry: DeferredRegistry): string[] =>
+	[...registry.entries()]
+		.sort(
+			(a, b) =>
+				((a[1] as { lane?: string }).lane === "low" ? 1 : 0) -
+				((b[1] as { lane?: string }).lane === "low" ? 1 : 0),
+		)
+		.map(([key]) => key);
+
+export const isDeferred = (value: unknown): value is Deferred<unknown> =>
+	typeof value === "object" && value !== null && DEFERRED in value;
+
+/** Marker object serialized in place of a deferred value */
+export const DEFER_MARKER = "__sfDefer";
+
+export type DeferredRegistry = Map<string, Promise<unknown>>;
+
+/**
+ * Deferred promise registry attached (non-enumerably) to a hydration
+ * payload — JSON serialization skips it
+ */
+export const deferredRegistry = (hydration: object): DeferredRegistry => {
+	const holder = hydration as { __deferred?: DeferredRegistry };
+	if (!holder.__deferred) {
+		Object.defineProperty(holder, "__deferred", {
+			value: new Map<string, Promise<unknown>>(),
+			enumerable: false,
+		});
+	}
+	return holder.__deferred as DeferredRegistry;
+};
+
+export const readDeferredRegistry = (
+	hydration: object,
+): DeferredRegistry | undefined =>
+	(hydration as { __deferred?: DeferredRegistry }).__deferred;
+
+let counter = 0;
+
+/**
+ * Deep-walk a loader result — replace every Deferred leaf with a
+ * `{__sfDefer: key}` marker and register its promise
+ */
+export const extractDeferred = (
+	value: unknown,
+	registry: DeferredRegistry,
+): unknown => {
+	if (isDeferred(value)) {
+		const key = `d${counter++}`;
+		const promise = value[DEFERRED];
+		if (value.lane) {
+			(promise as { lane?: string }).lane = value.lane;
+		}
+		registry.set(key, promise);
+		return { [DEFER_MARKER]: key };
+	}
+	if (Array.isArray(value)) {
+		return value.map((item) => extractDeferred(item, registry));
+	}
+	if (value !== null && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value)) {
+			out[k] = extractDeferred(v, registry);
+		}
+		return out;
+	}
+	return value;
+};
+
+/** Marker key of a serialized defer placeholder — undefined otherwise */
+export const deferMarkerKey = (value: unknown): string | undefined =>
+	typeof value === "object" && value !== null
+		? ((value as Record<string, unknown>)[DEFER_MARKER] as string | undefined)
+		: undefined;
+
+/**
+ * Loader-data shape after `useLoaderData` — every Deferred<T> leaf
+ * becomes its own Resource<T> so components suspend per field, not
+ * per route
+ */
+export type LeafMapped<T> =
+	T extends Deferred<infer V>
+		? Resource<V>
+		: T extends readonly (infer I)[]
+			? LeafMapped<I>[]
+			: T extends object
+				? { [K in keyof T]: LeafMapped<T[K]> }
+				: T;
+
+/**
+ * Deep-walk a loader result on the server — await every Deferred leaf
+ * so components render real values (the payload keeps markers)
+ */
+export const resolveDeferred = async (value: unknown): Promise<unknown> => {
+	if (isDeferred(value)) return value[DEFERRED];
+	if (Array.isArray(value)) {
+		return Promise.all(value.map((item) => resolveDeferred(item)));
+	}
+	if (value !== null && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value)) {
+			out[k] = await resolveDeferred(v);
+		}
+		return out;
+	}
+	return value;
+};
+
+const markerKey = deferMarkerKey;
+
+/** Script tag resolving one deferred key at the end of the stream */
+export const deferResolveScript = (key: string, value: unknown): string =>
+	`<script>window.__sfDeferResolve(${JSON.stringify(key)},${JSON.stringify(
+		value,
+	).replace(/</g, "\\u003c")})</script>`;
+
+declare global {
+	interface Window {
+		__sfDeferWait?: (key: string) => Promise<unknown>;
+	}
+}
+
+/**
+ * Deep-walk a client-side loader result — replace every defer marker
+ * with the awaited value (hydration `deferred` map or streamed waits)
+ */
+export const materializeDeferred = async (
+	value: unknown,
+	resolved: Record<string, unknown> = {},
+): Promise<unknown> => {
+	const key = markerKey(value);
+	if (key !== undefined) {
+		if (key in resolved) return resolved[key];
+		return window.__sfDeferWait?.(key);
+	}
+	if (Array.isArray(value)) {
+		return Promise.all(
+			value.map((item) => materializeDeferred(item, resolved)),
+		);
+	}
+	if (value !== null && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value)) {
+			out[k] = await materializeDeferred(v, resolved);
+		}
+		return out;
+	}
+	return value;
+};