api-reference.md

API Reference

Everything the package root exports, with a pointer to the page that explains it. Import from @afoures/http-client.

Functions and classes

Export	What it is	See
http_client	Turns a tree of Endpoints into a mirror-shaped object of typed fetch functions. Throws TypeError on an invalid base_url, or on a tree leaf that is not an Endpoint.	HTTP Client
Endpoint	A route plus its serializers and parsers. Throws PathnameError on a malformed pattern. Exposes method, options, context_default, resolve_definition, generate_url, serialize_body, parse_response.	Endpoint Definition
default_retry_condition	The when used when none is given: retries NetworkError, TimeoutError, 408, 429 and every 5xx.	Retry Policy
HttpClientError	Base class of the returned transport errors below. Never returned on its own.	Error Handling
TimeoutError	A total or attempt timeout expired.	Error Handling
AbortedError	The caller's AbortSignal fired.	Error Handling
SerializationError	params, query or body failed validation or serialization, or a param could not produce a pathname.	Error Handling
ParseError	A response body failed decoding or validation, or a parse function threw.	Error Handling
NetworkError	fetch rejected for a reason other than a timeout or abort.	Error Handling
UnexpectedError	User code threw where a value was expected, or a client invariant broke. Extends Error, not HttpClientError.	Error Handling
PathnameError	A pathname pattern is malformed (thrown by the constructor), or a param value cannot produce a pathname (the cause of a SerializationError).	Endpoint Definition
MissingParamsError	Subclass of PathnameError for required params with no value; lists them in missing_params.	Error Handling

Types

Export	What it is	See
HttpClientConfig	The second argument of http_client: base_url, options, context, fetch. Parameterized by the endpoint tree.	Wrapping the Client
ClientContext	The merged, all-optional context shape of an endpoint tree, for constraining a wrapper's type parameter.	Wrapping the Client
$infer	Namespace of helpers deriving Params, Query, Body, Context, Input, Result, Response, Data and Error from an endpoint or a fetch function.	Type Inference
EndpointRoute	The first Endpoint argument: method and pathname.	Endpoint Definition
EndpointDefinition	The second Endpoint argument: params, query, body, responses.	Endpoint Definition
EndpointOptions	The third Endpoint argument: default request options plus context defaults.	Endpoint Definition
ResolvedDefinition	A definition after normalization, as returned by resolve_definition and accepted by the three low-level methods.	Endpoint Definition
AnyEndpoint	An Endpoint with every type parameter widened, for constraints and endpoint-tree types.	HTTP Client
ErrorKind	Union of the kind literals carried by the error classes, one per class name, "HttpClientError" included.	Narrowing on kind
ErrorContext	The shape of every error's context: the failing operation plus optional request, response, timing and input details.	Error Context

Type namespaces

Export	What it holds	See
HTTPFetch	The four response envelopes (SuccessfulResponse, RedirectMessage, ClientErrorResponse, ServerErrorResponse), AnyResponse, ResponseKind, RequestMetadata, ResponseMetadata, TimeoutConfig, and the typed request-input pieces.	Response Parsing
HTTPMethod	Any, plus WithBody (POST, PUT, PATCH, DELETE, QUERY) and WithoutBody (GET).	Endpoint Definition
HTTPStatus	Status-code literal unions per class, the "2xx" / "4xx" / "5xx" wildcard literals, and AnyStatusClass for the three together.	Status Wildcards
Pathname	Relative, WithParams, Validate and Params<pathname>, the params object inferred from a pattern.	Endpoint Definition
Schema	Standard Schema aliases: _<input, output>, Any, Unknown, infer_input, infer_output, input_of, output_of, accepts, produces.	Schema Integration
Serializer	Params, QueryString and Body serializer configs, UrlencodedValue and UrlencodedCompatible.	Serialization
Parser	ResponseBody parser config, AllowedStatus keys and ResponseBodyByStatus.	Response Parsing
RetryPolicy	Configuration, Condition, Attempts, Delay, Recover, Overrides and AttemptError.	Retry Policy

Runtime requirements

Node 20.3 or later (AbortSignal.any), or any runtime with fetch, AbortSignal.any, AbortSignal.timeout and URL.canParse. No runtime dependencies.