@torpor/build 0.4.14 → 1.0.0

package/src/nav/navigate.ts

@@ -1,6 +1,6 @@
 import { clearLayoutSlot, fillLayoutSlot, hydrate } from "@torpor/view";
 import { type Component, type SlotRender } from "@torpor/view";
-import { mount } from "@torpor/view";
+import { mount, unmount } from "@torpor/view";
 import $page from "../state/$page";
 import client from "../state/client";
 import type LayoutPath from "../types/LayoutPath";
@@ -98,6 +98,13 @@ export default async function navigate(url: URL, withHydration = false): Promise
 	// TODO: There's probably a nicer way to do this with reducers or something
 	let component = clientEndPoint.component as Component;
 	let slots: Record<string, SlotRender> | undefined = undefined;
+	let reused = false;
+	// The index of the innermost reused layout. Its slotRegion is the region
+	// that must be cleared and refilled (it contains the next layout's or the
+	// page's content). This is usually the last entry of the stack, but not
+	// when an outer layout is reused while an inner one is new — e.g.
+	// navigating between sections that share the root layout.
+	let reusedIndex = -1;
 	if (handler.layouts) {
 		let slotFunctions: SlotRender[] = [];
 		// The last slot function will render the client component
@@ -119,12 +126,12 @@ export default async function navigate(url: URL, withHydration = false): Promise
 				?.default;
 			if (layoutEndPoint?.component) {
 				if (layoutStack[i].reuse) {
-					// Set the parent to add the new content to (from the old
-					// content), clear the range under this point, and set the
-					// component to the slot function within this layout
-					parent = layoutStack[i].slotRegion.startNode.parentNode as HTMLElement;
-					clearLayoutSlot(layoutStack[i].slotRegion);
-					component = slotFunctions[i + 1];
+					// Reuse this layout — clear and refill its slot (done in
+					// the try block below so a failure doesn't leave the slot
+					// half-cleared)
+					component = slotFunctions[i + 1] as Component;
+					reusedIndex = i;
+					reused = true;
 					break;
 				} else if (i === 0) {
 					component = layoutEndPoint.component as Component;
@@ -145,16 +152,34 @@ export default async function navigate(url: URL, withHydration = false): Promise
 		}
 	}
 
-	if (withHydration) {
-		hydrate(parent, component, $props, slots);
-	} else {
-		try {
+	try {
+		if (reused) {
+			// The layout is being reused — clear the old slot content, then
+			// call the slot function directly to fill it with the new page.
+			// We must not go through `mount` here: the slot's container still
+			// holds the layout's own children (e.g. a header), which `mount`
+			// refuses to mount into. Both the clear and the fill are inside
+			// the try so that a failure doesn't leave the slot half-cleared.
+			const slotRegion = layoutStack[reusedIndex].slotRegion;
+			parent = slotRegion.startNode!.parentNode as HTMLElement;
+			clearLayoutSlot(slotRegion);
+			component(parent, null);
+		} else if (withHydration) {
+			hydrate(parent, component, $props, slots);
+		} else {
+			// The layout chain changed (or there was no previous layout to
+			// reuse): tear down the previous UI entirely — disposing its
+			// region tree and clearing `#app` — so `mount` starts fresh.
+			// Without this, `mount` throws because `#app` still holds the
+			// previous render's children, and it would reuse a stale root
+			// region.
+			unmount(parent);
 			mount(parent, component, $props, slots);
-		} catch (error) {
-			// TODO: Show a proper Error component
-			parent.innerHTML = '<span style="color: red">Script syntax error</span><p>' + error + "</p>";
-			console.log(error);
 		}
+	} catch (error) {
+		// TODO: Show a proper Error component
+		parent.innerHTML = '<span style="color: red">Script syntax error</span><p>' + error + "</p>";
+		console.log(error);
 	}
 
 	// Reset prefetched data on each navigation

package/src/nav/route.ts

@@ -0,0 +1,38 @@
+import type { ExactRouteParams, ParseRouteParams } from "../types/ParseRouteParams";
+
+/**
+ * Builds a route path in a type-safe manner, filling in dynamic segments, e.g.
+ * `route("/posts/[id]", { id: 5 })` returns `/posts/5`. The params object is
+ * checked for exact keys: missing or unknown params error at compile time.
+ *
+ * NOTE: The rest args conditional must stay INLINE — routing it through a type
+ * alias defeats `Params` inference, and excess keys stop being checked
+ * @param path The route path
+ * @param params The route params, required if the path has dynamic segments
+ * @returns The path with the params filled in, URI-encoded
+ */
+export default function route<
+	Route extends string,
+	Params extends ParseRouteParams<Route> = ParseRouteParams<Route>,
+>(
+	path: Route,
+	...args: string extends Route
+		? [params?: Record<string, string>]
+		: keyof ParseRouteParams<Route> extends never
+			? []
+			: [params: Params & ExactRouteParams<Params, ParseRouteParams<Route>>]
+): string {
+	const params = ((args as unknown[])[0] ?? {}) as Record<string, string>;
+	return path.replace(/\[(\.\.\.)?([^\]]+)\]/g, (_, splat: string | undefined, name: string) => {
+		const value = params[name];
+		if (value === undefined) {
+			throw new Error(`Missing param '${name}' for route '${path}'`);
+		}
+		return splat
+			? value
+					.split("/")
+					.map((segment) => encodeURIComponent(segment))
+					.join("/")
+			: encodeURIComponent(String(value));
+	});
+}

package/src/nav.ts

@@ -1,4 +1,6 @@
+import makeApi from "./nav/api";
 import load from "./nav/load";
 import reload from "./nav/reload";
+import route from "./nav/route";
 
-export { load, reload };
+export { load, reload, route, makeApi };

package/src/openapi/docsHtml.ts

@@ -0,0 +1,25 @@
+/**
+ * A standalone HTML page loading Swagger UI from a CDN, pointed at the
+ * OpenAPI document endpoint.
+ */
+export default function openApiDocsHtml(docPath: string): string {
+	return `<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1" />
+	<title>API Docs</title>
+	<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+</head>
+<body>
+	<div id="swagger-ui"></div>
+	<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js" crossorigin></script>
+	<script>
+		window.addEventListener("DOMContentLoaded", () => {
+			SwaggerUIBundle({ url: ${JSON.stringify(docPath)}, dom_id: "#swagger-ui" });
+		});
+	</script>
+</body>
+</html>
+`;
+}

package/src/openapi/document.ts

@@ -0,0 +1,154 @@
+import type { StandardSchemaV1 } from "../types/StandardSchema";
+import type { OpenApiPluginOptions, OpenApiRouteEntry, JsonSchema } from "./types";
+
+// The endpoint handler names, in the order they appear in docs
+const METHODS = ["get", "post", "patch", "put", "del", "options", "head"] as const;
+type Method = (typeof METHODS)[number];
+
+// Handlers whose schema validates the query string; all others validate the
+// json request body
+const QUERY_METHODS: readonly string[] = ["get", "head"];
+const BODY_METHODS: readonly string[] = ["post", "patch", "put", "del", "options"];
+
+/**
+ * Builds an OpenAPI 3.1 document from a list of +server endpoints.
+ *
+ * Each endpoint's route path (`/api/posts/[id]`) is converted to OpenAPI
+ * syntax (`/api/posts/{id}`); its `params` schema becomes path parameters,
+ * its `get`/`head` schema becomes query parameters, and its `post`/`patch`/
+ * `put`/`del`/`options` schema becomes a json request body. Responses are
+ * stubbed: a `200` for every handler, plus a `422` when the handler declares
+ * an input schema (validation errors are returned automatically).
+ *
+ * Throws if any endpoint declares a schema but the options have no
+ * `toJsonSchema` converter.
+ */
+export default function buildOpenApiDocument(
+	entries: OpenApiRouteEntry[],
+	options: OpenApiPluginOptions,
+): Record<string, unknown> {
+	if (!options.toJsonSchema) {
+		const withSchema = entries.find(hasSchemas);
+		if (withSchema) {
+			throw new Error(
+				`The endpoint at ${withSchema.path} declares schema(s), but the openApi() plugin ` +
+					`was not given a "toJsonSchema" converter. Pass one, e.g. ` +
+					`openApi({ toJsonSchema: (s) => z.toJSONSchema(s) })`,
+			);
+		}
+	}
+
+	const paths: Record<string, Record<string, unknown>> = {};
+	for (const entry of entries) {
+		const pathItem = buildPathItem(entry, options);
+		if (pathItem) {
+			paths[openApiPath(entry.path)] = pathItem;
+		}
+	}
+
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: options.title ?? "API",
+			version: options.version ?? "1.0.0",
+		},
+		paths,
+	};
+}
+
+function hasSchemas(entry: OpenApiRouteEntry): boolean {
+	const schema = entry.endPoint?.schema;
+	if (!schema) return false;
+	return METHODS.some((method) => schema[method]) || !!schema.params;
+}
+
+function buildPathItem(
+	entry: OpenApiRouteEntry,
+	options: OpenApiPluginOptions,
+): Record<string, unknown> | undefined {
+	const endPoint = entry.endPoint;
+	const pathItem: Record<string, unknown> = {};
+	let count = 0;
+
+	for (const method of METHODS) {
+		if (typeof endPoint[method] !== "function") {
+			continue;
+		}
+		count++;
+
+		const schema = endPoint.schema?.[method];
+		const paramsSchema = endPoint.schema?.params;
+
+		const parameters: Record<string, unknown>[] = [];
+		if (paramsSchema) {
+			parameters.push(...flattenObject(convert(paramsSchema, options), "path"));
+		}
+		if (schema && QUERY_METHODS.includes(method)) {
+			parameters.push(...flattenObject(convert(schema, options), "query"));
+		}
+
+		const responses: Record<string, unknown> = { "200": { description: "OK" } };
+		if (schema) {
+			responses["422"] = { description: "Validation failed" };
+		}
+
+		pathItem[method === "del" ? "delete" : method] = {
+			operationId: operationId(method, entry.path),
+			...(parameters.length ? { parameters } : {}),
+			...(schema && BODY_METHODS.includes(method)
+				? {
+						requestBody: {
+							required: true,
+							content: { "application/json": { schema: convert(schema, options) } },
+						},
+					}
+				: {}),
+			responses,
+		};
+	}
+
+	return count > 0 ? pathItem : undefined;
+}
+
+function convert(schema: StandardSchemaV1, options: OpenApiPluginOptions): JsonSchema {
+	return options.toJsonSchema!(schema);
+}
+
+/**
+ * Flattens a converted object schema into OpenAPI parameters. Path
+ * parameters are always required; query parameters take their `required`
+ * flag from the schema's `required` array.
+ */
+function flattenObject(
+	jsonSchema: JsonSchema,
+	location: "path" | "query",
+): Record<string, unknown>[] {
+	const properties = jsonSchema.properties;
+	if (!properties || typeof properties !== "object") {
+		return [];
+	}
+	const required = Array.isArray(jsonSchema.required) ? jsonSchema.required : [];
+	return Object.entries(properties as Record<string, JsonSchema>).map(([name, propSchema]) => ({
+		name,
+		in: location,
+		required: location === "path" ? true : required.includes(name),
+		schema: propSchema,
+	}));
+}
+
+/**
+ * Converts a route path to OpenAPI syntax: `/api/posts/[id]` becomes
+ * `/api/posts/{id}`.
+ */
+function openApiPath(routePath: string): string {
+	return routePath.replace(/\[\.\.\.([^\]]+)\]/g, "{$1}").replace(/\[([^\]]+)\]/g, "{$1}");
+}
+
+function operationId(method: Method, routePath: string): string {
+	const segments = openApiPath(routePath)
+		.split(/[^a-zA-Z0-9]+/)
+		.filter((s) => s.length > 0)
+		.map((s) => s.charAt(0).toUpperCase() + s.slice(1));
+	const verb = method === "del" ? "delete" : method;
+	return verb + (segments.join("") || "Root");
+}

