shelving 1.173.1 → 1.174.0

package/endpoint/Endpoint.d.ts

@@ -1,9 +1,9 @@
 import { type Schema } from "../schema/Schema.js";
 import { type Data } from "../util/data.js";
-import type { AnyCaller } from "../util/function.js";
-import { type RequestMethod, type RequestOptions } from "../util/http.js";
-import type { URLString } from "../util/url.js";
-import type { EndpointCallback, EndpointHandler } from "./util.js";
+import type { AnyCaller, Arguments } from "../util/function.js";
+import { type RequestHandler, type RequestMethod, type RequestOptions } from "../util/http.js";
+import { type URLString } from "../util/url.js";
+import type { EndpointCallback } from "./util.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -23,22 +23,11 @@ export declare class Endpoint<P, R> {
     readonly result: Schema<R>;
     constructor(method: RequestMethod, url: URLString, payload: Schema<P>, result: Schema<R>);
     /**
-     * Return an `EndpointHandler` for this endpoint.
+     * Return an optional request handler for this endpoint.
      *
      * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      */
-    handler(callback: EndpointCallback<P, R>): EndpointHandler<P, R>;
-    /**
-     * Handle a request to this endpoint with a callback implementation, with a given payload and request.
-     *
-     * @param callback The endpoint callback function that implements the logic for this endpoint by receiving the payload and returning the response.
-     * @param unsafePayload The payload to pass into the callback (will be validated against this endpoint's payload schema).
-     * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
-     *
-     * @throws `string` if the payload is invalid.
-     * @throws `ValueError` if `callback()` returns an invalid result.
-     */
-    handle(callback: EndpointCallback<P, R>, unsafePayload: unknown, request: Request, caller?: AnyCaller): Promise<Response>;
+    handler<A extends Arguments = []>(callback: EndpointCallback<P, R, A>): RequestHandler<A>;
     /**
      * Render the URL for this endpoint with the given payload.
      * - URL might contain `{placeholder}` values that are replaced with values from the payload.

package/endpoint/Endpoint.js

@@ -1,10 +1,14 @@
+import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
 import { ValueError } from "../error/ValueError.js";
 import { UNDEFINED } from "../schema/Schema.js";
 import { isData } from "../util/data.js";
+import { getDictionary } from "../util/dictionary.js";
 import { getMessage } from "../util/error.js";
-import { getRequest, getResponse, getResponseContent } from "../util/http.js";
-import { renderTemplate } from "../util/template.js";
+import { getRequest, getRequestContent, getResponse, getResponseContent, } from "../util/http.js";
+import { isPlainObject } from "../util/object.js";
+import { matchTemplate, renderTemplate } from "../util/template.js";
+import { getURL } from "../util/url.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -29,42 +33,27 @@ export class Endpoint {
         this.result = result;
     }
     /**
-     * Return an `EndpointHandler` for this endpoint.
+     * Return an optional request handler for this endpoint.
      *
      * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      */
     handler(callback) {
-        return { endpoint: this, callback };
-    }
-    /**
-     * Handle a request to this endpoint with a callback implementation, with a given payload and request.
-     *
-     * @param callback The endpoint callback function that implements the logic for this endpoint by receiving the payload and returning the response.
-     * @param unsafePayload The payload to pass into the callback (will be validated against this endpoint's payload schema).
-     * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
-     *
-     * @throws `string` if the payload is invalid.
-     * @throws `ValueError` if `callback()` returns an invalid result.
-     */
-    async handle(callback, unsafePayload, request, caller = this.handle) {
-        // Validate the payload against this endpoint's payload type.
-        const payload = this.payload.validate(unsafePayload);
-        // Call the callback with the validated payload to get the result.
-        const unsafeResult = await callback(payload, request);
-        try {
-            // Convert the result to a `Response` object.
-            return getResponse(this.result.validate(unsafeResult));
-        }
-        catch (thrown) {
-            if (typeof thrown === "string")
-                throw new ValueError(`Invalid result for ${this.toString()}:\n${thrown}`, {
-                    endpoint: this,
-                    callback,
-                    cause: thrown,
-                    caller,
-                });
-            throw thrown;
-        }
+        const handler = (request, ...args) => {
+            // Ensure the request method e.g. `GET` matches the endpoint method e.g. `POST`.
+            if (request.method !== this.method)
+                return undefined;
+            // 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 url = getURL(request.url);
+            if (!url)
+                throw new RequestError("Invalid request URL", { received: request.url, caller: handler });
+            const { origin, pathname } = url;
+            const pathParams = matchTemplate(this.url, `${origin}${pathname}`, handler);
+            if (!pathParams)
+                return undefined;
+            return handleEndpoint(this, callback, request, args, handler);
+        };
+        return handler;
     }
     /**
      * Render the URL for this endpoint with the given payload.
@@ -127,6 +116,44 @@ export class Endpoint {
         return `${this.method} ${this.url}`;
     }
 }
+/**
+ * Handle a request to this endpoint with a callback implementation.
+ *
+ * @param callback The endpoint callback function that implements the logic for this endpoint by receiving the payload and returning the response.
+ * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
+ *
+ * @throws `string` if the payload is invalid.
+ * @throws `ValueError` if `callback()` returns an invalid result.
+ */
+async function handleEndpoint(endpoint, callback, request, args, caller = handleEndpoint) {
+    // Parse URL and collect path/query params for payload merging.
+    const url = getURL(request.url);
+    if (!url)
+        throw new RequestError("Invalid request URL", { received: request.url, caller });
+    const { origin, pathname, searchParams } = url;
+    const pathParams = matchTemplate(endpoint.url, `${origin}${pathname}`, caller);
+    if (!pathParams)
+        throw new RequestError("Invalid endpoint route", { received: request.url, endpoint, caller });
+    const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+    // Extract a data object from the request body and combine it with URL params.
+    const content = await getRequestContent(request, caller);
+    const unsafePayload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
+    // Validate the payload against this endpoint's payload type.
+    const payload = endpoint.payload.validate(unsafePayload);
+    // Call the callback with the validated payload to get the result.
+    const unsafeResult = await callback(payload, request, ...args);
+    try {
+        // Convert the result to a `Response` object.
+        return getResponse(endpoint.result.validate(unsafeResult));
+    }
+    catch (thrown) {
+        // If the result returned from the endpoint was invalid, throw an internal `ValueError`
+        if (typeof thrown === "string")
+            throw new ValueError(`Invalid result for ${endpoint.toString()}:\n${thrown}`, { endpoint, callback, cause: thrown, caller });
+        // Otherwise rethrow the error.
+        throw thrown;
+    }
+}
 export function HEAD(url, payload = UNDEFINED, result = UNDEFINED) {
     return new Endpoint("HEAD", url, payload, result);
 }

