@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/modules/cache/domain/operations/tags.ts

@@ -0,0 +1,114 @@
+/**
+ * Tagged Cache + Revalidation
+ * The "use cache" / revalidateTag equivalent:
+ *
+ *   const getUser = useCache(async (id) => db.user(id), {
+ *     key: "user",
+ *     tags: ["users"],
+ *     maxAge: 60,
+ *   });
+ *
+ *   // in a server function / action after a mutation:
+ *   revalidateTag("users");      // busts fn cache + prerender pages
+ *   revalidatePath("/users/42"); // busts one cached page
+ */
+
+import { sharedPrerenderCache } from "#app/modules/server-entry/application/usecases/prerender-cache";
+
+export interface CacheOptions {
+	/** Cache key prefix — defaults to the function name */
+	key?: string;
+	/** Tags for grouped invalidation via revalidateTag */
+	tags?: string[];
+	/** Freshness window in seconds — omit for no expiry */
+	maxAge?: number;
+}
+
+interface FnCacheEntry {
+	value: unknown;
+	tags: string[];
+	cachedAt: number;
+}
+
+const fnStore = new Map<string, FnCacheEntry>();
+
+const fnKey = (base: string, args: unknown[]): string =>
+	`${base}:${JSON.stringify(args)}`;
+
+/**
+ * Wrap an async function with a tagged in-memory cache — call sites get
+ * cached results while fresh; revalidateTag busts by tag
+ */
+export const useCache = <TArgs extends unknown[], TResult>(
+	fn: (...args: TArgs) => Promise<TResult>,
+	options: CacheOptions = {},
+): ((...args: TArgs) => Promise<TResult>) => {
+	const base = options.key ?? fn.name ?? "anonymous";
+	return async (...args: TArgs): Promise<TResult> => {
+		const key = fnKey(base, args);
+		const cached = fnStore.get(key);
+		if (cached) {
+			const fresh =
+				options.maxAge === undefined ||
+				(Date.now() - cached.cachedAt) / 1000 < options.maxAge;
+			if (fresh) return cached.value as TResult;
+		}
+		const value = await fn(...args);
+		fnStore.set(key, {
+			value,
+			tags: options.tags ?? [],
+			cachedAt: Date.now(),
+		});
+		return value;
+	};
+};
+
+// Extra caches (loader cache, …) register an invalidator so one
+// revalidateTag() busts every tag-aware store
+const tagInvalidators: ((tag: string) => number)[] = [];
+
+export const onRevalidateTag = (fn: (tag: string) => number): void => {
+	tagInvalidators.push(fn);
+};
+
+// Path invalidators — loader cache registers so revalidatePath()
+// busts loader entries for that pathname too
+const pathInvalidators: ((pathname: string) => number)[] = [];
+
+export const onRevalidatePath = (fn: (pathname: string) => number): void => {
+	pathInvalidators.push(fn);
+};
+
+/** Invalidate every fn-cache entry and prerendered page carrying the tag */
+export const revalidateTag = (tag: string): number => {
+	let evicted = sharedPrerenderCache.invalidateTag(tag);
+	for (const [key, entry] of fnStore) {
+		if (entry.tags.includes(tag)) {
+			fnStore.delete(key);
+			evicted++;
+		}
+	}
+	for (const fn of tagInvalidators) evicted += fn(tag);
+	return evicted;
+};
+
+/**
+ * `updateTag(tag)` — expire tagged entries AND read-your-writes:
+ * same invalidation as revalidateTag but also clears the memoized
+ * fn cache so the current request sees fresh values
+ */
+export const updateTag = (tag: string): number => {
+	const n = revalidateTag(tag);
+	fnStore.clear();
+	return n;
+};
+
+/** Invalidate one prerendered page (+ loader entries) by pathname */
+export const revalidatePath = (pathname: string): boolean => {
+	let evicted = sharedPrerenderCache.invalidatePath(pathname);
+	for (const fn of pathInvalidators) evicted = fn(pathname) > 0 || evicted;
+	return evicted;
+};
+
+/** Test hook — drop all fn-cache entries */
+export const clearFnCache = (): void => fnStore.clear();