package/src/openapi/plugin.ts

@@ -0,0 +1,78 @@
+import type SitePlugin from "../types/SitePlugin";
+import openApiDocsHtml from "./docsHtml";
+import type { OpenApiPluginOptions, ResolvedOpenApiOptions } from "./types";
+
+/**
+ * The `site.pluginState` key the openApi plugin stores its resolved options
+ * under. A registry symbol (`Symbol.for`), so that the user's config, the
+ * manifest plugin and the generated runtime code all resolve to the same
+ * key even when they are loaded as separate module instances.
+ */
+export const OPEN_API_STATE_KEY: symbol = Symbol.for("@torpor/build/openapi");
+
+/**
+ * Serves an OpenAPI 3.1 document for the site's `+server` endpoints, plus an
+ * optional interactive docs page.
+ *
+ * ```ts
+ * import { Site } from "@torpor/build";
+ * import { openApi } from "@torpor/build/openapi";
+ * import { z } from "zod";
+ *
+ * const site = new Site();
+ * site.addRouteFolder("src/routes");
+ * site.plugins = [
+ * 	openApi({
+ * 		title: "My API",
+ * 		toJsonSchema: (s) => z.toJSONSchema(s as z.ZodType, { io: "input" }),
+ * 	}),
+ * ];
+ * export default site;
+ * ```
+ *
+ * The document is served at `/openapi.json` (configurable with `path`) and
+ * the docs page at `/docs` (set `docs: false` to disable). Endpoints are
+ * picked up from every `+server.ts` route: its `params` schema becomes path
+ * parameters, `get`/`head` schemas become query parameters, and
+ * `post`/`patch`/`put`/`del`/`options` schemas become request bodies.
+ *
+ * The resolved options are stored in `site.pluginState` under
+ * `OPEN_API_STATE_KEY`, which the manifest plugin reads at build time to
+ * generate the document endpoint.
+ */
+export function openApi(options: OpenApiPluginOptions = {}): SitePlugin {
+	return (site) => {
+		const docPath = withLeadingSlash(options.path ?? "/openapi.json");
+		if (site.routes.some((route) => route.path === docPath)) {
+			throw new Error(
+				`There is already a route registered at ${docPath}, so the OpenAPI document can't be ` +
+					`served there. Pass a different "path" to the openApi() plugin`,
+			);
+		}
+
+		const resolved: ResolvedOpenApiOptions = {
+			path: docPath,
+			docs: options.docs === false ? undefined : withLeadingSlash(options.docs ?? "/docs"),
+			title: options.title ?? "API",
+			version: options.version ?? "1.0.0",
+			toJsonSchema: options.toJsonSchema,
+		};
+		site.pluginState.set(OPEN_API_STATE_KEY, resolved);
+
+		if (resolved.docs) {
+			const html = openApiDocsHtml(docPath);
+			site.addRoute(resolved.docs, {
+				server: {
+					get: () =>
+						new Response(html, {
+							headers: { "Content-Type": "text/html; charset=utf-8" },
+						}),
+				},
+			});
+		}
+	};
+}
+
+function withLeadingSlash(pathName: string): string {
+	return pathName.startsWith("/") ? pathName : "/" + pathName;
+}

