@wrikka/solid-framework 0.0.0-stage → 0.15.0

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

@@ -0,0 +1,65 @@
+export {
+	createRouteActionHandler,
+	type RouteActionContext,
+	type RouteActionFn,
+} from "./actions";
+export {
+	type ApiRouteContext,
+	type ApiRouteHandler,
+	type ApiRouteModule,
+	type ApiRouteModules,
+	createApiRouteHandler,
+} from "./api";
+export { generateApiTypes, generateRouteTypes } from "./codegen";
+export { contentMeta, renderMarkdown } from "./content";
+export {
+	DEFER_MARKER,
+	DEFERRED,
+	type DeferOptions,
+	type Deferred,
+	defer,
+	deferAll,
+	deferMarkerKey,
+	deferResolveScript,
+	deferredRegistry,
+	extractDeferred,
+	isDeferred,
+	type LeafMapped,
+	materializeDeferred,
+	orderDeferred,
+	readDeferredRegistry,
+	resolveDeferred,
+} from "./defer";
+export {
+	createLoaderHandler,
+	isLoaderRequest,
+	LOADER_ENDPOINT,
+	type LoaderContext,
+	type PageModuleWithLoader,
+	type RouteLoaderFn,
+	runFileRouteLoader,
+} from "./loader";
+export { buildRouteManifest } from "./manifest";
+export { matchAllFileRoutes, matchFileRoute, routePaths } from "./match";
+export {
+	expandStaticRoutes,
+	type GenerateStaticParamsFn,
+} from "./static-params";
+export type {
+	ExtractParams,
+	GeneratedRoutes,
+	GeneratedSearch,
+	HasParams,
+	ParamsFor,
+	RouteParamsFor,
+	RoutePath,
+	SearchFor,
+} from "./typed";
+export {
+	href,
+	link,
+	pathFor,
+	relativePath,
+	route,
+	routePattern,
+} from "./typed";

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

