nthen

nThen... Do this... nThen... Do that.

nThen is designed to be the most small, simple and intuitive asynchronous library.

How you used to do things

x = synchronous_call();
y = use(x);
a = another_sync_call(x);          # Hey!
b = yet_another_sync_call(x);      # these two could run at the same time!
z = something_else_synchronous(b);
c = last_synchronous_call(z);
do_next_job(c);

Ok so we learned that doing it that way is slow and we have asynchronous so we never have to be slow anymore.

The naive asynchronous approach

var context = {};
async_call(function(x) {
    context.y = use(x);
    another_call(x, function(a) {
        context.a = a;
        if (context.c) { do_next_job(context); }
    });
    yet_another_call(x, function(b) {
        something_else(b, function(z) {
            last_call(z, function(c) {
                context.c = c;
                if (context.a) { do_next_job(context); }
            });
        });
    });
});

That doesn't look like very much fun :( And to make matters worse, what happens if one of those functions never returns?

var to = setTimeout(function() { abort_process(); }, 3000);

You can see where this is going.

nThen to the rescue

var nThen = require('nthen');
var context = {};
nThen(function(waitFor) {
    // Remember to wrap all of your async callbacks with waitFor()
    // otherwise they won't block the next nThen block.
    asyncCall(waitFor(function(x) {
        context.x = x;
    }));
}).nThen(function(waitFor) {
    // These two functions run at the same time :D
    anotherCall(x, waitFor(function(a) {
        context.a = a;
    }));
    yetAnotherCall(x, waitFor(function(b) {
        context.b = b;
    }));
}).nThen(function(waitFor) {
    somethingElse(b, waitFor(function(z) {
        context.z = z;
    }));
}).nThen(function(waitFor) {
    lastCall(z, waitFor(function(c) {
        context.c = c;
    }));
}).nThen(function(waitFor) {

    doNextJob(context);

}).orTimeout(function(waitFor) {

    // Using the orTimeout() function, you can chain a failure timeout.
    abortProcess();

}, 3000).nThen(function(waitFor) {
    // Finally, you can chain more nThen calls after the timeout
    // these will be excuted regardless of whether the chain times out or not.
    // think of ajax.onComplete
    someFinalCleanup();
});

Chaining is Allowed

This is perfectly ok, your second call to waitFor() will cause the second function to block the entry of the next nThen block and it will perform as expected.

nThen(function(waitFor) {
    asyncCall(waitFor(function(x) {
        iWouldReallyRatherChainThisCall(x, waitFor(function(y) {
            context.y = y;
        }));
    }));
}).nThen(function(waitFor) {

Disclamer

The variable names used in this readme are only for example and to make you mad.

License

Public Domain

ChangeLog

• 1.0 The first versions, practically perfect in every way.

• 1.1 Ok maybe practically perfect was a stretch, fixed a bug which causes incorrect behavior if the the first nThen function returns synchronously.

  nThen(function(waitFor) { console.log("this function returns synchronously"); }).nThen(function(waitFor) { console.log("This never gets executed because nThen 1.0 has a bug :("); });