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 Data } from "./data.js";
import type { AnyCaller } from "./function.js";
import type { URLString } from "./url.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 undefined If the request method is `GET` or `HEAD` (these request methods have no body).
 * @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(request: 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 undefined If the request status is `204 No Content` (this response has no body).
 * @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(response: 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 string, return a 422 response with the string message, e.g. `"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;
/** HTTP request methods. */
export type RequestMethod = RequestBodyMethod | RequestHeadMethod;
/** HTTP request methods that have no body. */
export type RequestHeadMethod = "HEAD" | "GET";
/** HTTP request methods that have a body. */
export type RequestBodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
/** Configurable options for endpoint. */
export type RequestOptions = Omit<RequestInit, "method" | "body">;
/**
 * Create a `Request` instance for a method/url and payload.
 *
 * - If `{placeholders}` are set in the URL, they are replaced by values from payload (will throw if `payload` is not a data object).
 * - If the method is `HEAD` or `GET`, the payload is sent as `?query` parameters in the URL.
 * - If the method is anything else, the payload is sent in the body (plain text string, `FormData` object, or JSON for any other).
 *
 * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
 * @throws {RequiredError} if `{placeholders}` are set in the URL but `payload` is not a data object.
 */
export declare function getRequest(method: RequestHeadMethod, url: URLString, payload: Data, options?: RequestOptions, caller?: AnyCaller): Request;
export declare function getRequest(method: RequestMethod, url: URLString, payload: unknown, options?: RequestOptions, caller?: AnyCaller): Request;