shelving 1.236.0 → 1.236.2

package/util/function.d.ts

@@ -1,23 +1,78 @@
 import type { AnyConstructor } from "./class.js";
-/** Readonly unknown array that is being used as a set of arguments to a function. */
+/**
+ * Readonly unknown array that is being used as a set of arguments to a function.
+ *
+ * @see https://dhoulb.github.io/shelving/util/function/Arguments
+ */
 export type Arguments = readonly unknown[];
-/** Unknown function. */
+/**
+ * Unknown function.
+ *
+ * @see https://dhoulb.github.io/shelving/util/function/UnknownFunction
+ */
 export type UnknownFunction = (...args: unknown[]) => unknown;
-/** Any function (purposefully as wide as possible for use with `extends X` or `is X` statements). */
+/**
+ * Any function (purposefully as wide as possible for use with `extends X` or `is X` statements).
+ *
+ * @see https://dhoulb.github.io/shelving/util/function/AnyFunction
+ */
 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. */
+/**
+ * Any calling function or constructor, usually referring to something that can call in the current scope that can appear in a stack trace.
+ *
+ * @see https://dhoulb.github.io/shelving/util/function/AnyCaller
+ */
 export type AnyCaller = AnyFunction | AnyConstructor;
-/** A callback is a function that is called when something happens, optionally with multiple values. */
+/**
+ * A callback is a function that is called when something happens, optionally with multiple values.
+ *
+ * @see https://dhoulb.github.io/shelving/util/function/Callback
+ */
 export type Callback<A extends Arguments = []> = (...args: A) => void;
-/** A callback is a function that is called when something happens with a value. */
+/**
+ * A callback is a function that is called when something happens with a value.
+ *
+ * @see https://dhoulb.github.io/shelving/util/function/ValueCallback
+ */
 export type ValueCallback<T> = (value: T) => void;
-/** Function that is called when something errors. */
+/**
+ * Function that is called when something errors.
+ *
+ * @see https://dhoulb.github.io/shelving/util/function/ErrorCallback
+ */
 export type ErrorCallback = (reason: unknown) => void;
-/** Is a value a function? */
+/**
+ * Is a value a function?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a function, narrowing its type to `AnyFunction`.
+ * @example isFunction(() => {}) // true
+ * @see https://dhoulb.github.io/shelving/util/function/isFunction
+ */
 export declare function isFunction(value: unknown): value is AnyFunction;
-/** Assert that a value is a function. */
+/**
+ * Assert that a value is a function.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a function.
+ * @see https://dhoulb.github.io/shelving/util/function/assertFunction
+ */
 export declare function assertFunction(value: unknown): asserts value is AnyFunction;
-/** Function that just passes through the first argument. */
+/**
+ * Function that just passes through the first argument.
+ *
+ * @param value The value to return.
+ * @returns The exact `value` it was given, unchanged.
+ * @example PASSTHROUGH(123) // 123
+ * @see https://dhoulb.github.io/shelving/util/function/PASSTHROUGH
+ */
 export declare function PASSTHROUGH<T>(value: T): T;
-/** Function that does nothing with its arguments and always returns void. */
+/**
+ * Function that does nothing with its arguments and always returns void.
+ *
+ * @param _unused Zero or more arguments, all ignored.
+ * @returns Always `undefined`.
+ * @example BLACKHOLE(1, 2, 3) // undefined
+ * @see https://dhoulb.github.io/shelving/util/function/BLACKHOLE
+ */
 export declare function BLACKHOLE(..._unused: Arguments): void | undefined;

package/util/function.js

@@ -1,18 +1,45 @@
 import { RequiredError } from "../error/RequiredError.js";
-/** Is a value a function? */
+/**
+ * Is a value a function?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a function, narrowing its type to `AnyFunction`.
+ * @example isFunction(() => {}) // true
+ * @see https://dhoulb.github.io/shelving/util/function/isFunction
+ */
 export function isFunction(value) {
     return typeof value === "function";
 }
