shelving 1.139.1 → 1.140.0

package/api/Resource.d.ts

@@ -1,26 +1,33 @@
-import type { Validator } from "../util/validate.js";
+import type { AnyCaller } from "../error/BaseError.js";
+import type { Path } from "../util/path.js";
+import { type Validator } from "../util/validate.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>;
 /**
- * An abstract API resource definition, used to specify types for e.g. serverless functions..
+ * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
- * @param name The name of the resource, e.g. `getUser`.
- * @param payload The `Validator` the resource's payload must conform to (defaults to `undefined` if not specified).
- * @param returns The `Validator` the resource's returned value must conform to (defaults to `undefined` if not specified).
+ * @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 declare class Resource<P = undefined, R = void> implements Validator<R> {
-    /** Resource name.. */
-    readonly name: string;
+export declare class Resource<P, R> implements Validator<R> {
+    /** Resource method. */
+    readonly method: ResourceMethod;
+    /** Resource path, e.g. `/patient/{id}` */
+    readonly path: Path;
     /** Payload validator. */
     readonly payload: Validator<P>;
     /** Result validator. */
     readonly result: Validator<R>;
-    constructor(name: string, payload: Validator<P>, result: Validator<R>);
-    constructor(name: string, payload: Validator<P>);
-    constructor(name: string);
+    constructor(method: ResourceMethod, path: Path, payload: Validator<P>, result: Validator<R>);
     /**
      * Validate a payload for this resource.
      *
      * @returns The validated payload for this resource.
-     * @throws Feedback if the payload could not be validated.
+     * @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: unknown): P;
     /**
@@ -29,9 +36,44 @@ export declare class Resource<P = undefined, R = void> implements Validator<R> {
      * @returns The validated result for this resource.
      * @throws ValueError if the result could not be validated.
      */
-    validate(unsafeResult: unknown): R;
+    validate(unsafeResult: unknown, caller?: AnyCaller): R;
 }
 /** Extract the payload type from a `Resource`. */
-export type PayloadType<X extends Resource> = X extends Resource<infer Y, unknown> ? Y : never;
+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> = X extends Resource<unknown, infer Y> ? Y : never;
+export type ResourceType<X extends Resource<unknown, unknown>> = X extends Resource<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>;
+/**
+ * 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>;
+/**
+ * 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>;
+/**
+ * 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>;
+/**
+ * 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>;

package/api/Resource.js

@@ -2,21 +2,25 @@ 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..
+ * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
- * @param name The name of the resource, e.g. `getUser`.
- * @param payload The `Validator` the resource's payload must conform to (defaults to `undefined` if not specified).
- * @param returns The `Validator` the resource's returned value must conform to (defaults to `undefined` if not specified).
+ * @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 name.. */
-    name;
+    /** Resource method. */
+    method;
+    /** Resource path, e.g. `/patient/{id}` */
+    path;
     /** Payload validator. */
     payload;
     /** Result validator. */
     result;
-    constructor(name, payload = UNDEFINED, result = UNDEFINED) {
-        this.name = name;
+    constructor(method, path, payload, result) {
+        this.method = method;
+        this.path = path;
         this.payload = payload;
         this.result = result;
     }
@@ -24,10 +28,10 @@ export class Resource {
      * Validate a payload for this resource.
      *
      * @returns The validated payload for this resource.
-     * @throws Feedback if the payload could not be validated.
+     * @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);
+        return this.payload.validate(unsafePayload);
     }
     /**
      * Validate a result for this resource.
@@ -35,14 +39,29 @@ export class Resource {
      * @returns The validated result for this resource.
      * @throws ValueError if the result could not be validated.
      */
-    validate(unsafeResult) {
+    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.name}"`, { received: unsafeResult, caller: this.validate });
+                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);
+}

package/api/index.d.ts

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

package/api/index.js

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

package/api/util.d.ts