package/src/openapi/types.ts

@@ -0,0 +1,82 @@
+import type { StandardSchemaV1 } from "../types/StandardSchema";
+
+/**
+ * A JSON Schema object, as produced by a schema library's converter (e.g.
+ * `z.toJSONSchema`, valibot's `toJsonSchema`, arktype's `toJsonSchema`).
+ */
+export type JsonSchema = Record<string, unknown>;
+
+/**
+ * Converts a Standard Schema (zod, valibot, arktype, ...) into a JSON Schema
+ * object, for inclusion in an OpenAPI document. Supplied to the openApi
+ * plugin, since each schema library has its own conversion function:
+ *
+ * ```ts
+ * // zod
+ * openApi({ toJsonSchema: (s) => z.toJSONSchema(s as z.ZodType, { io: "input" }) })
+ * // arktype
+ * openApi({ toJsonSchema: (s) => (s as Type).toJsonSchema() })
+ * ```
+ */
+export type ToJsonSchema = (schema: StandardSchemaV1) => JsonSchema;
+
+/**
+ * Options for the openApi plugin.
+ */
+export type OpenApiPluginOptions = {
+	/**
+	 * The path to serve the OpenAPI document at. Defaults to `/openapi.json`.
+	 */
+	path?: string;
+	/**
+	 * The path to serve interactive API docs at, or `false` to disable the
+	 * docs page. Defaults to `/docs`.
+	 */
+	docs?: string | false;
+	/**
+	 * The API title for the document's `info` section. Defaults to `"API"`.
+	 */
+	title?: string;
+	/**
+	 * The API version for the document's `info` section. Defaults to
+	 * `"1.0.0"`.
+	 */
+	version?: string;
+	/**
+	 * Converts an endpoint's schemas into JSON Schema. Required for endpoints
+	 * that declare schemas; endpoints without schemas are documented with
+	 * their paths and methods only.
+	 */
+	toJsonSchema?: ToJsonSchema;
+};
+
+/**
+ * OpenApi options with defaults applied. Created by the openApi plugin and
+ * consumed by the document builder.
+ */
+export type ResolvedOpenApiOptions = {
+	path: string;
+	/** Undefined when the docs page is disabled */
+	docs: string | undefined;
+	title: string;
+	version: string;
+	toJsonSchema: ToJsonSchema | undefined;
+};
+
+/**
+ * A ServerEndPoint shape, loosely typed so that endpoint modules loaded from
+ * anywhere can be passed to the document builder.
+ */
+export type OpenApiEndPoint = {
+	schema?: Record<string, StandardSchemaV1 | undefined> | undefined;
+	[method: string]: unknown;
+};
+
+/**
+ * A single API endpoint to include in an OpenAPI document: its route path
+ * (with `[param]` segments) and its default-exported endpoint object.
+ */
+export type OpenApiRouteEntry = {
+	path: string;
+	endPoint: OpenApiEndPoint;
+};