-/** Assert that a value is a function. */
+/**
+ * Assert that a value is a function.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a function.
+ * @see https://dhoulb.github.io/shelving/util/function/assertFunction
+ */
 export function assertFunction(value) {
     if (typeof value !== "function")
         throw new RequiredError("Must be function", { received: value, caller: assertFunction });
 }
-/** Function that just passes through the first argument. */
+/**
+ * Function that just passes through the first argument.
+ *
+ * @param value The value to return.
+ * @returns The exact `value` it was given, unchanged.
+ * @example PASSTHROUGH(123) // 123
+ * @see https://dhoulb.github.io/shelving/util/function/PASSTHROUGH
+ */
 export function PASSTHROUGH(value) {
     return value;
 }
-/** Function that does nothing with its arguments and always returns void. */
+/**
+ * Function that does nothing with its arguments and always returns void.
+ *
+ * @param _unused Zero or more arguments, all ignored.
+ * @returns Always `undefined`.
+ * @example BLACKHOLE(1, 2, 3) // undefined
+ * @see https://dhoulb.github.io/shelving/util/function/BLACKHOLE
+ */
 export function BLACKHOLE(..._unused) {
     return undefined;
 }

package/util/geo.d.ts

@@ -1,5 +1,10 @@
 import type { AnyCaller } from "./function.js";