package/src/app/modules/cache/index.ts

@@ -0,0 +1,7 @@
+// NOTE: the fs adapter imports node:crypto/node:fs — it is exported
+// from the server-only subpath (@wrikka/solid-framework/server), not
+// here, so client bundles never touch node builtins
+export * from "./adapters/edge-kv";
+export * from "./adapters/memory";
+export * from "./domain/operations/tags";
+export * from "./ports/store";

package/src/app/modules/cache/ports/store.ts

@@ -0,0 +1,14 @@
+/**
+ * Cache Store Port
+ * Pluggable backend for the prerender/ISR cache — memory by default,
+ * filesystem for persistent builds; a KV/Redis adapter can implement
+ * the same synchronous surface (values are JSON-serializable)
+ */
+
+export interface CacheStore<V> {
+	get(key: string): V | undefined;
+	set(key: string, value: V): void;
+	delete(key: string): boolean;
+	keys(): string[];
+	clear(): void;
+}

package/src/app/modules/config/domain/index.ts

@@ -0,0 +1 @@
+export * from "./models";

package/src/app/modules/config/domain/models/config.ts

@@ -0,0 +1,72 @@
+/**
+ * Config Model
+ * Framework configuration with defaults — the nuxt.config/next.config equivalent
+ */
+
+import type { SolidFrameworkConfig } from "#app/types";
+
+export const defaultConfig: SolidFrameworkConfig = {
+	routesDir: "src/routes",
+	renderMode: "stream",
+	rules: {},
+	apiPrefixes: ["/api"],
+	head: {},
+	autoImports: true,
+	entries: {
+		server: "src/entry-server.tsx",
+		client: "src/entry-client.tsx",
+	},
+	publicEnvPrefixes: ["PUBLIC_"],
+};
+
+export type UserConfig = Partial<SolidFrameworkConfig>;
+
+/** Shallow-merge layer configs — later entries win over earlier */
+const mergeLayer = (base: UserConfig, layer: UserConfig): UserConfig => ({
+	...base,
+	...layer,
+	head: { ...base.head, ...layer.head },
+	entries: {
+		...base.entries,
+		...layer.entries,
+	} as SolidFrameworkConfig["entries"],
+	rules: { ...base.rules, ...layer.routeRules, ...layer.rules },
+	routeRules: { ...base.routeRules, ...layer.routeRules },
+	middleware: [...(base.middleware ?? []), ...(layer.middleware ?? [])],
+	plugins: [...(base.plugins ?? []), ...(layer.plugins ?? [])],
+	extends: [...(base.extends ?? []), ...(layer.extends ?? [])],
+});
+
+export const resolveConfig = (user: UserConfig = {}): SolidFrameworkConfig => {
+	// Layers — `extends` configs merge base→derived; user config wins last
+	let merged: UserConfig = {};
+	const visit = (cfg: UserConfig): void => {
+		for (const layer of cfg.extends ?? []) visit(layer);
+		merged = mergeLayer(merged, cfg);
+	};
+	visit(user);
+	const layers = merged.extends;
+
+	let config: SolidFrameworkConfig = {
+		...defaultConfig,
+		...merged,
+		head: { ...defaultConfig.head, ...merged.head },
+		entries: { ...defaultConfig.entries, ...merged.entries },
+		publicEnvPrefixes:
+			merged.publicEnvPrefixes ?? defaultConfig.publicEnvPrefixes,
+		apiPrefixes: merged.apiPrefixes ?? defaultConfig.apiPrefixes,
+		// `rules` wins; `routeRules` kept for back-compat
+		rules: { ...merged.routeRules, ...merged.rules },
+		extends: layers,
+	};
+
+	// Plugin config hooks — each plugin may patch the resolved config
+	for (const plugin of config.plugins ?? []) {
+		const patch = plugin.config?.(config);
+		if (patch) {
+			config = { ...config, ...patch, plugins: config.plugins };
+		}
+	}
+
+	return config;
+};

