shelving/util/http.d.ts

Toolkit for using data in JavaScript.

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>;
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>;
/**
 * Get the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
 *
 * @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 getRequestContent(message: Request, caller?: AnyCaller): Promise<unknown>;
/**
 * Get the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
 *
 * @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>;
/**
 * 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;