Sequencr.promiseChain

Sequencr.promiseChain(callbacks)

Description

Calls a chain of functions in order similar to Sequencer.chain, except using promises. This is useful for functions that contain asynchronous operations.

Sequencr.promiseChain is a bit different from JavaScript's Promise.all, which executes all the functions at once, returning an array of values. It's more like a chain of Promise.then. For instance,

var myPromise = (new Promise(function(r, t){function1(r, t)}))
    .then(function(value){return new Promise(function(r, t){function2(r, t, value)})})
    .then(function(value){return new Promise(function(r, t){function3(r, t, value)})});

becomes this (functions 1, 2, and 3 accept the same parameters as above):

var myPromise = Sequencr.promiseChain([function1, function2, function3]);

Arguments:

callbacks: An array of functions to be called one at a time. Functions may accept three parameters: resolve, reject, and value. The callbacks should call either resolve or reject at some point, when their work is done (read about promise usage). The value parameter will contain the value passed to resolve of the previously called function. Return values are ignored.

Examples

Basic Usage

var myPromise = Sequencr.promiseChain([
    (resolve, reject) => {
        resolve(100); //Arbitrary value.
    }, 
    (resolve, reject, x) => {
        resolve(x * 2);
    }, 
    (resolve, reject, x) = >{
        resolve(x + 10);
    }
]);
 
//Whenever/later:
myPromise.then(x => console.log(x)}); //Will print 210, given the above sequence.

Sequencr.promiseChain returns a reference to the very last promise in the chain. The nice thing about using Sequencr.js over native promises is that Sequencr.js creates and manages the actual promises themselves. All you need to worry about is calling resolve or reject when your work is done.

Here's a more practical example involving a fairly common chain of http requests.

Sequencr.promiseChain([
    //GET AN ACCESS TOKEN
    (resolve, reject) => {
        console.log("Getting access token.");
            $.get("http://jsideris.github.io/Sequencr.js/access_token", 
                {username: "jsideris", password: "123456789"})
                .done(data => {
                    console.log("Access token is: " + data);
                    resolve(data); //Return, pass access token into next function.
                }).fail(data => reject("Failed to get access token."));
    }, 
    //USE THE TOKEN TO ACCESS PRIVATE CONTENT
    (resolve, reject, accessToken) => {
        $.get("http://jsideris.github.io/Sequencr.js/secret_file?accesstoken=" 
            + accessToken)
            .done(function(data){resolve(data);})
            .fail(function(data){reject("Failed get secret file.");});
    }
]).then(data => {
    //PRINT FILE TO CONSOLE.
    console.log("Successfully retrieved file:");
    console.log(data);
}).catch(reason => {
    //ONE OF THE ABOVE ASYNC REQUESTS FAILED.
    console.log(reason);
});

Please note that at the moment, the scope of this may change (just as it would with native promise methodologies). You can change the scope manually by passing anonymous functions into Sequencr.promiseChain that, in turn, use JavaScript's native call or apply methods to set the desired scope. For instance,

function Obj(){
    this.x = 0;
    this.setX = (x, callback) => {
        this.x = x;
        console.log("x set to " + x);
        callback();
    }
}

var myObj = new Obj();

Sequencr.promiseChain([
    resolve => myObj.setX.call(myObj, 10, resolve), 
    resolve => myObj.setX.call(myObj, 5, resolve)
]);

I will be looking into fixing this problem in a future update so that it's more consistent with the other methods in this library.

There isn't much more to say since this is just an extension of functionality that's already built into JavaScript. If you're not familiar with promises, there are plenty of resources available online (especially check out YouTube, and while you're at it, subscribe to my channel - https://www.youtube.com/c/joshsideris).