@wrikka/solid-framework 0.0.0-stage → 0.15.0

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

@@ -0,0 +1,63 @@
+/**
+ * Node.js adapter — wraps the framework fetch handler in a `node:http`
+ * server. Loaded lazily so edge bundles never touch `node:http`.
+ *
+ *   const server = toNodeServer(handler, { port: 3000 });
+ *   await server.start();
+ */
+
+import type { NodeServerHandle } from "../domain/models/preset";
+
+export const toNodeServer = (
+	handler: (request: Request) => Promise<Response>,
+	options: { port?: number } = {},
+): NodeServerHandle => {
+	const port = options.port ?? Number(process.env.PORT ?? 3000);
+
+	let server: import("node:http").Server | undefined;
+
+	const start = async () => {
+		const { createServer } = await import("node:http");
+		server = createServer((req, res) => {
+			const chunks: Buffer[] = [];
+			req.on("data", (chunk: Buffer) => chunks.push(chunk));
+			req.on("end", async () => {
+				try {
+					const host = req.headers.host ?? "localhost";
+					const method = req.method ?? "GET";
+					const headers = new Headers();
+					for (const [key, value] of Object.entries(req.headers)) {
+						if (value !== undefined)
+							headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+					}
+					const response = await handler(
+						new Request(`http://${host}${req.url ?? "/"}`, {
+							method,
+							headers,
+							body:
+								method !== "GET" && method !== "HEAD"
+									? Buffer.concat(chunks)
+									: undefined,
+						} as RequestInit),
+					);
+					res.statusCode = response.status;
+					response.headers.forEach((value, key) => {
+						res.setHeader(key, value);
+					});
+					res.end(Buffer.from(await response.arrayBuffer()));
+				} catch {
+					res.statusCode = 500;
+					res.end("Internal Server Error");
+				}
+			});
+		});
+		server.listen(port);
+	};
+
+	const stop = () =>
+		new Promise<void>((resolve) =>
+			server ? server.close(() => resolve()) : resolve(),
+		);
+
+	return { start, stop };
+};

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

@@ -0,0 +1,22 @@
+/**
+ * Vercel / edge-function adapter
+ *
+ * Vercel functions dispatch on exported HTTP method handlers, so the
+ * preset re-exports the framework fetch handler under every method:
+ *
+ *   export const { GET, POST } = toVercelHandler(handler);
+ */
+
+import type { MethodHandlers } from "../domain/models/preset";
+
+export const toVercelHandler = (
+	handler: (request: Request) => Promise<Response>,
+): MethodHandlers => ({
+	GET: handler,
+	POST: handler,
+	PUT: handler,
+	PATCH: handler,
+	DELETE: handler,
+	HEAD: handler,
+	OPTIONS: handler,
+});

package/src/app/modules/deploy/domain/models/preset.ts

@@ -0,0 +1,38 @@
+/**
+ * Deploy preset types — the framework handler is a web-standard
+ * `(request: Request) => Promise<Response>`, so presets only adapt the
+ * export shape each platform expects
+ */
+
+export type DeployPreset =
+	| "node"
+	| "bun"
+	| "deno"
+	| "cloudflare"
+	| "netlify"
+	| "vercel"
+	| "aws-lambda";
+
+export interface WorkerEntry<Env = unknown, Ctx = unknown> {
+	fetch: (request: Request, env: Env, ctx: Ctx) => Promise<Response>;
+}
+
+export interface MethodHandlers {
+	GET: (request: Request) => Promise<Response>;
+	POST: (request: Request) => Promise<Response>;
+	PUT: (request: Request) => Promise<Response>;
+	PATCH: (request: Request) => Promise<Response>;
+	DELETE: (request: Request) => Promise<Response>;
+	HEAD: (request: Request) => Promise<Response>;
+	OPTIONS: (request: Request) => Promise<Response>;
+}
+
+export interface NodeServerHandle {
+	start: () => Promise<void>;
+	stop: () => Promise<void>;
+}
+
+export interface BunServeOptions {
+	fetch: (request: Request) => Promise<Response>;
+	port: number;
+}