@@ -0,0 +1,33 @@
+import { type OptionalHandler } from "../util/http.js";
+import type { Resource, ResourceCallback } from "./Resource.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.
+ *
+ * @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 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 declare function createResourceHandler<P, R>(resource: Resource<P, R>, callback: ResourceCallback<P, R>): OptionalHandler;
+/**
+ * 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).
+ */
+export declare function handleResourceRequest<P, R>(request: Request, resource: Resource<P, R>, callback: ResourceCallback<P, R>): Response | Promise<Response> | undefined;

package/api/util.js

@@ -0,0 +1,65 @@
+import { RequestError } from "../error/RequestError.js";
+import { getRequestData } from "../util/http.js";
+import { matchTemplate } from "../util/template.js";
+import { getURL } from "../util/url.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.
+ *
+ * @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 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).
+ */
+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;
+    // 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);
+}
+/** 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.
+    // Throw a `ValueError` if the result is not valid, which indicates an internal error in the callback implementation.
+    const result = resource.validate(unsafeResult, _getHandlerResponse);
+    // Return a new `Response` with a 200 status and the validated result data.
+    return Response.json(result);
+}

package/error/ResponseError.d.ts

@@ -0,0 +1,5 @@
+import { BaseError, type BaseErrorOptions } from "./BaseError.js";
+/** Error thrown when an HTTP response isn't well-formed. */
+export declare class ResponseError extends BaseError {
+    constructor(message?: string, options?: BaseErrorOptions);
+}

package/error/ResponseError.js

@@ -0,0 +1,9 @@
+import { BaseError } from "./BaseError.js";
+/** Error thrown when an HTTP response isn't well-formed. */
+export class ResponseError extends BaseError {
+    constructor(message = ResponseError.prototype.message, options) {
+        super(message, { caller: ResponseError, ...options });
+    }
+}
+ResponseError.prototype.name = "ResponseError";
+ResponseError.prototype.message = "Invalid response";

package/error/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./BaseError.js";
 export * from "./NetworkError.js";
+export * from "./ResponseError.js";
 export * from "./RequestError.js";
 export * from "./RequiredError.js";
 export * from "./UnexpectedError.js";

package/error/index.js

@@ -1,5 +1,6 @@
 export * from "./BaseError.js";
 export * from "./NetworkError.js";
+export * from "./ResponseError.js";
 export * from "./RequestError.js";
 export * from "./RequiredError.js";
 export * from "./UnexpectedError.js";

package/package.json

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

package/util/array.js

@@ -137,7 +137,7 @@ export function getLast(items) {
     return last;
 }
 /** Get the last item from an array or iterable. */
