async-wait-for-promise

Re-run a given asynchronous function (any function which returns a Promise), waiting for that function's result to be non-null within a bounded timeframe (timeout).

This project assumes you already have either platform support for promises (Node 0.12+) or you have a polyfill like es6-promise.

Installation

1$ npm install async-wait-for-promise

Arguments

Argument	Type	Description
fn	() => Promise<T | null>	async function to run as a check (returns a value or null)
opts.intervalMs	number	How often the function should be checked, in milliseconds
opts.timeoutMs	number	Timeout in milliseconds

Usage

Provide a function (fn) that produces a value or null. Checking will continue until the function provides a non-null value (and return that value).

Example

Given db.query('<some identifier>') function that returns:

• the object that you're looking for
• null when the object is missing

Here is how you'd use async-wait-for-promise to wait for completion:

1  const retrievedObject = await waitFor(() => db.query('object-id'));

A slightly more complete solution with error handling:

1import { waitFor, TimeoutError } from "async-wait-for-promise"
2
3// Try to find an object that is being created somewhere else,
4// once the object is present, it will be returned as the result
5// (default timeout is 10 seconds)
6try {
7  const retrievedObject = await waitFor(() => db.query('object-id'));
8  console.log("retrieved object:", retrievedObject);
9} catch (err) {
10    if (err instanceof TimeoutError) {
11      // Handle timeout error
12    }
13
14    // Handle unexpected error
15}

NOTE The function you pass to waitFor must return null when it is "not ready", and some non-null value otherwise. false is a non-null value, and will cause waitFor to finish.

ES2015 (async/await)

1import { waitFor } from "async-wait-for-promise";
2
3// Initial state
4let a = 1;
5
6// Add 1 every second
7const interval = setInterval(() => a++, 1000);
8
9// Wait for a to equal 5
10const result = await waitFor(
11  // remember, we return null to indicate to keep checking
12  async () => a >= 5 || null,
13  { timeoutMs: 10 * 1000 },
14);
15// At this point, result === true
16
17clearInterval(interval);

ES6

1"use strict";
2
3const { waitFor, TimeoutError } = require("async-wait-for-promise");
4
5waitFor(() => functionThatReturnsNullUntilTheRealValue())
6  .then(result => console.log("result was:", result))
7  .catch(err => {
8    if (err instanceof TimeoutError) {
9      // Handle timeout error (by default 10 seconds)
10    }
11
12    // Handle some unexpected error
13  })

FAQ

Why use null as an indicator for termination?

Using null is generally a mistake in the presences of better types, but this library uses null to indicate a very specific state -- the computation you passed resolving to a value that is not satisfactory. null is nice for this purpose as opposed to a general "falsy" check as false could very well be a value that the function should return, where null is less likely to be (how often do you write functions that are supposed to return null?).