Superutils

Appearance

Variable: fetch ​

const fetch: {<T, TOptions, TAs, TReturn>(url, options): IPromise_Fetch<TReturn>; defaults: FetchOptionsDefault; } & object

Defined in: packages/fetch/src/index.ts:178

A fetch() replacement that simplifies data fetching with automatic JSON parsing, request timeouts, retries, and handy interceptors that also work as transformers. It also includes deferred and throttled request capabilities for complex asynchronous control flows.

Will reject promise if response status code is not 2xx (200 <= status < 300).

Method Specific Functions ​

While fetch() provides access to all HTTP request methods by specifying it in options (eg: { method: 'get' }), for ease of use you can also use the following:

  • fetch.delete(...)
  • fetch.get(...)
  • fetch.head(...)
  • fetch.options(...)
  • fetch.patch(...)
  • fetch.post(...)
  • fetch.put(...)

Deferred variants: To debounce/throttle requests.

  • fetch.delete.deferred(...)
  • fetch.get.deferred(...)
  • fetch.head.deferred(...)
  • fetch.options.deferred(...)
  • fetch.patch.deferred(...)
  • fetch.post.deferred(...)
  • fetch.put.deferred(...)

Type Declaration ​

delete ​

delete: {<T, Options, Result>(url, data?, options?): IPromise_Fetch<Result>; deferred: <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>; }

Make HTTP requests with method DELETE

Executes the HTTP request using the configured client options.

This function is specifically designed for methods that require a request body (e.g., POST, PUT, PATCH), allowing the payload to be passed directly as the second argument.

Type Parameters ​

T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: "delete"; }, Options, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​

url ​

string | URL

data? ​

PostBody | () => ValueOrPromise<PostBody>

options? ​

Options

Returns ​

IPromise_Fetch<Result>

delete.deferred() ​

deferred<ThisArg, DefaultUrl, DefaultData, DefaultOptions, Delay>(deferOptions?, defaultUrl?, defaultData?, defaultOptions?): <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>

Returns a version of the client configured for debounced, throttled, or sequential execution.

This is particularly useful for optimizing high-frequency operations, such as auto-saving forms or managing rapid state updates, by automatically handling request cancellation and execution timing.

Type Parameters ​
ThisArg ​

ThisArg

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

DefaultData extends PostBody | () => ValueOrPromise<PostBody> | undefined

DefaultOptions ​

DefaultOptions extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Delay ​

Delay extends number = number

Parameters ​
deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<T, Options, TReturn>(...args): IPromise_Fetch<TReturn>

Type Parameters ​
T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

TReturn ​

TReturn = GetFetchResult<[{ method: "delete"; }, Options, DefaultOptions, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, Options>

Returns ​

IPromise_Fetch<TReturn>

get ​

get: {<T, TOptions, Result>(url, options?): IPromise_Fetch<Result>; deferred: <T, TOptions, Result>(...args) => IPromise_Fetch<Result>; }

Make HTTP requests with method GET

Type Parameters ​

T ​

T extends unknown = never

TOptions ​

TOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: string; }, TOptions, object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​

url ​

string | URL

options? ​

TOptions

Returns ​

IPromise_Fetch<Result>

get.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultOptions>(deferOptions?, defaultUrl?, defaultOptions?): <T, TOptions, Result>(...args) => IPromise_Fetch<Result>

Make requests with debounce/throttle behavior

Type Parameters ​
ThisArg ​

ThisArg

Delay ​

Delay extends number

DefaultUrl ​

DefaultUrl extends string | URL | undefined = string | URL | undefined

DefaultOptions ​

DefaultOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Parameters ​
deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultOptions? ​

DefaultOptions

Returns ​

<T, TOptions, Result>(...args): IPromise_Fetch<Result>

Type Parameters ​
T ​

T extends unknown = never

TOptions ​

TOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: string; }, TOptions, DefaultOptions, object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​
args ​

...DefaultUrl extends undefined ? [string | URL, TOptions] : [TOptions]

Returns ​

IPromise_Fetch<Result>

head: {<T, TOptions, Result>(url, options?): IPromise_Fetch<Result>; deferred: <T, TOptions, Result>(...args) => IPromise_Fetch<Result>; }

Make HTTP requests with method HEAD

Type Parameters ​

T ​

T extends unknown = never

TOptions ​

TOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: string; }, TOptions, object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​

url ​

string | URL

options? ​

TOptions

Returns ​

IPromise_Fetch<Result>

head.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultOptions>(deferOptions?, defaultUrl?, defaultOptions?): <T, TOptions, Result>(...args) => IPromise_Fetch<Result>

Make requests with debounce/throttle behavior

