Introduction

The async library is a widely used utility in the Node.js ecosystem that provides control flow functions for asynchronous code. One of these functions, async.whilst, runs an asynchronous function repeatedly while a test condition returns true. However, developers sometimes find that async.whilst does not execute at all, producing no output and no errors. This article explains how async.whilst works, walks through the most common reasons it fails silently, and provides working code examples to get you back on track.

How async.whilst Works

The async.whilst function accepts three arguments:

1. test: A function that returns a boolean. The loop continues as long as this returns true.
2. iteratee: An asynchronous function that runs on each iteration. It receives a callback that must be called when the iteration is done.
3. callback: A final function that runs after the loop ends or if an error occurs.

Here is a minimal working example:

1const async = require('async');
2
3let count = 0;
4
5async.whilst(
6  function test(cb) {
7    cb(null, count < 5);
8  },
9  function iteratee(cb) {
10    count++;
11    console.log('Count:', count);
12    setTimeout(cb, 100);
13  },
14  function done(err) {
15    if (err) {
16      console.error('Error:', err);
17    }
18    console.log('Loop finished. Final count:', count);
19  }
20);

This prints the numbers 1 through 5, then logs the final count. The key detail is the signature of the test function, which changed in version 3 of the async library.

Common Reason 1: Wrong Test Function Signature

This is by far the most common cause. In async v2 and earlier, the test function was synchronous and simply returned a boolean:

1// async v2 style (WILL NOT WORK in async v3+)
2async.whilst(
3  function test() {
4    return count < 5; // synchronous return
5  },
6  function iteratee(cb) {
7    count++;
8    cb(null);
9  },
10  function done(err) {
11    console.log('Done');
12  }
13);

Starting with async v3, the test function became asynchronous and receives a callback. If you pass a synchronous test function to async v3, it never receives the callback, so whilst never knows whether the condition is true or false. The loop simply never starts.

The fix is to update the test function to use the callback:

1// async v3 style (correct)
2async.whilst(
3  function test(cb) {
4    cb(null, count < 5); // pass result via callback
5  },
6  function iteratee(cb) {
7    count++;
8    cb(null);
9  },
10  function done(err) {
11    console.log('Done');
12  }
13);

Common Reason 2: Test Condition Starts as False

If the test condition evaluates to false on the very first check, the iteratee never runs. This is correct behavior, not a bug, but it catches developers off guard when the initial state is not what they expect.

1let items = []; // empty array
2
3async.whilst(
4  function test(cb) {
5    cb(null, items.length > 0); // false immediately
6  },
7  function iteratee(cb) {
8    // This never runs
9    console.log('Processing item');
10    items.pop();
11    cb(null);
12  },
13  function done(err) {
14    console.log('Finished'); // This DOES run
15  }
16);

If you want the iteratee to run at least once regardless of the initial condition, use async.doWhilst instead, which checks the condition after each iteration rather than before.

Common Reason 3: Forgetting to Call the Iteratee Callback

Every asynchronous function in the async library expects you to call the provided callback to signal completion. If you forget to call cb in the iteratee, the loop stalls after the first iteration.

1// BUG: cb is never called in the iteratee
2async.whilst(
3  function test(cb) {
4    cb(null, count < 5);
5  },
6  function iteratee(cb) {
7    count++;
8    console.log(count);
9    // Missing: cb(null);
10  },
11  function done(err) {
12    console.log('This never runs');
13  }
14);

The fix is straightforward: always call cb(null) at the end of your iteratee, or cb(err) if an error occurred.

Common Reason 4: Importing the Wrong Module

The async npm package must be installed and imported correctly. If you accidentally shadow it with a local variable named async or import a different module, the whilst function will not exist on the object.

// Verify you have the right module
const async = require('async');
console.log(typeof async.whilst); // should log 'function'

If this logs undefined, check your package.json to confirm the async package is listed as a dependency and run npm install to ensure it is present in node_modules.

Debugging Tips

When async.whilst is not executing, add targeted log statements to narrow down the problem:

1async.whilst(
2  function test(cb) {
3    console.log('Test called, count =', count);
4    cb(null, count < 5);
5  },
6  function iteratee(cb) {
7    console.log('Iteratee called');
8    count++;
9    cb(null);
10  },
11  function done(err) {
12    console.log('Done called, error =', err);
13  }
14);

If "Test called" never appears, the function is not being invoked at all, which points to an import or version issue. If "Test called" appears once but "Iteratee called" never does, the condition is evaluating to false. If "Iteratee called" appears once but the loop stops, the callback inside the iteratee is not being called.

Common Pitfalls

Mixing async v2 and v3 APIs. Many tutorials online show the v2 synchronous test signature. Always check which version of async you have installed with npm list async.

Swallowing errors. If you pass an error to cb(err) in the iteratee, the loop stops and calls done with the error. If your done function does not log the error, you will not see any output and may think the loop never ran.

Using async.whilst when async.eachSeries is more appropriate. If you are iterating over a known collection, eachSeries or eachLimit is usually a better fit than whilst.

Summary

When async.whilst appears to do nothing, the most likely cause is a mismatch between the test function signature and the version of the async library you are using. In async v3 and later, the test function receives a callback and must pass the boolean result through it. Other common issues include a test condition that starts as false, a missing callback in the iteratee, or an incorrect import. Adding log statements to each of the three functions (test, iteratee, done) will quickly reveal where the execution is stalling.