shelving 1.139.1 → 1.141.0

package/api/Endpoint.d.ts

@@ -0,0 +1,81 @@
+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 EndpointMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * 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 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: EndpointMethod, 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 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;
+    /**
+     * 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: unknown): R;
+    /**
+     * Return an `EndpointHandler` for this endpoint
+     */
+    handler(callback: EndpointCallback<P, R>): EndpointHandler<P, R>;
+}
+/** 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>): 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>): 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>): 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>): 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>): 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 +1,2 @@
-export * from "./Resource.js";
+export * from "./Endpoint.js";
+export * from "./util.js";

package/api/index.js

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

package/api/util.d.ts

@@ -0,0 +1,32 @@
+import type { Endpoint } from "./Endpoint.js";
+/**
+ * A function that handles a endpoint request, with a payload and returns a result.
+ *
+ * @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.
+ */
+export type EndpointCallback<P, R> = (payload: P, request: Request) => R | Promise<R>;
+/**
+ * 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 `OptionalHandler` in 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 handleEndpoints(request: Request, endpoints: EndpointHandlers): Promise<Response>;

package/api/util.js

@@ -0,0 +1,53 @@
+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";
+/**
+ * Handler a `Request` with the first matching `OptionalHandler` in 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 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: 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;
+        // Merge the search params and path params.
+        const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+        // Get the response by calling the callback.
+        return _getResponse(endpoint, callback, params, request);
+    }
+    throw new NotFoundError("Not found", { request, caller: handleEndpoints });
+}
+async function _getResponse(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 handler with the validated payload to get the result.
+    const unsafeResult = await callback(payload, request);
+    // 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 = getValid(unsafeResult, endpoint, ValueError, handleEndpoints);
+    // 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.141.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,28 @@
+import type { AnyCaller } from "../error/BaseError.js";
+import { RequestError } from "../error/RequestError.js";
+import { ResponseError } from "../error/ResponseError.js";
+/** A handler function takes a `Request` and returns a `Response` (possibly asynchronously). */
+export type Handler = (request: Request) => Response | Promise<Response>;
+export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
+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>;
+/**
+ * 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 `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, caller?: AnyCaller): Promise<unknown>;
+/**
+ * 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 `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, caller?: AnyCaller): Promise<unknown>;

package/util/http.js

@@ -0,0 +1,58 @@
+import { RequestError } from "../error/RequestError.js";
+import { ResponseError } from "../error/ResponseError.js";
+import { getDictionary } from "./dictionary.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 _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("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 });
+}
+/**
+ * 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 `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, caller = getRequestContent) {
+    if (message.method === "GET" || message.method === "HEAD")
+        return Promise.resolve(undefined);
+    return _getMessageContent(message, RequestError, caller);
+}
+/**
+ * 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 `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, caller = getResponseContent) {
+    return _getMessageContent(message, ResponseError, caller);
+}

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,20 @@
+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";
-/** 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.
  *
@@ -19,13 +29,14 @@ 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): TemplateValues | 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.
  */
-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 +44,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, 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)
@@ -99,18 +100,18 @@ 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);
+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/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;
     }
 }

package/api/Resource.d.ts

@@ -1,37 +0,0 @@
-import type { Validator } from "../util/validate.js";
-/**
- * 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).
- */
-export declare class Resource<P = undefined, R = void> implements Validator<R> {
-    /** Resource name.. */
-    readonly name: string;
-    /** 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);
-    /**
-     * Validate a payload for this resource.
-     *
-     * @returns The validated payload for this resource.
-     * @throws Feedback if the payload could not be validated.
-     */
-    prepare(unsafePayload: unknown): P;
-    /**
-     * Validate a result for this resource.
-     *
-     * @returns The validated result for this resource.
-     * @throws ValueError if the result could not be validated.
-     */
-    validate(unsafeResult: unknown): R;
-}
-/** Extract the payload type from a `Resource`. */
-export type PayloadType<X extends Resource> = 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;

package/api/Resource.js

@@ -1,48 +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 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).
- */
-export class Resource {
-    /** Resource name.. */
-    name;
-    /** Payload validator. */
-    payload;
-    /** Result validator. */
-    result;
-    constructor(name, payload = UNDEFINED, result = UNDEFINED) {
-        this.name = name;
-        this.payload = payload;
-        this.result = result;
-    }
-    /**
-     * Validate a payload for this resource.
-     *
-     * @returns The validated payload for this resource.
-     * @throws Feedback if the payload could not be validated.
-     */
-    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) {
-        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 thrown;
-        }
-    }
-}