Superutils

Appearance

Variable: default ​

const default: <T, TOptions, TAs, TReturn>(url, options?) => IPromisE<TReturn> & object

Defined in: packages/fetch/src/fetchDefault.ts:137

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, TOptions, TAs, TReturn>(url, data?, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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 = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

data? ​

PostBody | () => PostBody

options? ​

TOptions

Returns ​

IPromisE<TReturn>

delete.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultData, DefaultOptions>(deferOptions, defaultUrl?, defaultData?, defaultOptions?): <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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

Delay ​

Delay extends number

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

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

DefaultOptions ​

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

Parameters ​
deferOptions ​

DeferredAsyncOptions<ThisArg, Delay> = ...

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<TResult, TOptions, TAs, TReturn>(...args): IPromisE<TReturn>

Type Parameters ​
TResult ​

TResult = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions>

Returns ​

IPromisE<TReturn>

get ​

get: {<T, TOptions, TAs, TReturn>(url, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<TReturn>; }

Make HTTP requests with method GET

Type Parameters ​

T ​

T

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

options? ​

TOptions

Returns ​

IPromisE<TReturn>

get.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultOptions>(deferOptions, defaultUrl?, defaultOptions?): <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<TReturn>

Make requests with debounce/throttle behavior

Type Parameters ​
ThisArg ​

ThisArg = unknown

Delay ​

Delay extends number = 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 ​

<TResult, TOptions, TAs, TReturn>(...args): IPromisE<TReturn>

Type Parameters ​
TResult ​

TResult = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

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

Returns ​

IPromisE<TReturn>

head: {<T, TOptions, TAs, TReturn>(url, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<TReturn>; }

Make HTTP requests with method HEAD

Type Parameters ​

T ​

T

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

options? ​

TOptions

Returns ​

IPromisE<TReturn>

head.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultOptions>(deferOptions, defaultUrl?, defaultOptions?): <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<TReturn>

Make requests with debounce/throttle behavior

Type Parameters ​
ThisArg ​

ThisArg = unknown

Delay ​

Delay extends number = 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 ​

<TResult, TOptions, TAs, TReturn>(...args): IPromisE<TReturn>

Type Parameters ​
TResult ​

TResult = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

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

Returns ​

IPromisE<TReturn>

options ​

options: {<T, TOptions, TAs, TReturn>(url, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<TReturn>; }

Make HTTP requests with method OPTIONS

Type Parameters ​

T ​

T

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

options? ​

TOptions

Returns ​

IPromisE<TReturn>

options.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultOptions>(deferOptions, defaultUrl?, defaultOptions?): <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<TReturn>

Make requests with debounce/throttle behavior

Type Parameters ​
ThisArg ​

ThisArg = unknown

Delay ​

Delay extends number = 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 ​

<TResult, TOptions, TAs, TReturn>(...args): IPromisE<TReturn>

Type Parameters ​
TResult ​

TResult = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

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

Returns ​

IPromisE<TReturn>

patch ​

patch: {<T, TOptions, TAs, TReturn>(url, data?, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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 = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

data? ​

PostBody | () => PostBody

options? ​

TOptions

Returns ​

IPromisE<TReturn>

patch.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultData, DefaultOptions>(deferOptions, defaultUrl?, defaultData?, defaultOptions?): <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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

Delay ​

Delay extends number

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

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

DefaultOptions ​

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

Parameters ​
deferOptions ​

DeferredAsyncOptions<ThisArg, Delay> = ...

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<TResult, TOptions, TAs, TReturn>(...args): IPromisE<TReturn>

Type Parameters ​
TResult ​

TResult = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions>

Returns ​

IPromisE<TReturn>

post ​

post: {<T, TOptions, TAs, TReturn>(url, data?, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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 = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

data? ​

PostBody | () => PostBody

options? ​

TOptions

Returns ​

IPromisE<TReturn>

post.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultData, DefaultOptions>(deferOptions, defaultUrl?, defaultData?, defaultOptions?): <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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

Delay ​

Delay extends number

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

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

DefaultOptions ​

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

Parameters ​
deferOptions ​

DeferredAsyncOptions<ThisArg, Delay> = ...

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<TResult, TOptions, TAs, TReturn>(...args): IPromisE<TReturn>

Type Parameters ​
TResult ​

TResult = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions>

Returns ​

IPromisE<TReturn>

put ​

put: {<T, TOptions, TAs, TReturn>(url, data?, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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 = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

data? ​

PostBody | () => PostBody

options? ​

TOptions

Returns ​

IPromisE<TReturn>

put.deferred() ​

deferred<ThisArg, Delay, DefaultUrl, DefaultData, DefaultOptions>(deferOptions, defaultUrl?, defaultData?, defaultOptions?): <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<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

Delay ​

Delay extends number

DefaultUrl ​

DefaultUrl extends string | URL | undefined

DefaultData ​

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

DefaultOptions ​

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

Parameters ​
deferOptions ​

DeferredAsyncOptions<ThisArg, Delay> = ...

defaultUrl? ​

DefaultUrl

defaultData? ​

DefaultData

defaultOptions? ​

DefaultOptions

Returns ​

<TResult, TOptions, TAs, TReturn>(...args): IPromisE<TReturn>

Type Parameters ​
TResult ​

TResult = unknown

TOptions ​

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

TAs ​

TAs extends FetchAs = FetchAsFromOptions<TOptions, json>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

...PostDeferredCbArgs<DefaultUrl, DefaultData, TOptions>

Returns ​

IPromisE<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.

Param ​

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

Param ​

(optional) request headers Default: { 'content-type': 'application/json' } (or whaterver is set in the fetch.defaults).

Param ​

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

Param ​

(optional) fetch method. Default: 'get'

Param ​

(optional) duration in milliseconds to abort the request if it takes longer.

Examples ​

Try Now!
javascript
import fetch from '@superutils/fetch'

fetch('https://dummyjson.com/products/1')
    .then(response => response.json())
    .then(console.log, console.error)
Try Now!
javascript
import fetch from '@superutils/fetch'

// no need for `response.json()` or `result.data.data` drilling
fetch.get('https://dummyjson.com/products/1')
    .then(product => console.log(product))
fetch.get('https://dummyjson.com/products/1')
    .then(product => console.log(product))

fetch.post('https://dummyjson.com/products/add', { title: 'Product title' })
    .then(product => console.log(product))

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

Try Now!
typescript
import fetch from '@superutils/fetch'

fetch.defaults = {
    errMsgs: {
       invalidUrl: 'Invalid URL',
       parseFailed: 'Failed to parse response as',
       reqTimedout: 'Request timed out',
       requestFailed: 'Request failed with status code:',
    },
    headers: new Headers([['content-type', 'application/json']]),
	   // Global/application-wide Interceptor & Transfermers
    interceptors: {
    	   error: [],
    	   request: [],
    	   response: [],
    	   result: [],
    },
    timeout: 0,
    //........
}