package/endpoint/util.d.ts

@@ -1,40 +1,30 @@
-import type { AnyCaller } from "../util/function.js";
-import type { Endpoint } from "./Endpoint.js";
+import type { Arguments } from "../util/function.js";
+import type { RequestHandler, RequestHandlers } from "../util/http.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.
+ * - If payload is _not_ a data object (i.e. it's another JSON type like `string` or `number`) then the payload is that raw body value.
  *
  * @param request The raw `Request` object in case it needs any additional processing.
+ * @param args Additional arguments passed through `handleEndpoints()`.
  *
  * @returns The correct `Result` type for the `Endpoint`, or a raw `Response` object if you wish to return a custom response.
  */
-export type EndpointCallback<P, R> = (payload: P, request: Request) => R | Response | Promise<R | Response>;
+export type EndpointCallback<P, R, A extends Arguments = []> = (payload: P, request: Request, ...args: A) => R | Response | Promise<R | Response>;
 /**
- * Object combining an abstract `Endpoint` and an `EndpointCallback` implementation.
+ * List of endpoint handlers that can match and handle requests.
  */
-export interface EndpointHandler<P, R> {
-    readonly endpoint: Endpoint<P, R>;
-    readonly callback: EndpointCallback<P, R>;
-}
+export type EndpointHandlers<A extends Arguments = []> = ReadonlyArray<RequestHandler<A>>;
 /**
- * Any handler (purposefully as wide as possible for use with `extends X` or `is X` statements).
- */
-export type AnyEndpointHandler = EndpointHandler<any, any>;
-/**
- * List of `EndpointHandler` objects objects that can handle requests to an `Endpoint`.
- */
-export type EndpointHandlers = ReadonlyArray<AnyEndpointHandler>;
-/**
- * Handler a `Request` with the first matching `EndpointHandlers`.
+ * Handle a `Request` with the first matching endpoint handler.
  *
- * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
- * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`.
+ * 2. Make an array of endpoint handlers created via `endpoint.handler(callback)`.
  *
  * @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, caller?: AnyCaller): Promise<Response>;
+export declare function handleEndpoints<A extends Arguments = []>(endpoints: RequestHandlers<A>, request: Request, ...args: A): Promise<Response> | Response;

package/endpoint/util.js

@@ -1,50 +1,26 @@
 import { NotFoundError, RequestError } from "../error/RequestError.js";
-import { getDictionary } from "../util/dictionary.js";
-import { getRequestContent } from "../util/http.js";
-import { isPlainObject } from "../util/object.js";
-import { matchTemplate } from "../util/template.js";
 import { getURL } from "../util/url.js";
 /**
- * Handler a `Request` with the first matching `EndpointHandlers`.
+ * Handle a `Request` with the first matching endpoint handler.
  *
- * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
- * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`.
+ * 2. Make an array of endpoint handlers created via `endpoint.handler(callback)`.
  *
  * @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, caller = handleEndpoints) {
+export function handleEndpoints(endpoints, request, ...args) {
+    const caller = handleEndpoints;
     // Parse the URL of the request.
     const url = getURL(request.url);
     if (!url)
         throw new RequestError("Invalid request URL", { received: request.url, caller });
-    const { origin, 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.url, `${origin}${pathname}`, caller);
-        if (!pathParams)
-            continue;
-        // Make a simple dictionary object from the `{placeholder}` path params and the `?a=123` query params from the URL.
-        const combinedParams = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
-        // Get the response by calling the callback.
-        return handleEndpoint(endpoint, callback, combinedParams, request, caller);
+    for (const endpoint of endpoints) {
+        const response = endpoint(request, ...args);
+        if (response)
+            return response;
     }
     // No handler matched the request.
     throw new NotFoundError("No matching endpoint", { received: request.url, caller });
 }
-/** Handle an individual call to an endpoint callback. */
-async function handleEndpoint(endpoint, callback, params, request, caller = handleEndpoint) {
-    // Extract a data object from the request body and validate it against the endpoint's payload type.
-    const content = await getRequestContent(request, caller);
-    // If content is undefined, it means the request has no body, so params are the only payload.
-    // - If the content is a plain object, merge if with the params.
-    // - If the content is anything else (e.g. string, number, array), return it directly (but you'll have no way to access the other params).
-    const payload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
-    // Call `endpoint.handle()` with the payload and request.
-    return endpoint.handle(callback, payload, request, caller);
-}

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.173.1",
+	"version": "1.174.0",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/dhoulb/shelving.git"
@@ -48,7 +48,7 @@
 		"test": "bun run test:check && bun run test:types && bun run test:unit",
 		"test:check": "biome check .",
 		"test:types": "tsc --noEmit",
-		"test:unit": "bun test",
+		"test:unit": "bun test --concurrent",
 		"fix": "bun run fix:biome",
 		"fix:biome": "biome check --write .",
 		"build": "bun run build:setup && bun run build:copy && bun run build:emit && bun run build:test:syntax && bun run build:test:unit",

package/util/http.d.ts

@@ -1,10 +1,12 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
 import { type Data } from "./data.js";
-import type { AnyCaller } from "./function.js";
+import type { AnyCaller, Arguments } from "./function.js";
 import type { URLString } from "./url.js";
-/** A handler function takes a `Request` and returns a `Response` (possibly asynchronously). */
-export type RequestHandler = (request: Request) => Response | Promise<Response>;
+/** A handler function takes a `Request` and optional extra arguments, and returns a `Response` (possibly asynchronously) or `undefined` if the request could not be handled. */
+export type RequestHandler<A extends Arguments = []> = (request: Request, ...args: A) => Response | Promise<Response> | undefined;
+/** A list of optional request handlers. */
+export type RequestHandlers<A extends Arguments = []> = Iterable<RequestHandler<A>>;
 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>;