shelving 1.141.0 → 1.142.0

package/api/util.d.ts

@@ -6,8 +6,12 @@ import type { Endpoint } from "./Endpoint.js";
  * - Payload is validated by the payload validator for the `Endpoint`.
  * - If the body of the `Request` is a data object (i.e. a plain object), then body data is merged with the path and query parameters to form a single flat object.
  * - If payload is _not_ a data object (i.e. it's another JSON type like `string` or `number`) then the payload include the path and query parameters, and a key called `content` that contains the body of the request.
+ *
+ * @param request The raw `Request` object in case it needs any additional processing.
+ *
+ * @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 | Promise<R>;
+export type EndpointCallback<P, R> = (payload: P, request: Request) => R | Response | Promise<R | Response>;
 /**
  * Object combining an abstract `Endpoint` and an `EndpointCallback` implementation.
  */
@@ -24,7 +28,11 @@ export type AnyEndpointHandler = EndpointHandler<any, any>;
  */
 export type EndpointHandlers = ReadonlyArray<AnyEndpointHandler>;
 /**
- * Handler a `Request` with the first matching `OptionalHandler` in a `Handlers` array.
+ * Handler a `Request` with the first matching `EndpointHandlers`.
+ *
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
+ * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * -
  *
  * @returns The resulting `Response` from the first handler that matches the `Request`.
  * @throws `NotFoundError` if no handler matches the `Request`.

package/api/util.js

@@ -7,7 +7,11 @@ 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.
+ * Handler a `Request` with the first matching `EndpointHandlers`.
+ *
+ * 1. Define your `Endpoint` objects with a method, path, payload and result validators, e.g. `GET("/test/{id}", PAYLOAD, STRING)`
+ * 2. Make an array of `EndpointHandler` objects combining an `Endpoint` with a `callback` function
+ * -
  *
  * @returns The resulting `Response` from the first handler that matches the `Request`.
  * @throws `NotFoundError` if no handler matches the `Request`.
@@ -28,14 +32,15 @@ export function handleEndpoints(request, endpoints) {
         const pathParams = matchTemplate(endpoint.path, pathname, handleEndpoints);
         if (!pathParams)
             continue;
-        // Merge the search params and path params.
+        // Make a simple dictionary object from the `{placeholder}` path params and the `?a=123` query params from the URL.
         const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
         // Get the response by calling the callback.
-        return _getResponse(endpoint, callback, params, request);
+        return getEndpointResponse(endpoint, callback, params, request);
     }
+    // No handler matched the request.
     throw new NotFoundError("Not found", { request, caller: handleEndpoints });
 }
-async function _getResponse(endpoint, callback, params, request) {
+async function getEndpointResponse(endpoint, callback, params, request) {
     // Extract a data object from the request body and validate it against the endpoint's payload type.
     const content = await getRequestContent(request, handleEndpoints);
     // If content is undefined, it means the request has no body, so params are the only payload.
@@ -43,11 +48,14 @@ async function _getResponse(endpoint, callback, params, request) {
     // 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.
+    // Call the callback with the validated payload to get the result.
+    const returned = await callback(payload, request);
+    // If the callback returned a `Response`, return it directly.
+    if (returned instanceof Response)
+        return returned;
+    // Otherwise validate the result against the endpoint's result type.
     // Throw a `ValueError` if the result is not valid, which indicates an internal error in the callback implementation.
-    const result = getValid(unsafeResult, endpoint, ValueError, handleEndpoints);
+    const result = getValid(returned, endpoint, ValueError, handleEndpoints);
     // Return a new `Response` with a 200 status and the validated result data.
     return Response.json(result);
 }

package/package.json

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

package/util/http.d.ts

@@ -2,7 +2,7 @@ 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 type RequestHandler = (request: Request) => Response | Promise<Response>;
 export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
 export declare function _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>;