Automatically migrated from Gitolite

Sven Slootweg 0d7a2b8e9c 1.0.1 4 years ago
lib 94531f7fea 1.0.0 4 years ago
src 94531f7fea 1.0.0 4 years ago
.gitignore 89edbbe1f4 .gitignore created by brackets-git extension 4 years ago 325c44ac00 Fix recursion example in documentation to return the last result correctly 4 years ago
gulpfile.js 94531f7fea 1.0.0 4 years ago
index.js 94531f7fea 1.0.0 4 years ago
package.json 0d7a2b8e9c 1.0.1 4 years ago
test.js 94531f7fea 1.0.0 4 years ago


An asynchronous while-loop implementation with full support for Promises - both for the main logic, and for the predicate function.

A word of caution

Think very carefully before using a while loop for asynchronous code. In many cases, it will be cleaner to simply use recursion - if the code is asynchronous, this will never cause stack overflows, no matter how many levels you nest. In fact, recursion is what this module uses internally; it's the only real way to implement asynchronous loops.

A simple example of using recursion, without promise-while-loop:

var Promise = require("bluebird");
var bhttp = require("bhttp");

function loop(pageNumber) {
	return Promise.try(function() {
		return bhttp.get("" + pageNumber);
	}).then(function(response) {
		if (response.headers["x-next-page"] != null) {
			return Promise.try(function() {
				return loop(response.headers["x-next-page"]);
			}).then(function(recursiveResults) {
				return [response.body].concat(recursiveResults);
		} else {
			// Done looping
			return [response.body];

Promise.try(function() {
	var i = 0;
	return loop(1);
}).then(function(results) {
	// Now `results` is an array that contains the response for each HTTP request made.

If you're sure that you can write cleaner code with a while loop than through recursion, then this is the module for you :)


WTFPL or CC0, whichever you prefer. A donation and/or attribution are appreciated, but not required.


My income consists largely of donations for my projects. If this module is useful to you, consider making a donation!

You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else.


Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in src/, not those in lib/.

Build tool of choice is gulp; simply run gulp while developing, and it will watch for changes.

Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.


A simple (contrived) example:

var i = 0;

Promise.try(function() {
	return whileLoop(function(lastResult) {
		return Promise.try(function() {
			return lastResult < 20;
		}).delay(500); // Artificial delay, to prove that this really is asynchronous
	}, function(lastResult) {
		return Promise.try(function() {
			var currentIteration = i;
			i += 1;
			console.log("Last iteration: " + lastResult + " // Current iteration: " + currentIteration + " // Next iteration: " + i);
			return currentIteration;			
}).then(function(results) {
	console.log("i: " + i + " // Results: " + results)


whileLoop(predicate, func)

Initiates the loop. The loop will always run at least once - the predicate function will only be called after the first iteration.

  • predicate: This should be a function, returning either true or false (or a Promise that resolves to either of those) - depending on whether the loop should continue running or not. It receives a single argument, containing the result (return/resolve value) of the 'main function' from the last iteration.
  • func: This should be a function, optionally returning a Promise or synchronous value. It's the 'main' function that contains the 'body' of the loop - ie. the code that is executed on each iteration. It also receives a single argument, with the result of the last operation - except for the first iteration, where it contains undefined, as there is no previous result to provide.

The whileLoop call will return a Promise, collect the results into an (ordered) array, and resolve with that array once the loop has finished. Any kind of rejection/thrown error, in either the predicate function or the main body, will immediately abort the loop, and reject the returned Promise with the error that caused it.