npwork/async-wait-until

Waits for the given callback to return a truthy value, with a convenient Promise API

async-wait-until

A tiny yet convenient and fast zero-dependency library that makes it possible to write an asynchronous code that awaits some event to happen. It works on any JavaScript runtime that supports Promises either natively or with a polyfill (i.e. this one), including old Node.js versions and old web browsers.

⚙️ Installation

The package is available on npm:

$ npm install --save async-wait-until

It ships with an UMD bundle by default (which works well as-is on Node.js and web browsers), but bundles for other module systems are also available in the package's dist/ folder.

import { waitUntil } from 'async-wait-until';

// ...
await waitUntil(() => document.querySelector('#hey') != null);

Click to see examples for other module systems

• CommonJS:

  const { waitUntil } = require('async-wait-until/dist/commonjs');
  // ...

• ES Modules:

  import { waitUntil } from 'async-wait-until';
  // ...

  or

  import { waitUntil } from 'async-wait-until/dist/index.esm.js';
  // ...

• AMD:

  <script type="text/javascript" src="scripts/require.js"></script>
  <script type="text/javascript">
    requirejs.config({
      baseUrl: 'scripts/node_modules',
      paths: {
        'async-wait-until': 'async-wait-until/dist/amd.js',
      },
    });
    define(['async-wait-until'], ({ waitUntil }) => {
      // ...
    });
  </script>

• IIFE:

  <script type="text/javascript" src="async-wait-until/dist/iife.js"></script>
  <script type="text/javascript">
    const { waitUntil } = asyncWaitUntil;
    // ...    
  </script>

• SystemJS:

  <script src="scripts/system.js"></script>
  <script type="systemjs-importmap">
    {
      imports: {
        'async-wait-until': './scripts/node_modules/async-wait-until/dist/systemjs.js',
      }
    }
  </script>
  <script type="systemjs-module">
    System
        .import('async-wait-until')
        .then(({ waitUntil }) => {
          // ...
        });
  </script>

👨‍💻👩‍💻 Use

Let's assume we have a piece of code that asynchronously appends a new <div /> node to the page body, and we want to wait for it to happen and then do something with that node. Let's also assume that for some unknown reason, we can neither use MutationObserver nor modify the code that adds the node 🤷‍♂️. How bizarre!

However, we know that optimistically, on a fast enough computer, this will happen within let's say 10 seconds (but it's not guaranteed). The following code snippet mimics this behaviour:

// @file a-sneaky-module.js

// Aha! Sometimes, it can take more than 10 seconds, and this is how we emulate it
const MAX_IDLE_INTERVAL_MILLISECONDS_BEFORE_ADDING_A_DIV_IN = 11 * 1000;

// Some utility functions, it's safe to ignore them 
const randomIntegerInRange = ({ min = 0, max }) => 
  min + Math.floor(Math.random() * (max - min));
const randomTimeInterval = () => randomIntegerInRange({ 
  max: MAX_IDLE_INTERVAL_MILLISECONDS_BEFORE_ADDING_A_DIV_IN,
});

// Adds a <div /> to the document body
const appendADivToTheDocumentBody = () => {
  const node = document.createElement('div');
  node.className = 'spooky-spooky-skeleton';
  window.document.body.appendChild(node);
};

// A sneaky function that schedules adding a <div /> to the document body 
// at some time within 11 seconds
const appendADivToTheDocumentBodySomeAtTimeWithinAGivenTimeInterval = () => 
  setTimeout(
    appendADivToTheDocumentBody,
    randomTimeInterval(),
  );

export const doTheDivThing = appendADivToTheDocumentBodySomeAtTimeWithinAGivenTimeInterval;

Let's call the above code a-sneaky-module.js.

So how do we the consumers of the a-sneaky-module.js know when exactly the <div /> node gets added?

import { doTheDivThing } from './a-sneaky-module.js';

const doOutThing = async () => {
  // ...

  doTheDivThing();
  // Hmmmm... so what? How do we work with that <div />. Is it already in the DOM?
};

async-wait-until to the rescue, we can easily detect when it happens (and react to it):

import { doTheDivThing } from './a-sneaky-module.js';
import { waitUntil } from './async-wait-until';

