shelving 1.143.0 → 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/error/BaseError.d.ts

@@ -1,7 +1,4 @@
-import type { AnyConstructor } from "../util/class.js";
-import type { AnyFunction } from "../util/function.js";
-/** Any calling function or constructor that can appear in a stack tracer. */
-export type AnyCaller = AnyFunction | AnyConstructor;
+import type { AnyCaller } from "../util/function.js";
 /** Options for `BaseError` that provide additional helpful error functionality. */
 export interface BaseErrorOptions extends ErrorOptions {
     /**
@@ -15,7 +12,7 @@ export interface BaseErrorOptions extends ErrorOptions {
 }
 /** An error that provides additional helpful functionality. */
 export declare abstract class BaseError extends Error {
-    /** Provide additional named contextual data that should be attached to the `Error` instance. */
-    [key: string]: unknown;
+    /** Provide additional named contextual data that is relevant to the `Error` instance. */
+    readonly [key: string]: unknown;
     constructor(message?: string, options?: BaseErrorOptions);
 }

package/error/BaseError.js

@@ -1,18 +1,11 @@
 /** An error that provides additional helpful functionality. */
 export class BaseError extends Error {
-    constructor(message, options) {
-        if (options) {
-            super(message, options);
-            const { cause, caller = BaseError, ...rest } = options;
-            for (const [key, value] of Object.entries(rest))
-                this[key] = value;
-            Error.captureStackTrace(this, caller);
-        }
-        else {
-            super(message);
-            Error.captureStackTrace(this, BaseError);
-        }
+    constructor(message, options = {}) {
+        super(message, options);
+        const { cause, caller = BaseError, ...rest } = options;
+        for (const [key, value] of Object.entries(rest))
+            this[key] = value;
+        Error.captureStackTrace(this, caller);
     }
 }
 BaseError.prototype.name = "BaseError";
-BaseError.prototype.message = "Unknown error";

package/error/NetworkError.js

@@ -6,4 +6,3 @@ export class NetworkError extends BaseError {
     }
 }
 NetworkError.prototype.name = "NetworkError";
-NetworkError.prototype.message = "Network error";

package/error/RequestError.d.ts

@@ -1,32 +1,27 @@
 import { BaseError, type BaseErrorOptions } from "./BaseError.js";
-/** Options for a `RequestError` */
-interface RequestErrorOptions extends BaseErrorOptions {
-    code?: number;
-}
 /** Error thrown when a request isn't well-formed. */
 export declare class RequestError extends BaseError {
     /** The corresponding HTTP status code for this error, in the range `400-499` */
-    code: number;
-    constructor(message?: string, options?: RequestErrorOptions);
+    readonly code: number;
+    constructor(message?: string, options?: BaseErrorOptions);
 }
 /** Thrown if an operation failed because the user is not logged in, or the login information is not well-formed. */
 export declare class UnauthorizedError extends RequestError {
     readonly code: number;
-    constructor(message?: string, options?: RequestErrorOptions);
+    constructor(message?: string, options?: BaseErrorOptions);
 }
 /** Thrown if the requested content is not found. */
 export declare class NotFoundError extends RequestError {
-    readonly code = 404;
-    constructor(message?: string, options?: RequestErrorOptions);
+    readonly code: number;
+    constructor(message?: string, options?: BaseErrorOptions);
 }
 /** Error thrown when a request is is valid and well-formed, but its actual data is not. */
 export declare class UnprocessableError extends RequestError {
     readonly code: number;
-    constructor(message?: string, options?: RequestErrorOptions);
+    constructor(message?: string, options?: BaseErrorOptions);
 }
 /** Thrown if an operation failed because the user is logged in, but does not have sufficient privileges to access this content. */
 export declare class ForbiddenError extends RequestError {
     readonly code: number;
-    constructor(message?: string, options?: RequestErrorOptions);
+    constructor(message?: string, options?: BaseErrorOptions);
 }
-export {};

package/error/RequestError.js

@@ -2,49 +2,41 @@ import { BaseError } from "./BaseError.js";
 /** Error thrown when a request isn't well-formed. */
 export class RequestError extends BaseError {
     /** The corresponding HTTP status code for this error, in the range `400-499` */
-    code;
-    constructor(message = RequestError.prototype.message, options) {
+    code = 400;
+    constructor(message, options) {
         super(message, { caller: RequestError, ...options });
-        this.code = options?.code || 400;
     }
 }
 RequestError.prototype.name = "RequestError";
-RequestError.prototype.message = "Invalid request";
 /** Thrown if an operation failed because the user is not logged in, or the login information is not well-formed. */
 export class UnauthorizedError extends RequestError {
     code = 401;
-    constructor(message = UnauthorizedError.prototype.message, options) {
-        super(message, { caller: UnauthorizedError, code: 401, ...options });
+    constructor(message, options) {
+        super(message, { caller: UnauthorizedError, ...options });
     }
 }
 UnauthorizedError.prototype.name = "UnauthorizedError";
-UnauthorizedError.prototype.message = "Authorization is required";
 /** Thrown if the requested content is not found. */
 export class NotFoundError extends RequestError {
     code = 404;
-    constructor(message = NotFoundError.prototype.message, options) {
-        super(message, { caller: NotFoundError, code: 404, ...options });
-        Error.captureStackTrace(this, NotFoundError);
+    constructor(message, options) {
+        super(message, { caller: NotFoundError, ...options });
     }
 }
 NotFoundError.prototype.name = "NotFoundError";
-NotFoundError.prototype.message = "Cannot find requested content";
 /** Error thrown when a request is is valid and well-formed, but its actual data is not. */
 export class UnprocessableError extends RequestError {
     code = 422;
-    constructor(message = UnprocessableError.prototype.message, options) {
-        super(message, { caller: UnprocessableError, code: 422, ...options });
-        Error.captureStackTrace(this, UnprocessableError);
+    constructor(message, options) {
+        super(message, { caller: UnprocessableError, ...options });
     }
 }
 UnprocessableError.prototype.name = "UnprocessableError";
-UnprocessableError.prototype.message = "Input data is invalid";
 /** Thrown if an operation failed because the user is logged in, but does not have sufficient privileges to access this content. */
 export class ForbiddenError extends RequestError {
     code = 403;
-    constructor(message = ForbiddenError.prototype.message, options) {
-        super(message, { caller: ForbiddenError, code: 403, ...options });
+    constructor(message, options) {
+        super(message, { caller: ForbiddenError, ...options });
     }
 }
 ForbiddenError.prototype.name = "ForbiddenError";
-ForbiddenError.prototype.message = "Insufficient privileges to access this content";

package/error/RequiredError.js

@@ -9,4 +9,3 @@ export class RequiredError extends BaseError {
     }
 }
 RequiredError.prototype.name = "RequiredError";
-RequiredError.prototype.message = "Value is required";

package/error/ResponseError.js

@@ -6,4 +6,3 @@ export class ResponseError extends BaseError {
     }
 }
 ResponseError.prototype.name = "ResponseError";
-ResponseError.prototype.message = "Invalid response";

package/error/UnexpectedError.js

@@ -6,4 +6,3 @@ export class UnexpectedError extends BaseError {
     }
 }
 UnexpectedError.prototype.name = "UnexpectedError";
-UnexpectedError.prototype.message = "Unexpected error";

package/error/UnimplementedError.js

@@ -6,4 +6,3 @@ export class UnimplementedError extends BaseError {
     }
 }
 UnimplementedError.prototype.name = "UnimplementedError";
-UnimplementedError.prototype.message = "Not implemented";

package/error/ValueError.js

@@ -6,4 +6,3 @@ export class ValueError extends BaseError {
     }
 }
 ValueError.prototype.name = "ValueError";
-ValueError.prototype.message = "Invalid value";

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.143.0",
+	"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/array.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /**
  * Mutable array: an array that can be changed.
  * - Consistency with `MutableObject<T>` and `ImmutableArray<T>`

package/util/async.d.ts

@@ -1,6 +1,5 @@
 import type { ImmutableArray } from "./array.js";
-import type { ValueCallback } from "./callback.js";
-import type { Report } from "./error.js";
+import type { ErrorCallback, ValueCallback } from "./callback.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export declare function isAsync<T>(value: PromiseLike<T> | T): value is PromiseLike<T>;
 /** Is a value a synchronous value. */
@@ -39,14 +38,14 @@ export declare abstract class AbstractPromise<T> extends Promise<T> {
     /** Resolve this promise with a value. */
     protected readonly _resolve: ValueCallback<T>;
     /** Reject this promise with a reason. */
-    protected readonly _reject: Report;
+    protected readonly _reject: ErrorCallback;
     constructor();
 }
 /** Deferred allows you to access the internal resolve/reject callbacks of a `Promise` */
 export type Deferred<T> = {
     promise: Promise<T>;
     resolve: ValueCallback<T>;
-    reject: Report;
+    reject: ErrorCallback;
 };
 /**
  * Get a deferred to access the `resolve()` and `reject()` functions of a promise.

package/util/boolean.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Is a value a boolean? */
 export declare function isBoolean(value: unknown): value is boolean;
 /** Is a value true? */

package/util/bytes.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Types that can be converted to a `Uint8Array` byte sequence. */
 export type PossibleBytes = Uint8Array | ArrayBuffer | string;
 /** Assert that an unknown value is a `Uint8Array` byte sequence. */

package/util/callback.d.ts

@@ -11,6 +11,8 @@ export type AsyncValueCallback<T = void> = (value: T) => void | PromiseLike<void
 export type ValuesCallback<T extends Arguments = []> = (...values: T) => void;
 /** Callback function that receives multiple values and possibly returns a promise that must be handled. */
 export type AsyncValuesCallback<T extends Arguments = []> = (...values: T) => void | PromiseLike<void>;
+/** Callback function that receives an error. */
+export type ErrorCallback = (reason: unknown) => void;
 /** Safely call a callback function (possibly with a value). */
 export declare function call<A extends Arguments = []>(callback: (...v: A) => unknown, ...values: A): void;
 /** Return a callback function that safely calls a callback function (possibly with a value). */

package/util/color.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 export declare const HEX3_REGEXP: RegExp;
 export declare const HEX6_REGEXP: RegExp;
 /** Things that can be converted to a `Color` instance. */

package/util/data.d.ts

@@ -1,6 +1,6 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
 import type { EntryObject } from "./entry.js";
+import type { AnyCaller } from "./function.js";
 import type { DeepPartial } from "./object.js";
 /** Data object. */
 export type Data = {

package/util/date.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Values that can be converted to dates. */
 export type PossibleDate = "now" | "today" | "tomorrow" | "yesterday" | Date | number | string;
 /**

package/util/dictionary.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Readonly dictionary object. */
 export type ImmutableDictionary<T = unknown> = {
     readonly [K in string]: T;

package/util/entity.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 import type { Optional } from "./optional.js";
 /** Entity strings combine a type and ID, e.g. `challenge:a1b2c3` */
 export type Entity<T extends string = string> = `${T}:${string}`;

package/util/equal.d.ts

@@ -1,6 +1,6 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
 import type { Match } from "./filter.js";
+import type { AnyCaller } from "./function.js";
 import type { ImmutableMap } from "./map.js";
 import type { ImmutableObject } from "./object.js";
 /** Assert two values are equal. */

package/util/error.d.ts

@@ -1,5 +1,3 @@
-/** Callback function that reports an error. */
-export type Report = (reason: unknown) => void;
 /** Log an error to the console. */
 export declare function logError(reason: unknown): void;
 /** Is an unknown value an `Error` instance? */

package/util/error.js

@@ -4,5 +4,5 @@ export function logError(reason) {
 }
 /** Is an unknown value an `Error` instance? */
 export function isError(v) {
-    return v instanceof Error;
+    return typeof Error.isError === "function" ? Error.isError(v) : v instanceof Error;
 }

package/util/file.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** List of file types in `extension: mime` format. */
 export type FileTypes = {
     [extension: string]: string;

package/util/function.d.ts

@@ -1,7 +1,10 @@
+import type { AnyConstructor } from "./class.js";
 /** Unknown function. */
 export type UnknownFunction = (...args: unknown[]) => unknown;
 /** Any function (purposefully as wide as possible for use with `extends X` or `is X` statements). */
 export type AnyFunction = (...args: any) => any;
+/** Any calling function or constructor, usually referring to something that can call in the current scope that can appear in a stack trace. */
+export type AnyCaller = AnyFunction | AnyConstructor;
 /** Is a value a function? */
 export declare function isFunction(value: unknown): value is AnyFunction;
 /** Assert that a value is a function. */

package/util/http.d.ts

@@ -1,6 +1,6 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
+import type { AnyCaller } from "./function.js";
 /** A handler function takes a `Request` and returns a `Response` (possibly asynchronously). */
 export type RequestHandler = (request: Request) => Response | Promise<Response>;
 export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
@@ -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";

package/util/jwt.d.ts

@@ -1,6 +1,6 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import { type PossibleBytes } from "./bytes.js";
 import type { Data } from "./data.js";
+import type { AnyCaller } from "./function.js";
 /**
  * Encode a JWT and return the string token.
  * - Currently only supports HMAC SHA-512 signing.

package/util/link.d.ts

@@ -1,5 +1,5 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
+import type { AnyCaller } from "./function.js";
 import type { Optional } from "./optional.js";
 import type { Path } from "./path.js";
 import { type PossibleURL } from "./url.js";

package/util/map.d.ts

@@ -1,5 +1,5 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { Entry } from "./entry.js";
+import type { AnyCaller } from "./function.js";
 /** `Map` that cannot be changed. */
 export type ImmutableMap<K = unknown, T = unknown> = ReadonlyMap<K, T>;
 /** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */

package/util/null.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Function that always returns null. */
 export declare function getNull(): null;
 /** Nullable is the value or `null` */

package/util/number.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Values that can be converted to a number. */
 export type PossibleNumber = number | string | Date;
 /** Is a value a finite number? */

package/util/optional.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Optional is the value or `null` or `undefined` (synonym for `Nullish`). */
 export type Optional<T> = T | null | undefined;
 /** Get a required value. */

package/util/path.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 import { type Optional } from "./optional.js";
 /** Absolute path string starts with `/` slash. */
 export type AbsolutePath = `/` | `/${string}`;

package/util/sequence.d.ts

@@ -1,6 +1,6 @@
 import type { AsyncValueCallback, ValueCallback } from "./callback.js";
+import type { ErrorCallback } from "./callback.js";
 import { STOP } from "./constants.js";
-import type { Report } from "./error.js";
 import type { Stop } from "./start.js";
 /**
  * Is a value an async iterable object?
@@ -15,4 +15,4 @@ export declare function repeatDelay(ms: number): AsyncIterable<number>;
 /** Dispatch items in a sequence to a (possibly async) callback. */
 export declare function callSequence<T>(sequence: AsyncIterable<T>, callback: AsyncValueCallback<T>): AsyncIterable<T>;
 /** Pull values from a sequence until the returned function is called. */
-export declare function runSequence<T>(sequence: AsyncIterable<T>, onNext?: ValueCallback<T>, onError?: Report): Stop;
+export declare function runSequence<T>(sequence: AsyncIterable<T>, onNext?: ValueCallback<T>, onError?: ErrorCallback): Stop;

package/util/set.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** `Set` that cannot be changed. */
 export type ImmutableSet<T = unknown> = ReadonlySet<T>;
 /** `Set` that can be changed. */

package/util/source.d.ts

@@ -1,5 +1,5 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { Class } from "./class.js";
+import type { AnyCaller } from "./function.js";
 /** Something that has a source of a specified type. */
 export interface Sourceable<T> {
     readonly source: T;

package/util/string.d.ts

@@ -1,5 +1,5 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
+import type { AnyCaller } from "./function.js";
 /**
  * Type that never matches the `string` type.
  * - `string` itself is iterable (iterating over its individual characters) and implements `Iterable<string>`

package/util/template.d.ts

@@ -1,6 +1,6 @@
-import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
 import { type ImmutableDictionary } from "./dictionary.js";
+import type { AnyCaller } from "./function.js";
 import type { NotString } from "./string.js";
 /** Dictionary of named template values in `{ myPlaceholder: "value" }` format. */
 export type TemplateDictionary = ImmutableDictionary<string>;

package/util/time.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Class representing a time in the day in 24 hour format in the user's current locale. */
 export declare class Time {
     /** Make a new `Time` instance from a time string. */

package/util/undefined.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 /** Function that always returns undefined. */
 export declare function getUndefined(): undefined;
 /** Is a value undefined? */

package/util/url.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCaller } from "../error/BaseError.js";
+import type { AnyCaller } from "./function.js";
 import { type Optional } from "./optional.js";
 /** Values that can be converted to a URL instance. */
 export type PossibleURL = string | URL;

package/util/validate.d.ts

@@ -1,8 +1,9 @@
-import type { AnyCaller, BaseError, BaseErrorOptions } from "../error/BaseError.js";
+import type { BaseError, BaseErrorOptions } from "../error/BaseError.js";
 import type { ImmutableArray, PossibleArray } from "./array.js";
 import type { Constructor } from "./class.js";
 import type { Data } from "./data.js";
 import type { ImmutableDictionary } from "./dictionary.js";
+import type { AnyCaller } from "./function.js";
 import type { DeepPartial } from "./object.js";
 /** Object that can validate an unknown value with its `validate()` method. */
 export interface Validator<T> {