async-flo v0.0.4

Flo

Flo is a node module that provides asynchronous control flow helper functions. Specifically, Flo enables ES7 style async/await support through the use of ES6 generators. It also provides an alternative to Promise.All() that supports limiting the number of concurrent async operations.

async/await

You can achieve synchronous use of asynchronous functions similar to async/await by writing your functions as ES6 generators and wrapping them in a call to flo(). Example:

let flo = require('async-flo');

// example function
let displayPosts = flo(function*(username, password) {
    let loginToken = yield login(username, password),
        posts = yield getPosts(token);

    console.log(posts);
});

displayPosts('joe', 'password');

Here login() and getPosts() are asynchronous functions that return a Promise. By yielding the promises inside of our flo-wrapped function we get the same functionality as using await.

Any function we create in this manner still runs asynchronously, and actually returns a Promise itself. So for example this is also valid:

displayPosts('joe', 'password').then(value => {
    console.log('All of the posts have been displayed!');
});

Queues

Flo provides an alternative to Promise.All() in the form of a simple queue object. You create Flo queues by calling flo.queue() and passing an asynchronous function and the limit of concurrent asynchronous operations to perform.

You add items to the queue by calling .push() and passing any arguments that are needed by the original asynchronous function. You can then process the queue by calling .run() which returns a promise similar in behavior to Promise.All().

let flo = require('async-flo');

//example function
let downloadFiles = flo(function*(files) {
    let queue = flo.queue(fetchFile, 2); // limit to two concurrent file downloads

    for (let file of files) {
        queue.push(file);
    }

    return yield queue.run();
});

let files = ['file1.txt', 'file2.txt', 'file3.txt', 'file4.txt'];
downloadFiles(files).then(values => console.log(values));

Traditional Callbacks

Many libraries are still designed to use traditional callbacks, but Flo relies on the use of the ES6 Promise object. If your code uses traditional callbacks you will need to wrap the asynchronous functions with flo.wrap() first.

// traditional asynchronous function that takes a callback
function asyncStuff(data, callback) {
    // simulate an async operation such as an AJAX request or
    // file operation using setTimeout, delay 1 second
    setTimeout(function() {
        if (callback) callback(null, 'complete!');
    }, 1000);
}

// create a wrapped version that uses promises
let pAsyncStuff = flo.wrap(asyncStuff);

pAsyncStuff(1000).then(value => {
    console.log(value) // 'complete!'
});

License

(MIT License)

Copyright (c) 2017 Chris Frazier

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.