@torpor/build 0.4.13 → 1.0.0

package/src/types/ParseRouteParams.test-d.ts

@@ -0,0 +1,84 @@
+import type PageEndPoint from "./PageEndPoint";
+import type PageLoadEvent from "./PageLoadEvent";
+import type PageServerEndPoint from "./PageServerEndPoint";
+import type { ParseRouteParams, RouteArgs, RouteParamsOf } from "./ParseRouteParams";
+import type ServerLoadEvent from "./ServerLoadEvent";
+import route from "../nav/route";
+
+type Equals<A, B> =
+	(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Mutual<A, B> = A extends B ? (B extends A ? true : false) : false;
+type Expect<T extends true> = T;
+type IsNever<T> = [T] extends [never] ? true : false;
+
+// --- ParseRouteParams ---
+
+export type T01 = Expect<Equals<ParseRouteParams<"/about">, unknown>>;
+export type T02 = Expect<Equals<ParseRouteParams<"/">, unknown>>;
+export type T03 = Expect<Equals<ParseRouteParams<"/posts/[id]">, { id: string }>>;
+export type T04 = Expect<
+	Mutual<ParseRouteParams<"/users/[userId]/posts/[postId]">, { userId: string; postId: string }>
+>;
+export type T05 = Expect<Equals<ParseRouteParams<"/files/[...path]">, { path: string }>>;
+export type T06 = Expect<Equals<ParseRouteParams<"/api/posts/[id]/~server">, { id: string }>>;
+export type T07 = Expect<IsNever<keyof ParseRouteParams<"/about">>>;
+
+export const postParams: ParseRouteParams<"/posts/[id]"> = { id: "5" };
+export const paramValue: string = postParams.id;
+// @ts-expect-error 'nope' is not a param of /posts/[id]
+export const badParam: string = postParams.nope;
+// @ts-expect-error 'id' is required
+export const missingParam: ParseRouteParams<"/posts/[id]"> = {};
+
+// --- RouteParamsOf (loose defaults) ---
+
+export type T08 = Expect<Equals<RouteParamsOf<undefined>, Record<string, string>>>;
+export type T09 = Expect<Equals<RouteParamsOf<string>, Record<string, string>>>;
+export type T10 = Expect<Equals<RouteParamsOf<"/posts/[id]">, { id: string }>>;
+
+// --- RouteArgs ---
+
+export type T11 = Expect<Equals<RouteArgs<"/about">, []>>;
+export type T12 = Expect<Equals<RouteArgs<"/posts/[id]">, [params: { id: string }]>>;
+
+// --- Typed events ---
+
+export const serverEvent: ServerLoadEvent<"/posts/[id]"> = null as never;
+export const serverParam: string = serverEvent.params.id;
+// @ts-expect-error 'nope' is not a param of /posts/[id]
+export const badServerParam: string = serverEvent.params.nope;
+
+export const pageEvent: PageLoadEvent<"/users/[userId]"> = null as never;
+export const pageParam: string = pageEvent.params.userId;
+
+// --- Usage sites ---
+
+export const pageServer: PageServerEndPoint<"/posts/[id]"> = {
+	load: (ev) => void ev.params.id,
+};
+
+// @ts-expect-error 'nope' is not a param of /posts/[id]
+export const badServer: PageServerEndPoint<"/posts/[id]"> = { load: (ev) => void ev.params.nope };
+
+export const page: PageEndPoint<"/posts/[id]"> = {
+	load: (ev) => void ev.params.id,
+};
+
+// --- Typed link builder ---
+
+export const staticRoute: string = route("/about");
+export const dynamicRoute: string = route("/posts/[id]", { id: "5" });
+export const splatRoute: string = route("/files/[...path]", { path: "a/b" });
+// @ts-expect-error missing params
+void route("/posts/[id]");
+// @ts-expect-error params are not accepted for static routes
+void route("/about", {});
+// @ts-expect-error 'nope' is not a param of /posts/[id]
+void route("/posts/[id]", { nope: "1" });
+// @ts-expect-error 'extra' is not a param of /posts/[id]
+void route("/posts/[id]", { id: "5", extra: "x" });
+// @ts-expect-error 'id' is required
+void route("/posts/[id]", {});
+
+// Non-literal paths fall back to a loose optional params object
+export const looseRoute: string = route("/posts/[id]" as string, { id: "5" });

package/src/types/ParseRouteParams.ts

@@ -0,0 +1,64 @@
+/**
+ * Extracts the params object from a route path string.
+ *
+ * Dynamic segments (`[id]`) and splat segments (`[...path]`) become string
+ * properties; static segments are ignored. For example:
+ *
+ * ```ts
+ * type Params = ParseRouteParams<"/posts/[id]/comments/[commentId]">;
+ * // { id: string; commentId: string }
+ * ```
+ */
+export type ParseRouteParams<Route extends string> = ParseSegments<Route, unknown>;
+
+type ParseSegments<Route extends string, Params> = Route extends `${infer Head}/${infer Rest}`
+	? ParseSegments<Rest, ParseSegment<Head, Params>>
+	: ParseSegment<Route, Params>;
+
+type ParseSegment<Segment extends string, Params> = Segment extends `[...${infer Name}]`
+	? Params & { [Key in Name]: string }
+	: Segment extends `[${infer Name}]`
+		? Params & { [Key in Name]: string }
+		: Params;
+
+/**
+ * Resolves the params for a route annotation: the parsed params for a literal
+ * route path, or a loose record when no route (or a non-literal string) is
+ * given.
+ */
+export type RouteParamsOf<Route extends string | undefined> = string extends Route
+	? Record<string, string>
+	: Route extends string
+		? ParseRouteParams<Route>
+		: Record<string, string>;
+
+/**
+ * Validates an inferred params object against a route's params shape:
+ * resolves to the params type when its keys are exactly the route's keys, and
+ * `never` when keys are missing or extra — so wrong keys error at the call
+ * site (excess property checks are skipped for deferred conditional rest
+ * tuples, but assignability to `never` can't be).
+ */
+export type ExactRouteParams<Params, Shape> = Params extends Shape
+	? [Exclude<keyof Params, keyof Shape>] extends [never]
+		? Params
+		: never
+	: never;
+
+/**
+ * The arguments for building a route path: nothing for static routes, or the
+ * route's params object for dynamic routes.
+ */
+export type RouteArgs<Route extends string> = string extends Route
+	? [params?: Record<string, string>]
+	: keyof ParseRouteParams<Route> extends never
+		? []
+		: [params: ParseRouteParams<Route>];
+
+/**
+ * RouteArgs for an optional route annotation, defaulting to a single optional
+ * loose params object.
+ */
+export type RouteArgsOf<Route extends string | undefined> = Route extends string
+	? RouteArgs<Route>
+	: [params?: Record<string, string>];

package/src/types/Route.ts

@@ -1,11 +1,30 @@
+import type PageEndPoint from "./PageEndPoint";
+import type PageServerEndPoint from "./PageServerEndPoint";
+import type ServerEndPoint from "./ServerEndPoint";
+import type ServerHook from "./ServerHook";
 import { type RouteType } from "./RouteType";
 
+/**
+ * Any endpoint shape that can be stored inline on a Route.
+ */
+export type InlineEndPoint = PageServerEndPoint | ServerEndPoint | ServerHook | PageEndPoint;
+
 /**
  * A route that is added to the Site.
  */
 export default interface Route {
 	path: string;
-	file: string;
+	/**
+	 * The file for this route, relative to the site root. Omitted for inline
+	 * endpoints (see `endPoint`).
+	 */
+	file?: string;
+	/**
+	 * For inline routes (defined in code rather than by file), the endpoint
+	 * object itself. The shape depends on the route type
+	 * (`PageServerEndPoint`, `ServerEndPoint`, `ServerHook`, etc.).
+	 */
+	endPoint?: InlineEndPoint;
 	type: RouteType;
 	subFolder?: string;
 }

package/src/types/RouteHandler.ts

@@ -1,4 +1,5 @@
 import type RouteLayoutHandler from "./RouteLayoutHandler";
+import type ServerHook from "./ServerHook";
 
 /**
  * A handler for a route in the Router.
@@ -12,5 +13,11 @@ export default interface RouteHandler {
 	loaded?: boolean;
 	layouts?: RouteLayoutHandler[];
 	serverEndPoint?: () => Promise<any>;
-	serverHook?: () => Promise<any>;
+	serverHooks?: (() => Promise<any>)[];
+
+	// The endpoint module and the resolved server hooks are cached on the
+	// handler after first use, so warm requests don't pay for the loaders
+	modulePromise?: Promise<any>;
+	resolvedModule?: any;
+	resolvedHooks?: Promise<ServerHook[]>;
 }

package/src/types/ServerEndPoint.test-d.ts

@@ -0,0 +1,77 @@
+import ok from "../response/ok";
+import type { ParamsOf, SchemaBody, SchemaQuery } from "./ServerEndPoint";
+import type ServerEndPoint from "./ServerEndPoint";
+import type { StandardSchemaV1 } from "./StandardSchema";
+
+type Equals<A, B> =
+	(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Expect<T extends true> = T;
+
+// A mock schema library's schema, with input and output types
+declare const postSchema: StandardSchemaV1<{ title: string }, { title: string; upper: string }>;
+declare const querySchema: StandardSchemaV1<{ page: string }, { page: number }>;
+declare const paramsSchema: StandardSchemaV1<{ id: string }, { id: number }>;
+
+const schemas: { post: typeof postSchema } = { post: postSchema };
+
+// An endpoint declaring a schema for its post handler. The `.upper` access
+// below compiles only when json() is typed from the schema's output
+const endpoint: ServerEndPoint<"/api/posts", typeof schemas> = {
+	schema: schemas,
+	post: async ({ json }) => ok({ echoed: (await json()).upper }),
+};
+
+// json() returns the schema's output type
+type PostEvent = Parameters<NonNullable<typeof endpoint.post>>[0];
+export type R01 = Expect<
+	Equals<Awaited<ReturnType<PostEvent["json"]>>, { title: string; upper: string }>
+>;
+
+// The schema's input type is available via InferInput
+export type R02 = Expect<Equals<StandardSchemaV1.InferInput<typeof postSchema>, { title: string }>>;
+
+// Client callers made with makeApi accept the schema's output as their body
+type PostEndPoint = ServerEndPoint<"/api/posts", typeof schemas>;
+export type R03 = Expect<
+	Equals<Parameters<Api<PostEndPoint>["post"]>[0], { title: string; upper: string } | undefined>
+>;
+type Api<E extends object> = import("../nav/api").ApiMethods<E>;
+
+// The type helpers behind the handler signatures
+export type R04 = Expect<
+	Equals<SchemaBody<typeof schemas, "post">, { title: string; upper: string }>
+>;
+export type R05 = Expect<
+	Equals<SchemaQuery<typeof schemas, "get">, Record<string, string | string[]>>
+>;
+
+// A get handler's schema types the query string instead of the body
+const getEndpoint: ServerEndPoint<"/api/posts", { get: typeof querySchema }> = {
+	schema: { get: querySchema },
+	get: async ({ query }) => ok({ page: (await query()).page }),
+};
+type GetEvent = Parameters<NonNullable<typeof getEndpoint.get>>[0];
+export type R06 = Expect<Equals<Awaited<ReturnType<GetEvent["query"]>>, { page: number }>>;
+export type R07 = Expect<Equals<Awaited<ReturnType<GetEvent["json"]>>, unknown>>;
+
+// A params schema types (and coerces) the event's params
+const paramsEndpoint: ServerEndPoint<"/api/posts/[id]", { params: typeof paramsSchema }> = {
+	schema: { params: paramsSchema },
+	get: async ({ params }) => ok({ id: params.id }),
+};
+type ParamsEvent = Parameters<NonNullable<typeof paramsEndpoint.get>>[0];
+export type R08 = Expect<Equals<ParamsEvent["params"], { id: number }>>;
+
+// Endpoints without schemas keep the loose types
+const plainEndpoint: ServerEndPoint<"/api/posts"> = {
+	post: async ({ json }) => ok({ v: await json() }),
+};
+type PlainEvent = Parameters<NonNullable<typeof plainEndpoint.post>>[0];
+export type R09 = Expect<Equals<Awaited<ReturnType<PlainEvent["json"]>>, unknown>>;
+
+// The params of a route without a params schema are string record of the
+// route's dynamic segments
+export type R10 = Expect<
+	Equals<ParamsOf<ServerEndPointSchemas, "/api/posts/[id]">, { id: string }>
+>;
+type ServerEndPointSchemas = import("./ServerEndPoint").ServerEndPointSchemas;

package/src/types/ServerEndPoint.ts

@@ -1,37 +1,169 @@
+import type { RouteParamsOf } from "./ParseRouteParams";
+import type { FormDataRecord, QueryRecord } from "./ServerLoadEvent";
+import type { StandardSchemaV1 } from "./StandardSchema";
 import type ServerRequest from "./ServerRequest";
 
 /**
- * For +server.
+ * Optional standard schemas for +server endpoints, keyed by handler name.
+ * Any schema implementing the Standard Schema interface (zod, valibot,
+ * arktype, etc) can be used.
+ *
+ * - `get`/`head` schemas validate the URL's query string, surfaced through
+ *   `event.query()`
+ * - `post`/`patch`/`put`/`del`/`options` schemas validate the JSON request
+ *   body, surfaced through `event.json()`
+ * - a `params` schema validates (and generally coerces) the route params,
+ *   surfaced through `event.params`
+ *
+ * When a request body or query string fails validation, the handler is not
+ * called and a 422 response with the schema's issues is returned. When route
+ * params fail validation, a 404 response is returned, since the URL can't
+ * refer to an existing resource.
  */
-type ServerEndPoint = { [key: string]: ServerRequest } & {
+export type ServerEndPointSchemas = {
+	params?: StandardSchemaV1;
+	get?: StandardSchemaV1;
+	post?: StandardSchemaV1;
+	patch?: StandardSchemaV1;
+	put?: StandardSchemaV1;
+	del?: StandardSchemaV1;
+	options?: StandardSchemaV1;
+	head?: StandardSchemaV1;
+};
+
+/**
+ * The json body type for a handler, inferred from its schema. Falls back to
+ * `unknown` for handlers without a declared schema.
+ */
+export type SchemaBody<Schemas extends ServerEndPointSchemas, Method extends string> = [
+	Method,
+] extends [keyof Schemas & string]
+	? Schemas[Method] extends StandardSchemaV1
+		? StandardSchemaV1.InferOutput<Schemas[Method]>
+		: unknown
+	: unknown;
+
+/**
+ * The query type for a handler, inferred from its schema. Falls back to a
+ * loose record for handlers without a declared schema.
+ */
+export type SchemaQuery<Schemas extends ServerEndPointSchemas, Method extends string> = [
+	Method,
+] extends [keyof Schemas & string]
+	? Schemas[Method] extends StandardSchemaV1
+		? StandardSchemaV1.InferOutput<Schemas[Method]>
+		: QueryRecord
+	: QueryRecord;
+
+/**
+ * The route params type for an endpoint, inferred from its `params` schema.
+ * Falls back to the route's string params when no schema is declared.
+ */
+export type ParamsOf<
+	Schemas extends { params?: StandardSchemaV1 },
+	Route extends string | undefined,
+> = Schemas extends { params: StandardSchemaV1 }
+	? StandardSchemaV1.InferOutput<Schemas["params"]>
+	: RouteParamsOf<Route>;
+
+/**
+ * For +server. Annotate with a route path to get typed params, e.g.
+ * `ServerEndPoint<"/api/posts/[id]">`, and with a schemas object to get
+ * typed (and validated) request bodies, query strings and params, e.g.
+ * `ServerEndPoint<"/api/posts", typeof schema>`.
+ */
+type ServerEndPoint<
+	Route extends string | undefined = undefined,
+	Schemas extends ServerEndPointSchemas = ServerEndPointSchemas,
+> = {
+	/**
+	 * Optional standard schemas for validating requests, keyed by handler
+	 * name (plus a `params` schema for the route params), e.g.
+	 *
+	 * ```ts
+	 * const schema = {
+	 *   params: z.object({ id: z.coerce.number() }),
+	 *   get: z.object({ sort: z.enum(["asc", "desc"]) }),
+	 *   post: z.object({ title: z.string() }),
+	 * };
+	 * export default {
+	 *   schema,
+	 *   get: async (event) => ok(await event.query()),
+	 *   post: async (event) => ok((await event.json()).title),
+	 * } satisfies ServerEndPoint<"/api/posts/[id]", typeof schema>;
+	 * ```
+	 */
+	schema?: Schemas | undefined;
 	/**
-	 * Performs a GET.
+	 * Performs a GET. Its schema validates the query string.
 	 */
-	get?: ServerRequest;
+	get?: ServerRequest<
+		Route,
+		unknown,
+		FormDataRecord,
+		SchemaQuery<Schemas, "get">,
+		ParamsOf<Schemas, Route>
+	>;
 	/**
-	 * Performs a POST.
+	 * Performs a POST. Its schema validates the JSON request body.
 	 */
-	post?: ServerRequest;
+	post?: ServerRequest<
+		Route,
+		SchemaBody<Schemas, "post">,
+		FormDataRecord,
+		QueryRecord,
+		ParamsOf<Schemas, Route>
+	>;
 	/**
-	 * Performs a PATCH.
+	 * Performs a PATCH. Its schema validates the JSON request body.
 	 */
-	patch?: ServerRequest;
+	patch?: ServerRequest<
+		Route,
+		SchemaBody<Schemas, "patch">,
+		FormDataRecord,
+		QueryRecord,
+		ParamsOf<Schemas, Route>
+	>;
 	/**
-	 * Performs a PUT.
+	 * Performs a PUT. Its schema validates the JSON request body.
 	 */
-	put?: ServerRequest;
+	put?: ServerRequest<
+		Route,
+		SchemaBody<Schemas, "put">,
+		FormDataRecord,
+		QueryRecord,
+		ParamsOf<Schemas, Route>
+	>;
 	/**
-	 * Performs a DELETE.
+	 * Performs a DELETE. Its schema validates the JSON request body.
 	 */
-	del?: ServerRequest;
+	del?: ServerRequest<
+		Route,
+		SchemaBody<Schemas, "del">,
+		FormDataRecord,
+		QueryRecord,
+		ParamsOf<Schemas, Route>
+	>;
 	/**
-	 * Performs an OPTIONS request.
+	 * Performs an OPTIONS request. Its schema validates the JSON request body.
 	 */
-	options?: ServerRequest;
+	options?: ServerRequest<
+		Route,
+		SchemaBody<Schemas, "options">,
+		FormDataRecord,
+		QueryRecord,
+		ParamsOf<Schemas, Route>
+	>;
 	/**
-	 * Performs a HEAD request.
+	 * Performs a HEAD request. Its schema validates the query string.
 	 */
-	head?: ServerRequest;
+	head?: ServerRequest<
+		Route,
+		unknown,
+		FormDataRecord,
+		SchemaQuery<Schemas, "head">,
+		ParamsOf<Schemas, Route>
+	>;
 };
 
 export default ServerEndPoint;

package/src/types/ServerHook.ts

@@ -3,9 +3,16 @@ import type ServerLoadEvent from "./ServerLoadEvent";
 /**
  * For _hook.server.
  */
-export default interface ServerHook {
+export default interface ServerHook<Route extends string | undefined = undefined> {
 	/**
-	 * Called on each server request.
+	 * Called before each server request is handled. Return a Response to
+	 * short-circuit the request, skipping the load, action or view rendering
+	 * (e.g. a redirect for unauthenticated users).
 	 */
-	handle?: (event: ServerLoadEvent) => Promise<void> | void;
+	enter?: (event: ServerLoadEvent<Route>) => Promise<Response | void> | Response | void;
+	/**
+	 * Called after the request has been handled, even if the handler threw
+	 * an error or the enter hook short-circuited it.
+	 */
+	exit?: (event: ServerLoadEvent<Route>) => Promise<void> | void;
 }

package/src/types/ServerLoadEvent.ts

@@ -1,15 +1,43 @@
 import CookieHelper from "../server/CookieHelper";
 import HeaderHelper from "../server/HeaderHelper";
+import type { RouteParamsOf } from "./ParseRouteParams";
 
-export default interface ServerLoadEvent {
+/**
+ * The values read from a form submission: one value per field, or an array
+ * when a field was submitted with multiple values (e.g. a multi select).
+ */
+export type FormDataRecord = Record<string, FormDataEntryValue | FormDataEntryValue[]>;
+
+/**
+ * The values read from a URL's query string: one string per param, or an
+ * array when a param was repeated.
+ */
+export type QueryRecord = Record<string, string | string[]>;
+
+/**
+ * The event passed to server functions. Annotate with a route path to get
+ * typed params, e.g. `ServerLoadEvent<"/posts/[id]">`, and with a body type
+ * to get typed request bodies in API endpoints, e.g.
+ * `ServerLoadEvent<"/api/posts", { title: string }>` — which also types the
+ * `body` param of client calls made with `makeApi`.
+ */
+export default interface ServerLoadEvent<
+	Route extends string | undefined = undefined,
+	Body = unknown,
+	FormBody = FormDataRecord,
+	QueryBody = QueryRecord,
+	Params = RouteParamsOf<Route>,
+> {
 	/**
 	 * The URL for the server function.
 	 */
 	url: URL;
 	/**
-	 * Route params from the URL and route path.
+	 * Route params from the URL and route path. When the endpoint declares a
+	 * `params` schema, the values are validated and typed by the schema's
+	 * output.
 	 */
-	params: Record<string, string>;
+	params: Params;
 	// TODO: Maybe we should find a better name for the data that is set set in
 	// pages, and just call this data?
 	/**
@@ -22,6 +50,23 @@ export default interface ServerLoadEvent {
 	 */
 	request: Request;
 	//response: ServerResponse;
+	/**
+	 * Reads the request body as JSON, typed by the event's `Body` annotation.
+	 */
+	json: () => Promise<Body>;
+	/**
+	 * Reads the request body as form data, returning a record of field values.
+	 * When the endpoint declares a schema for the form, the values are
+	 * validated and typed by the schema's output.
+	 */
+	form: () => Promise<FormBody>;
+	/**
+	 * Reads the URL's query string, returning a record of param values. When
+	 * the endpoint declares a schema for the query (get/head handlers and the
+	 * load function), the values are validated and typed by the schema's
+	 * output.
+	 */
+	query: () => Promise<QueryBody>;
 	/**
 	 * A helper for getting and setting cookie data.
 	 */

package/src/types/ServerRequest.ts

@@ -1,7 +1,15 @@
+import type { RouteParamsOf } from "./ParseRouteParams";
+import type { FormDataRecord, QueryRecord } from "./ServerLoadEvent";
 import type ServerLoadEvent from "./ServerLoadEvent";
 
-type ServerRequest = (
-	event: ServerLoadEvent,
+type ServerRequest<
+	Route extends string | undefined = undefined,
+	Body = unknown,
+	FormBody = FormDataRecord,
+	QueryBody = QueryRecord,
+	Params = RouteParamsOf<Route>,
+> = (
+	event: ServerLoadEvent<Route, Body, FormBody, QueryBody, Params>,
 ) => Response | undefined | void | Promise<Response | undefined | void>;
 
 export default ServerRequest;

package/src/types/SitePlugin.ts

@@ -0,0 +1,24 @@
+import type Site from "../site/Site";
+
+/**
+ * A Torpor site plugin. A plugin is a function that receives the Site and
+ * sets itself up on it, typically by registering routes (e.g. an OpenAPI
+ * document endpoint) or adding configuration.
+ *
+ * Plugins are added to `site.plugins` in the site config file, and are run
+ * once when the config is loaded (for dev and build), and once when the
+ * server starts up in production:
+ *
+ * ```ts
+ * import { Site } from "@torpor/build";
+ * import { openApi } from "@torpor/build/openapi";
+ *
+ * const site = new Site();
+ * site.addRouteFolder("src/routes");
+ * site.plugins = [openApi()];
+ * export default site;
+ * ```
+ */
+type SitePlugin = (site: Site) => void | Promise<void>;
+
+export default SitePlugin;