package/src/openapi.ts

@@ -0,0 +1,14 @@
+import buildOpenApiDocument from "./openapi/document";
+import openApiDocsHtml from "./openapi/docsHtml";
+import { OPEN_API_STATE_KEY, openApi } from "./openapi/plugin";
+
+export { buildOpenApiDocument, openApi, openApiDocsHtml, OPEN_API_STATE_KEY };
+
+export type {
+	JsonSchema,
+	OpenApiEndPoint,
+	OpenApiPluginOptions,
+	OpenApiRouteEntry,
+	ResolvedOpenApiOptions,
+	ToJsonSchema,
+} from "./openapi/types";

package/src/response/TypedResponse.ts

@@ -0,0 +1,17 @@
+/**
+ * A Response whose JSON body type is known, as returned by e.g. `ok({ ... })`.
+ * Purely a compile-time marker: `__body` is never set at runtime.
+ */
+export default interface TypedResponse<T> extends Response {
+	/**
+	 * Phantom property carrying the body type. Required so that plain
+	 * `Response` values do not match `TypedResponse<infer T>`.
+	 */
+	readonly __body: T;
+}
+
+/**
+ * A Response that does not carry typed JSON data (e.g. redirects, errors,
+ * plain-text bodies). Loads may return these alongside typed data responses.
+ */
+export type UntypedResponse = Response & { readonly __body?: never };

