Have ideas to improve npm?Join in the discussion! »

    async-wait-until
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.5 • Public • Published

    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.

    npm version npm downloads, weekly online documentation build status maintainability code coverage minzipped bundle size license

    ⚙️ Installation

    The package is available on npm:

    $ npm install --save async-wait-until

    It ships with a 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/dist/es.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 functions 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 'preddcate') 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 user to retry
          alert('No <div /> have been detected unfortunately');
        } else {
          // Some another 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

    Lets' 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 500 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 could see the options param. Here are the available options:

    Parameter Type Required Default Description
    timeout number 🚫 No 500 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 with a process 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

    Install

    npm i async-wait-until

    DownloadsWeekly Downloads

    21,474

    Version

    2.0.5

    License

    MIT

    Unpacked Size

    22.9 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar