@rtorcato/js-common / fetch
fetch
Classes
HttpError
Defined in: fetch/index.ts:13
Thrown by the fetch helpers when the response status is not 2xx.
Example
try {
await getJson('https://api.example.com/missing')
} catch (e) {
if (e instanceof HttpError) e.status // 404
}
Extends
Error
Constructors
Constructor
new HttpError(
status,statusText,url,body?):HttpError
Defined in: fetch/index.ts:29
Parameters
status
number
statusText
string
url
string
body?
string
Returns
Overrides
Error.constructor
Properties
status
readonlystatus:number
Defined in: fetch/index.ts:15
The HTTP status code, e.g. 404.
statusText
readonlystatusText:string
Defined in: fetch/index.ts:17
The HTTP status text, e.g. 'Not Found'.
url
readonlyurl:string
Defined in: fetch/index.ts:22
The response URL as received. Sensitive: it can carry credentials in the query string or
userinfo, so don't log it. message uses a redacted form instead.
body
readonlybody:string|undefined
Defined in: fetch/index.ts:27
The response body as text, truncated to the first 4 KB, or undefined when it could not be
read.
Functions
fetchWithTimeout()
fetchWithTimeout(
url,options?,timeout?):Promise<unknown>
Defined in: fetch/index.ts:95
Fetches a resource with a timeout.
Example
await fetchWithTimeout('https://api.example.com/health') // { status: 'ok' }
await fetchWithTimeout('https://slow.example.com', {}, 500)
// rejects with a TimeoutError DOMException after 500ms (covers the body read too)
const controller = new AbortController()
await fetchWithTimeout('https://api.example.com', { signal: controller.signal })
// controller.abort() rejects with AbortError
Parameters
url
string
The URL to fetch.
options?
RequestInit = {}
Fetch options. A caller signal is honoured alongside the timeout.
timeout?
number = 8000
Timeout in milliseconds (default: 8000).
Returns
Promise<unknown>
The parsed JSON response.
Throws
When the response status is not 2xx.
Throws
When a 2xx body is empty (e.g. 204) or is not valid JSON.
postJson()
postJson<
T,R>(url,body,options?):Promise<R>
Defined in: fetch/index.ts:127
Sends a POST request with a JSON body.
Example
const user = await postJson<{ name: string }, { id: number }>(
'https://api.example.com/users',
{ name: 'Ada' }
)
user.id // 42
Type Parameters
T
T = unknown
R
R = unknown
Parameters
url
string
The URL to post to.
body
T
The body to send.
options?
RequestInit = {}
Additional fetch options. method defaults to POST; pass e.g. 'PUT' or
'PATCH' to override it. Caller headers are merged; Content-Type defaults to
application/json unless the caller sets it.
Returns
Promise<R>
The parsed JSON response.
Throws
When the response status is not 2xx.
Throws
When a 2xx body is empty (e.g. 204) or is not valid JSON.
getJson()
getJson<
T>(url,options?):Promise<T>
Defined in: fetch/index.ts:158
Sends a GET request and returns JSON.
Example
const user = await getJson<{ id: number }>('https://api.example.com/users/42')
user.id // 42
Type Parameters
T
T = unknown
Parameters
url
string
The URL to fetch.
options?
RequestInit = {}
Additional fetch options.
Returns
Promise<T>
The parsed JSON response.
Throws
When the response status is not 2xx.
Throws
When a 2xx body is empty (e.g. 204) or is not valid JSON.
fetchText()
fetchText(
url,options?):Promise<string>
Defined in: fetch/index.ts:170
Fetches a resource and returns the response as text.
Parameters
url
string
The URL to fetch.
options?
RequestInit = {}
Fetch options.
Returns
Promise<string>
The response as text.
Throws
When the response status is not 2xx.
handleApiError()
handleApiError<
T>(promise,fallback?):Promise<T>
Defined in: fetch/index.ts:181
Handles fetch errors and returns a fallback value or throws.
Type Parameters
T
T
Parameters
promise
Promise<T>
The fetch promise.
fallback?
T
The fallback value to return on error.
Returns
Promise<T>
The resolved value or the fallback.