@@ -0,0 +1,138 @@
+/**
+ * Route Loader Endpoint
+ * `/_server/loader?path=/users/42` — runs the matched page module's
+ * `loader` export and returns its data as JSON. Used by client-side
+ * navigation so loaders re-run without a full page load
+ *
+ *   // src/routes/users/[id].tsx
+ *   export const loader = async ({ params }) => fetchUser(params.id);
+ */
+
+import { useRequestEvent as requestEvent } from "#server/modules/http";
+import { loaderErrorBody } from "../errors";
+import type { RouteManifest } from "../models";
+import type { ApiRouteModules } from "./api";
+import { extractDeferred } from "./defer";
+import { matchFileRoute } from "./match";
+
+export const LOADER_ENDPOINT = "/_server/loader";
+
+export interface LoaderContext<S = Record<string, unknown>> {
+	request: Request;
+	params: Record<string, string>;
+	/**
+	 * Parent loader data — when layouts export `loader`, the chain
+	 * runs outermost→innermost and each receives the previous result
+	 */
+	parent?: unknown;
+	/** Middleware-written request state — `state.user`, `state.tenant` */
+	state: S;
+}
+
+export type RouteLoaderFn = (ctx: LoaderContext) => unknown | Promise<unknown>;
+
+export interface PageModuleWithLoader {
+	default?: unknown;
+	loader?: RouteLoaderFn;
+	/**
+	 * Guard hook — runs before `loader`; return a Response to
+	 * short-circuit (redirect, 401) or throw to abort the route
+	 */
+	beforeLoad?: (ctx: LoaderContext) => unknown | Response | Promise<unknown>;
+	[key: string]: unknown;
+}
+
+export const isLoaderRequest = (request: Request): boolean =>
+	new URL(request.url).pathname === LOADER_ENDPOINT;
+
+const loadModule = async (
+	modules: ApiRouteModules,
+	file: string,
+): Promise<PageModuleWithLoader | undefined> => {
+	const entry = modules[file] ?? modules[`/${file}`];
+	if (!entry) return undefined;
+	return (await Promise.resolve(
+		typeof entry === "function" ? entry() : entry,
+	)) as PageModuleWithLoader;
+};
+
+/**
+ * Run the loader chain for a matched route — layout loaders run
+ * outermost→innermost first and each receives the previous result as
+ * `ctx.parent`; the page loader runs last and its result is returned
+ */
+export const runFileRouteLoader = async (
+	path: string,
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+	request: Request,
+): Promise<unknown> => {
+	const pages = manifest.filter((r) => r.kind !== "api");
+	const match = matchFileRoute(path, pages);
+	if (!match) return undefined;
+
+	let parent: unknown;
+	const state = requestEvent()?.state ?? {};
+	for (const file of [...match.route.layouts, match.route.file]) {
+		const mod = await loadModule(modules, file);
+		if (!mod) continue;
+		if (mod.beforeLoad) {
+			const verdict = await mod.beforeLoad({
+				request,
+				params: match.params,
+				parent,
+				state,
+			});
+			if (verdict instanceof Response) throw verdict;
+		}
+		if (mod.loader) {
+			parent = await mod.loader({
+				request,
+				params: match.params,
+				parent,
+				state,
+			});
+		}
+	}
+	return parent;
+};
+
+export const createLoaderHandler = (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+): ((request: Request) => Promise<Response>) => {
+	const pages = manifest.filter((r) => r.kind !== "api");
+
+	return async (request: Request): Promise<Response> => {
+		const url = new URL(request.url);
+		const path = url.searchParams.get("path") ?? "/";
+		const match = matchFileRoute(path, pages);
+		if (!match) {
+			return Response.json(
+				{ error: { code: "NOT_FOUND", message: `No route: ${path}` } },
+				{ status: 404 },
+			);
+		}
+
+		// Layout → page loader chain; a beforeLoad verdict short-circuits
+		try {
+			const data = await runFileRouteLoader(path, manifest, modules, request);
+			// Deferred leaves → markers + resolved values in `deferred`
+			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;
+			return Response.json({
+				data: marked ?? null,
+				...(Object.keys(deferred).length > 0 ? { deferred } : {}),
+			});
+		} catch (error) {
+			if (error instanceof Response) return error;
+			const body = loaderErrorBody(error);
+			return Response.json(
+				{ error: body },
+				{ status: body.code === "NOT_FOUND" ? 404 : 500 },
+			);
+		}
+	};
+};

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

