Superutils

Appearance

Function: createClient() ​

createClient<FixedOpts, CommonOpts, FixedAs>(fixedOptions?, commonOptions?, commonDeferOptions?): {<T, TOptions, TAs, TReturn>(url, options?): IPromisE<TReturn>; deferred: <TResult, TOptions, TAs, TReturn>(...args) => IPromisE<TReturn>; }

Defined in: packages/fetch/src/createClient.ts:71

Create a reusable fetch client with shared options. The returned function comes attached with a .deferred() function for debounce and throttle behavior.

The createClient utility streamlines the creation of dedicated API clients by generating pre-configured fetch functions. These functions can be equipped with default options like headers, timeouts, or a specific HTTP method, which minimizes code repetition across your application. If a method is not specified during creation, the client will default to GET.

The returned client also includes a .deferred() method, providing the same debounce, throttle, and sequential execution capabilities found in functions like fetch.get.deferred().

Type Parameters ​

FixedOpts ​

FixedOpts extends FetchOptions | undefined

CommonOpts ​

CommonOpts extends FetchOptions | object & Omit<FetchOptions, "body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl"> & Partial<Record<"body" | "cache" | "credentials" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl", never>> | undefined

FixedAs ​

FixedAs extends FetchAs | undefined = FetchAsFromOptions<FixedOpts, undefined>

Parameters ​

fixedOptions? ​

FixedOpts

Mandatory fetch options that cannot be overriden by individual request

commonOptions? ​

Omit<RequestInit, "body"> & object & Omit<Partial<RetryOptions>, "retry" | "retryIf"> & object & CommonOpts

Common fetch options that can be overriden by individual request

commonDeferOptions? ​

DeferredAsyncOptions<unknown, unknown>

Returns ​

<T, TOptions, TAs, TReturn>(url, options?): IPromisE<TReturn>

Type Parameters ​

T ​

T

TOptions ​

TOptions extends FetchOptions | object & Omit<FetchOptions, "body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl"> & Partial<Record<"body" | "cache" | "credentials" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl", never>> | undefined = ExcludeOptions<FixedOpts> | undefined

TAs ​

TAs extends FetchAs = FixedAs extends FetchAs ? FixedAs<FixedAs> : FetchAsFromOptions<TOptions, FetchAsFromOptions<CommonOpts>>

TReturn ​

TReturn = FetchResult<T>[TAs]

Parameters ​

url ​

string | URL

options? ​

TOptions

Returns ​

IPromisE<TReturn>

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 FetchOptions | object & Omit<FetchOptions, "body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl"> & Partial<Record<"body" | "cache" | "credentials" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl", never>> | undefined = ExcludeOptions<FixedOpts> | 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 FetchOptions | object & Omit<FetchOptions, "body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl"> & Partial<Record<"body" | "cache" | "credentials" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "signal" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "abortCtrl" | "errMsgs" | "interceptors" | "timeout" | "validateUrl", never>> | undefined = ExcludeOptions<FixedOpts> | undefined

TAs ​

TAs extends FetchAs = FixedAs extends FetchAs ? FixedAs<FixedAs> : FetchAsFromOptions<TOptions, FetchAsFromOptions<CommonOpts>>

TReturn ​

TReturn = FetchResult<TResult>[TAs]

Parameters ​
args ​

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

Returns ​

IPromisE<TReturn>

Example ​

Try Now!
javascript
import { createClient } from '@superutils/fetch'

// Create a "GET" client with default headers and a 5-second timeout
const apiClient = createClient(
	{
		// fixed options cannot be overridden
		method: 'get',
	},
	{
		// default options can be overridden
		headers: {
			Authorization: 'Bearer my-secret-token',
			'Content-Type': 'application/json',
		},
		timeout: 5000,
	},
	{
		// default defer options (can be overridden)
		delayMs: 300,
		retry: 2, // If request fails, retry up to two more times
	},
)

// Use it just like the standard fetch
apiClient('https://dummyjson.com/products/1', {
	// The 'method' property cannot be overridden as it is used in the fixed options when creating the client.
	// In TypeScript, the compiler will not allow this property.
	// In Javascript, it will simply be ignored.
	// method: 'post',
	timeout: 3000, // The 'timeout' property can be overridden
}).then(console.log, console.warn)

// create a deferred client using "apiClient"
const deferredClient = apiClient.deferred(
	{ retry: 0 }, // disable retrying by overriding the `retry` defer option
	'https://dummyjson.com/products/1',
	{ timeout: 3000 },
)
deferredClient({ timeout: 10000 }) // timeout is overridden by individual request
	.then(console.log, console.warn)