Type Parameters ​
ThisArg ​

ThisArg

Delay ​

Delay extends number

DefaultUrl ​

DefaultUrl extends string | URL | undefined = string | URL | undefined

DefaultOptions ​

DefaultOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Parameters ​
deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultOptions? ​

DefaultOptions

Returns ​

<T, TOptions, Result>(...args): IPromise_Fetch<Result>

Type Parameters ​
T ​

T extends unknown = never

TOptions ​

TOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: string; }, TOptions, DefaultOptions, object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​
args ​

...DefaultUrl extends undefined ? [string | URL, TOptions] : [TOptions]

Returns ​

IPromise_Fetch<Result>

options ​

options: {<T, TOptions, Result>(url, options?): IPromise_Fetch<Result>; deferred: <T, TOptions, Result>(...args) => IPromise_Fetch<Result>; }

Make HTTP requests with method OPTIONS

Type Parameters ​

T ​

T extends unknown = never

TOptions ​

TOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: string; }, TOptions, object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​

url ​

string | URL

options? ​

TOptions

Returns ​

IPromise_Fetch<Result>

options.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultOptions>(deferOptions?, defaultUrl?, defaultOptions?): <T, TOptions, Result>(...args) => IPromise_Fetch<Result>

Make requests with debounce/throttle behavior

Type Parameters ​
ThisArg ​

ThisArg

Delay ​

Delay extends number

DefaultUrl ​

DefaultUrl extends string | URL | undefined = string | URL | undefined

DefaultOptions ​

DefaultOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Parameters ​
deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultOptions? ​

DefaultOptions

Returns ​

<T, TOptions, Result>(...args): IPromise_Fetch<Result>

Type Parameters ​
T ​

T extends unknown = never

TOptions ​

TOptions extends object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: string; }, TOptions, DefaultOptions, object & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​
args ​

...DefaultUrl extends undefined ? [string | URL, TOptions] : [TOptions]

Returns ​

IPromise_Fetch<Result>

patch ​

patch: {<T, Options, Result>(url, data?, options?): IPromise_Fetch<Result>; deferred: <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>; }

Make HTTP requests with method PATCH

Executes the HTTP request using the configured client options.

This function is specifically designed for methods that require a request body (e.g., POST, PUT, PATCH), allowing the payload to be passed directly as the second argument.

Type Parameters ​

T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: "patch"; }, Options, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​

url ​

string | URL

data? ​

PostBody | () => ValueOrPromise<PostBody>

options? ​

Options

Returns ​

IPromise_Fetch<Result>

patch.deferred() ​

deferred<ThisArg, DefaultUrl, DefaultData, DefaultOptions, Delay>(deferOptions?, defaultUrl?, defaultData?, defaultOptions?): <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>

Returns a version of the client configured for debounced, throttled, or sequential execution.

This is particularly useful for optimizing high-frequency operations, such as auto-saving forms or managing rapid state updates, by automatically handling request cancellation and execution timing.

Type Parameters ​
ThisArg ​

ThisArg

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

DefaultData extends PostBody | () => ValueOrPromise<PostBody> | undefined

DefaultOptions ​

DefaultOptions extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Delay ​

Delay extends number = number

Parameters ​
deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<T, Options, TReturn>(...args): IPromise_Fetch<TReturn>

Type Parameters ​
T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

TReturn ​

TReturn = GetFetchResult<[{ method: "patch"; }, Options, DefaultOptions, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, Options>

Returns ​

IPromise_Fetch<TReturn>

post ​

post: {<T, Options, Result>(url, data?, options?): IPromise_Fetch<Result>; deferred: <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>; }

Make HTTP requests with method POST

Executes the HTTP request using the configured client options.

This function is specifically designed for methods that require a request body (e.g., POST, PUT, PATCH), allowing the payload to be passed directly as the second argument.

Type Parameters ​

T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: "post"; }, Options, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​

url ​

string | URL

data? ​

PostBody | () => ValueOrPromise<PostBody>

options? ​

Options

Returns ​

IPromise_Fetch<Result>

post.deferred() ​

deferred<ThisArg, DefaultUrl, DefaultData, DefaultOptions, Delay>(deferOptions?, defaultUrl?, defaultData?, defaultOptions?): <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>

Returns a version of the client configured for debounced, throttled, or sequential execution.

This is particularly useful for optimizing high-frequency operations, such as auto-saving forms or managing rapid state updates, by automatically handling request cancellation and execution timing.

Type Parameters ​
ThisArg ​

ThisArg

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

DefaultData extends PostBody | () => ValueOrPromise<PostBody> | undefined

DefaultOptions ​

DefaultOptions extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Delay ​

Delay extends number = number