@@ -0,0 +1,229 @@
+/**
+ * Route Manifest Builder
+ * Maps files inside routesDir to route entries using filesystem
+ * conventions — SolidStart/Nuxt style:
+ *
+ *   src/routes/index.tsx            → /
+ *   src/routes/about.tsx            → /about
+ *   src/routes/users/[id].tsx       → /users/:id
+ *   src/routes/blog/[...slug].tsx   → /blog/*slug   (catch-all)
+ *   src/routes/(mkt)/home.tsx       → /home         (pathless group)
+ *   src/routes/users/[id]/edit.tsx  → /users/:id/edit
+ *
+ * Non-route files: layout.tsx, error.tsx, loading.tsx, not-found.tsx,
+ * and anything starting with "_" or inside "_" directories.
+ */
+
+import type { FileRoute, RouteManifest } from "../models";
+
+const MODULE_EXT = /\.(tsx|ts|jsx|js|md|mdx)$/;
+const CONTENT_EXT = /\.(md|mdx)$/;
+const CATCH_ALL = /^\[\.\.\.(.+)\]$/;
+const PARAM = /^\[(.+)\]$/;
+const GROUP = /^\(.+\)$/;
+const INTERCEPT = /^\(\.+\)(.+)$/;
+const SLOT = /^@(.+)$/;
+const PRIVATE = /^_/;
+
+const CONVENTION_NAMES = new Set([
+	"layout",
+	"error",
+	"loading",
+	"not-found",
+	"middleware",
+]);
+
+const normalize = (file: string): string => file.replace(/\\/g, "/");
+
+const stripExt = (file: string): string => file.replace(MODULE_EXT, "");
+
+const splitSegments = (relative: string): string[] =>
+	stripExt(normalize(relative)).split("/");
+
+interface Segment {
+	/** url segment text, or param name when dynamic */
+	text: string;
+	kind: "static" | "param" | "splat";
+	/** group segments contribute no url text but can hold conventions */
+	group: boolean;
+}
+
+const parseSegment = (raw: string): Segment => {
+	// `(.)name` — intercepted route: contributes url text like a plain
+	// segment; the route is flagged intercepted for modal rendering
+	const intercepted = raw.match(INTERCEPT);
+	if (intercepted) {
+		return { text: intercepted[1] ?? raw, kind: "static", group: false };
+	}
+	// `@slot` — parallel-route dir: no url text (like a group) but the
+	// route records its slot name
+	if (SLOT.test(raw)) return { text: raw, kind: "static", group: true };
+	if (GROUP.test(raw)) return { text: "", kind: "static", group: true };
+	const splat = raw.match(CATCH_ALL);
+	if (splat) return { text: splat[1] ?? "all", kind: "splat", group: false };
+	const param = raw.match(PARAM);
+	if (param) return { text: param[1] ?? "", kind: "param", group: false };
+	return { text: raw, kind: "static", group: false };
+};
+
+const API_SUFFIX = ".api";
+
+const isRouteFile = (segments: Segment[], fileName: string): boolean => {
+	if (CONVENTION_NAMES.has(fileName)) return false;
+	return !segments.some((s) => PRIVATE.test(s.text)) && !PRIVATE.test(fileName);
+};
+
+/** Specificity — static beats param beats splat; longer paths tie-break later */
+const scoreRoute = (segments: Segment[]): number =>
+	segments.reduce(
+		(score, seg) =>
+			score * 4 + (seg.kind === "static" ? 3 : seg.kind === "param" ? 2 : 1),
+		0,
+	);
+
+const dirSegments = (relative: string): string[] => {
+	const segs = normalize(relative).split("/");
+	segs.pop();
+	return segs;
+};
+
+const ancestorDirs = (relative: string, root: string): string[] => {
+	// "users/[id]/edit.tsx" → ["root/users/[id]", "root/users", "root"]
+	const dirs = dirSegments(relative);
+	const chain: string[] = [];
+	for (let i = dirs.length; i >= 0; i--) {
+		const dir = dirs.slice(0, i).join("/");
+		chain.push(dir ? `${root}/${dir}` : root);
+	}
+	return chain;
+};
+
+const conventionIndex = (files: string[]): Map<string, Map<string, string>> => {
+	// dir → convention name → file
+	const index = new Map<string, Map<string, string>>();
+	for (const file of files) {
+		const rel = normalize(file);
+		const name = stripExt(rel.split("/").pop() ?? "");
+		if (!CONVENTION_NAMES.has(name)) continue;
+		const dir = rel.replace(/\/[^/]*$/, "");
+		const entry = index.get(dir) ?? new Map<string, string>();
+		entry.set(name, file);
+		index.set(dir, entry);
+	}
+	return index;
+};
+
+const findConvention = (
+	index: Map<string, Map<string, string>>,
+	ancestors: string[],
+	name: string,
+): string | undefined => {
+	for (const dir of ancestors) {
+		const found = index.get(dir)?.get(name);
+		if (found) return found;
+	}
+	return undefined;
+};
+
+const middlewareChain = (
+	index: Map<string, Map<string, string>>,
+	ancestors: string[],
+): string[] => {
+	// every ancestor's _middleware applies — outermost → innermost
+	const chain: string[] = [];
+	for (const dir of [...ancestors].reverse()) {
+		const mw = index.get(dir)?.get("middleware");
+		if (mw) chain.push(mw);
+	}
+	return chain;
+};
+
+const layoutChain = (
+	index: Map<string, Map<string, string>>,
+	ancestors: string[],
+): string[] => {
+	// ancestors are innermost → outermost; layouts render outermost first
+	const chain: string[] = [];
+	for (const dir of [...ancestors].reverse()) {
+		const layout = index.get(dir)?.get("layout");
+		if (layout) chain.push(layout);
+	}
+	return chain;
+};
+
+export const buildRouteManifest = (
+	files: string[],
+	routesDir = "src/routes",
+): RouteManifest => {
+	const root = normalize(routesDir).replace(/\/$/, "");
+	const conventions = conventionIndex(files);
+	const routes: RouteManifest = [];
+
+	for (const file of files) {
+		const rel = normalize(file);
+		if (!rel.startsWith(`${root}/`)) continue;
+		const relPath = rel.slice(root.length + 1);
+		const segments = splitSegments(relPath).map(parseSegment);
+		const fileName = stripExt(relPath.split("/").pop() ?? "");
+
+		if (!isRouteFile(segments, fileName)) continue;
+
+		// "*.api.ts" files are API endpoints — path drops the .api suffix
+		const isApi = fileName.endsWith(API_SUFFIX);
+		// "*.md" pages render markdown content — `kind: "content"`
+		const isContent = CONTENT_EXT.test(rel);
+		const routeName = isApi ? fileName.slice(0, -API_SUFFIX.length) : fileName;
+
+		// "index" or "page" collapses to the directory path
+		const urlSegments =
+			routeName === "index" || routeName === "page"
+				? segments.slice(0, -1)
+				: [...segments.slice(0, -1), parseSegment(routeName)];
+
+		const params: string[] = [];
+		const parts: string[] = [];
+		for (const seg of urlSegments) {
+			if (seg.group) continue;
+			if (seg.kind === "param") {
+				params.push(seg.text);
+				parts.push(`:${seg.text}`);
+			} else if (seg.kind === "splat") {
+				params.push(seg.text);
+				parts.push(`*${seg.text}`);
+			} else {
+				parts.push(seg.text);
+			}
+		}
+
+		const ancestors = ancestorDirs(relPath, root); // innermost → root
+		const rawSegs = splitSegments(relPath);
+		const intercepted = rawSegs.some((s) => INTERCEPT.test(s));
+		const slotSeg = rawSegs.map((s) => s.match(SLOT)).find(Boolean)?.[1];
+		const route: FileRoute = {
+			path: `/${parts.join("/")}`.replace(/\/$/, "") || "/",
+			file,
+			...(intercepted ? { intercepted: true as const } : {}),
+			...(slotSeg ? { slot: slotSeg } : {}),
+			...(isApi ? { kind: "api" as const } : {}),
+			...(isContent ? { kind: "content" as const } : {}),
+			// API endpoints serve raw responses — page conventions don't apply
+			layouts: isApi ? [] : layoutChain(conventions, ancestors),
+			middleware: middlewareChain(conventions, ancestors),
+			params,
+			score: scoreRoute(urlSegments.filter((s) => !s.group)),
+		};
+
+		if (!isApi) {
+			const error = findConvention(conventions, ancestors, "error");
+			const loading = findConvention(conventions, ancestors, "loading");
+			const notFound = findConvention(conventions, ancestors, "not-found");
+			if (error) route.error = error;
+			if (loading) route.loading = loading;
+			if (notFound) route.notFound = notFound;
+		}
+
+		routes.push(route);
+	}
+
+	return routes.sort((a, b) => b.score - a.score);
+};

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

