Skip to main content

@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​

HttpError

Overrides​

Error.constructor

Properties​

status​

readonly status: number

Defined in: fetch/index.ts:15

The HTTP status code, e.g. 404.

statusText​

readonly statusText: string

Defined in: fetch/index.ts:17

The HTTP status text, e.g. 'Not Found'.

url​

readonly url: 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​

readonly body: 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.