package/src/app/modules/deploy/domain/operations/presets.ts

@@ -0,0 +1,92 @@
+/**
+ * resolveDeployEntry — pick the export shape a hosting platform expects
+ *
+ * The framework handler is always `(request) => Promise<Response>`; each
+ * preset only adapts that contract:
+ *
+ *   "node"       → NodeServerHandle (start/stop around node:http)
+ *   "bun"        → Bun.serve options
+ *   "cloudflare" → Worker `export default { fetch }`
+ *   "vercel"     → named HTTP method handlers
+ */
+
+import {
+	type LambdaHttpEvent,
+	type LambdaHttpResult,
+	toLambdaHandler,
+} from "../../adapters/aws-lambda";
+import { toBunServeOptions } from "../../adapters/bun";
+import { toWorkerEntry } from "../../adapters/cloudflare";
+import { toDenoServeOptions } from "../../adapters/deno";
+import { type NetlifyContext, toNetlifyHandler } from "../../adapters/netlify";
+import { toNodeServer } from "../../adapters/node";
+import { toVercelHandler } from "../../adapters/vercel";
+import type {
+	BunServeOptions,
+	DeployPreset,
+	MethodHandlers,
+	NodeServerHandle,
+	WorkerEntry,
+} from "../models/preset";
+
+export interface DeployOptions {
+	port?: number;
+}
+
+export function resolveDeployEntry(
+	preset: "node",
+	handler: (request: Request) => Promise<Response>,
+	options?: DeployOptions,
+): NodeServerHandle;
+export function resolveDeployEntry(
+	preset: "bun",
+	handler: (request: Request) => Promise<Response>,
+	options?: DeployOptions,
+): BunServeOptions;
+export function resolveDeployEntry(
+	preset: "cloudflare",
+	handler: (request: Request) => Promise<Response>,
+	options?: DeployOptions,
+): WorkerEntry;
+export function resolveDeployEntry(
+	preset: "vercel",
+	handler: (request: Request) => Promise<Response>,
+	options?: DeployOptions,
+): MethodHandlers;
+export function resolveDeployEntry(
+	preset: "deno",
+	handler: (request: Request) => Promise<Response>,
+	options?: DeployOptions,
+): BunServeOptions;
+export function resolveDeployEntry(
+	preset: "netlify",
+	handler: (request: Request) => Promise<Response>,
+	options?: DeployOptions,
+): (request: Request, context: NetlifyContext) => Promise<Response>;
+export function resolveDeployEntry(
+	preset: "aws-lambda",
+	handler: (request: Request) => Promise<Response>,
+	options?: DeployOptions,
+): (event: LambdaHttpEvent) => Promise<LambdaHttpResult>;
+export function resolveDeployEntry(
+	preset: DeployPreset,
+	handler: (request: Request) => Promise<Response>,
+	options: DeployOptions = {},
+) {
+	switch (preset) {
+		case "node":
+			return toNodeServer(handler, options);
+		case "bun":
+			return toBunServeOptions(handler, options);
+		case "deno":
+			return toDenoServeOptions(handler, options);
+		case "cloudflare":
+			return toWorkerEntry(handler);
+		case "netlify":
+			return toNetlifyHandler(handler);
+		case "vercel":
+			return toVercelHandler(handler);
+		case "aws-lambda":
+			return toLambdaHandler(handler);
+	}
+}

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

@@ -0,0 +1,9 @@
+export * from "./adapters/aws-lambda";
+export * from "./adapters/bun";
+export * from "./adapters/cloudflare";
+export * from "./adapters/deno";
+export * from "./adapters/netlify";
+export * from "./adapters/node";
+export * from "./adapters/vercel";
+export * from "./domain/models/preset";
+export * from "./domain/operations/presets";