@@ -0,0 +1,75 @@
+/**
+ * Route Matcher
+ * Matches a pathname against a FileRoute manifest — static segments
+ * must equal, ":param" takes one segment, "*splat" takes the rest
+ */
+
+import type { FileRoute, FileRouteMatch, RouteManifest } from "../models";
+
+const matchRoute = (
+	pathname: string,
+	route: FileRoute,
+): FileRouteMatch | null => {
+	const pattern = route.path.split("/").filter(Boolean);
+	const parts = pathname.split("/").filter(Boolean);
+	const params: Record<string, string> = {};
+
+	for (let i = 0; i < pattern.length; i++) {
+		const seg = pattern[i];
+		if (seg === undefined) return null;
+		if (seg.startsWith("*")) {
+			params[seg.slice(1)] = parts.slice(i).join("/");
+			return { route, params };
+		}
+		const part = parts[i];
+		if (part === undefined) return null;
+		if (seg.startsWith(":")) {
+			params[seg.slice(1)] = decodeURIComponent(part);
+			continue;
+		}
+		if (seg !== part) return null;
+	}
+
+	if (parts.length !== pattern.length) return null;
+	return { route, params };
+};
+
+/**
+ * Match a pathname to a route — manifest is expected pre-sorted by
+ * score (buildRouteManifest does this); falls back to the best match
+ */
+export const matchFileRoute = (
+	pathname: string,
+	manifest: RouteManifest,
+	kind: "page" | "api" = "page",
+): FileRouteMatch | null => {
+	const clean = pathname.split("?")[0]?.replace(/\/+$/, "") || "/";
+	for (const route of manifest) {
+		if ((route.kind ?? "page") !== kind) continue;
+		const match = matchRoute(clean, route);
+		if (match) return match;
+	}
+	return null;
+};
+
+/**
+ * Match all routes at a pathname — the default page (no slot) plus
+ * every `@slot` parallel route that also matches
+ */
+export const matchAllFileRoutes = (
+	pathname: string,
+	manifest: RouteManifest,
+): FileRouteMatch[] => {
+	const clean = pathname.split("?")[0]?.replace(/\/+$/, "") || "/";
+	const out: FileRouteMatch[] = [];
+	for (const route of manifest) {
+		if ((route.kind ?? "page") !== "page") continue;
+		const match = matchRoute(clean, route);
+		if (match) out.push(match);
+	}
+	return out;
+};
+
+/** Route paths for type generation — literal list used by typed routes */
+export const routePaths = (manifest: RouteManifest): string[] =>
+	manifest.map((r) => r.path);

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

