shelving 1.166.0 → 1.167.1

package/api/Endpoint.d.ts

@@ -48,11 +48,27 @@ export declare class Endpoint<P, R> {
      */
     renderURL(payload: P, caller?: AnyCaller): string;
     /**
-     * Validate a payload against this endpoints payload schema, and return an HTTP `Request` that will send it to this endpoint.
+     * Get an HTTP `Request` object for this endpoint.
+     * - Validates a payload against this endpoints payload schema
+     * - Return an HTTP `Request` that will send it the valid payload to this endpoint.
+     *
+     * @throws Feedback if the payload is invalid.
      */
     request(payload: P, options?: EndpointOptions, caller?: AnyCaller): Request;
     /**
-     * Perform a fetch to this endpoint, and validate the returned response against this endpoint's result schema.
+     * Validate an HTTP `Response` against this endpoint.
+     * @throws ResponseError if the response status is not ok (200-299)
+     * @throws ResponseError if the response content is invalid.
+     */
+    response(response: Response, caller?: AnyCaller): Promise<R>;
+    /**
+     * Perform a fetch to this endpoint.
+     * - Validate the `payload` against this endpoint's payload schema.
+     * - Validate the returned response against this endpoint's result schema.
+     *
+     * @throws Feedback if the payload is invalid.
+     * @throws ResponseError if the response status is not ok (200-299)
+     * @throws ResponseError if the response content is invalid.
      */
     fetch(payload: P, options?: EndpointOptions, caller?: AnyCaller): Promise<R>;
     /** Convert to string, e.g. `GET https://a.com/user/{id}` */

package/api/Endpoint.js

@@ -70,18 +70,21 @@ export class Endpoint {
         return url;
     }
     /**
-     * Validate a payload against this endpoints payload schema, and return an HTTP `Request` that will send it to this endpoint.
+     * Get an HTTP `Request` object for this endpoint.
+     * - Validates a payload against this endpoints payload schema
+     * - Return an HTTP `Request` that will send it the valid payload to this endpoint.
+     *
+     * @throws Feedback if the payload is invalid.
      */
     request(payload, options = {}, caller = this.request) {
         return createRequest(this.method, this.url, this.payload.validate(payload), options, caller);
     }
     /**
-     * Perform a fetch to this endpoint, and validate the returned response against this endpoint's result schema.
+     * Validate an HTTP `Response` against this endpoint.
+     * @throws ResponseError if the response status is not ok (200-299)
+     * @throws ResponseError if the response content is invalid.
      */
-    async fetch(payload, options = {}, caller = this.fetch) {
-        // Fetch the response.
-        const request = this.request(payload, options, caller);
-        const response = await fetch(request);
+    async response(response, caller = this.response) {
         // Get the response.
         const { ok, status } = response;
         const content = await getResponseContent(response, caller);
@@ -91,6 +94,19 @@ export class Endpoint {
         // Validate the success response.
         return getValid(content, this.result, ResponseError, caller);
     }
+    /**
+     * Perform a fetch to this endpoint.
+     * - Validate the `payload` against this endpoint's payload schema.
+     * - Validate the returned response against this endpoint's result schema.
+     *
+     * @throws Feedback if the payload is invalid.
+     * @throws ResponseError if the response status is not ok (200-299)
+     * @throws ResponseError if the response content is invalid.
+     */
+    async fetch(payload, options = {}, caller = this.fetch) {
+        const response = await fetch(this.request(payload, options, caller));
+        return this.response(response, caller);
+    }
     /** Convert to string, e.g. `GET https://a.com/user/{id}` */
     toString() {
         return `${this.method} ${this.url}`;

package/api/util.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../util/function.js";
 import type { Endpoint } from "./Endpoint.js";
 /**
  * A function that handles a endpoint request, with a payload and returns a result.
@@ -32,9 +33,8 @@ export type EndpointHandlers = ReadonlyArray<AnyEndpointHandler>;
  *
  * 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`.
  */
-export declare function handleEndpoints(request: Request, endpoints: EndpointHandlers): Promise<Response>;
+export declare function handleEndpoints(request: Request, endpoints: EndpointHandlers, caller?: AnyCaller): Promise<Response>;

package/api/util.js

@@ -9,17 +9,16 @@ import { getURL } from "../util/url.js";
  *
  * 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`.
  */
-export function handleEndpoints(request, endpoints) {
+export function handleEndpoints(request, endpoints, caller = handleEndpoints) {
     // Parse the URL of the request.
     const requestUrl = request.url;
     const url = getURL(requestUrl);
     if (!url)
-        throw new RequestError("Invalid request URL", { received: requestUrl, caller: handleEndpoints });
+        throw new RequestError("Invalid request URL", { received: requestUrl, 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) {
@@ -28,7 +27,7 @@ export function handleEndpoints(request, endpoints) {
             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}`, handleEndpoints);
+        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.
@@ -37,7 +36,7 @@ export function handleEndpoints(request, endpoints) {
         return handleEndpoint(endpoint, callback, combinedParams, request);
     }
     // No handler matched the request.
-    throw new NotFoundError("No matching endpoint", { received: requestUrl, caller: handleEndpoints });
+    throw new NotFoundError("No matching endpoint", { received: requestUrl, caller });
 }
 /** Handle an individual call to an endpoint callback. */
 async function handleEndpoint(endpoint, callback, params, request) {

package/package.json

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