API Reference

Functions

Export	Import	Description
expectStatus	expect-status	Default instance — validate status, narrow types, dispatch errors
createExpectStatus	expect-status	Factory — create a configured instance with defaults, hooks, and adapter
fetchExpect	expect-status/fetch	Native fetch wrapper — fetches, parses JSON, validates status
defaultExtractMessage	expect-status	Built-in message extractor (tries message, detail, error, etc.)
chainExtractors	expect-status	Compose multiple extractors into one — first non-undefined wins

expectStatus signature

expectStatus(successStatus, response, dispatch?)

Parameter	Type	Description
successStatus	number | string | Array	Which status(es) count as success — see Status Reference
response	R | PromiseLike<R>	Response object or promise. Must have status and body fields
dispatch	object (optional)	Per-call handlers, messages, and options — see below

Per-call dispatch options

Key	Type	Description
[status]	string	Message — throws ExpectStatusError with this message
[status]	(body) => T	Handler — receives typed body, can return or throw
[range]	string | Function	Range key ('4xx', '5xx') — catches entire HTTP class
[group]	string | Function	Custom group key ('auth') — catches group members
throws	false	Return SafeResult<T> instead of throwing
exhaustive	true	Type error if any error status is uncovered
transform	(body) => T	Reshape the success body before returning
recover	(error) => T	Catch-all — return a fallback value instead of throwing
onError	(err, res) => void	Observability hook — fires before throwing (shadows instance)
onSuccess	(res) => void	Observability hook — fires on success (shadows instance)

createExpectStatus options

Option	Type	Default	Description
adapter	(res) => { status, body }	—	Normalize non-standard response shapes (Axios, custom envelopes)
defaults	{ [key]: string | Function }	{}	Instance-wide flat dispatch entries — shadowed by per-call
groups	{ [name]: number[] }	{}	Custom named status groups (auth: [401, 403])
errorFactory	(msg, res) => Error	ExpectStatusError	Custom error class or factory
extractMessage	(body) => string?	defaultExtractMessage	Pull error message from response body
fallbackMessage	string	'Request failed...'	Last-resort message when nothing else matches
onError	(err, res) => void	—	Instance observability hook for errors
onSuccess	(res) => void	—	Instance observability hook for success
statusField	string	'status'	Custom field name for status discriminator
bodyField	string	'body'	Custom field name for response body

When adapter is provided, statusField and bodyField are ignored.

fetchExpect options

Option	Type	Description
init	RequestInit	Passed through to fetch (method, headers, body, etc.)
[status]	string | Function	Flat dispatch — same as expectStatus
errorFactory	(msg, res) => Error	Custom error factory
extractMessage	(body) => string?	Custom message extractor
fallbackMessage	string	Fallback message

Return types

Scenario	Return type
Default	Promise<SuccessBody> — typed body of the matching branch
Handler returns T	Promise<SuccessBody | T> — widened union
throws: false	Promise<SafeResult<SuccessBody>>
recover returns T	Promise<SuccessBody | T>
transform returns T	Promise<T>

Built-in extractors

Export	What it extracts
messageField	body.message
problemDetail	body.detail (RFC 7807)
stringBody	The body itself if it’s a string
arrayErrors	body.errors[0] or body.errors.join()
springError	body.error (Spring Boot format)

Compose them with chainExtractors — first non-undefined result wins:

import { chainExtractors, problemDetail, messageField, stringBody } from 'expect-status'

const extractMessage = chainExtractors(problemDetail, messageField, stringBody)

Error class

import { ExpectStatusError } from 'expect-status'

// Properties
err.message   // string — extracted or fallback message
err.status    // number — the HTTP status code
err.body      // unknown — the raw response body

Exported types

Type	Description
SafeResult<T>	{ ok: true; data: T } | { ok: false; error: Error; status: number; body: unknown }
StatusResponse	Base type for status-discriminated unions
StatusRange	'1xx' | '2xx' | '3xx' | '4xx' | '5xx'
StatusGroup	'success' | 'error'
StatusSpecifier	StatusRange | StatusGroup
NegatedSpecifier	`!${StatusSpecifier}`
StatusArg	Union of all valid first-argument forms
ResolveSuccessBody<R, S>	Extracts the body type for a given status from a response union
ResolveErrorStatus<R, S>	Extracts the error status codes not covered by S
StatusOf<R>	All status codes in a response union
BodyOf<R, S>	Body type for a specific status
ExpectStatusOptions	Type for createExpectStatus options
ExpectStatusFn	Type for the returned expectStatus function
ExpectStatusDispatch	Type for per-call dispatch object
ExpectStatusDefaults	Type for instance defaults
ExhaustiveCheck	Conditional type — boolean when covered, error when not
Extractor	(body: unknown) => string | undefined