@torpor/build 1.0.0 → 1.0.1

package/src/nav/navigate.ts

@@ -1,189 +0,0 @@
-import { clearLayoutSlot, fillLayoutSlot, hydrate } from "@torpor/view";
-import { type Component, type SlotRender } 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";
-import type PageEndPoint from "../types/PageEndPoint";
-import type PageServerEndPoint from "../types/PageServerEndPoint";
-import formSubmit from "./formSubmit";
-import loadData from "./loadData";
-
-// @ts-ignore
-export default async function navigate(url: URL, withHydration = false): Promise<boolean> {
-	let parent = document.getElementById("app");
-	if (!parent) {
-		// TODO: 500
-		console.log("500");
-		return false;
-	}
-
-	const path = url.pathname;
-	const query = url.searchParams;
-
-	//console.log(`navigating to '${path}'${query.size ? ` with ${query}` : ""}`);
-
-	const route = client.router.match(path, query);
-	if (!route) {
-		// TODO: 404
-		console.log("404");
-		return false;
-	}
-
-	// Update $page before building the components
-	$page.url = url;
-	if (path.endsWith("/_error")) {
-		$page.status = parseInt(query.get("status") ?? "404");
-		$page.error = { message: query.get("message") ?? "" };
-		// Make it look a bit classier by removing the query
-		window.history.replaceState({}, "", url.toString().split("?")[0]);
-	} else {
-		$page.status = 200;
-	}
-	const handler = route.handler;
-	const params = route.params || {};
-
-	// There must be a client endpoint with a component
-	const clientEndPoint: PageEndPoint | undefined = (await handler.endPoint()).default;
-	if (!clientEndPoint?.component) {
-		// TODO: 404
-		console.log("404");
-		return false;
-	}
-
-	// There may be a server endpoint
-	const serverEndPoint: PageServerEndPoint | undefined =
-		handler.serverEndPoint && (await handler.serverEndPoint())?.default;
-
-	let newLayoutStack: LayoutPath[] = [];
-
-	// Pass the data into $props
-	// TODO: Don't load if this is the first time -- it should have been passed
-	// to us, somehow...
-	const data = await loadData(
-		handler,
-		params,
-		path,
-		query,
-		newLayoutStack,
-		clientEndPoint,
-		serverEndPoint,
-	);
-	// We may have form data in a hidden input -- not sure if this is the best
-	// way to do it
-	let formInput = document.getElementById("t-form-data") as HTMLInputElement;
-	let form: Record<string, string> | undefined;
-	if (formInput) {
-		form = JSON.parse(formInput.value);
-		$page.form = form;
-		formInput.remove();
-	}
-	let $props: Record<string, any> = { data };
-
-	// We may have form data in $page.form, either from the hidden input
-	// (above), or added via onformsubmit (below)
-	$props.form = $page.form;
-
-	// Add some special context for submitting Forms client-side
-	const $context = {
-		TorporBuildContext: { onformsubmit: formSubmit },
-	};
-
-	client.layoutStack.push({ path: route.handler.path, data: {}, reuse: false, slotRegion: null });
-	client.layoutStack = newLayoutStack;
-	let layoutStack = client.layoutStack;
-
-	// If there are layouts, work our way upwards, pushing each component into
-	// the default slot of its parent
-	// 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
-		slotFunctions[handler.layouts.length] = function clientComponent(parent, anchor) {
-			let i = layoutStack.length - 1;
-			layoutStack[i].slotRegion = fillLayoutSlot(
-				clientEndPoint.component!,
-				slotFunctions[i + 1],
-				parent,
-				anchor,
-				$props,
-				$context,
-			);
-		};
-
-		// Each earlier slot function will render a layout
-		for (let i = handler.layouts.length - 1; i >= 0; i--) {
-			const layoutEndPoint: PageEndPoint | undefined = (await handler.layouts[i].endPoint())
-				?.default;
-			if (layoutEndPoint?.component) {
-				if (layoutStack[i].reuse) {
-					// 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;
-					slots = { _: slotFunctions[i + 1] };
-				} else {
-					slotFunctions[i] = function layoutComponent(parent, anchor, _, $context) {
-						layoutStack[i - 1].slotRegion = fillLayoutSlot(
-							layoutEndPoint.component!,
-							slotFunctions[i + 1],
-							parent,
-							anchor,
-							$props,
-							$context,
-						);
-					};
-				}
-			}
-		}
-	}
-
-	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);
-	}
-
-	// Reset prefetched data on each navigation
-	client.prefetchedData = {};
-
-	return true;
-}

package/src/nav/reload.ts

@@ -1,9 +0,0 @@
-import navigate from "./navigate";
-
-/**
- * Reloads data for the currently loaded page and rerenders it.
- */
-export default async function reload(): Promise<boolean> {
-	const url = new URL(document.location.href);
-	return await navigate(url);
-}

package/src/nav/route.ts

@@ -1,38 +0,0 @@
-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,6 +0,0 @@
-import makeApi from "./nav/api";
-import load from "./nav/load";
-import reload from "./nav/reload";
-import route from "./nav/route";
-
-export { load, reload, route, makeApi };

package/src/openapi/docsHtml.ts

@@ -1,25 +0,0 @@
-/**
- * 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

@@ -1,154 +0,0 @@
-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

@@ -1,78 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,17 +0,0 @@
-/**
- * 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,31 +0,0 @@
-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
- *
- * The HTTP 400 Bad Request client error response status code indicates that the
- * server would not process the request due to something the server considered
- * to be a client error. The reason for a 400 response is typically due to
- * malformed request syntax, invalid request message framing, or deceptive
- * request routing.
- *
- * 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<T extends object | string | undefined>(
-	body?: T,
-): BadRequestResponse<T> {
-	return response(400, body ?? "Bad request") as BadRequestResponse<T>;
-}

package/src/response/created.ts

@@ -1,31 +0,0 @@
-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
- *
- * The HTTP 201 Created successful response status code indicates that the HTTP
- * request has led to the creation of a resource. This status code is commonly
- * sent as the result of a POST request.
- *
- * The new resource, or a description and link to the new resource, is created
- * before the response is returned. The newly-created items can be returned in
- * the body of the response message, but must be locatable by the URL of the
- * 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<T extends object | string | undefined>(
-	body?: T,
-): CreatedResponse<T> {
-	return response(201, body) as CreatedResponse<T>;
-}