@@ -0,0 +1,58 @@
+/**
+ * generateStaticParams
+ * Route modules export `generateStaticParams` to enumerate dynamic
+ * segments for build-time prerendering (Next.js convention):
+ *
+ *   // src/routes/users/[id].tsx
+ *   export const generateStaticParams = () => [{ id: "1" }, { id: "2" }];
+ *
+ * expandStaticRoutes resolves those into concrete paths a prerender
+ * pass can visit
+ */
+
+import type { RouteManifest } from "../models";
+import type { ApiRouteModules } from "./api";
+
+export type GenerateStaticParamsFn = () =>
+	| Record<string, string>[]
+	| Promise<Record<string, string>[]>;
+
+const substitute = (pattern: string, params: Record<string, string>) => {
+	let path = pattern;
+	for (const [key, value] of Object.entries(params)) {
+		path = path.replace(`:${key}`, value).replace(`*${key}`, value);
+	}
+	return path;
+};
+
+/**
+ * Expand route patterns into concrete paths — static segments pass
+ * through; param routes enumerate via generateStaticParams
+ */
+export const expandStaticRoutes = async (
+	manifest: RouteManifest,
+	modules: ApiRouteModules,
+	routes: string[] = [],
+): Promise<string[]> => {
+	const out = new Set<string>(routes.filter((r) => !r.includes(":")));
+
+	for (const route of manifest) {
+		if (route.kind === "api") continue;
+		if (!route.path.includes(":") && !route.path.includes("*")) {
+			out.add(route.path);
+			continue;
+		}
+
+		const entry = modules[route.file] ?? modules[`/${route.file}`];
+		if (!entry) continue;
+		const mod = (await Promise.resolve(
+			typeof entry === "function" ? entry() : entry,
+		)) as { generateStaticParams?: GenerateStaticParamsFn };
+		if (!mod.generateStaticParams) continue;
+
+		for (const params of await mod.generateStaticParams()) {
+			out.add(substitute(route.path, params));
+		}
+	}
+	return [...out];
+};

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

