Superutils

Appearance

Function: createClient() ​

createClient<FixedOptions, CommonOptions, CommonDelay>(fixedOptions?, commonOptions?, commonDeferOptions?): {<T, TOptions, Result>(url, options?): IPromise_Fetch<Result>; deferred: <T, TOptions, Result>(...args) => IPromise_Fetch<Result>; }

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

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.

Option Priority:

  1. fixedOptions: Highest priority. Cannot be overridden by the caller.
  2. options: Options passed during the specific call.
  3. commonOptions: Default options set at creation time.

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 ​

FixedOptions ​

FixedOptions extends FetchOptions | undefined

CommonOptions ​

CommonOptions extends FetchOptions | object & Omit<FetchOptions, "body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "errMsgs" | "interceptors" | "ignoreGlobalDefaults" | "fetchFunc" | "onDownloadProgress" | "validateUrl" | keyof TimeoutOptions<[]>> & Partial<Record<"body" | "cache" | "credentials" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "errMsgs" | "interceptors" | "ignoreGlobalDefaults" | "fetchFunc" | "onDownloadProgress" | "validateUrl" | keyof TimeoutOptions<[]>, never>> | undefined

CommonDelay ​

CommonDelay extends number

Parameters ​

fixedOptions? ​

FixedOptions

Mandatory fetch options that cannot be overriden by individual request

commonOptions? ​

Omit<RequestInit, "body"> & object & Omit<Partial<RetryOptions>, "retry" | "retryIf"> & object & TimeoutOptions<[]> & CommonOptions

Common fetch options that can be overriden by individual request

commonDeferOptions? ​

DeferredAsyncOptions<unknown, CommonDelay>

Returns ​

<T, TOptions, Result>(url, options?): IPromise_Fetch<Result>

Executes the HTTP request using pre-configured client options.

Type Parameters ​

T ​

T extends unknown = never

TOptions ​

TOptions extends FetchOptions | object & Omit<FetchOptions, "body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "errMsgs" | "interceptors" | "ignoreGlobalDefaults" | "fetchFunc" | "onDownloadProgress" | "validateUrl" | keyof TimeoutOptions<[]>> & Partial<Record<"body" | "cache" | "credentials" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "errMsgs" | "interceptors" | "ignoreGlobalDefaults" | "fetchFunc" | "onDownloadProgress" | "validateUrl" | keyof TimeoutOptions<[]>, never>> | undefined = ExcludeOptions<FixedOptions> | undefined

Result ​

Result = GetFetchResult<[FixedOptions, TOptions, CommonOptions], T>

Parameters ​

url ​

URL | RequestInfo

The request URL.

options? ​

TOptions

Individual request options that can override common options.

Returns ​

IPromise_Fetch<Result>

A promise resolving to the parsed result or response.

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 URL | RequestInfo | undefined = URL | RequestInfo | undefined

DefaultOptions ​

DefaultOptions extends FetchOptions | object & Omit<FetchOptions, "body" | "cache" | "credentials" | "headers" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "errMsgs" | "interceptors" | "ignoreGlobalDefaults" | "fetchFunc" | "onDownloadProgress" | "validateUrl" | keyof TimeoutOptions<[]>> & Partial<Record<"body" | "cache" | "credentials" | "integrity" | "keepalive" | "method" | "mode" | "priority" | "redirect" | "referrer" | "referrerPolicy" | "window" | "retry" | "retryIf" | "retryBackOff" | "retryDelay" | "retryDelayJitter" | "retryDelayJitterMax" | "as" | "errMsgs" | "interceptors" | "ignoreGlobalDefaults" | "fetchFunc" | "onDownloadProgress" | "validateUrl" | keyof TimeoutOptions<[]>, never>> | undefined = ExcludeOptions<FixedOptions> | undefined

Parameters ​

deferOptions? ​

DeferredAsyncOptions<ThisArg, Delay>

defaultUrl? ​

DefaultUrl

defaultOptions? ​

DefaultOptions

Returns ​

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

Example ​

Create reusable clients ​

javascript
import { createClient } from '@superutils/fetch'

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

// Use it just like the standard fetch
apiClient('[DUMMYJSON-DOT-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
  '[DUMMYJSON-DOT-COM]/products/1',
  { timeout: 3000 },
)
deferredClient({ timeout: 10000 }) // timeout is overridden by individual request
	.then(console.log, console.warn)