package/src/app/modules/config/domain/models/index.ts

@@ -0,0 +1 @@
+export * from "./config";

package/src/app/modules/config/index.ts

@@ -0,0 +1 @@
+export * from "./domain";

package/src/app/modules/content/domain/operations/collection.ts

@@ -0,0 +1,109 @@
+/**
+ * Content Collections
+ * Markdown files → typed entries with frontmatter — pair with
+ * `import.meta.glob` (eager raw imports) so loaders and static
+ * generation read content as data:
+ *
+ *   const posts = defineCollection<{ title: string; date: string }>({
+ *     source: import.meta.glob("./content/posts/*.md", {
+ *       eager: true, query: "?raw", import: "default",
+ *     }),
+ *     schema: (data) => data as { title: string; date: string },
+ *   });
+ *
+ *   export const loader = () => ({ posts: posts.all() });
+ *   posts.get("hello-world")?.body
+ */
+
+export interface CollectionEntry<T = Record<string, unknown>> {
+	/** Filename without extension — "hello-world.md" → "hello-world" */
+	slug: string;
+	/** Frontmatter fields, schema-validated when a schema is given */
+	data: T;
+	/** Markdown body after the frontmatter block */
+	body: string;
+	/** Source file path */
+	file: string;
+}
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+const scalar = (raw: string): unknown => {
+	const v = raw.trim();
+	if (v === "true") return true;
+	if (v === "false") return false;
+	if (v === "null" || v === "~") return null;
+	if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+	if (v.startsWith("[") && v.endsWith("]")) {
+		return v
+			.slice(1, -1)
+			.split(",")
+			.map((item) => scalar(item));
+	}
+	return v.replace(/^["']|["']$/g, "");
+};
+
+/**
+ * YAML-lite frontmatter — flat `key: value` pairs, inline arrays,
+ * numbers/booleans/null. Deliberately not full YAML: nested blocks
+ * keep their raw string form
+ */
+export const parseFrontmatter = (
+	raw: string,
+): { data: Record<string, unknown>; body: string } => {
+	const match = raw.match(FRONTMATTER);
+	if (!match) return { data: {}, body: raw };
+	const data: Record<string, unknown> = {};
+	for (const line of match[1].split(/\r?\n/)) {
+		const sep = line.indexOf(":");
+		if (sep <= 0) continue;
+		const key = line.slice(0, sep).trim();
+		if (key) data[key] = scalar(line.slice(sep + 1));
+	}
+	return { data, body: raw.slice(match[0].length) };
+};
+
+export interface CollectionOptions<T = Record<string, unknown>> {
+	/** path → raw file content (import.meta.glob eager raw) */
+	source: Record<string, string>;
+	/** Validate/coerce frontmatter — throw to exclude the entry */
+	schema?: (data: Record<string, unknown>, file: string) => T;
+}
+
+export interface Collection<T = Record<string, unknown>> {
+	/** All entries, sorted by slug */
+	all: () => CollectionEntry<T>[];
+	/** Single entry by slug */
+	get: (slug: string) => CollectionEntry<T> | undefined;
+	/** All slugs — static path generation */
+	slugs: () => string[];
+	/** Entries filtered by a frontmatter predicate */
+	where: (fn: (entry: CollectionEntry<T>) => boolean) => CollectionEntry<T>[];
+}
+
+const slugOf = (file: string): string =>
+	(file.split("/").pop() ?? file).replace(/\.(md|mdx|markdown)$/, "");
+
+export const defineCollection = <T = Record<string, unknown>>(
+	options: CollectionOptions<T>,
+): Collection<T> => {
+	const entries = new Map<string, CollectionEntry<T>>();
+	for (const [file, raw] of Object.entries(options.source)) {
+		const { data, body } = parseFrontmatter(raw);
+		let parsed: T;
+		try {
+			parsed = options.schema ? options.schema(data, file) : (data as T);
+		} catch {
+			continue; // schema rejects — entry excluded
+		}
+		entries.set(slugOf(file), { slug: slugOf(file), data: parsed, body, file });
+	}
+	const all = () =>
+		[...entries.values()].sort((a, b) => a.slug.localeCompare(b.slug));
+	return {
+		all,
+		get: (slug) => entries.get(slug),
+		slugs: () => [...entries.keys()].sort(),
+		where: (fn) => all().filter(fn),
+	};
+};

package/src/app/modules/content/index.ts

@@ -0,0 +1,8 @@
+export {
+	type Collection,
+	type CollectionEntry,
+	type CollectionOptions,
+	defineCollection,
+	parseFrontmatter,
+} from "./domain/operations/collection";
+export { Markdown, renderMarkdown } from "./presentation/Markdown";

package/src/app/modules/content/presentation/Markdown.tsx

@@ -0,0 +1,78 @@
+/**
+ * <Markdown> — render collection `body` strings as HTML.
+ * Minimal pipeline (no dependency): headings, code fences, inline
+ * code, bold, italic, links, lists, paragraphs. Escapes raw HTML
+ * before transforming so content is safe by default.
+ *
+ *   <Markdown content={post.body} />
+ */
+
+import type { JSX } from "solid-js";
+
+const esc = (s: string): string =>
+	s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&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>');
+
+/** Markdown string → HTML (block level) */
+export const renderMarkdown = (md: string): string => {
+	const out: string[] = [];
+	let inCode = false;
+	let inList = false;
+	let code: string[] = [];
+
+	for (const raw of md.split("\n")) {
+		const line = raw.trimEnd();
+		if (line.startsWith("```")) {
+			if (inCode) {
+				out.push(`<pre><code>${esc(code.join("\n"))}</code></pre>`);
+				code = [];
+				inCode = false;
+			} else inCode = true;
+			continue;
+		}
+		if (inCode) {
+			code.push(raw);
+			continue;
+		}
+		if (/^[-*] /.test(line)) {
+			if (!inList) {
+				out.push("<ul>");
+				inList = true;
+			}
+			out.push(`<li>${inline(line.slice(2))}</li>`);
+			continue;
+		}
+		if (inList) {
+			out.push("</ul>");
+			inList = false;
+		}
+		const h = line.match(/^(#{1,6})\s+(.*)$/);
+		if (h) {
+			out.push(`<h${h[1].length}>${inline(h[2])}</h${h[1].length}>`);
+		} else if (line === "") {
+			// paragraph break
+		} else {
+			out.push(`<p>${inline(line)}</p>`);
+		}
+	}
+	if (inCode) out.push(`<pre><code>${esc(code.join("\n"))}</code></pre>`);
+	if (inList) out.push("</ul>");
+	return out.join("\n");
+};
+
+export const Markdown = (props: {
+	content: string;
+	class?: string;
+}): JSX.Element => (
+	<div
+		class={props.class}
+		// eslint-disable-next-line solid/no-innerhtml — escaped by renderMarkdown
+		innerHTML={renderMarkdown(props.content)}
+	/>
+);

package/src/app/modules/conventions/domain/index.ts

@@ -0,0 +1 @@
+export * from "./operations";

package/src/app/modules/conventions/domain/operations/index.ts

@@ -0,0 +1 @@
+export * from "./scan";

package/src/app/modules/conventions/domain/operations/scan.ts

@@ -0,0 +1,73 @@
+/**
+ * Route Conventions
+ * Resolve colocated route files — error.tsx, loading.tsx, not-found.tsx, layout.tsx
+ */
+
+import type { RouteConventions } from "#app/types";
+
+const CONVENTION_FILES = {
+	error: "error",
+	loading: "loading",
+	"not-found": "notFound",
+	layout: "layout",
+} as const;
+
+const basename = (file: string): string => {
+	const name = file.replace(/\\/g, "/").split("/").pop() ?? "";
+	return name.replace(/\.(tsx|ts|jsx|js)$/, "");
+};
+
+const dirname = (file: string): string =>
+	file.replace(/\\/g, "/").replace(/\/[^/]*$/, "");
+
+/**
+ * Scan a flat file list and resolve which convention files exist per directory
+ */
+export const scanRouteConventions = (
+	files: string[],
+): Map<string, RouteConventions> => {
+	const byDir = new Map<string, RouteConventions>();
+
+	for (const file of files) {
+		const name = basename(file);
+		const kind = CONVENTION_FILES[name as keyof typeof CONVENTION_FILES];
+		if (!kind) continue;
+
+		const dir = dirname(file);
+		const conventions = byDir.get(dir) ?? {};
+		conventions[kind] = file;
+		byDir.set(dir, conventions);
+	}
+
+	return byDir;
+};
+
+/**
+ * Merge conventions walking up from the route directory to the routes root —
+ * a route inherits the nearest ancestor's error/loading/not-found boundaries
+ */
+export const resolveConventionsForRoute = (
+	routeDir: string,
+	conventions: Map<string, RouteConventions>,
+	routesDir: string,
+): RouteConventions => {
+	const resolved: RouteConventions = {};
+	let dir = routeDir.replace(/\\/g, "/");
+	const root = routesDir.replace(/\\/g, "/");
+
+	while (dir.startsWith(root)) {
+		const current = conventions.get(dir);
+		if (current) {
+			resolved.error ??= current.error;
+			resolved.loading ??= current.loading;
+			resolved.notFound ??= current.notFound;
+			resolved.layout ??= current.layout;
+		}
+		if (dir === root) break;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+
+	return resolved;
+};

package/src/app/modules/conventions/index.ts

@@ -0,0 +1 @@
+export * from "./domain";

package/src/app/modules/db/application/usecases/db.ts

@@ -0,0 +1,49 @@
+/**
+ * Request-scoped Database Context
+ * `createDb` opens a connection/transaction per request and exposes
+ * it through middleware state — loaders read it via ctx.state or
+ * useDb() in components (server-side only):
+ *
+ *   const db = createDb({ connect: () => drizzle(postgres(DSN)) });
+ *   middleware: [db.middleware]
+ *
+ *   export const loader = async (ctx) =>
+ *     db.of(ctx.request).select().from(users);
+ */
+
+import { useRouteState } from "#app/modules/file-routes/presentation/location";
+import type { AppMiddleware } from "#app/types";
+
+export interface DbOptions<TDb> {
+	/** Open the request-scoped handle (connection or transaction) */
+	connect: (request: Request) => TDb | Promise<TDb>;
+	/** Release the handle after the request — fires post-render */
+	release?: (db: TDb, request: Request) => void | Promise<void>;
+	/** State key — default "db" */
+	key?: string;
+}
+
+export interface RequestDb<TDb> {
+	middleware: AppMiddleware;
+	/** The request's db handle — reads middleware state */
+	of: (request: Request) => TDb;
+}
+
+const handles = new WeakMap<Request, unknown>();
+
+export const createDb = <TDb>(options: DbOptions<TDb>): RequestDb<TDb> => {
+	const key = options.key ?? "db";
+	return {
+		middleware: async (ctx) => {
+			const db = await options.connect(ctx.request);
+			handles.set(ctx.request, db);
+			ctx.state[key] = db;
+			return undefined;
+		},
+		of: (request) => handles.get(request) as TDb,
+	};
+};
+
+/** Read the request db inside components — `useDb<DrizzleDb>()` */
+export const useDb = <TDb = unknown>(key = "db"): TDb =>
+	useRouteState<Record<string, TDb>>()[key];

package/src/app/modules/db/index.ts

@@ -0,0 +1 @@
+export * from "./application/usecases/db";

package/src/app/modules/deploy/adapters/aws-lambda.ts

@@ -0,0 +1,54 @@
+/**
+ * AWS Lambda adapter (Function URL / API Gateway HTTP API v2)
+ * Converts the proxy event into a web Request and back:
+ *
+ *   export const handler = toLambdaHandler(appHandler);
+ */
+
+export interface LambdaHttpEvent {
+	rawPath: string;
+	rawQueryString?: string;
+	headers?: Record<string, string>;
+	body?: string;
+	isBase64Encoded?: boolean;
+	requestContext: { http: { method: string } };
+}
+
+export interface LambdaHttpResult {
+	statusCode: number;
+	headers: Record<string, string>;
+	body: string;
+	isBase64Encoded?: boolean;
+}
+
+export const toLambdaHandler = (
+	handler: (request: Request) => Promise<Response>,
+): ((event: LambdaHttpEvent) => Promise<LambdaHttpResult>) => {
+	return async (event) => {
+		const method = event.requestContext.http.method;
+		const url = `https://${event.headers?.host ?? "lambda.local"}${event.rawPath}${
+			event.rawQueryString ? `?${event.rawQueryString}` : ""
+		}`;
+		const request = new Request(url, {
+			method,
+			headers: event.headers,
+			body:
+				method !== "GET" && method !== "HEAD" && event.body !== undefined
+					? event.isBase64Encoded
+						? Uint8Array.from(atob(event.body), (c) => c.charCodeAt(0))
+						: event.body
+					: undefined,
+		});
+
+		const response = await handler(request);
+		const headers: Record<string, string> = {};
+		response.headers.forEach((value, key) => {
+			headers[key] = value;
+		});
+		return {
+			statusCode: response.status,
+			headers,
+			body: await response.text(),
+		};
+	};
+};

package/src/app/modules/deploy/adapters/bun.ts

@@ -0,0 +1,15 @@
+/**
+ * Bun adapter — produces the options object for `Bun.serve`:
+ *
+ *   Bun.serve(toBunServeOptions(handler, { port: 3000 }));
+ */
+
+import type { BunServeOptions } from "../domain/models/preset";
+
+export const toBunServeOptions = (
+	handler: (request: Request) => Promise<Response>,
+	options: { port?: number } = {},
+): BunServeOptions => ({
+	fetch: handler,
+	port: options.port ?? 3000,
+});

package/src/app/modules/deploy/adapters/cloudflare.ts

@@ -0,0 +1,15 @@
+/**
+ * Cloudflare Workers adapter
+ *
+ * Usage in a worker entry:
+ *   import handler from "./app";
+ *   export default toWorkerEntry(handler);
+ */
+
+import type { WorkerEntry } from "../domain/models/preset";
+
+export const toWorkerEntry = <Env = unknown, Ctx = unknown>(
+	handler: (request: Request) => Promise<Response>,
+): WorkerEntry<Env, Ctx> => ({
+	fetch: (request, _env, _ctx) => handler(request),
+});

package/src/app/modules/deploy/adapters/deno.ts

@@ -0,0 +1,15 @@
+/**
+ * Deno adapter — options for `Deno.serve`
+ *
+ *   Deno.serve(toDenoServeOptions(handler));
+ */
+
+import type { BunServeOptions } from "../domain/models/preset";
+
+export const toDenoServeOptions = (
+	handler: (request: Request) => Promise<Response>,
+	options: { port?: number } = {},
+): BunServeOptions => ({
+	fetch: handler,
+	port: options.port ?? 8000,
+});

package/src/app/modules/deploy/adapters/netlify.ts

@@ -0,0 +1,18 @@
+/**
+ * Netlify Edge Functions adapter
+ * Edge functions export a default `(request, context)` handler:
+ *
+ *   export default toNetlifyHandler(handler);
+ */
+
+export interface NetlifyContext {
+	ip?: string;
+	geo?: { country?: { code?: string }; city?: string };
+	[key: string]: unknown;
+}
+
+export const toNetlifyHandler = (
+	handler: (request: Request) => Promise<Response>,
+): ((request: Request, context: NetlifyContext) => Promise<Response>) => {
+	return (request, _context) => handler(request);
+};