Superutils

Appearance

Function: deferred() ​

deferred<T, ThisArg, Delay>(options): DeferredAsyncCallback

Defined in: packages/promise/src/deferred.ts:116

Function

PromisE.deferred

The adaptation of the deferred() function from @superutils/core tailored for Promises.

Notes ​

  • A "request" simply means invokation of the returned callback function
  • By "handled" it means a "request" will be resolved or rejected.
  • PromisE.deferred is to be used with promises/functions. PromisE.deferredCallback is for use with callback functions.
  • There is no specific time delay.
  • If a request takes longer than delayMs, the following request will be added to queue and either be ignored or exectued based on the debounce/throttle configuration.
  • If not throttled:
    1. Once a request is handled, all previous requests will be ignored and pool starts anew.
    2. If a function is provided in the returned callback, ALL of them will be invoked, regardless of pool size.
    3. The last/only request in an on-going requests' pool will handled (resolve/reject).
  • If throttled:
    1. Once a requst starts executing, subsequent requests will be added to a queue.
    2. The last/only item in the queue will be handled. Rest will be ignored.
    3. If a function is provided in the returned callback, it will be invoked only if the request is handled. Thus, improving performance by avoiding unnecessary invokations.
    4. If every single request/function needs to be invoked, avoid using throttle.
  • If throttled and strict is truthy, all subsequent request while a request is being handled will be ignored.

Type Parameters ​

T ​

T = unknown

ThisArg ​

ThisArg = unknown

Delay ​

Delay = unknown

Parameters ​

options ​

DeferredAsyncOptions<ThisArg, Delay> = {}

(optional) Debounce/throttle configuration.

The properties' default values can be overridden to be EFFECTIVE GLOBALLY:

Try Now!
typescript
deferred.defaults = {
    delayMs: 100,
    resolveError: ResolveError.REJECT,
    resolveIgnored: ResolveIgnored.WITH_LAST,
}

Returns ​

DeferredAsyncCallback

Callback function that can be invoked in one of the followin 3 methods:

  • sequential: when delayMs <= 0
  • debounced: when delayMs > 0 and throttle = false
  • throttled: when delayMs > 0 and throttle = true

Examples ​

Try Now!
typescript
const example = async (options = {}) => {
	const df = PromisE.deferred({
		delayMs: 100,
		resolveIgnored: ResolveIgnored.NEVER, // never resolve ignored calls
		...options,
	})
	df(() => PromisE.delay(500)).then(console.log)
	df(() => PromisE.delay(1000)).then(console.log)
	df(() => PromisE.delay(5000)).then(console.log)
	// delay 2 seconds and invoke df() again
	await PromisE.delay(2000)
	df(() => PromisE.delay(200)).then(console.log)
}
example({ ignoreStale: false, throttle: false })
// `200` and `1000` will be printed in the console
example({ ignoreStale: true, throttle: false })
// `200` will be printed in the console
Try Now!
typescript
const example = async (options = {}) => {
	const df = PromisE.deferred({
		delayMs: 100,
		resolveIgnored: ResolveIgnored.NEVER, // never resolve ignored calls
		...options,
	})
	df(() => PromisE.delay(5000)).then(console.log)
	df(() => PromisE.delay(500)).then(console.log)
	df(() => PromisE.delay(1000)).then(console.log)
	// delay 2 seconds and invoke df() again
	await PromisE.delay(2000)
	df(() => PromisE.delay(200)).then(console.log)
}

example({ ignoreStale: true, throttle: true })
// `200` will be printed in the console

example({ ignoreStale: false, throttle: true })
// `200` and `5000` will be printed in the console