@@ -0,0 +1,127 @@
+/**
+ * Typed Routes
+ * Type-level param extraction + a `route()` helper — the generated
+ * `.solid/routes.d.ts` augments `GeneratedRoutes` so paths and params
+ * are fully typed (routeTree.gen equivalent, manifest-driven)
+ */
+
+/** Extract param names from a route pattern type: "/users/:id" → "id" */
+export type ExtractParams<P extends string> =
+	P extends `${string}:${infer Tail}`
+		? Tail extends `${infer Name}/${infer Rest}`
+			? Name | ExtractParams<`/${Rest}`>
+			: Tail
+		: P extends `${string}*${infer Tail}`
+			? Tail extends `${infer Name}/${infer Rest}`
+				? Name | ExtractParams<`/${Rest}`>
+				: Tail
+			: never;
+
+export type RouteParamsFor<P extends string> = [ExtractParams<P>] extends [
+	never,
+]
+	? Record<string, never>
+	: Record<ExtractParams<P>, string>;
+
+export type HasParams<P extends string> = [ExtractParams<P>] extends [never]
+	? false
+	: true;
+
+/**
+ * Route tree — `solid generate` emits a declaration merging into this
+ * interface, mapping each path literal to its params object. Until
+ * generated it stays empty and every string is a valid RoutePath.
+ */
+export interface GeneratedRoutes {}
+
+/** All known route paths — literal union after `solid generate` */
+export type RoutePath = [keyof GeneratedRoutes] extends [never]
+	? string
+	: keyof GeneratedRoutes & string;
+
+/**
+ * Params for a path — the generated map wins; otherwise param names are
+ * extracted from the pattern literal at the type level
+ */
+export type ParamsFor<P extends string> = P extends keyof GeneratedRoutes
+	? GeneratedRoutes[P]
+	: RouteParamsFor<P>;
+
+/**
+ * Search-param shapes per route — augmentable like GeneratedRoutes;
+ * stays empty until `solid generate` (or user code) fills it
+ */
+export interface GeneratedSearch {}
+
+export type SearchFor<P extends string> = P extends keyof GeneratedSearch
+	? GeneratedSearch[P]
+	: Record<string, string | number | boolean>;
+
+/**
+ * Build a concrete URL from a route pattern — typed against the
+ * generated manifest when present.
+ *   pathFor("/users/:id", { id: "42" })        → "/users/42"
+ *   pathFor("/blog/*slug", { slug: "a/b" })   → "/blog/a/b"
+ *   pathFor("/search", {}, { q: "x" })        → "/search?q=x"
+ */
+export const pathFor = <P extends RoutePath>(
+	path: P,
+	params?: ParamsFor<P>,
+	search?: SearchFor<P>,
+	/** `#section` fragment — appended after the query string */
+	hash?: string,
+): string => {
+	let url: string = path;
+	for (const [key, value] of Object.entries(params ?? {})) {
+		url = url.replace(`:${key}`, encodeURIComponent(String(value)));
+		url = url.replace(`*${key}`, String(value));
+	}
+	if (url.includes(":") || url.includes("*")) {
+		throw new Error(`[solid-framework] pathFor("${path}") missing params`);
+	}
+	if (search && Object.keys(search).length > 0) {
+		const query = new URLSearchParams(
+			Object.fromEntries(
+				Object.entries(search).map(([k, v]) => [k, String(v)]),
+			),
+		).toString();
+		url += `?${query}`;
+	}
+	if (hash) url += hash.startsWith("#") ? hash : `#${hash}`;
+	return url;
+};
+
+/** @deprecated renamed to pathFor — `route` collides with route concepts */
+export const route = pathFor;
+
+/** @deprecated renamed to pathFor */
+export const href = pathFor;
+
+/**
+ * Resolve a relative href against a base path — `relativePath("/a/b", "../c")`
+ * → "/a/c". Powers `link.relative()` for nested-route navigation.
+ */
+export const relativePath = (from: string, to: string): string => {
+	if (to.startsWith("/")) return to;
+	const base = from.endsWith("/")
+		? from
+		: from.slice(0, from.lastIndexOf("/") + 1);
+	const stack = base.split("/").filter(Boolean);
+	for (const seg of to.split("/")) {
+		if (seg === "..") stack.pop();
+		else if (seg !== "." && seg !== "") stack.push(seg);
+	}
+	return `/${stack.join("/")}`;
+};
+
+/**
+ * The route pattern itself, type-checked — `link.pattern("/users/:id")`
+ * returns "/users/:id" so templates stay typed to the manifest
+ */
+export const routePattern = <P extends RoutePath>(path: P): P => path;
+
+/** `link(path, params, search)` + `link.relative` + `link.pattern` */
+export const link = Object.assign(pathFor, {
+	relative: relativePath,
+	pattern: routePattern,
+});