-/** List of countries by two-letter ISO code. */
+/**
+ * List of countries by two-letter ISO 3166-1 alpha-2 code.
+ * - Keys are uppercase two-letter codes; values are the full English country name.
+ *
+ * @see https://dhoulb.github.io/shelving/util/geo/COUNTRIES
+ */
 export declare const COUNTRIES: {
     readonly AF: "Afghanistan";
     readonly AX: "Aland Islands";
@@ -248,17 +253,55 @@ export declare const COUNTRIES: {
     readonly ZM: "Zambia";
     readonly ZW: "Zimbabwe";
 };
-/** Country code string. */
+/**
+ * Two-letter ISO 3166-1 alpha-2 country code string (a key of `COUNTRIES`).
+ *
+ * @see https://dhoulb.github.io/shelving/util/geo/Country
+ */
 export type Country = keyof typeof COUNTRIES;
-/** Things that can possibly be a country. */
+/**
+ * A value that can possibly be resolved to a `Country` — either a country code or the literal `"detect"`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/geo/PossibleCountry
+ */
 export type PossibleCountry = Country | "detect";
-/** Parse a country string, or detect a browser country from `navigator.language`. */
+/**
+ * Parse a country string, or detect a browser country from `navigator.language`.
+ * - When `value` is `"detect"`, reads the last two characters of `navigator.language` (if available).
+ * - Matching is case-insensitive; the value is uppercased before lookup.
+ *
+ * @param value The country code to parse, or `"detect"` to read it from the browser. Defaults to `"detect"`.
+ * @returns The matching `Country` code, or `undefined` if it could not be resolved.
+ * @example getCountry("gb") // "GB"
+ * @see https://dhoulb.github.io/shelving/util/geo/getCountry
+ */
 export declare function getCountry(value?: unknown): Country | undefined;
-/** Parse a country string, or detect a browser country from `navigator.language`, or throw `RequiredError` */
+/**
+ * Parse a country string, or detect a browser country from `navigator.language`, or throw `RequiredError`.
+ *
+ * @param value The country code to parse, or `"detect"` to read it from the browser.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The matching `Country` code.
+ * @throws RequiredError If a country could not be resolved.
+ * @example requireCountry("gb") // "GB"
+ * @see https://dhoulb.github.io/shelving/util/geo/requireCountry
+ */
 export declare function requireCountry(value?: unknown, caller?: AnyCaller): Country;
-/** Format a country code into its full country name. */
+/**
+ * Format a country code into its full country name.
+ * - Matching is case-insensitive; unknown codes are returned unchanged.
+ *
+ * @param country The country code to format.
+ * @returns The full English country name, or the input unchanged if it is not a known code.
+ * @example formatCountry("GB") // "United Kingdom"
+ * @see https://dhoulb.github.io/shelving/util/geo/formatCountry
+ */
 export declare function formatCountry(country: string): string;
-/** Valid shape for physical address data. */
+/**
+ * Valid shape for physical address data.
+ *
+ * @see https://dhoulb.github.io/shelving/util/geo/AddressData
+ */
 export type AddressData = {
     readonly address1: string;
     readonly address2: string;
@@ -267,5 +310,14 @@ export type AddressData = {
     readonly postcode: string;
     readonly country: Country;
 };
-/** Format address data into a single multiline string. */
+/**
+ * Format address data into a single multiline string.
+ * - Each field is placed on its own line; an empty `address2` is omitted.
+ * - The country code is expanded to its full name via `formatCountry`.
+ *
+ * @param address The address data to format.
+ * @returns A newline-separated address string.
+ * @example formatAddress({ address1: "1 High St", address2: "", city: "London", state: "", postcode: "SW1", country: "GB" })
+ * @see https://dhoulb.github.io/shelving/util/geo/formatAddress
+ */
 export declare function formatAddress({ address1, address2, city, state, postcode, country }: AddressData): string;

package/util/geo.js

@@ -1,6 +1,11 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { isProp } from "./object.js";
-/** List of countries by two-letter ISO code. */
+/**
+ * List of countries by two-letter ISO 3166-1 alpha-2 code.
+ * - Keys are uppercase two-letter codes; values are the full English country name.
+ *
+ * @see https://dhoulb.github.io/shelving/util/geo/COUNTRIES
+ */
 export const COUNTRIES = {
     AF: "Afghanistan",
     AX: "Aland Islands",
@@ -249,7 +254,16 @@ export const COUNTRIES = {
     ZM: "Zambia",
     ZW: "Zimbabwe",
 };
-/** Parse a country string, or detect a browser country from `navigator.language`. */
+/**
+ * Parse a country string, or detect a browser country from `navigator.language`.
+ * - When `value` is `"detect"`, reads the last two characters of `navigator.language` (if available).
+ * - Matching is case-insensitive; the value is uppercased before lookup.
+ *
+ * @param value The country code to parse, or `"detect"` to read it from the browser. Defaults to `"detect"`.
+ * @returns The matching `Country` code, or `undefined` if it could not be resolved.
+ * @example getCountry("gb") // "GB"
+ * @see https://dhoulb.github.io/shelving/util/geo/getCountry
+ */
 export function getCountry(value = "detect") {
     if (value === "detect") {
         if (typeof navigator === "object") {
@@ -264,19 +278,45 @@ export function getCountry(value = "detect") {
             return code;
     }
 }
-/** Parse a country string, or detect a browser country from `navigator.language`, or throw `RequiredError` */
+/**
+ * Parse a country string, or detect a browser country from `navigator.language`, or throw `RequiredError`.
+ *
+ * @param value The country code to parse, or `"detect"` to read it from the browser.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The matching `Country` code.
+ * @throws RequiredError If a country could not be resolved.
+ * @example requireCountry("gb") // "GB"
+ * @see https://dhoulb.github.io/shelving/util/geo/requireCountry
+ */
 export function requireCountry(value, caller = requireCountry) {
     const country = getCountry(value);
     if (!country)
         throw new RequiredError("Must be country", { received: value, caller });
     return country;
 }
-/** Format a country code into its full country name. */
+/**
+ * Format a country code into its full country name.
+ * - Matching is case-insensitive; unknown codes are returned unchanged.
+ *
+ * @param country The country code to format.
+ * @returns The full English country name, or the input unchanged if it is not a known code.
+ * @example formatCountry("GB") // "United Kingdom"
+ * @see https://dhoulb.github.io/shelving/util/geo/formatCountry
+ */
 export function formatCountry(country) {
     const code = country.toUpperCase();
     return isProp(COUNTRIES, code) ? COUNTRIES[code] : country;
 }
-/** Format address data into a single multiline string. */
+/**
+ * Format address data into a single multiline string.
+ * - Each field is placed on its own line; an empty `address2` is omitted.
+ * - The country code is expanded to its full name via `formatCountry`.
+ *
+ * @param address The address data to format.
+ * @returns A newline-separated address string.
+ * @example formatAddress({ address1: "1 High St", address2: "", city: "London", state: "", postcode: "SW1", country: "GB" })
+ * @see https://dhoulb.github.io/shelving/util/geo/formatAddress
+ */
 export function formatAddress({ address1, address2, city, state, postcode, country }) {
     return `${address1}\n${address2 ? `${address2}\n` : ""}${city}\n${state}\n${postcode}\n${formatCountry(country)}`;
 }

package/util/hash.d.ts

@@ -1,4 +1,23 @@
-/** Hash a string into an idempotent number. */
+/**
+ * Hash a string into an idempotent number.
+ * - Sums the char codes of every character, so the same string always produces the same number.
+ * - Not cryptographically secure — intended for cheap, stable bucketing.
+ *
+ * @param str The string to hash.
+ * @returns A non-negative number derived from the string's characters.
+ * @example hashString("abc") // 294
+ * @see https://dhoulb.github.io/shelving/util/hash/hashString
+ */
 export declare function hashString(str: string): number;
-/** Hash a string into an idempotent number between two values. */
+/**
+ * Hash a string into an idempotent number wrapped between two values.
+ * - Useful for deterministically mapping a string into a fixed range, e.g. a colour or bucket index.
+ *
+ * @param str The string to hash.
+ * @param min The inclusive lower bound of the output range. Defaults to `0`.
+ * @param max The exclusive upper bound of the output range. Defaults to `256`.
+ * @returns A number in the range `min` to `max` derived from the string.
+ * @example hashStringBetween("abc", 0, 10) // 4
+ * @see https://dhoulb.github.io/shelving/util/hash/hashStringBetween
+ */
 export declare function hashStringBetween(str: string, min?: number, max?: number): number;

package/util/hash.js

@@ -1,12 +1,31 @@
 import { wrapNumber } from "./number.js";
-/** Hash a string into an idempotent number. */
+/**
+ * Hash a string into an idempotent number.
+ * - Sums the char codes of every character, so the same string always produces the same number.
+ * - Not cryptographically secure — intended for cheap, stable bucketing.
+ *
+ * @param str The string to hash.
+ * @returns A non-negative number derived from the string's characters.
+ * @example hashString("abc") // 294
+ * @see https://dhoulb.github.io/shelving/util/hash/hashString
+ */
 export function hashString(str) {
     let hash = 0;
     for (let i = 0; i < str.length; i++)
         hash += str.charCodeAt(i);
     return hash;
 }
-/** Hash a string into an idempotent number between two values. */
+/**
+ * Hash a string into an idempotent number wrapped between two values.
+ * - Useful for deterministically mapping a string into a fixed range, e.g. a colour or bucket index.
+ *
+ * @param str The string to hash.
+ * @param min The inclusive lower bound of the output range. Defaults to `0`.
+ * @param max The exclusive upper bound of the output range. Defaults to `256`.
+ * @returns A number in the range `min` to `max` derived from the string.
+ * @example hashStringBetween("abc", 0, 10) // 4
+ * @see https://dhoulb.github.io/shelving/util/hash/hashStringBetween
+ */
 export function hashStringBetween(str, min = 0, max = 256) {
     return wrapNumber(hashString(str), min, max);
 }

package/util/http.d.ts

@@ -4,62 +4,107 @@ import type { AnyCaller, Arguments } from "./function.js";
 import { type Nullish } from "./null.js";
 import { type PossibleURIParams } from "./uri.js";
 import { type PossibleURL } from "./url.js";
-/** A handler function takes a `Request` and optional extra arguments and returns a `Response` (possibly asynchronously). */
+/**
+ * A handler function takes a `Request` and optional extra arguments and returns a `Response` (possibly asynchronously).
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/RequestHandler
+ */
 export type RequestHandler<A extends Arguments = []> = (request: Request, ...args: A) => Response | Promise<Response>;
-/** An optional request handler that may return `undefined` to indicate no match. */
+/**
+ * An optional request handler that may return `undefined` to indicate no match.
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/OptionalRequestHandler
+ */
 export type OptionalRequestHandler<A extends Arguments = []> = (request: Request, ...args: A) => Response | Promise<Response> | undefined;
-/** A list of optional request handlers. */
+/**
+ * A list of optional request handlers.
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/OptionalRequestHandlers
+ */
 export type OptionalRequestHandlers<A extends Arguments = []> = Iterable<OptionalRequestHandler<A>>;
 /**
  * Parse the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
+ * @param request The `Request` whose body to parse.
+ * @param caller Identity of the calling function for error attribution.
  * @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.
+ * @throws {RequestError} If the content is not `text/plain`, or `application/json` with valid JSON.
+ * @example const body = await parseRequestBody(request);
+ * @see https://dhoulb.github.io/shelving/util/http/parseRequestBody
  */
 export declare function parseRequestBody(request: Request, caller?: AnyCaller): Promise<unknown>;
 /**
  * Parse JSON from an HTTP `Request`, or return `undefined` when the request has no body.
  *
- * @throws RequestError If the request body is not valid JSON.
+ * @param request The `Request` whose JSON body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed JSON value, or `undefined` if the body is empty.
+ * @throws {RequestError} If the request body is not valid JSON.
+ * @example const data = await parseRequestJSON(request);
+ * @see https://dhoulb.github.io/shelving/util/http/parseRequestJSON
  */
 export declare function parseRequestJSON(request: Request, caller?: AnyCaller): Promise<unknown>;
 /**
  * Parse `FormData` from an HTTP `Request`, or return `undefined` when the request has no body.
  *
- * @throws RequestError If the request body is not valid multipart form-data.
+ * @param request The `Request` whose form-data body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed `FormData`.
+ * @throws {RequestError} If the request body is not valid multipart form-data.
+ * @example const form = await parseRequestFormData(request);
+ * @see https://dhoulb.github.io/shelving/util/http/parseRequestFormData
  */
 export declare function parseRequestFormData(request: Request, caller?: AnyCaller): Promise<FormData | undefined>;
 /**
  * Parse the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
+ * @param response The `Response` whose body to parse.
+ * @param caller Identity of the calling function for error attribution.
  * @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 ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
+ * @throws {ResponseError} If the content is not `text/plain` or `application/json` with valid JSON.
+ * @example const body = await parseResponseBody(response);
+ * @see https://dhoulb.github.io/shelving/util/http/parseResponseBody
  */
 export declare function parseResponseBody(response: Response, caller?: AnyCaller): Promise<unknown>;
 /**
  * Parse JSON from an HTTP `Response`, or return `undefined` when the response has no body.
  *
- * @throws ResponseError If the response body is not valid JSON.
+ * @param response The `Response` whose JSON body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed JSON value, or `undefined` if the body is empty.
+ * @throws {ResponseError} If the response body is not valid JSON.
+ * @example const data = await parseResponseJSON(response);
+ * @see https://dhoulb.github.io/shelving/util/http/parseResponseJSON
  */
 export declare function parseResponseJSON(response: Response, caller?: AnyCaller): Promise<unknown>;
 /**
  * Parse `FormData` from an HTTP `Response`, or return `undefined` when the response has no body.
  *
- * @throws ResponseError If the response body is not valid multipart form-data.
+ * @param response The `Response` whose form-data body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed `FormData`.
+ * @throws {ResponseError} If the response body is not valid multipart form-data.
+ * @example const form = await parseResponseFormData(response);
+ * @see https://dhoulb.github.io/shelving/util/http/parseResponseFormData
  */
 export declare function parseResponseFormData(response: Response, caller?: AnyCaller): Promise<FormData>;
 /**
  * Get an HTTP `Response` for an unknown value.
+ * - A `Response` value is returned unchanged.
+ * - `undefined` becomes a `204 No Content` response.
+ * - Anything else becomes a `200` JSON response.
  *
  * @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`
+ * @example getResponse({ name: "abc" }) // 200 JSON Response
+ * @see https://dhoulb.github.io/shelving/util/http/getResponse
  */
 export declare function getResponse(value: unknown): Response;
 /**
@@ -73,28 +118,71 @@ export declare function getResponse(value: unknown): Response;
  * - 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).
+ * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security). Defaults to `false`.
+ * @returns A `Response` with a status code and (optionally) body derived from the error.
+ * @example getErrorResponse("Invalid input") // 422 Response
+ * @see https://dhoulb.github.io/shelving/util/http/getErrorResponse
  */
 export declare function getErrorResponse(reason: unknown, debug?: boolean): Response;
-/** HTTP request methods that have no body. */
+/**
+ * HTTP request methods that have no body.
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/RequestHeadMethod
+ */
 export type RequestHeadMethod = "HEAD" | "GET";
-/** HTTP request methods that have a body. */
+/**
+ * HTTP request methods that have a body.
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/RequestBodyMethod
+ */
 export type RequestBodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
-/** HTTP request methods. */
+/**
+ * HTTP request methods.
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/RequestMethod
+ */
 export type RequestMethod = RequestHeadMethod | RequestBodyMethod;
-/** Check whether an HTTP Request method string is a supported request methods. */
+/**
+ * Is a string a supported HTTP request method?
+ *
+ * @param method The method string to test.
+ * @returns `true` if `method` is a supported `RequestMethod`, narrowing its type.
+ * @example isRequestMethod("GET") // true
+ * @see https://dhoulb.github.io/shelving/util/http/isRequestMethod
+ */
 export declare function isRequestMethod(method: string): method is RequestMethod;
-/** Check whether an HTTP Request method string is a supported request method that never sends a body. */
+/**
+ * Is a string a supported HTTP request method that never sends a body?
+ *
+ * @param method The method string to test.
+ * @returns `true` if `method` is a supported `RequestHeadMethod`, narrowing its type.
+ * @example isRequestHeadMethod("GET") // true
+ * @see https://dhoulb.github.io/shelving/util/http/isRequestHeadMethod
+ */
 export declare function isRequestHeadMethod(method: string): method is RequestHeadMethod;
-/** Params in requests are a dictionary of strings. */
+/**
+ * Params in requests are a dictionary of strings.
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/RequestParams
+ */
 export type RequestParams = ImmutableDictionary<string>;
-/** Configurable options for endpoint requests. */
+/**
+ * Configurable options for endpoint requests.
+ *
+ * @see https://dhoulb.github.io/shelving/util/http/RequestOptions
+ */
 export type RequestOptions = Pick<RequestInit, "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "mode" | "redirect" | "referrer" | "referrerPolicy" | "signal">;
 /**
  * Merge provider-level and call-level request options.
  * - Scalar options from `b` override `a`.
  * - Header dictionaries are merged so call-level headers override default headers by key.
  * - Abort signals are merged, so either abort signal will cancel the request.
+ *
+ * @param a The provider-level (default) request options.
+ * @param b The call-level request options whose values override `a`.
+ * @returns A merged `RequestOptions` with combined headers and abort signals.
+ * @example mergeRequestOptions({ cache: "no-store" }, { mode: "cors" }) // { cache: "no-store", mode: "cors", ... }
+ * @see https://dhoulb.github.io/shelving/util/http/mergeRequestOptions
  */
 export declare function mergeRequestOptions({ headers: aHeaders, signal: aSignal, ...a }?: RequestOptions, { headers: bHeaders, signal: bSignal, ...b }?: RequestOptions): RequestOptions;
 /**
@@ -105,9 +193,11 @@ export declare function mergeRequestOptions({ headers: aHeaders, signal: aSignal
  * @param url The target URL.
  * @param params `?query` params to encode into the URL.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createHeadRequest`).
  * @returns A `Request` with no body content.
  *
  * @example createHeadRequest("POST", "https://api.example.com/items", { name: "abc" })
+ * @see https://dhoulb.github.io/shelving/util/http/createHeadRequest
  */
 export declare function createHeadRequest(method: RequestHeadMethod, url: PossibleURL, params: Nullish<PossibleURIParams>, options?: RequestOptions, caller?: AnyCaller): Request;
 /**
@@ -119,9 +209,11 @@ export declare function createHeadRequest(method: RequestHeadMethod, url: Possib
  * @param url The target URL.
  * @param body The plain-text request body.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createTextRequest`).
  * @returns A `Request` with `text/plain` content type.
  *
  * @example createTextRequest("POST", "https://api.example.com/items", "hello")
+ * @see https://dhoulb.github.io/shelving/util/http/createTextRequest
  */
 export declare function createTextRequest(method: RequestMethod, url: PossibleURL, body: string, options?: RequestOptions, caller?: AnyCaller): Request;
 /**
@@ -133,9 +225,11 @@ export declare function createTextRequest(method: RequestMethod, url: PossibleUR
  * @param url The target URL.
  * @param body The value to JSON-encode.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createJSONRequest`).
  * @returns A `Request` with `application/json` content type.
  *
  * @example createJSONRequest("POST", "https://api.example.com/items", { name: "abc" })
+ * @see https://dhoulb.github.io/shelving/util/http/createJSONRequest
  */
 export declare function createJSONRequest(method: RequestBodyMethod, url: PossibleURL, body: unknown, options?: RequestOptions, caller?: AnyCaller): Request;
 /**
@@ -146,9 +240,11 @@ export declare function createJSONRequest(method: RequestBodyMethod, url: Possib
  * @param url The target URL.
  * @param body The `FormData` payload.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createFormDataRequest`).
  * @returns A `Request` with a multipart body.
  *
  * @example createFormDataRequest("POST", "https://api.example.com/upload", new FormData())
+ * @see https://dhoulb.github.io/shelving/util/http/createFormDataRequest
  */
 export declare function createFormDataRequest(method: RequestBodyMethod, url: PossibleURL, body: FormData, options?: RequestOptions, caller?: AnyCaller): Request;
 /**
@@ -160,11 +256,13 @@ export declare function createFormDataRequest(method: RequestBodyMethod, url: Po
  * @param url The target URL.
  * @param data The data object to serialize as XML.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createXMLRequest`).
  * @returns A `Request` with `application/xml` content type.
  *
  * @throws {RequiredError} If the XML data contains invalid element names or values.
  *
  * @example createXMLRequest("POST", "https://api.example.com/items", { item: { name: "abc" } })
+ * @see https://dhoulb.github.io/shelving/util/http/createXMLRequest
  */
 export declare function createXMLRequest(method: RequestBodyMethod, url: PossibleURL, data: Data, options?: RequestOptions, caller?: AnyCaller): Request;
 /**
@@ -176,10 +274,27 @@ export declare function createXMLRequest(method: RequestBodyMethod, url: Possibl
  * - Expects a fully valid URL (any `{placeholders}` in the URL are not considered).
  * - As per the HTTP spec, `GET` and `HEAD` requests cannot contain a body
  *
- * @returns Request object.
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param payload The body payload, whose type selects the content type.
+ * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createRequest`).
+ * @returns A `Request` with a content type chosen to match `payload`.
  *
  * @throws {RequiredError} if this is a `HEAD` or `GET` request but `body` is not a data object.
+ *
+ * @example createRequest("POST", "https://api.example.com/items", { name: "abc" }) // JSON Request
+ * @see https://dhoulb.github.io/shelving/util/http/createRequest
  */
 export declare function createRequest(method: RequestMethod, url: PossibleURL, payload: unknown, options?: RequestOptions, caller?: AnyCaller): Request;
-/** Assert that the payload for a HEAD or GET method is a data object, null, or undefined. */
+/**
+ * Assert that the payload for a `HEAD` or `GET` method is a data object, `null`, or `undefined`.
+ *
+ * @param payload The payload to assert.
+ * @param method The HTTP method the payload is for (used in the error message).
+ * @param caller Function to attribute a thrown error to (defaults to `assertRequestHeadPayload`).
+ * @throws {RequiredError} If `payload` is not a data object, `null`, or `undefined`.
+ * @example assertRequestHeadPayload({ q: "abc" }, "GET"); // passes
+ * @see https://dhoulb.github.io/shelving/util/http/assertRequestHeadPayload
+ */
 export declare function assertRequestHeadPayload(payload: unknown, method: RequestHeadMethod, caller?: AnyCaller): asserts payload is Nullish<Data>;