-export function requireLast(items, caller = requireFirst) {
+export function requireLast(items, caller = requireLast) {
     const item = getLast(items);
     if (item === undefined)
         throw new RequiredError("Last item is required", { items, caller });

package/util/color.js

@@ -80,6 +80,6 @@ export function getColor(value) {
 /** Convert a possible color to a `Color` instance, or throw `RequiredError` if it can't be converted. */
 export function requireColor(value, caller = requireColor) {
     const color = getColor(value);
-    assertColor(color, requireColor);
+    assertColor(color, caller);
     return color;
 }

package/util/entity.js

@@ -13,5 +13,5 @@ export function requireEntity(entity, caller = requireEntity) {
     const bits = entity.split(":", 2);
     if (bits[0] && bits[1])
         return bits;
-    throw new RequiredError("Invalid entity", { received: entity, caller: requireEntity });
+    throw new RequiredError("Invalid entity", { received: entity, caller });
 }

package/util/http.d.ts

@@ -0,0 +1,89 @@
+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 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 _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.
+ *
+ * @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).
+ *
+ * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
+ */
+export declare function getRequestContent(message: Request): Promise<unknown>;
+/**
+ * Get the 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).
+ *
+ * @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>;

package/util/http.js

@@ -0,0 +1,130 @@
+import { NotFoundError, RequestError } from "../error/RequestError.js";
+import { ResponseError } from "../error/ResponseError.js";
+import { isData } from "./data.js";
+export async function _getMessageJSON(message, MessageError, caller) {
+    const trimmed = (await message.text()).trim();
+    if (!trimmed.length)
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        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 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();
+    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.
+ *
+ * @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).
+ *
+ * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
+ */
+export function getRequestContent(message) {
+    return _getMessageContent(message, RequestError, getRequestContent);
+}
+/**
+ * Get the 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).
+ *
+ * @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 });
+}

package/util/index.d.ts

@@ -25,6 +25,7 @@ export * from "./focus.js";
 export * from "./format.js";
 export * from "./function.js";
 export * from "./hash.js";
+export * from "./http.js";
 export * from "./hydrate.js";
 export * from "./item.js";
 export * from "./iterate.js";

package/util/index.js

@@ -25,6 +25,7 @@ export * from "./focus.js";
 export * from "./format.js";
 export * from "./function.js";
 export * from "./hash.js";
+export * from "./http.js";
 export * from "./hydrate.js";
 export * from "./item.js";
 export * from "./iterate.js";

package/util/jwt.d.ts

@@ -1,6 +1,6 @@
+import type { AnyCaller } from "../error/BaseError.js";
 import { type PossibleBytes } from "./bytes.js";
 import type { Data } from "./data.js";
-import type { AnyFunction } from "./function.js";
 /**
  * Encode a JWT and return the string token.
  * - Currently only supports HMAC SHA-512 signing.
@@ -20,14 +20,48 @@ export type TokenData = {
 /**
  * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
  */
-export declare function splitToken(token: unknown): TokenData;
-export declare function _splitToken(caller: AnyFunction, token: unknown): TokenData;
+export declare function splitToken(token: string, caller?: AnyCaller): TokenData;
 /**
  * Decode a JWT, verify it, and return the full payload data.
  * - Currently only supports HMAC SHA-512 signing.
  *
  * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
- * @throws RequestError If the token is invalid or malformed.
+ * @throws UnauthorizedError If the token is invalid or malformed.
  * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
  */
-export declare function verifyToken(token: unknown, secret: PossibleBytes): Promise<Data>;
+export declare function verifyToken(token: string, secret: PossibleBytes, caller?: AnyCaller): Promise<Data>;
+/**
+ * Set the `Authorization: Bearer {token}` on a `Request` object (by reference).
+ *
+ * @param request The `Request` object to set the token on.
+ * @returns The same `Request` object that was passed in.
+ */
+export declare function setRequestToken(request: Request, token: string): Request;
+/**
+ * Extract the `Authorization: Bearer {token}` from a `Request` object, or return `undefined` if not set.
+ *
+ * @param request The `Request` object possibly containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @returns The string token extracted from the `Authorization` header, or `undefined` if not set.
+ */
+export declare function getRequestToken(request: Request): string | undefined;
+/**
+ * Extract the `Authorization: Bearer {token}` from a `Request` object, or throw `UnauthorizedError` if not set or malformed.
+ *
+ * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @returns The string token extracted from the `Authorization` header.
+ * @throws UnauthorizedError If the `Authorization` header is not set, or the JWT it contains is not well-formed.
+ */
+export declare function requireRequestToken(request: Request, caller?: AnyCaller): string;
+/**
+ * Extract the `Authorization: Bearer {token}` from a `Request` object and verify it using a signature, or throw `UnauthorizedError` if not set, malformed, or invalid.
+ * - Same as doing `requireRequestToken(request)` and then `verifyToken(token, secret)`.
+ *
+ * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @param secret The secret key to verify the JWT signature with.
+ *
+ * @returns The decoded payload data from the JWT.
+ * @throws UnauthorizedError If the `Authorization` header is not set, the JWT it contains is not well-formed, or the JWT signature is invalid.
+ *
+ * @example `const { sub, iss, customClaim } = await verifyRequestToken(request, secret);`
+ */
+export declare function verifyRequestToken(request: Request, secret: PossibleBytes, caller?: AnyCaller): Promise<Data>;

package/util/jwt.js

@@ -1,4 +1,4 @@
-import { RequestError, UnauthorizedError } from "../error/RequestError.js";
+import { UnauthorizedError } from "../error/RequestError.js";
 import { ValueError } from "../error/ValueError.js";
 import { decodeBase64URLBytes, decodeBase64URLString, encodeBase64URL } from "./base64.js";
 import { getBytes, requireBytes } from "./bytes.js";
@@ -41,23 +41,18 @@ export async function encodeToken(claims, secret) {
 /**
  * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
  */
-export function splitToken(token) {
-    return _splitToken(splitToken, token);
-}
-export function _splitToken(caller, token) {
-    if (typeof token !== "string")
-        throw new RequestError("JWT token must be string", { received: token, caller });
+export function splitToken(token, caller = splitToken) {
     // Split token.
     const [header, payload, signature] = token.split(".");
     if (!header || !payload || !signature)
-        throw new RequestError("JWT token must have header, payload, and signature", { received: token, caller });
+        throw new UnauthorizedError("JWT token must have header, payload, and signature", { received: token, caller });
     // Decode signature.
     let signatureBytes;
     try {
         signatureBytes = decodeBase64URLBytes(signature);
     }
     catch (cause) {
-        throw new RequestError("JWT token signature must be Base64URL encoded", { received: signature, cause, caller });
+        throw new UnauthorizedError("JWT token signature must be Base64URL encoded", { received: signature, cause, caller });
     }
     // Decode header.
     let headerData;
@@ -65,7 +60,7 @@ export function _splitToken(caller, token) {
         headerData = JSON.parse(decodeBase64URLString(header));
     }
     catch (cause) {
-        throw new RequestError("JWT token header must be Base64URL encoded JSON", { received: header, cause, caller });
+        throw new UnauthorizedError("JWT token header must be Base64URL encoded JSON", { received: header, cause, caller });
     }
     // Decode payload.
     let payloadData;
@@ -73,7 +68,7 @@ export function _splitToken(caller, token) {
         payloadData = JSON.parse(decodeBase64URLString(payload));
     }
     catch (cause) {
-        throw new RequestError("JWT token payload must be Base64URL encoded JSON", { received: payload, cause, caller });
+        throw new UnauthorizedError("JWT token payload must be Base64URL encoded JSON", { received: payload, cause, caller });
     }
     return { header, payload, signature, headerData, payloadData, signatureBytes };
 }
@@ -82,29 +77,79 @@ export function _splitToken(caller, token) {
  * - Currently only supports HMAC SHA-512 signing.
  *
  * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
- * @throws RequestError If the token is invalid or malformed.
+ * @throws UnauthorizedError If the token is invalid or malformed.
  * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
  */
-export async function verifyToken(token, secret) {
-    const { header, payload, signature, headerData, payloadData } = _splitToken(verifyToken, token);
+export async function verifyToken(token, secret, caller = verifyToken) {
+    const { header, payload, signature, headerData, payloadData } = splitToken(token, caller);
     // Validate header.
     if (headerData.typ !== HEADER.typ)
-        throw new RequestError(`JWT header type must be \"${HEADER.typ}\"`, { received: headerData.typ, caller: verifyToken });
+        throw new UnauthorizedError(`JWT header type must be \"${HEADER.typ}\"`, { received: headerData.typ, caller });
     if (headerData.alg !== HEADER.alg)
-        throw new RequestError(`JWT header algorithm must be \"${HEADER.alg}\"`, { received: headerData.alg, caller: verifyToken });
+        throw new UnauthorizedError(`JWT header algorithm must be \"${HEADER.alg}\"`, { received: headerData.alg, caller });
     // Validate signature.
     const key = await _getKey(verifyToken, secret, "verify");
     const isValid = await crypto.subtle.verify("HMAC", key, decodeBase64URLBytes(signature), requireBytes(`${header}.${payload}`));
     if (!isValid)
-        throw new UnauthorizedError("JWT signature does not match", { received: token, caller: verifyToken });
+        throw new UnauthorizedError("JWT signature does not match", { received: token, caller });
     // Validate payload.
     const { nbf, iat, exp } = payloadData;
     const now = Math.floor(Date.now() / 1000);
     if (typeof nbf === "number" && nbf < now - SKEW_MS)
-        throw new UnauthorizedError("JWT cannot be used yet", { received: payloadData, expected: now, caller: verifyToken });
+        throw new UnauthorizedError("JWT cannot be used yet", { received: payloadData, expected: now, caller });
     if (typeof iat === "number" && iat > now + SKEW_MS)
-        throw new UnauthorizedError("JWT not issued yet", { received: payloadData, expected: now, caller: verifyToken });
+        throw new UnauthorizedError("JWT not issued yet", { received: payloadData, expected: now, caller });
     if (typeof exp === "number" && exp < now - SKEW_MS)
-        throw new UnauthorizedError("JWT has expired", { received: payloadData, expected: now, caller: verifyToken });
+        throw new UnauthorizedError("JWT has expired", { received: payloadData, expected: now, caller });
     return payloadData;
 }
+/**
+ * Set the `Authorization: Bearer {token}` on a `Request` object (by reference).
+ *
+ * @param request The `Request` object to set the token on.
+ * @returns The same `Request` object that was passed in.
+ */
+export function setRequestToken(request, token) {
+    request.headers.set("Authorization", `Bearer ${token}`);
+    return request;
+}
+/**
+ * Extract the `Authorization: Bearer {token}` from a `Request` object, or return `undefined` if not set.
+ *
+ * @param request The `Request` object possibly containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @returns The string token extracted from the `Authorization` header, or `undefined` if not set.
+ */
+export function getRequestToken(request) {
+    const auth = request.headers.get("Authorization");
+    if (auth?.startsWith("Bearer "))
+        return auth.substring(7).trim() || undefined;
+}
+/**
+ * Extract the `Authorization: Bearer {token}` from a `Request` object, or throw `UnauthorizedError` if not set or malformed.
+ *
+ * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @returns The string token extracted from the `Authorization` header.
+ * @throws UnauthorizedError If the `Authorization` header is not set, or the JWT it contains is not well-formed.
+ */
+export function requireRequestToken(request, caller = requireRequestToken) {
+    const token = getRequestToken(request);
+    if (!token)
+        throw new UnauthorizedError("JWT is required", { received: request.headers.get("Authorization"), caller });
+    return token;
+}
+/**
+ * Extract the `Authorization: Bearer {token}` from a `Request` object and verify it using a signature, or throw `UnauthorizedError` if not set, malformed, or invalid.
+ * - Same as doing `requireRequestToken(request)` and then `verifyToken(token, secret)`.
+ *
+ * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @param secret The secret key to verify the JWT signature with.
+ *
+ * @returns The decoded payload data from the JWT.
+ * @throws UnauthorizedError If the `Authorization` header is not set, the JWT it contains is not well-formed, or the JWT signature is invalid.
+ *
+ * @example `const { sub, iss, customClaim } = await verifyRequestToken(request, secret);`
+ */
+export function verifyRequestToken(request, secret, caller = verifyRequestToken) {
+    const token = requireRequestToken(request, caller);
+    return verifyToken(token, secret, caller);
+}

package/util/string.js

@@ -7,7 +7,7 @@ export function isString(value, min = 0, max = Number.POSITIVE_INFINITY) {
     return typeof value === "string" && value.length >= min && value.length <= max;
 }
 /** Assert that a value is a string (optionally with specified min/max length). */
-export function assertString(value, min, max, caller = requireString) {
+export function assertString(value, min, max, caller = assertString) {
     if (!isString(value, min, max))
         throw new RequiredError(`Must be string${min !== undefined || max !== undefined ? ` with ${min ?? 0} to ${max ?? "∞"} characters` : ""}`, {
             received: value,

package/util/template.d.ts

@@ -1,10 +1,19 @@
 import type { ImmutableArray } from "./array.js";
 import { type ImmutableDictionary } from "./dictionary.js";
 import type { NotString } from "./string.js";
-/** Template values in `{ placeholder: value }` format. */
-type TemplateValues = ImmutableDictionary<string>;
-/** Things that can be converted to the value for a named placeholder. */
-type PlaceholderValues = string | ((name: string) => string) | ImmutableArray<string> | TemplateValues;
+/** Dictionary of named template values in `{ myPlaceholder: "value" }` format. */
+export type TemplateDictionary = ImmutableDictionary<string>;
+/** Callback that returns the right replacement string for a given placeholder. */
+export type TemplateCallback = (placeholder: string) => string;
+/**
+ * Things that can be converted to the value for a named placeholder.
+ *
+ * `string` — Single string used for every `{placeholder}`
+ * `ImmutableArray<string>` — Array of strings (or functions that return strings) used for `*` numbered placeholders e.g. `["John"]`
+ * `TemplateValues` — Object containing named strings used for named placeholders, e.g. `{ myPlaceholder: "Ellie" }`
+ * `TemplateCallback` — Function that returns the right string for a named `{placeholder}`.v
+ */
+export type TemplateValues = string | ImmutableArray<string> | TemplateDictionary | TemplateCallback;
 /**
  * Get list of placeholders named in a template string.
  *
@@ -21,11 +30,11 @@ export declare function getPlaceholders(template: string): readonly string[];
  * @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): TemplateValues | undefined;
+export declare function matchTemplate(template: string, target: string): TemplateDictionary | undefined;
 /**
  * Match multiple templates against a target string and return the first match.
  */
-export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateValues | undefined;
+export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateDictionary | undefined;
 /**
  * Turn ":year-:month" and `{ year: "2016"... }` etc into "2016-06..." etc.
  *
@@ -33,7 +42,6 @@ export declare function matchTemplates(templates: Iterable<string> & NotString,
  * @param values An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }` (functions are called, everything else converted to string), or a function or string to use for all placeholders.
  * @return The rendered string, e.g. `Dave-UK/Manchester`
  *
- * @throws {ReferenceError} If a placeholder in the template string is not specified in values.
+ * @throws {RequiredError} If a placeholder in the template string is not specified in values.
  */
-export declare function renderTemplate(template: string, values: PlaceholderValues): string;
-export {};
+export declare function renderTemplate(template: string, values: TemplateValues): string;

package/util/template.js

@@ -99,7 +99,7 @@ export function matchTemplates(templates, target) {
  * @param values An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }` (functions are called, everything else converted to string), or a function or string to use for all placeholders.
  * @return The rendered string, e.g. `Dave-UK/Manchester`
  *
- * @throws {ReferenceError} If a placeholder in the template string is not specified in values.
+ * @throws {RequiredError} If a placeholder in the template string is not specified in values.
  */
 export function renderTemplate(template, values) {
     const chunks = _splitTemplateCached(template, renderTemplate);

package/util/validate.d.ts

@@ -1,4 +1,4 @@
-import type { BaseError, BaseErrorOptions } from "../error/BaseError.js";
+import type { AnyCaller, BaseError, BaseErrorOptions } from "../error/BaseError.js";
 import type { ImmutableArray, PossibleArray } from "./array.js";
 import type { Constructor } from "./class.js";
 import type { Data } from "./data.js";
@@ -29,7 +29,7 @@ export type ValidatorsType<T> = {
     readonly [K in keyof T]: ValidatorType<T[K]>;
 };
 /** Get value that validates against a given `Validator`, or throw `ValueError` */
-export declare function getValid<T>(value: unknown, validator: Validator<T>, ErrorConstructor?: Constructor<BaseError, [string, BaseErrorOptions]>): T;
+export declare function getValid<T>(value: unknown, validator: Validator<T>, ErrorConstructor?: Constructor<BaseError, [string, BaseErrorOptions]>, caller?: AnyCaller): T;
 /**
  * Validate an iterable set of items with a validator.
  *

package/util/validate.js

@@ -9,13 +9,13 @@ import { isIterable } from "./iterate.js";
 import { getNull } from "./null.js";
 import { getUndefined } from "./undefined.js";
 /** Get value that validates against a given `Validator`, or throw `ValueError` */
-export function getValid(value, validator, ErrorConstructor = ValueError) {
+export function getValid(value, validator, ErrorConstructor = ValueError, caller = getValid) {
     try {
         return validator.validate(value);
     }
     catch (thrown) {
         if (thrown instanceof Feedback)
-            throw new ErrorConstructor(thrown.message, { received: value, cause: thrown, caller: getValid });
+            throw new ErrorConstructor(thrown.message, { received: value, cause: thrown, caller });
         throw thrown;
     }
 }