shelving 1.140.0 → 1.142.0

package/api/{Resource.d.ts → Endpoint.d.ts}

@@ -1,10 +1,8 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { Path } from "../util/path.js";
 import { type Validator } from "../util/validate.js";
+import type { EndpointCallback, EndpointHandler } from "./util.js";
 /** Types for an HTTP request or response that does something. */
-export type ResourceMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-/** A function that handles a resource request, with a payload and returns a result. */
-export type ResourceCallback<P, R> = (payload: P, request: Request) => R | Promise<R>;
+export type EndpointMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -13,16 +11,16 @@ export type ResourceCallback<P, R> = (payload: P, request: Request) => R | Promi
  * @param payload A `Validator` for the payload of the resource.
  * @param result A `Validator` for the result of the resource.
  */
-export declare class Resource<P, R> implements Validator<R> {
-    /** Resource method. */
-    readonly method: ResourceMethod;
-    /** Resource path, e.g. `/patient/{id}` */
+export declare class Endpoint<P, R> implements Validator<R> {
+    /** Endpoint method. */
+    readonly method: EndpointMethod;
+    /** Endpoint path, e.g. `/patient/{id}` */
     readonly path: Path;
     /** Payload validator. */
     readonly payload: Validator<P>;
     /** Result validator. */
     readonly result: Validator<R>;
-    constructor(method: ResourceMethod, path: Path, payload: Validator<P>, result: Validator<R>);
+    constructor(method: EndpointMethod, path: Path, payload: Validator<P>, result: Validator<R>);
     /**
      * Validate a payload for this resource.
      *
@@ -34,46 +32,50 @@ export declare class Resource<P, R> implements Validator<R> {
      * Validate a result for this resource.
      *
      * @returns The validated result for this resource.
-     * @throws ValueError if the result could not be validated.
+     * @throws `Feedback` if the value is invalid. `Feedback` instances can be reported safely back to the end client so they know how to fix their request.
      */
-    validate(unsafeResult: unknown, caller?: AnyCaller): R;
+    validate(unsafeResult: unknown): R;
+    /**
+     * Return an `EndpointHandler` for this endpoint
+     */
+    handler(callback: EndpointCallback<P, R>): EndpointHandler<P, R>;
 }
-/** Extract the payload type from a `Resource`. */
-export type PayloadType<X extends Resource<unknown, unknown>> = X extends Resource<infer Y, unknown> ? Y : never;
-/** Extract the result type from a `Resource`. */
-export type ResourceType<X extends Resource<unknown, unknown>> = X extends Resource<unknown, infer Y> ? Y : never;
+/** Extract the payload type from a `Endpoint`. */
+export type PayloadType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<infer Y, unknown> ? Y : never;
+/** Extract the result type from a `Endpoint`. */
+export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<unknown, infer Y> ? Y : never;
 /**
  * Represent a GET request to a specified path, with validated payload and return types.
  * "The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should not contain a request content."
  */
-export declare function GET<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Resource<P, R>;
-export declare function GET<P>(path: Path, payload: Validator<P>): Resource<P, undefined>;
-export declare function GET<R>(path: Path, payload: undefined, result: Validator<R>): Resource<undefined, R>;
+export declare function GET<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function GET<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function GET<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a POST request to a specified path, with validated payload and return types.
  * "The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
  */
-export declare function POST<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Resource<P, R>;
-export declare function POST<P>(path: Path, payload: Validator<P>): Resource<P, undefined>;
-export declare function POST<R>(path: Path, payload: undefined, result: Validator<R>): Resource<undefined, R>;
+export declare function POST<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function POST<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function POST<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a PUT request to a specified path, with validated payload and return types.
  * "The PUT method replaces all current representations of the target resource with the request content."
  */
-export declare function PUT<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Resource<P, R>;
-export declare function PUT<P>(path: Path, payload: Validator<P>): Resource<P, undefined>;
-export declare function PUT<R>(path: Path, payload: undefined, result: Validator<R>): Resource<undefined, R>;
+export declare function PUT<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function PUT<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function PUT<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a PATCH request to a specified path, with validated payload and return types.
  * "The PATCH method applies partial modifications to a resource."
  */
-export declare function PATCH<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Resource<P, R>;
-export declare function PATCH<P>(path: Path, payload: Validator<P>): Resource<P, undefined>;
-export declare function PATCH<R>(path: Path, payload: undefined, result: Validator<R>): Resource<undefined, R>;
+export declare function PATCH<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function PATCH<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function PATCH<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
 /**
  * Represent a DELETE request to a specified path, with validated payload and return types.
  * "The DELETE method deletes the specified resource."
  */
-export declare function DELETE<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Resource<P, R>;
-export declare function DELETE<P>(path: Path, payload: Validator<P>): Resource<P, undefined>;
-export declare function DELETE<R>(path: Path, payload: undefined, result: Validator<R>): Resource<undefined, R>;
+export declare function DELETE<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
+export declare function DELETE<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
+export declare function DELETE<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;

package/api/Endpoint.js

@@ -0,0 +1,64 @@
+import { UNDEFINED } from "../util/validate.js";
+/**
+ * An abstract API resource definition, used to specify types for e.g. serverless functions.
+ *
+ * @param method The method of the resource, e.g. `GET`
+ * @param path The path of the resource optionally including `{placeholder}` values, e.g. `/patient/{id}`
+ * @param payload A `Validator` for the payload of the resource.
+ * @param result A `Validator` for the result of the resource.
+ */
+export class Endpoint {
+    /** Endpoint method. */
+    method;
+    /** Endpoint path, e.g. `/patient/{id}` */
+    path;
+    /** Payload validator. */
+    payload;
+    /** Result validator. */
+    result;
+    constructor(method, path, payload, result) {
+        this.method = method;
+        this.path = path;
+        this.payload = payload;
+        this.result = result;
+    }
+    /**
+     * Validate a payload for this resource.
+     *
+     * @returns The validated payload for this resource.
+     * @throws `Feedback` if the payload is invalid. `Feedback` instances can be reported safely back to the end client so they know how to fix their request.
+     */
+    prepare(unsafePayload) {
+        return this.payload.validate(unsafePayload);
+    }
+    /**
+     * Validate a result for this resource.
+     *
+     * @returns The validated result for this resource.
+     * @throws `Feedback` if the value is invalid. `Feedback` instances can be reported safely back to the end client so they know how to fix their request.
+     */
+    validate(unsafeResult) {
+        return this.result.validate(unsafeResult);
+    }
+    /**
+     * Return an `EndpointHandler` for this endpoint
+     */
+    handler(callback) {
+        return { endpoint: this, callback };
+    }
+}
+export function GET(path, payload, result) {
+    return new Endpoint("GET", path, payload || UNDEFINED, result || UNDEFINED);
+}
+export function POST(path, payload, result) {
+    return new Endpoint("POST", path, payload || UNDEFINED, result || UNDEFINED);
+}
+export function PUT(path, payload, result) {
+    return new Endpoint("PUT", path, payload || UNDEFINED, result || UNDEFINED);
+}
+export function PATCH(path, payload, result) {
+    return new Endpoint("PATCH", path, payload || UNDEFINED, result || UNDEFINED);
+}
+export function DELETE(path, payload, result) {
+    return new Endpoint("DELETE", path, payload || UNDEFINED, result || UNDEFINED);
+}

package/api/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./Resource.js";
+export * from "./Endpoint.js";
 export * from "./util.js";

package/api/index.js

@@ -1,2 +1,2 @@
-export * from "./Resource.js";
+export * from "./Endpoint.js";
 export * from "./util.js";

package/api/util.d.ts

@@ -1,33 +1,40 @@
-import { type OptionalHandler } from "../util/http.js";
-import type { Resource, ResourceCallback } from "./Resource.js";
+import type { Endpoint } from "./Endpoint.js";
 /**
- * Create a handler that matches an HTTP `Request` against a `Resource`, and returns a `Response` (possibly async) if the request matches, or `undefined` otherwise.
+ * A function that handles a endpoint request, with a payload and returns a result.
  *
- * @param resource A `Resource` instance that defines the method, path, and allowed types for the request.
+ * @param payload The payload of the request is the result of merging the `{placeholder}` path parameters and `?a=123` query parameters from the URL, with the body of the request.
+ * - Payload is validated by the payload validator for the `Endpoint`.
+ * - If the body of the `Request` is a data object (i.e. a plain object), then body data is merged with the path and query parameters to form a single flat object.
+ * - If payload is _not_ a data object (i.e. it's another JSON type like `string` or `number`) then the payload include the path and query parameters, and a key called `content` that contains the body of the request.
  *
- * @param callback A callback function that will be called with the validated payload and should return the correct response type for the resource.
- * > @param payload is the parse body content of the request.
- * > - If the body is parsed as a `Data` object, also adds in path `{placeholders}` and `?query=` parameters in the URL.
+ * @param request The raw `Request` object in case it needs any additional processing.
  *
- * @returns An `OptionalHandler` that might handle a given `Request` if it matches the resource's method and path.
- * > @returns `undefined` if the request does not match the resource's method or path.
- * > @returns `Response` (possibly async) if the callback returns a valid response.
- * > @throws `RequestError` if the request matches but the payload from the request is invalid (this is an end user error in the request that needs to be reported back).
- * > @throws `ValueError` if the request matches but the value returned by the callback is invalid (this is more likely internal developer error that is reporting something wrong in the callback implementation).
+ * @returns The correct `Result` type for the `Endpoint`, or a raw `Response` object if you wish to return a custom response.
  */
-export declare function createResourceHandler<P, R>(resource: Resource<P, R>, callback: ResourceCallback<P, R>): OptionalHandler;
+export type EndpointCallback<P, R> = (payload: P, request: Request) => R | Response | Promise<R | Response>;
 /**
- * Handle a `Request` to a `Resource` using a `ResourceCallback` that implements the logic for the resource.
+ * Object combining an abstract `Endpoint` and an `EndpointCallback` implementation.
+ */
+export interface EndpointHandler<P, R> {
+    readonly endpoint: Endpoint<P, R>;
+    readonly callback: EndpointCallback<P, R>;
+}
+/**
+ * Any handler (purposefully as wide as possible for use with `extends X` or `is X` statements).
+ */
+export type AnyEndpointHandler = EndpointHandler<any, any>;
+/**
+ * List of `EndpointHandler` objects objects that can handle requests to an `Endpoint`.
+ */
+export type EndpointHandlers = ReadonlyArray<AnyEndpointHandler>;
+/**
+ * Handler a `Request` with the first matching `EndpointHandlers`.
  *
- * @param request The `Request` to handle, which may have a method and URL that match the resource's method and path.
- * @param resource A `Resource` instance that defines the method, path, and allowed types for the request.
- * @param callback A callback function that will be called with the validated payload and should return the correct response type for the resource.
- * > @param payload is the parse body content of the request.
- * > - If the body is parsed as a `Data` object, also adds in path `{placeholders}` and `?query=` parameters in the URL.
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
+ * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * -
  *
- * @returns `undefined` if the request does not match the resource's method or path.
- * @returns `Response` (possibly async) if the callback returns a valid response.
- * @throws `Feedback` if the payload the client user provided is invalid. `Feedback` instances can be reported safely back to the end client so they know how to fix their request.
- * @throws `ValueError` if the request matches but the value returned by the callback is invalid (this is an internal error that is reporting something wrong in the callback implementation).
+ * @returns The resulting `Response` from the first handler that matches the `Request`.
+ * @throws `NotFoundError` if no handler matches the `Request`.
  */
-export declare function handleResourceRequest<P, R>(request: Request, resource: Resource<P, R>, callback: ResourceCallback<P, R>): Response | Promise<Response> | undefined;
+export declare function handleEndpoints(request: Request, endpoints: EndpointHandlers): Promise<Response>;

package/api/util.js

@@ -1,65 +1,61 @@
-import { RequestError } from "../error/RequestError.js";
-import { getRequestData } from "../util/http.js";
+import { NotFoundError, RequestError } from "../error/RequestError.js";
+import { ValueError } from "../error/ValueError.js";
+import { isData } from "../util/data.js";
+import { getDictionary } from "../util/dictionary.js";
+import { getRequestContent } from "../util/http.js";
 import { matchTemplate } from "../util/template.js";
 import { getURL } from "../util/url.js";
+import { getValid } from "../util/validate.js";
 /**
- * Create a handler that matches an HTTP `Request` against a `Resource`, and returns a `Response` (possibly async) if the request matches, or `undefined` otherwise.
+ * Handler a `Request` with the first matching `EndpointHandlers`.
  *
- * @param resource A `Resource` instance that defines the method, path, and allowed types for the request.
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
+ * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * -
  *
- * @param callback A callback function that will be called with the validated payload and should return the correct response type for the resource.
- * > @param payload is the parse body content of the request.
- * > - If the body is parsed as a `Data` object, also adds in path `{placeholders}` and `?query=` parameters in the URL.
- *
- * @returns An `OptionalHandler` that might handle a given `Request` if it matches the resource's method and path.
- * > @returns `undefined` if the request does not match the resource's method or path.
- * > @returns `Response` (possibly async) if the callback returns a valid response.
- * > @throws `RequestError` if the request matches but the payload from the request is invalid (this is an end user error in the request that needs to be reported back).
- * > @throws `ValueError` if the request matches but the value returned by the callback is invalid (this is more likely internal developer error that is reporting something wrong in the callback implementation).
- */
-export function createResourceHandler(resource, callback) {
-    return request => handleResourceRequest(request, resource, callback);
-}
-/**
- * Handle a `Request` to a `Resource` using a `ResourceCallback` that implements the logic for the resource.
- *
- * @param request The `Request` to handle, which may have a method and URL that match the resource's method and path.
- * @param resource A `Resource` instance that defines the method, path, and allowed types for the request.
- * @param callback A callback function that will be called with the validated payload and should return the correct response type for the resource.
- * > @param payload is the parse body content of the request.
- * > - If the body is parsed as a `Data` object, also adds in path `{placeholders}` and `?query=` parameters in the URL.
- *
- * @returns `undefined` if the request does not match the resource's method or path.
- * @returns `Response` (possibly async) if the callback returns a valid response.
- * @throws `Feedback` if the payload the client user provided is invalid. `Feedback` instances can be reported safely back to the end client so they know how to fix their request.
- * @throws `ValueError` if the request matches but the value returned by the callback is invalid (this is an internal error that is reporting something wrong in the callback implementation).
+ * @returns The resulting `Response` from the first handler that matches the `Request`.
+ * @throws `NotFoundError` if no handler matches the `Request`.
  */
-export function handleResourceRequest(request, resource, callback) {
-    // Ensure the request method e.g. `GET`, does not match the resource method e.g. `POST`
-    if (request.method !== resource.method)
-        return undefined;
+export function handleEndpoints(request, endpoints) {
     // Parse the URL of the request.
     const url = getURL(request.url);
     if (!url)
-        throw new RequestError("Invalid request URL", { received: request.url, caller: handleResourceRequest });
-    // Ensure the request URL e.g. `/user/123` matches the resource path e.g. `/user/{id}`
-    // Any `{placeholders}` in the resource path are matched against the request URL to extract parameters.
-    const params = matchTemplate(url.pathname, resource.path);
-    if (!params)
-        return undefined;
-    // Extract a data object from the request body and validate it against the resource's payload type.
-    const data = getRequestData(request);
-    const payload = resource.prepare({ ...params, ...data });
-    // Return the `Response` that results from calling the callback with the `Request` and the matching params.
-    return _getHandlerResponse(resource, callback, payload, request);
+        throw new RequestError("Invalid request URL", { received: request.url, caller: handleEndpoints });
+    const { pathname, searchParams } = url;
+    // Iterate over the handlers and return the first one that matches the request.
+    for (const { endpoint, callback } of endpoints) {
+        // Ensure the request method e.g. `GET`, does not match the endpoint method e.g. `POST`
+        if (request.method !== endpoint.method)
+            continue;
+        // Ensure the request URL e.g. `/user/123` matches the endpoint path e.g. `/user/{id}`
+        // Any `{placeholders}` in the endpoint path are matched against the request URL to extract parameters.
+        const pathParams = matchTemplate(endpoint.path, pathname, handleEndpoints);
+        if (!pathParams)
+            continue;
+        // Make a simple dictionary object from the `{placeholder}` path params and the `?a=123` query params from the URL.
+        const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+        // Get the response by calling the callback.
+        return getEndpointResponse(endpoint, callback, params, request);
+    }
+    // No handler matched the request.
+    throw new NotFoundError("Not found", { request, caller: handleEndpoints });
 }
-/** Internal async function that calls `callback()` asyncronously and validates the result. */
-async function _getHandlerResponse(resource, callback, payload, request) {
-    // Call the handler with the validated payload to get the result.
-    const unsafeResult = await callback(payload, request);
-    // Validate the result against the resource's result type.
+async function getEndpointResponse(endpoint, callback, params, request) {
+    // Extract a data object from the request body and validate it against the endpoint's payload type.
+    const content = await getRequestContent(request, handleEndpoints);
+    // If content is undefined, it means the request has no body, so params are the only payload.
+    // If the content is a data object merge if with the params.
+    // If the content is not a data object (e.g. string, number, array), set a single `content` property and merge it with the params.
+    const unsafePayload = content === undefined ? params : isData(content) ? { ...content, ...params } : { content, ...params };
+    const payload = endpoint.prepare(unsafePayload);
+    // Call the callback with the validated payload to get the result.
+    const returned = await callback(payload, request);
+    // If the callback returned a `Response`, return it directly.
+    if (returned instanceof Response)
+        return returned;
+    // Otherwise validate the result against the endpoint's result type.
     // Throw a `ValueError` if the result is not valid, which indicates an internal error in the callback implementation.
-    const result = resource.validate(unsafeResult, _getHandlerResponse);
+    const result = getValid(returned, endpoint, ValueError, handleEndpoints);
     // Return a new `Response` with a 200 status and the validated result data.
     return Response.json(result);
 }

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.140.0",
+	"version": "1.142.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/util/http.d.ts

@@ -1,89 +1,28 @@
 import type { AnyCaller } from "../error/BaseError.js";
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
-import type { ImmutableArray } from "./array.js";
-import { type Data } from "./data.js";
-import type { Optional } from "./optional.js";
 /** A handler function takes a `Request` and returns a `Response` (possibly asynchronously). */
-export type Handler = (request: Request) => Response | Promise<Response>;
-/** An optional handler function _may_ match a `Request` and return a `Response`, or may return `undefined` if it doesn't match. */
-export type OptionalHandler = (request: Request) => Optional<Response | Promise<Response>>;
-/** A list of `OptionalHandler` functions that may match a `Request` */
-export type Handlers = ImmutableArray<OptionalHandler>;
+export type RequestHandler = (request: Request) => Response | Promise<Response>;
 export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
-export declare function _getMessageData(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<Data | undefined>;
-export declare function _requireMessageData(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<Data>;
+export declare function _getMessageFormData(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
 export declare function _getMessageContent(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
 /**
- * Parse the content of an HTTP `Request` based as JSON, or throw `RequestError` if the content could not be getd.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export declare function getRequestJSON(message: Request): Promise<unknown>;
-/**
- * Parse the content of an HTTP `Response` based as JSON, or throw `ResponseError` if the content could not be getd.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export declare function getResponseJSON(message: Response): Promise<unknown>;
-/**
- * Require the content of an HTTP `Request` as a data object in JSON format, or throw `RequestError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export declare function getRequestData(message: Request): Promise<Data | undefined>;
-/**
- * Require the content of an HTTP `Response` as a data object in JSON format, or throw `ResponseError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export declare function getResponseData(message: Response): Promise<Data | undefined>;
-/**
- * Require the content of an HTTP `Request` as a data object in JSON format, or throw `RequestError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws RequestError if the content is not `application/json` with valid JSON that parses as a Data object.
- */
-export declare function requireRequestData(message: Request): Promise<Data>;
-/**
- * Require the content of an HTTP `Response` as a data object in JSON format, or throw `ResponseError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws ResponseError if the content is not `application/json` with valid JSON that parses as a Data object.
- */
-export declare function requireResponseData(message: Response): Promise<Data>;
-/**
- * Get the content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
+ * Get the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
  * @returns string If content type is `text/plain` (including empty string if it's empty).
- * @returns unknown If content type is `application/JSON` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
-export declare function getRequestContent(message: Request): Promise<unknown>;
+export declare function getRequestContent(message: Request, caller?: AnyCaller): Promise<unknown>;
 /**
- * Get the content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
+ * Get the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
  * @returns string If content type is `text/plain` (including empty string if it's empty).
- * @returns unknown If content type is `application/JSON` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  *
  * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
  */
-export declare function getResponseContent(message: Response): Promise<unknown>;
-/**
- * Match a `Request` against a `Handlers` array.
- *
- * @returns The resulting `Response` from the first handler that matches the `Request`.
- * @throws `NotFoundError` if no handler matches the `Request`.
- */
-export declare function handleRequest(request: Request, handlers: ImmutableArray<OptionalHandler>): Response | Promise<Response>;
+export declare function getResponseContent(message: Response, caller?: AnyCaller): Promise<unknown>;

package/util/http.js

@@ -1,6 +1,6 @@
-import { NotFoundError, RequestError } from "../error/RequestError.js";
+import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
-import { isData } from "./data.js";
+import { getDictionary } from "./dictionary.js";
 export async function _getMessageJSON(message, MessageError, caller) {
     const trimmed = (await message.text()).trim();
     if (!trimmed.length)
@@ -12,119 +12,47 @@ export async function _getMessageJSON(message, MessageError, caller) {
         throw new MessageError("Body must be valid JSON", { received: trimmed, caller });
     }
 }
-export async function _getMessageData(message, MessageError, caller) {
-    const data = await _getMessageJSON(message, MessageError, caller);
-    if (isData(data) || data === undefined)
-        return data;
-    throw new MessageError("Body must be data object or undefined", { received: data, caller });
-}
-export async function _requireMessageData(message, MessageError, caller) {
-    const data = await _getMessageJSON(message, MessageError, caller);
-    if (isData(data))
-        return data;
-    throw new MessageError("Body must be data object", { received: data, caller });
+export async function _getMessageFormData(message, MessageError, caller) {
+    try {
+        return getDictionary(await message.formData());
+    }
+    catch {
+        throw new MessageError("Body must be valid valid form multipart data", { caller });
+    }
 }
 export function _getMessageContent(message, MessageError, caller) {
     const type = message.headers.get("Content-Type");
-    if (type?.startsWith("application/json"))
-        return _getMessageJSON(message, MessageError, caller);
     if (type?.startsWith("text/plain"))
         return message.text();
+    if (type?.startsWith("application/json"))
+        return _getMessageJSON(message, MessageError, caller);
+    if (type?.startsWith("multipart/form-data"))
+        return _getMessageFormData(message, MessageError, caller);
     throw new MessageError("Unexpected content type", { received: type, caller });
 }
 /**
- * Parse the content of an HTTP `Request` based as JSON, or throw `RequestError` if the content could not be getd.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export function getRequestJSON(message) {
-    return _getMessageJSON(message, RequestError, getRequestJSON);
-}
-/**
- * Parse the content of an HTTP `Response` based as JSON, or throw `ResponseError` if the content could not be getd.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export function getResponseJSON(message) {
-    return _getMessageJSON(message, ResponseError, getResponseJSON);
-}
-/**
- * Require the content of an HTTP `Request` as a data object in JSON format, or throw `RequestError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export function getRequestData(message) {
-    return _getMessageData(message, RequestError, getRequestData);
-}
-/**
- * Require the content of an HTTP `Response` as a data object in JSON format, or throw `ResponseError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
- */
-export function getResponseData(message) {
-    return _getMessageData(message, ResponseError, getResponseData);
-}
-/**
- * Require the content of an HTTP `Request` as a data object in JSON format, or throw `RequestError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws RequestError if the content is not `application/json` with valid JSON that parses as a Data object.
- */
-export function requireRequestData(message) {
-    return _requireMessageData(message, RequestError, requireRequestData);
-}
-/**
- * Require the content of an HTTP `Response` as a data object in JSON format, or throw `ResponseError` if the content cannot not be parsed or is not a data object in JSON format.
- *
- * @returns string (if the content type is `text/plain`)
- * @returns Data If the content can be parsed as a JSON object, or `undefined` if the content was empty.
- * @throws ResponseError if the content is not `application/json` with valid JSON that parses as a Data object.
- */
-export function requireResponseData(message) {
-    return _requireMessageData(message, ResponseError, requireResponseData);
-}
-/**
- * Get the content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
+ * Get the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
  * @returns string If content type is `text/plain` (including empty string if it's empty).
- * @returns unknown If content type is `application/JSON` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
-export function getRequestContent(message) {
-    return _getMessageContent(message, RequestError, getRequestContent);
+export function getRequestContent(message, caller = getRequestContent) {
+    if (message.method === "GET" || message.method === "HEAD")
+        return Promise.resolve(undefined);
+    return _getMessageContent(message, RequestError, caller);
 }
 /**
- * Get the content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
+ * Get the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
  * @returns string If content type is `text/plain` (including empty string if it's empty).
- * @returns unknown If content type is `application/JSON` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
+ * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  *
  * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
  */
-export function getResponseContent(message) {
-    return _getMessageContent(message, ResponseError, getResponseContent);
-}
-/**
- * Match a `Request` against a `Handlers` array.
- *
- * @returns The resulting `Response` from the first handler that matches the `Request`.
- * @throws `NotFoundError` if no handler matches the `Request`.
- */
-export function handleRequest(request, handlers) {
-    for (const handler of handlers) {
-        const response = handler(request);
-        if (response)
-            return response;
-    }
-    throw new NotFoundError("Not found", { request, caller: handleRequest });
+export function getResponseContent(message, caller = getResponseContent) {
+    return _getMessageContent(message, ResponseError, caller);
 }

package/util/template.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
 import { type ImmutableDictionary } from "./dictionary.js";
 import type { NotString } from "./string.js";
@@ -28,9 +29,10 @@ export declare function getPlaceholders(template: string): readonly string[];
  * @param templates Either a single template string, or an iterator that returns multiple template template strings.
  * - Template strings can include placeholders (e.g. `:name-${country}/{city}`).
  * @param target The string containing values, e.g. `Dave-UK/Manchester`
+ *
  * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.
  */
-export declare function matchTemplate(template: string, target: string): TemplateDictionary | undefined;
+export declare function matchTemplate(template: string, target: string, caller?: AnyCaller): TemplateDictionary | undefined;
 /**
  * Match multiple templates against a target string and return the first match.
  */
@@ -44,4 +46,4 @@ export declare function matchTemplates(templates: Iterable<string> & NotString,
  *
  * @throws {RequiredError} If a placeholder in the template string is not specified in values.
  */
-export declare function renderTemplate(template: string, values: TemplateValues): string;
+export declare function renderTemplate(template: string, values: TemplateValues, caller?: AnyCaller): string;

package/util/template.js

@@ -24,7 +24,7 @@ function _splitTemplate(template, caller) {
         const placeholder = matches[i];
         const post = matches[i + 1];
         if (i > 1 && !pre.length)
-            throw new ValueError("Placeholders must be separated by at least one character", { received: template, caller });
+            throw new ValueError("Template placeholders must be separated by at least one character", { received: template, caller });
         const name = placeholder === "*" ? String(asterisks++) : R_NAME.exec(placeholder)?.[0] || "";
         chunks.push({ pre, placeholder, name, post });
     }
@@ -53,11 +53,12 @@ function _getPlaceholder({ name }) {
  * @param templates Either a single template string, or an iterator that returns multiple template template strings.
  * - Template strings can include placeholders (e.g. `:name-${country}/{city}`).
  * @param target The string containing values, e.g. `Dave-UK/Manchester`
+ *
  * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.
  */
-export function matchTemplate(template, target) {
+export function matchTemplate(template, target, caller = matchTemplate) {
     // Get separators and placeholders from template.
-    const chunks = _splitTemplateCached(template, matchTemplate);
+    const chunks = _splitTemplateCached(template, caller);
     const firstChunk = chunks[0];
     // Return early if empty.
     if (!firstChunk)
@@ -101,16 +102,16 @@ export function matchTemplates(templates, target) {
  *
  * @throws {RequiredError} If a placeholder in the template string is not specified in values.
  */
-export function renderTemplate(template, values) {
-    const chunks = _splitTemplateCached(template, renderTemplate);
+export function renderTemplate(template, values, caller = renderTemplate) {
+    const chunks = _splitTemplateCached(template, caller);
     if (!chunks.length)
         return template;
     let output = template;
     for (const { name, placeholder } of chunks)
-        output = output.replace(placeholder, _replaceTemplateKey(name, values));
+        output = output.replace(placeholder, _replaceTemplateKey(name, values, caller));
     return output;
 }
-function _replaceTemplateKey(key, values) {
+function _replaceTemplateKey(key, values, caller) {
     if (typeof values === "string")
         return values;
     if (typeof values === "function")
@@ -120,5 +121,5 @@ function _replaceTemplateKey(key, values) {
         if (typeof v === "string")
             return v;
     }
-    throw new RequiredError(`Template key "${key}" must be defined`, { received: values, key, caller: renderTemplate });
+    throw new RequiredError(`Template key "${key}" must be defined`, { received: values, key, caller });
 }

package/api/Resource.js

@@ -1,67 +0,0 @@
-import { ValueError } from "../error/ValueError.js";
-import { Feedback } from "../feedback/Feedback.js";
-import { UNDEFINED } from "../util/validate.js";
-/**
- * An abstract API resource definition, used to specify types for e.g. serverless functions.
- *
- * @param method The method of the resource, e.g. `GET`
- * @param path The path of the resource optionally including `{placeholder}` values, e.g. `/patient/{id}`
- * @param payload A `Validator` for the payload of the resource.
- * @param result A `Validator` for the result of the resource.
- */
-export class Resource {
-    /** Resource method. */
-    method;
-    /** Resource path, e.g. `/patient/{id}` */
-    path;
-    /** Payload validator. */
-    payload;
-    /** Result validator. */
-    result;
-    constructor(method, path, payload, result) {
-        this.method = method;
-        this.path = path;
-        this.payload = payload;
-        this.result = result;
-    }
-    /**
-     * Validate a payload for this resource.
-     *
-     * @returns The validated payload for this resource.
-     * @throws `Feedback` if the payload is invalid. `Feedback` instances can be reported safely back to the end client so they know how to fix their request.
-     */
-    prepare(unsafePayload) {
-        return this.payload.validate(unsafePayload);
-    }
-    /**
-     * Validate a result for this resource.
-     *
-     * @returns The validated result for this resource.
-     * @throws ValueError if the result could not be validated.
-     */
-    validate(unsafeResult, caller = this.validate) {
-        try {
-            return this.result.validate(unsafeResult);
-        }
-        catch (thrown) {
-            if (thrown instanceof Feedback)
-                throw new ValueError(`Invalid result for resource "${this.path}"`, { received: unsafeResult, caller });
-            throw thrown;
-        }
-    }
-}
-export function GET(path, payload = UNDEFINED, result = UNDEFINED) {
-    return new Resource("GET", path, payload, result);
-}
-export function POST(path, payload = UNDEFINED, result = UNDEFINED) {
-    return new Resource("POST", path, payload, result);
-}
-export function PUT(path, payload = UNDEFINED, result = UNDEFINED) {
-    return new Resource("PUT", path, payload, result);
-}
-export function PATCH(path, payload = UNDEFINED, result = UNDEFINED) {
-    return new Resource("PATCH", path, payload, result);
-}
-export function DELETE(path, payload = UNDEFINED, result = UNDEFINED) {
-    return new Resource("DELETE", path, payload, result);
-}