Parameters ​
deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<T, Options, TReturn>(...args): IPromise_Fetch<TReturn>

Type Parameters ​
T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

TReturn ​

TReturn = GetFetchResult<[{ method: "post"; }, Options, DefaultOptions, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, Options>

Returns ​

IPromise_Fetch<TReturn>

put ​

put: {<T, Options, Result>(url, data?, options?): IPromise_Fetch<Result>; deferred: <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>; }

Make HTTP requests with method PUT

Executes the HTTP request using the configured client options.

This function is specifically designed for methods that require a request body (e.g., POST, PUT, PATCH), allowing the payload to be passed directly as the second argument.

Type Parameters ​

T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Result ​

Result = GetFetchResult<[{ method: "put"; }, Options, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​

url ​

string | URL

data? ​

PostBody | () => ValueOrPromise<PostBody>

options? ​

Options

Returns ​

IPromise_Fetch<Result>

put.deferred() ​

deferred<ThisArg, DefaultUrl, DefaultData, DefaultOptions, Delay>(deferOptions?, defaultUrl?, defaultData?, defaultOptions?): <T, Options, TReturn>(...args) => IPromise_Fetch<TReturn>

Returns a version of the client configured for debounced, throttled, or sequential execution.

This is particularly useful for optimizing high-frequency operations, such as auto-saving forms or managing rapid state updates, by automatically handling request cancellation and execution timing.

Type Parameters ​
ThisArg ​

ThisArg

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

DefaultData extends PostBody | () => ValueOrPromise<PostBody> | undefined

DefaultOptions ​

DefaultOptions extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

Delay ​

Delay extends number = number

Parameters ​
deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<T, Options, TReturn>(...args): IPromise_Fetch<TReturn>

Type Parameters ​
T ​

T extends unknown = never

Options ​

Options extends object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined = object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined

TReturn ​

TReturn = GetFetchResult<[{ method: "put"; }, Options, DefaultOptions, object & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>> | undefined], T>

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, Options>

Returns ​

IPromise_Fetch<TReturn>

Template ​

The type of the value that the fetch resolves to.

Template ​

Return value type.

If T is not specified defaults to the following based on the value of options.as:

  • FetchAs.arrayBuffer: ArrayBuffer
  • FetchAs.blob: Blob
  • FetchAs.bytes: Uint8Array<ArrayBuffer>
  • FetchAs.formData: FormData
  • FetchAs.json: unknown
  • FetchAs.text: string
  • FetchAs.response: Response

Param ​

Param ​

(optional) Standard fetch options extended with FetchCustomOptions

Param ​

(optional) if not provided AbortController will be instantiated when timeout used.

Default: new AbortController()

Param ​

(optional) (optional) specify how to parse the result. For raw Response use FetchAs.response

Default: FetchAs.json

Param ​

(optional) request headers

Default: { 'content-type': 'application/json' }

Param ​

(optional) request interceptor/transformer callbacks. See FetchInterceptors for details.

Param ​

(optional) fetch method.

Default: 'get'

Param ​

(optional) duration in milliseconds to abort the request. This duration includes the execution of all interceptors/transformers.

Default: 60_000

Examples ​

Drop-in replacement for built-in fetch ​

javascript
import fetch from '@superutils/fetch'

fetch('[DUMMYJSON-DOT-COM]/products/1')
  .then(response => response.json())
  .then(console.log, console.error)

Method specific function with JSON parsing by default ​

javascript
import fetch from '@superutils/fetch'

// no need for `response.json()` or "result.data.data" drilling
fetch.get('[DUMMYJSON-DOT-COM]/products/1')
  .then(product => console.log(product))
fetch.post('[DUMMYJSON-DOT-COM]/products/add', { title: 'Product title' })
  .then(product => console.log(product))

Set default options. ​

Options' default values (excluding as and method) can be configured to be EFFECTIVE GLOBALLY.

typescript
import fetch from '@superutils/fetch'

const { defaults, errorMsgs, interceptors } = fetch

// set default request timeout duration in milliseconds
defaults.timeout = 40_000

// default headers
defaults.headers = { 'content-type': 'text/plain' }

// override error messages
errorMsgs.invalidUrl = 'URL is not valid'
errorMsgs.timedout = 'Request took longer than expected'

// add an interceptor to log all request failures.
const fetchLogger = (fetchErr, url, options) => console.log('Fetch error log', fetchErr)
interceptors.error.push(fetchLogger)

// add an interceptor to conditionally include header before making requests
interceptors.request.push((url, options) => {
  // ignore login requests
  if (`${url}`.includes('/login')) return

  options.headers.set('x-auth-token', 'my-auth-token')
})