shelving 1.143.1 → 1.144.0

package/api/Endpoint.d.ts

@@ -36,9 +36,19 @@ export declare class Endpoint<P, R> implements Validator<R> {
      */
     validate(unsafeResult: unknown): R;
     /**
-     * Return an `EndpointHandler` for this endpoint
+     * Return an `EndpointHandler` 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).
+     */
+    handle(callback: EndpointCallback<P, R>, unsafePayload: unknown, request: Request): Promise<Response>;
 }
 /** 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,4 +1,5 @@
-import { UNDEFINED } from "../util/validate.js";
+import { ValueError } from "../error/ValueError.js";
+import { UNDEFINED, getValid } from "../util/validate.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -41,11 +42,33 @@ export class Endpoint {
         return this.result.validate(unsafeResult);
     }
     /**
-     * Return an `EndpointHandler` for this endpoint
+     * Return an `EndpointHandler` 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).
+     */
+    async handle(callback, unsafePayload, request) {
+        const payload = this.prepare(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);
+    }
 }
 export function GET(path, payload, result) {
     return new Endpoint("GET", path, payload || UNDEFINED, result || UNDEFINED);

package/api/util.d.ts

@@ -38,3 +38,17 @@ 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,11 +1,11 @@
 import { NotFoundError, RequestError } from "../error/RequestError.js";
-import { ValueError } from "../error/ValueError.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";
-import { getValid } from "../util/validate.js";
 /**
  * Handler a `Request` with the first matching `EndpointHandlers`.
  *
@@ -18,9 +18,10 @@ import { getValid } from "../util/validate.js";
  */
 export function handleEndpoints(request, endpoints) {
     // Parse the URL of the request.
-    const url = getURL(request.url);
+    const requestUrl = request.url;
+    const url = getURL(requestUrl);
     if (!url)
-        throw new RequestError("Invalid request URL", { received: request.url, caller: handleEndpoints });
+        throw new RequestError("Invalid request URL", { received: requestUrl, 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) {
@@ -35,27 +36,47 @@ export function handleEndpoints(request, endpoints) {
         // 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 getEndpointResponse(endpoint, callback, params, request);
+        return handleEndpoint(endpoint, callback, params, request);
     }
     // No handler matched the request.
-    throw new NotFoundError("Not found", { request, caller: handleEndpoints });
+    throw new NotFoundError("No matching endpoint", { received: requestUrl, caller: handleEndpoints });
 }
-async function getEndpointResponse(endpoint, callback, params, request) {
+/** Handle an individual call to an endpoint callback. */
+async function handleEndpoint(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 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, endpoint, ValueError, handleEndpoints);
-    // Return a new `Response` with a 200 status and the validated result data.
-    return Response.json(result);
+    const payload = content === undefined ? params : isData(content) ? { ...content, ...params } : { content, ...params };
+    // 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.143.1",
+	"version": "1.144.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/util/ansi.d.ts

@@ -0,0 +1,24 @@
+export declare const ANSI_TEXT_DEFAULT = "\u001B[39m";
+export declare const ANSI_TEXT_BLACK = "\u001B[30m";
+export declare const ANSI_TEXT_RED = "\u001B[31m";
+export declare const ANSI_TEXT_GREEN = "\u001B[32m";
+export declare const ANSI_TEXT_YELLOW = "\u001B[33m";
+export declare const ANSI_TEXT_BLUE = "\u001B[34m";
+export declare const ANSI_TEXT_MAGENTA = "\u001B[35m";
+export declare const ANSI_TEXT_CYAN = "\u001B[36m";
+export declare const ANSI_TEXT_WHITE = "\u001B[37m";
+export declare const ANSI_FILL_DEFAULT = "\u001B[49m";
+export declare const ANSI_FILL_BLACK = "\u001B[40m";
+export declare const ANSI_FILL_RED = "\u001B[41m";
+export declare const ANSI_FILL_GREEN = "\u001B[42m";
+export declare const ANSI_FILL_YELLOW = "\u001B[43m";
+export declare const ANSI_FILL_BLUE = "\u001B[44m";
+export declare const ANSI_FILL_MAGENTA = "\u001B[45m";
+export declare const ANSI_FILL_CYAN = "\u001B[46m";
+export declare const ANSI_FILL_WHITE = "\u001B[47m";
+export declare const ANSI_BOLD = "\u001B[1m";
+export declare const ANSI_ITALIC = "\u001B[3m";
+export declare const ANSI_UNDERLINE = "\u001B[4m";
+export declare const ANSI_STRIKE = "\u001B[9m";
+export declare const ANSI_INVERSE = "\u001B[7m";
+export declare const ANSI_RESET = "\u001B[0m";

package/util/ansi.js

@@ -0,0 +1,28 @@
+// Foreground colors.
+export const ANSI_TEXT_DEFAULT = "\x1b[39m";
+export const ANSI_TEXT_BLACK = "\x1b[30m";
+export const ANSI_TEXT_RED = "\x1b[31m";
+export const ANSI_TEXT_GREEN = "\x1b[32m";
+export const ANSI_TEXT_YELLOW = "\x1b[33m";
+export const ANSI_TEXT_BLUE = "\x1b[34m";
+export const ANSI_TEXT_MAGENTA = "\x1b[35m";
+export const ANSI_TEXT_CYAN = "\x1b[36m";
+export const ANSI_TEXT_WHITE = "\x1b[37m";
+// Background colors.
+export const ANSI_FILL_DEFAULT = "\x1b[49m";
+export const ANSI_FILL_BLACK = "\x1b[40m";
+export const ANSI_FILL_RED = "\x1b[41m";
+export const ANSI_FILL_GREEN = "\x1b[42m";
+export const ANSI_FILL_YELLOW = "\x1b[43m";
+export const ANSI_FILL_BLUE = "\x1b[44m";
+export const ANSI_FILL_MAGENTA = "\x1b[45m";
+export const ANSI_FILL_CYAN = "\x1b[46m";
+export const ANSI_FILL_WHITE = "\x1b[47m";
+// Styles.
+export const ANSI_BOLD = "\x1b[1m";
+export const ANSI_ITALIC = "\x1b[3m";
+export const ANSI_UNDERLINE = "\x1b[4m";
+export const ANSI_STRIKE = "\x1b[9m";
+export const ANSI_INVERSE = "\x1b[7m";
+// Reset.
+export const ANSI_RESET = "\x1b[0m";

package/util/http.d.ts

@@ -9,9 +9,9 @@ export declare function _getMessageContent(message: Request | Response, MessageE
 /**
  * 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.
+ * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
@@ -19,10 +19,28 @@ export declare function getRequestContent(message: Request, caller?: AnyCaller):
 /**
  * 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.
+ * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @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>;
+/**
+ * Get the body content of an HTTP `Request` as JSON, or throw `RequestError` if the content could not be parsed.
+ * - Doesn't check the `Content-Type` header, so it can be used for any request.
+ *
+ * @returns unknown The parsed JSON content of the request body, or `undefined` if the body is empty.
+ *
+ * @throws RequestError if the content is not valid JSON.
+ */
+export declare function getRequestJSON(message: Request, caller?: AnyCaller): Promise<unknown>;
+/**
+ * Get the body content of an HTTP `Response` as JSON, or throw `ResponseError` if the content could not be parsed.
+ * - Doesn't check the `Content-Type` header, so it can be used for any response.
+ *
+ * @returns unknown The parsed JSON content of the response body, or `undefined` if the body is empty.
+ *
+ * @throws RequestError if the content is not valid JSON.
+ */
+export declare function getResponseJSON(message: Response, caller?: AnyCaller): Promise<unknown>;

package/util/http.js

@@ -22,20 +22,18 @@ export async function _getMessageFormData(message, MessageError, 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 });
+    return message.text();
 }
 /**
  * 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.
+ * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
@@ -47,12 +45,34 @@ export function getRequestContent(message, caller = getRequestContent) {
 /**
  * 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.
+ * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
  * @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);
 }
+/**
+ * Get the body content of an HTTP `Request` as JSON, or throw `RequestError` if the content could not be parsed.
+ * - Doesn't check the `Content-Type` header, so it can be used for any request.
+ *
+ * @returns unknown The parsed JSON content of the request body, or `undefined` if the body is empty.
+ *
+ * @throws RequestError if the content is not valid JSON.
+ */
+export function getRequestJSON(message, caller = getRequestJSON) {
+    return _getMessageJSON(message, RequestError, caller);
+}
+/**
+ * Get the body content of an HTTP `Response` as JSON, or throw `ResponseError` if the content could not be parsed.
+ * - Doesn't check the `Content-Type` header, so it can be used for any response.
+ *
+ * @returns unknown The parsed JSON content of the response body, or `undefined` if the body is empty.
+ *
+ * @throws RequestError if the content is not valid JSON.
+ */
+export function getResponseJSON(message, caller = getResponseJSON) {
+    return _getMessageJSON(message, ResponseError, caller);
+}

package/util/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./ansi.js";
 export * from "./array.js";
 export * from "./async.js";
 export * from "./base64.js";

package/util/index.js

@@ -1,3 +1,4 @@
+export * from "./ansi.js";
 export * from "./array.js";
 export * from "./async.js";
 export * from "./base64.js";