shelving 1.144.0 → 1.145.0

package/api/Endpoint.d.ts

@@ -11,7 +11,7 @@ export type EndpointMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  * @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> {
+export declare class Endpoint<P, R> {
     /** Endpoint method. */
     readonly method: EndpointMethod;
     /** Endpoint path, e.g. `/patient/{id}` */
@@ -21,20 +21,6 @@ export declare class Endpoint<P, R> implements Validator<R> {
     /** 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.
      *
@@ -49,6 +35,8 @@ export declare class Endpoint<P, R> implements Validator<R> {
      * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
      */
     handle(callback: EndpointCallback<P, R>, unsafePayload: unknown, request: Request): Promise<Response>;
+    /** Convert to string, e.g. `GET /user/{id}` */
+    toString(): string;
 }
 /** Extract the payload type from a `Endpoint`. */
 export type PayloadType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<infer Y, unknown> ? Y : never;

package/api/Endpoint.js

@@ -1,5 +1,5 @@
-import { ValueError } from "../error/ValueError.js";
-import { UNDEFINED, getValid } from "../util/validate.js";
+import { getResponse } from "../util/http.js";
+import { UNDEFINED } from "../util/validate.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -23,24 +23,6 @@ export class Endpoint {
         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.
      *
@@ -57,17 +39,14 @@ export class Endpoint {
      * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
      */
     async handle(callback, unsafePayload, request) {
-        const payload = this.prepare(unsafePayload);
+        // 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 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(returned, this, ValueError, this.handle);
-        // Return a new `Response` with a 200 status and the validated result data.
-        return Response.json(result);
+        return getResponse(await callback(payload, request));
+    }
+    /** Convert to string, e.g. `GET /user/{id}` */
+    toString() {
+        return `${this.method} ${this.path}`;
     }
 }
 export function GET(path, payload, result) {

package/api/util.d.ts

@@ -38,17 +38,3 @@ export type EndpointHandlers = ReadonlyArray<AnyEndpointHandler>;
  * @throws `NotFoundError` if no handler matches the `Request`.
  */
 export declare function handleEndpoints(request: Request, endpoints: EndpointHandlers): Promise<Response>;
-/**
- * Correctly interpret an error thrown from an endpoint and return the correct `Response`.
- *
- * Returns the correct `Response` based on the type of error thrown:
- * - If `reason` is a `Response` instance, return it directly.
- * - If `reason` is a `Feedback` instance, return a 400 response with the feedback's message as JSON, e.g. `{ message: "Invalid input" }`
- * - If `reason` is an `RequestError` instance, return a response with the error's message and code (but only if `debug` is true so we don't leak error details to the client).
- * - If `reason` is an `Error` instance, return a 500 response with the error's message (but only if `debug` is true so we don't leak error details to the client).
- * - Anything else returns a 500 response.
- *
- * @param reason The error thrown from the endpoint.
- * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
- */
-export declare function handleEndpointError(reason: unknown, debug?: boolean): Response;

package/api/util.js

@@ -1,8 +1,6 @@
 import { NotFoundError, RequestError } from "../error/RequestError.js";
-import { Feedback } from "../feedback/Feedback.js";
 import { isData } from "../util/data.js";
 import { getDictionary } from "../util/dictionary.js";
-import { isError } from "../util/error.js";
 import { getRequestContent } from "../util/http.js";
 import { matchTemplate } from "../util/template.js";
 import { getURL } from "../util/url.js";
@@ -52,31 +50,3 @@ async function handleEndpoint(endpoint, callback, params, request) {
     // Call `endpoint.handle()` with the payload and request.
     return endpoint.handle(callback, payload, request);
 }
-/**
- * Correctly interpret an error thrown from an endpoint and return the correct `Response`.
- *
- * Returns the correct `Response` based on the type of error thrown:
- * - If `reason` is a `Response` instance, return it directly.
- * - If `reason` is a `Feedback` instance, return a 400 response with the feedback's message as JSON, e.g. `{ message: "Invalid input" }`
- * - If `reason` is an `RequestError` instance, return a response with the error's message and code (but only if `debug` is true so we don't leak error details to the client).
- * - If `reason` is an `Error` instance, return a 500 response with the error's message (but only if `debug` is true so we don't leak error details to the client).
- * - Anything else returns a 500 response.
- *
- * @param reason The error thrown from the endpoint.
- * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
- */
-export function handleEndpointError(reason, debug = false) {
-    // Throw `Response` to do a custom response that is not logged.
-    if (reason instanceof Response)
-        return reason;
-    // Throw 'Feedback' to return `{ message: "etc" }` to the client, e.g. for input validation.
-    if (reason instanceof Feedback)
-        return Response.json(reason, { status: 422 }); // HTTP 422 Unprocessable Entity
-    // Throw `RequestError` to set a custom status code (e.g. `UnauthorizedError`).
-    const status = reason instanceof RequestError ? reason.code : 500;
-    // Throw `Error` to return `{ message: "etc" }` to the client (but only if `debug` is true so we don't leak error details to the client).
-    if (debug && isError(reason))
-        return Response.json(reason, { status });
-    // Otherwise return a generic error message.
-    return new Response(undefined, { status });
-}

package/package.json

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

package/util/http.d.ts

@@ -44,3 +44,24 @@ export declare function getRequestJSON(message: Request, caller?: AnyCaller): Pr
  * @throws RequestError if the content is not valid JSON.
  */
 export declare function getResponseJSON(message: Response, caller?: AnyCaller): Promise<unknown>;
+/**
+ * Get an HTTP `Response` for an unknown value.
+ *
+ * @param value The value to convert to a `Response`.
+ * @returns A `Response` with a 2xx status, and response body as JSON (if it was set), or no body if `value` is `undefined`
+ */
+export declare function getResponse(value: unknown): Response;
+/**
+ * Get an HTTP `Response` for an unknown error value.
+ *
+ * Returns the correct `Response` based on the type of error thrown:
+ * - If `reason` is a `Response` instance, return it directly.
+ * - If `reason` is a `Feedback` instance, return a 400 response with the feedback's message as JSON, e.g. `{ message: "Invalid input" }`
+ * - If `reason` is an `RequestError` instance, return a response with the error's message and code (but only if `debug` is true so we don't leak error details to the client).
+ * - If `reason` is an `Error` instance, return a 500 response with the error's message (but only if `debug` is true so we don't leak error details to the client).
+ * - Anything else returns a 500 response.
+ *
+ * @param reason The error value to convert to a `Response`.
+ * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
+ */
+export declare function getErrorResponse(reason: unknown, debug?: boolean): Response;

package/util/http.js

@@ -1,6 +1,8 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
+import { Feedback } from "../feedback/Feedback.js";
 import { getDictionary } from "./dictionary.js";
+import { isError } from "./error.js";
 export async function _getMessageJSON(message, MessageError, caller) {
     const trimmed = (await message.text()).trim();
     if (!trimmed.length)
@@ -76,3 +78,47 @@ export function getRequestJSON(message, caller = getRequestJSON) {
 export function getResponseJSON(message, caller = getResponseJSON) {
     return _getMessageJSON(message, ResponseError, caller);
 }
+/**
+ * Get an HTTP `Response` for an unknown value.
+ *
+ * @param value The value to convert to a `Response`.
+ * @returns A `Response` with a 2xx status, and response body as JSON (if it was set), or no body if `value` is `undefined`
+ */
+export function getResponse(value) {
+    // If it's already a `Response`, return it directly.
+    if (value instanceof Response)
+        return value;
+    // If result is undefined, return 204 No Content response.
+    if (value === undefined)
+        return new Response(undefined, { status: 204 });
+    // Return a new `Response` with a 2xx status and response body as JSON.
+    return Response.json(value, { status: 200 });
+}
+/**
+ * Get an HTTP `Response` for an unknown error value.
+ *
+ * Returns the correct `Response` based on the type of error thrown:
+ * - If `reason` is a `Response` instance, return it directly.
+ * - If `reason` is a `Feedback` instance, return a 400 response with the feedback's message as JSON, e.g. `{ message: "Invalid input" }`
+ * - If `reason` is an `RequestError` instance, return a response with the error's message and code (but only if `debug` is true so we don't leak error details to the client).
+ * - If `reason` is an `Error` instance, return a 500 response with the error's message (but only if `debug` is true so we don't leak error details to the client).
+ * - Anything else returns a 500 response.
+ *
+ * @param reason The error value to convert to a `Response`.
+ * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
+ */
+export function getErrorResponse(reason, debug = false) {
+    // If it's already a `Response`, return it directly.
+    if (reason instanceof Response)
+        return reason;
+    // Throw 'Feedback' to return `{ message: "etc" }` to the client, e.g. for input validation.
+    if (reason instanceof Feedback)
+        return Response.json(reason, { status: 422 }); // HTTP 422 Unprocessable Entity
+    // Throw `RequestError` to set a custom status code (e.g. `UnauthorizedError`).
+    const status = reason instanceof RequestError ? reason.code : 500;
+    // Throw `Error` to return `{ message: "etc" }` to the client (but only if `debug` is true so we don't leak error details to the client).
+    if (debug && isError(reason))
+        return Response.json(reason, { status });
+    // Otherwise return a generic error message with no details.
+    return new Response(undefined, { status });
+}