package/src/response/badRequest.ts

@@ -1,4 +1,10 @@
 import response from "./response";
+import type { Jsonify } from "../types/Jsonify";
+import type TypedResponse from "./TypedResponse";
+
+type BadRequestResponse<T extends object | string | undefined> = T extends object
+	? TypedResponse<Jsonify<T>>
+	: Response;
 
 /**
  * 400 Bad Request
@@ -12,8 +18,14 @@ import response from "./response";
  * Clients that receive a 400 response should expect that repeating the request
  * without modification will fail with the same error.
  *
+ * An object body is typed: it becomes the page's `$props.form` (with its JSON
+ * form) after a form submit, so validation errors can be surfaced with their
+ * field types via `PageForm`.
+ *
  * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400
  */
-export default function badRequest(body?: object | string): Response {
-	return response(400, body ?? "Bad request");
+export default function badRequest<T extends object | string | undefined>(
+	body?: T,
+): BadRequestResponse<T> {
+	return response(400, body ?? "Bad request") as BadRequestResponse<T>;
 }

package/src/response/created.ts

@@ -1,5 +1,11 @@
+import type { Jsonify } from "../types/Jsonify";
+import type TypedResponse from "./TypedResponse";
 import response from "./response";
 
+type CreatedResponse<T extends object | string | undefined> = T extends object
+	? TypedResponse<Jsonify<T>>
+	: Response;
+
 /**
  * 201 Created
  *
@@ -13,8 +19,13 @@ import response from "./response";
  * initiating request or by the URL in the value of the Location header provided
  * with the response.
  *
+ * An object body is typed: the client sees its JSON form through
+ * `makeApi`-created callers.
+ *
  * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/201
  */
-export default function created(body?: object | string): Response {
-	return response(201, body);
+export default function created<T extends object | string | undefined>(
+	body?: T,
+): CreatedResponse<T> {
+	return response(201, body) as CreatedResponse<T>;
 }

package/src/response/found.ts

@@ -25,6 +25,6 @@ import transfer from "./transfer";
  *
  * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/302
  */
-export default function permRedirect(location: string): Response {
-	return transfer(308, location);
+export default function found(location: string): Response {
+	return transfer(302, location);
 }

package/src/response/movedPermanently.ts

@@ -20,6 +20,6 @@ import transfer from "./transfer";
  *
  * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/301
  */
-export default function permRedirect(location: string): Response {
-	return transfer(308, location);
+export default function movedPermanently(location: string): Response {
+	return transfer(301, location);
 }

package/src/response/notModified.ts

@@ -29,6 +29,6 @@ import transfer from "./transfer";
  *
  * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/304
  */
-export default function notModified(location: string): Response {
-	return transfer(304, location);
+export default function notModified(): Response {
+	return transfer(304, "");
 }

package/src/response/ok.ts

@@ -1,5 +1,11 @@
+import type { Jsonify } from "../types/Jsonify";
+import type TypedResponse from "./TypedResponse";
 import response from "./response";
 
+type OkResponse<T extends object | string | undefined> = T extends object
+	? TypedResponse<Jsonify<T>>
+	: Response;
+
 /**
  * 200 OK
  *
@@ -17,13 +23,16 @@ import response from "./response";
  * - TRACE: The response has a message body containing the request as received
  *   by the server.
  *
- * Although possible, successful PUT or DELETE requests often do not result in a
- * 200 OK response. It is more common to see 201 Created if the resource is
+ * Although possible, successful PUT or DELETE requests often do not result in
+ * a 200 OK response. It is more common to see 201 Created if the resource is
  * uploaded or created for the first time, or 204 No Content upon successful
  * deletion of a resource.
  *
+ * An object body is typed: the client sees its JSON form through
+ * `makeApi`-created callers.
+ *
  * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200
  */
-export default function ok(body?: object | string): Response {
-	return response(200, body);
+export default function ok<T extends object | string | undefined>(body?: T): OkResponse<T> {
+	return response(200, body) as OkResponse<T>;
 }

package/src/response/response.ts

@@ -1,18 +1,18 @@
 /**
  * Creates a response with the supplied status code and optional body.
  *
- * If the body is an object, it will be converted to JSON and the content-type
+ * If the body is an object, it will be converted to JSON and the Content-Type
  * header set to "application/json". Otherwise, if the body is a string, the
- * content-type header will be set to "text/plain".
+ * Content-Type header will be set to "text/plain".
  */
 export default function response(status: number, body?: object | string): Response {
 	let headers: Record<string, string> | undefined = undefined;
 	if (body) {
 		if (typeof body === "object") {
-			headers = { "content-type": "application/json" };
+			headers = { "Content-Type": "application/json" };
 			body = JSON.stringify(body);
 		} else {
-			headers = { "content-type": "text/plain" };
+			headers = { "Content-Type": "text/plain" };
 		}
 	}
 	return new Response(body, {