package/src/app/modules/draft/domain/operations/draft-mode.ts

@@ -0,0 +1,125 @@
+/**
+ * Draft Mode — bypass prerender/ISR cache for previewing edits.
+ * The cookie is HMAC-signed with `secret` (+expiry) so it can't be
+ * forged without knowing the token:
+ *
+ *   // config.middleware
+ *   draftMode({ secret: "preview-secret" })
+ *
+ * Enable:  /posts?__draft=preview-secret → signed cookie, clean redirect
+ * Disable: /posts?__draft=0            → clears cookie
+ * While active, state.draft = true and cached pages are skipped.
+ */
+
+import { redirect } from "#app/modules/middleware";
+import type { AppMiddleware } from "#app/types";
+
+export const DRAFT_COOKIE = "__draft";
+export const DRAFT_STATE = "draft";
+
+export interface DraftModeOptions {
+	/** Required token to enable — also signs the cookie; omit for dev-only plain cookie */
+	secret?: string;
+	/** Cookie name — default "__draft" */
+	cookie?: string;
+	/** Cookie lifetime seconds — default 3600 */
+	ttl?: number;
+}
+
+const b64 = (buf: ArrayBuffer): string =>
+	btoa(String.fromCharCode(...new Uint8Array(buf)))
+		.replaceAll("+", "-")
+		.replaceAll("/", "_")
+		.replaceAll("=", "");
+
+const sign = async (payload: string, secret: string): Promise<string> => {
+	const key = await crypto.subtle.importKey(
+		"raw",
+		new TextEncoder().encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign", "verify"],
+	);
+	return b64(
+		await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload)),
+	);
+};
+
+const timingSafeEq = (a: string, b: string): boolean => {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+};
+
+export const draftMode = (options: DraftModeOptions = {}): AppMiddleware => {
+	const name = options.cookie ?? DRAFT_COOKIE;
+	const ttl = options.ttl ?? 3600;
+	return async (ctx) => {
+		const param = ctx.url.searchParams.get(DRAFT_COOKIE);
+		if (param === "0") {
+			// Disable — strip the param and expire the cookie
+			const clean = new URL(ctx.url);
+			clean.searchParams.delete(DRAFT_COOKIE);
+			const res = redirect(clean.pathname + clean.search);
+			res.headers.append(
+				"Set-Cookie",
+				`${name}=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax`,
+			);
+			return res;
+		}
+		if (param !== null) {
+			if (
+				options.secret !== undefined &&
+				!timingSafeEq(param, options.secret)
+			) {
+				return new Response("invalid draft secret", { status: 401 });
+			}
+			// Enable — signed cookie when a secret is configured
+			const clean = new URL(ctx.url);
+			clean.searchParams.delete(DRAFT_COOKIE);
+			const res = redirect(clean.pathname + clean.search);
+			const value = options.secret
+				? await (async () => {
+						const exp = Math.floor(Date.now() / 1000) + ttl;
+						const payload = `1.${exp}`;
+						return `${payload}.${await sign(payload, options.secret as string)}`;
+					})()
+				: "1";
+			res.headers.append(
+				"Set-Cookie",
+				`${name}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${ttl}`,
+			);
+			return res;
+		}
+		const raw = ctx.request.headers
+			.get("cookie")
+			?.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`))?.[1];
+		if (raw) {
+			if (options.secret) {
+				const parts = raw.split(".");
+				if (parts.length === 3) {
+					const [v, expS, sig] = parts;
+					const payload = `${v}.${expS}`;
+					const expected = await sign(payload, options.secret);
+					const expired = Number(expS) < Date.now() / 1000;
+					if (
+						v === "1" &&
+						!expired &&
+						sig.length === expected.length &&
+						timingSafeEq(sig, expected)
+					) {
+						ctx.state[DRAFT_STATE] = true;
+					}
+				}
+			} else if (raw === "1") {
+				ctx.state[DRAFT_STATE] = true;
+			}
+		}
+		return undefined;
+	};
+};
+
+/** Read draft state inside loaders/middleware */
+export const isDraft = (state: Record<string, unknown>): boolean =>
+	state[DRAFT_STATE] === true;

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

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

package/src/app/modules/env/domain/operations/create-env.ts

@@ -0,0 +1,156 @@
+/**
+ * Typed Environment
+ * Validate process.env / import.meta.env once at startup — server
+ * vars never leak to the client (they throw when read on the client),
+ * public vars are the PUBLIC_*-prefixed set (Nuxt runtimeConfig /
+ * Next NEXT_PUBLIC equivalent)
+ */
+
+export interface EnvField<T> {
+	parse: (raw: string | undefined) => T;
+	optional?: boolean;
+}
+
+export const env = {
+	string: (opts?: { default?: string }): EnvField<string> => ({
+		optional: opts?.default !== undefined,
+		parse: (raw) => {
+			if (raw === undefined || raw === "") {
+				if (opts?.default !== undefined) return opts.default;
+				throw new Error("required");
+			}
+			return raw;
+		},
+	}),
+	number: (opts?: { default?: number }): EnvField<number> => ({
+		optional: opts?.default !== undefined,
+		parse: (raw) => {
+			if (raw === undefined || raw === "") {
+				if (opts?.default !== undefined) return opts.default;
+				throw new Error("required");
+			}
+			const n = Number(raw);
+			if (Number.isNaN(n)) throw new Error("not a number");
+			return n;
+		},
+	}),
+	boolean: (): EnvField<boolean> => ({
+		optional: true,
+		parse: (raw) => raw === "true" || raw === "1",
+	}),
+	url: (): EnvField<string> => ({
+		parse: (raw) => {
+			if (!raw) throw new Error("required");
+			return new URL(raw).toString();
+		},
+	}),
+};
+
+type Parsed<F extends Record<string, AnyEnvField<unknown>>> = {
+	[K in keyof F]: F[K] extends EnvField<infer T>
+		? T
+		: F[K] extends SchemaField<infer T>
+			? T
+			: never;
+};
+
+export interface CreateEnvOptions<
+	S extends Record<string, AnyEnvField<unknown>>,
+	P extends Record<string, AnyEnvField<unknown>>,
+> {
+	server?: S;
+	public?: P;
+	/** Env source — defaults to process.env / import.meta.env */
+	source?: Record<string, string | undefined>;
+}
+
+const isClient = (): boolean =>
+	typeof window !== "undefined" && typeof document !== "undefined";
+
+/** Arktype-compatible validator — `{ assert(data): T }` */
+export interface SchemaField<T> {
+	assert: (raw: string | undefined) => T;
+}
+
+export type AnyEnvField<T> = EnvField<T> | SchemaField<T>;
+
+const parseField = <T>(field: AnyEnvField<T>, raw: string | undefined): T =>
+	"parse" in field ? field.parse(raw) : field.assert(raw);
+
+export const createEnv = <
+	S extends Record<string, AnyEnvField<unknown>>,
+	P extends Record<string, AnyEnvField<unknown>>,
+>(
+	options: CreateEnvOptions<S, P>,
+): Parsed<S> & Parsed<P> => {
+	const source =
+		options.source ??
+		({
+			...(typeof process !== "undefined" ? process.env : {}),
+			// Vite client bundles expose PUBLIC_* via import.meta.env
+			...(typeof import.meta !== "undefined"
+				? (import.meta as { env?: Record<string, string | undefined> }).env
+				: {}),
+		} as Record<string, string | undefined>);
+
+	const result: Record<string, unknown> = {};
+	const errors: string[] = [];
+
+	for (const [group, fields] of [
+		["server", options.server ?? {}],
+		["public", options.public ?? {}],
+	] as const) {
+		for (const [name, field] of Object.entries(
+			fields as Record<string, AnyEnvField<unknown>>,
+		)) {
+			try {
+				result[name] = parseField(field, source[name]);
+			} catch {
+				errors.push(`${name} (${group})`);
+			}
+		}
+	}
+
+	if (errors.length > 0) {
+		throw new Error(
+			`[solid-framework] invalid environment: ${errors.join(", ")}`,
+		);
+	}
+
+	// Server vars throw when read in the browser bundle
+	if (isClient()) {
+		for (const name of Object.keys(options.server ?? {})) {
+			Object.defineProperty(result, name, {
+				get() {
+					throw new Error(
+						`[solid-framework] server env "${name}" is not available on the client`,
+					);
+				},
+			});
+		}
+	}
+
+	return result as Parsed<S> & Parsed<P>;
+};
+
+/** Alias — `defineEnv({ server: {SECRET: env.string()}, public: {...} })` */
+export const defineEnv = createEnv;
+
+/**
+ * Public-only view of a createEnv result — safe in client bundles;
+ * returns just the listed `public` group keys, typed:
+ *
+ *   const e = createEnv({ public: { PUBLIC_API: env.string() } });
+ *   const pub = usePublicEnv(e, ["PUBLIC_API"]); // {PUBLIC_API: string}
+ */
+export const usePublicEnv = <
+	T extends Record<string, unknown>,
+	K extends keyof T,
+>(
+	created: T,
+	keys: readonly K[],
+): Pick<T, K> => {
+	const out = {} as Pick<T, K>;
+	for (const k of keys) out[k] = created[k];
+	return out;
+};

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

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

package/src/app/modules/file-routes/application/usecases/api-client.ts

@@ -0,0 +1,120 @@
+/**
+ * Typed API Client
+ * Runtime client for `.api.ts` routes — paths and methods are typed
+ * from the manifest; `solid generate` emits the ApiPaths union so
+ * callers get autocomplete + param checking:
+ *
+ *   const api = createApiClient<{ "/users/[id]": { GET: User } }>();
+ *   const user = await api.get("/users/[id]", { params: { id: "1" } });
+ */
+
+export type ApiMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * Api Error — thrown by `client.json()` on non-2xx responses;
+ * `body` carries the parsed `{error}` envelope when present
+ */
+export class ApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+	readonly body: unknown;
+	constructor(status: number, body: unknown) {
+		const env = body as { error?: { code?: string; message?: string } } | null;
+		super(env?.error?.message ?? `api request failed: ${status}`);
+		this.name = "ApiError";
+		this.status = status;
+		this.code = env?.error?.code ?? "API_ERROR";
+		this.body = body;
+	}
+}
+
+export const isApiError = (error: unknown): error is ApiError =>
+	error instanceof ApiError;
+
+/** Augmented by `.solid/api.d.ts` (solid generate) — path → methods map */
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merged by generated api.d.ts — must stay an interface
+export interface GeneratedApiPaths {}
+
+type ParamsOf<Path extends string> =
+	Path extends `${string}[${infer Param}]${infer Rest}`
+		? { [K in Param]: string } & ParamsOf<Rest>
+		: Record<never, never>;
+
+type MethodsOf<TPaths, Path extends keyof TPaths & string> = keyof TPaths[Path];
+
+export interface ApiCallOptions<Path extends string> {
+	params?: ParamsOf<Path>;
+	search?: Record<string, string | number | boolean | undefined>;
+	headers?: Record<string, string>;
+	body?: unknown;
+}
+
+export interface ApiClient<TPaths> {
+	call<Path extends keyof TPaths & string>(
+		method: MethodsOf<TPaths, Path> & ApiMethod,
+		path: Path,
+		options?: ApiCallOptions<Path>,
+	): Promise<Response>;
+	get<Path extends keyof TPaths & string>(
+		path: Path,
+		options?: ApiCallOptions<Path>,
+	): Promise<Response>;
+	post<Path extends keyof TPaths & string>(
+		path: Path,
+		options?: ApiCallOptions<Path>,
+	): Promise<Response>;
+	json<Path extends keyof TPaths & string>(
+		method: MethodsOf<TPaths, Path> & ApiMethod,
+		path: Path,
+		options?: ApiCallOptions<Path>,
+	): Promise<unknown>;
+}
+
+const fillParams = (path: string, params?: Record<string, string>): string =>
+	path.replace(/\[(\w+)\]/g, (_, key) =>
+		encodeURIComponent(params?.[key] ?? ""),
+	);
+
+export const createApiClient = <
+	TPaths = GeneratedApiPaths extends { [K in never]: never }
+		? Record<string, Record<string, unknown>>
+		: GeneratedApiPaths,
+>(
+	options: { baseUrl?: string; fetch?: typeof fetch } = {},
+): ApiClient<TPaths> => {
+	const fetchFn = options.fetch ?? fetch;
+	const base = options.baseUrl ?? "";
+
+	const call = async <Path extends string>(
+		method: ApiMethod,
+		path: Path,
+		opts?: ApiCallOptions<Path>,
+	): Promise<Response> => {
+		const url = new URL(`${base}${fillParams(path, opts?.params)}`, "http://x");
+		for (const [k, v] of Object.entries(opts?.search ?? {})) {
+			if (v !== undefined) url.searchParams.set(k, String(v));
+		}
+		return fetchFn(url.pathname + url.search, {
+			method,
+			headers: {
+				...(opts?.body !== undefined
+					? { "Content-Type": "application/json" }
+					: {}),
+				...opts?.headers,
+			},
+			body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,
+		});
+	};
+
+	return {
+		call: (method, path, opts) => call(method, path, opts),
+		get: (path, opts) => call("GET", path, opts),
+		post: (path, opts) => call("POST", path, opts),
+		json: async (method, path, opts) => {
+			const response = await call(method, path, opts);
+			const body = await response.json().catch(() => null);
+			if (!response.ok) throw new ApiError(response.status, body);
+			return body;
+		},
+	};
+};

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

@@ -0,0 +1,61 @@
+/**
+ * Route Errors
+ * notFound() throws a typed error the render pipeline translates
+ * into a 404 status + the nearest not-found convention module
+ */
+
+export class NotFoundError extends Error {
+	readonly code = "NOT_FOUND" as const;
+	constructor(message = "Not Found") {
+		super(message);
+		this.name = "NotFoundError";
+	}
+}
+
+export const notFound = (message = "Not Found"): never => {
+	throw new NotFoundError(message);
+};
+
+export const isNotFoundError = (error: unknown): error is NotFoundError =>
+	error instanceof NotFoundError ||
+	(typeof error === "object" &&
+		error !== null &&
+		(error as { code?: string }).code === "NOT_FOUND");
+
+/**
+ * Loader Error — thrown by the client loader path when the endpoint
+ * (or SSR chain) fails; carries a serialized code + status so
+ * error.tsx boundaries can branch on it
+ */
+export class LoaderError extends Error {
+	readonly code: string;
+	readonly status: number;
+	constructor(code: string, message: string, status = 500) {
+		super(message);
+		this.name = "LoaderError";
+		this.code = code;
+		this.status = status;
+	}
+}
+
+export const isLoaderError = (error: unknown): error is LoaderError =>
+	error instanceof LoaderError ||
+	(typeof error === "object" &&
+		error !== null &&
+		(error as { code?: string }).code === "LOADER_ERROR");
+
+/** Serialize an unknown error into the loader error envelope */
+export const loaderErrorBody = (
+	error: unknown,
+): { code: string; message: string } => {
+	if (isNotFoundError(error)) {
+		return { code: "NOT_FOUND", message: error.message };
+	}
+	if (isLoaderError(error)) {
+		return { code: error.code, message: error.message };
+	}
+	return {
+		code: "LOADER_ERROR",
+		message: error instanceof Error ? error.message : "Loader failed",
+	};
+};