const doOutThing = async () => {
  // ...
  
  doTheDivThing();

  // Yup! Easy right?
  const divNode = await waitUntil(
    // Here, we specify a function that will be repeatedly called from time to time
    // Let's call this kind of function a `predicate`
    () => window.document.body.querySelector('div.spooky-spooky-skeleton'),
    // Here, we can specify a timeout in milliseconds. Once it passes, 
    // we'll stop waiting and throw an exception
    { timeout: 10000 },
  );
  // A colour of triumph
  divNode.style.backgroundColor = 'rgba(255, 0, 0, 0.5)';
};

However, we aren't 100% sure that the <div /> will be added within 10 seconds. What will happen if 10 seconds have passed and the <div /> node still isn't there?

From the above code, it's clear that our 'predicate' function (or simply 'predicate') won't return the DOM node. So what waitUntil will do in that case is it will throw a TimeoutException (also exported from the library so you can handle it).

import { doTheDivThing } from './a-sneaky-module.js';
import { waitUntil, TimeoutError } from './async-wait-until';

const doOurThing = async () => {
  // ...
  
  doTheDivThing();

  try {
    const predicate = () => window.document.body.querySelector('div.spooky-spooky-skeleton');
    const divNode = await waitUntil(predicate, { timeout: 10000 });
    
    divNode.style.backgroundColor = 'rgba(255, 0, 0, 0.5)';
  } catch (e) {
    if (e instanceof TimeoutError) {
      // Unfortunately, 10 seconds have passed but we haven't detected the `<div />`
      // If we had a UI, we could show an error there or allow the user to retry
      alert('No <div /> have been detected unfortunately');
    } else {
      // Some other error, most likely thrown from the predicate function.
      alert('Unknown error occurred');
      console.error(e);
    }    
  }
};

So, summing up the above, the predicate will run again and again within the given timeout, until it first returns a non-falsy value. If this doesn't happen, a TimeoutError is thrown.

API

Let's start with the waitUntil function. It takes up to two parameters (deprecated: up to three), and returns a Promise that will be resolved with the first non-falsy value returned by the predicate.

Parameter	Type	Required	Default	Description
predicate	Function	✅ Yes	-	A function that is expected to return a non-falsy (aka a 'truthy') value, or a Promise to return such a value. Hence, both sync and async functions are supported.
options	Options object	🚫 No	5000 ms	Options for the wait algorithm implemented by waitUntil, see its properties on the below table. Deprecated: timeout in milliseconds.
intervalBetweenAttempts	number	🚫 No	50 ms	Deprecated parameter: number of milliseconds between retry attempts. Please use options instead.

Above, you can see the options param. Here are the available options:

Parameter	Type	Required	Default	Description
timeout	number	🚫 No	5000 ms	Timeout in milliseconds.
intervalBetweenAttempts	number	🚫 No	50 ms	Number of milliseconds between retry attempts.

Recipes

Waiting for something forever

If you aren't sure how long a process will take, you can use waitUntil.Forever (which is a shortcut for Number.POSITIVE_INFINITY) as the timeout value:

import { waitUntil, WAIT_FOREVER } from 'async-wait-until';

// ...

const result = waitUntil(() => Date.now() >= new Date('Jan 13, 2022 11:35 am'), {
  timeout: WAIT_FOREVER, // === Number.POSITIVE_INFINITY
});

Customizing the interval between retries

In addition to the timeout option, you can customize the interval between retries:

import { waitUntil } from 'async-wait-until';

// ...

const result = waitUntil(() => Date.now() >= new Date('Jan 13, 2022 11:35 am'), {
  intervalBetweenAttempts: 1000, // Retry every second instead of 50 milliseconds
});

👨‍⚖️👩‍⚖️ License

Library is shipped "as is" under the MIT License.

👷‍♂️👷‍♀️ Contributing

Contributions (issues, bug and feature requests, and PRs) are welcome! Please follow the contribution guidelines.

Click for additional information on development dependencies and available commands

Development dependencies

1. The library is written in TypeScript and is bundled with Parcel.
2. Code style is powered by ESLint and Prettier with a custom config.
3. We use jest for running unit tests.

Available commands

Test:

$ npm test

Lint:

$ npm run lint

Reformat:

$ npm run format

Build

$ npm run build

Generate docs

$ npm run docs