await-until v2.1.0

awaitUntil

awaitUntil<T>(opts|predicate): Promise<T>

Runs predicate function after every interval until predicate function returns truthy or run out of timeout.

OPTIONS: an object of the following:

• predicate: (args: { data: T | boolean | undefined, retriesSoFar: number, maxRetries: number, timeout: number }) => T | boolean | undefined - callback function (maybe async) to do whatever test needed at each interval, returns truthy to indicate success. Function is called with data from worker fn if worker fn is provided. Should be free to access any services or external data.
• worker?: (args: { retriesSoFar: number, maxRetries: number, timeout: number }) => T | boolean | undefined - callback function (maybe async) to run and do something that returns a result to be analysed by predicate. If predicates accepts the result to conclude everything, the final result of worker is returned instead of the predicate. The reason there is a worker is that we may want to actually return falsey data from awaitUntil, that can be done by the worker, but the predicate can just return a falsey or truthy to indicate loop progress.
• timeout? number - maximum number of ms to wait until predicates returns truth. defaults to 42000 or calculated from interval * maxRetries if provided.
• interval?: number - interval between retries. defaults to 100 or calculated from timeout/maxRetries if provided.
• maxRetries?: number - number of retries before we quit, use Infinity to indicate such. defaults to calculation of timeout/interval.
• waitFirst?: boolean - wait 1 interval first before executing predicate function for the first time.
• debug?: boolean - flag to show debug information.

Usage 1:

awaitUntil works without a worker and can be used to evaluate external or async data. eg: this will evaluate after every second. It will time out after 30seconds.

 let res = await awaitUntil({
    predicate: ()=>{/*evaluate/analyse result and return true/false to break/continue waiting*/},
    timeout: 30000, 
    interval: 1000
}).catch(result=>{/*do something when we have failed*/});

Usage 2:

Use a worker to produce data then predicate to evaluate the result. Helps code to look cleaner and avoid repeating the same process just to check if something is done or get its data.

eg: instead of doing this:

const selector = 'div';
/** wait until a certain element is available in the dom, default timeout will apply etc */
await awaitUntil({
    predicate: () => !!document.querySelectorAll(selector).length,
});
/** then re-get the same element now that it's available do something with it */
document.querySelectorAll(selector).forEach((el) => {
    // do something with element
});

eg: do this to query the selector only during the wait:

/** wait until a certain element is available in the dom, default timeout will apply etc */
const elements = await awaitUntil({
    worker: () => document.querySelectorAll('div'),
    predicate: ({ data }) => !!data.length,
});

elements.forEach((el) => {
    // do something with element
});

Usage 3:

or use it by passing the predicate as the only parameter, in this case it uses defaults as indicated above:

// this will try to get result within 42secs for 420 times 
let res = await awaitUntil(()=>{/*evaluate/analyse state return true/false to break/continue waiting*/});

NB: or all other promise methods can be used since this is a promise. You can catch the timeout when it happens as it throws on timeout.

promiseTimeout

promiseTimeout<T>(promise, timeout): Promise<T>

Useful for timing out given promise. It will throw if timeout ms is reached before promise settles with resolve or rejection.

waitFor()

waitFor(Record<any,any>, prop: string): Promise<any>

WIP* has a few issues on certain objects, but works

Fast, non-polling wait for mutation or existence of an object's property.

• @param object {Object} - Object to check property on

• @param property {String} - property to check for

  useful when you don't want to do something before a property, function etc. is available.

Usage:

waitFor(app, 'someProperty').then(r=>{
 // something with the prop
 app.someProperty()
})

Return value is a promise that resolves to the value or the property.

sleep(ms)

sleep(ms: number): Promise<void>

Returns a promise that can be used to wait/sleep for given ms.

Author

Emmanuel Mahuni

MIT