async-magic

Promises FTW! A pure promised based, straight forward async library for Node.js >=7.6.

yarn add async-magic --save

Features

Convert callback based functions into promised based once (with named functions)
Advanced promised based control flows (parallel, series)
Run a set of promised functions in parallel with given number of maximum parallel tasks
Queue promised based function including arguments
Standalone, no external dependencies required
Designed to run with the pure power of native Promise, await and async function
No backward compatibility layer

API

promisify - Promisify a callback-based function
promisifyAll - Promisify a set of callback-based functions
parallel - Executes multiple PromiseResolver in parallel with given task limit
series - Executes multiple PromiseResolver in series
PromiseResolver - Utility function to cache a promised function including arguments for resolving. Required for advanced, promised based, control flows
wait - Promise.all alias
sleep - Intercept the current function execution
Mutex - asynchronous Mutex lock pattern

promisify

Description: Promisify a callback-based function

Requirements:

Last function argument has to be the callback (Nodejs Standard)
The first argument of the callback has to be a possible error (Nodejs Standard)

Syntax: fn:function = promisify(fn:function, [functionName:String])

Arguments:

fn:function - the callback based function which should be converted into a promise based
functionName:String(optinal) - an optional name which is used as native js function name

Example:

const _asyncMagic = require('async-magic');
const _fs = require('fs');

// create promisified fs-stat. set "stat" as native function name
const fsStat = _asyncMagic.promisify(_fs, 'stat');

// use promisified version
(async function(){
    const fstats = await _fsStat(__filename);
    console.log('Size:', fstats.size);
})();

promisifyAll

Description: Promisify a set of callback-based functions

Syntax: promisifiedFunctionSet:Object = promisifyAll(functionSet:Object, functionNames:StringArray)

Arguments:

functionSet:Object - a set of functions identified by the objects keys
functionNames:StringArray - a list of the object keys which should be promisified (names are also taken as native function names!)

Example:

Promisify some fs functions. Just as showcase, take a look at fs-magic - it is based on async-magic.

const _asyncMagic = require('async-magic');
const _fs = require('fs');

// list of fs methods to promisify
const fsApi = [
    'access',
    'appendFile',
    'chmod'
];

// create promisified fs version
const _fsPromised = _asyncMagic.promisifyAll(_fs, fsApi);

// use promisified version
(async function(){
    const fstats = await _fsPromised.stat(__filename);
    console.log('Size:', fstats.size);
})();

parallel

Description: Executes multiple PromiseResolver in parallel with given task limit

Syntax: results:array = parallel(resolvers:array, [limit:int=1000])

const _asyncMagic = require('async-magic');
const _fsMagic = require('fs-magic');
const PromiseResolver = _asyncMagic.PromiseResolver;

(async function(){
    // task list
    const tasks = [];
    
    // stat a large list of files 
    tasks.push(PromiseResolver(_fsMagic.stat, 'file1.txt'));
    tasks.push(PromiseResolver(_fsMagic.stat, 'file2.txt'));
    ...
    tasks.push(PromiseResolver(_fsMagic.stat, 'fileN.txt'));
    
    // resolves the promise with predefined arguments
    // limit the number of parallel executed promises to 100 (IO handle limitation)
    const stats = await _asyncMagic.parallel(tasks, 100);
})();

series

Description: Executes multiple PromiseResolver in series

Syntax: results:array = series(resolvers:array, [failOnError:boolean=true])

In case failOnError is not set, the resultset will contain the error object thrown during execution. Otherwise the executor will abort directly if an error has been thrown.

const _asyncMagic = require('async-magic');
const _fsMagic = require('fs-magic');
const PromiseResolver = _asyncMagic.PromiseResolver;

(async function(){
    // task list
    const tasks = [];
    
    // stat a large list of files 
    tasks.push(PromiseResolver(_fsMagic.stat, 'file1.txt'));
    tasks.push(PromiseResolver(_fsMagic.stat, 'file2.txt'));
    ...
    tasks.push(PromiseResolver(_fsMagic.stat, 'fileN.txt'));
    
    // resolves the promise with predefined arguments)
    const stats = await _asyncMagic.series(tasks);
})();

PromiseResolver

Description: Utility function to cache a promised function including arguments for resolving. Required for advanced, promised based, control flows

Syntax: p:PromiseResolver = PromiseResolver(fn:function, [...args:any])

const _asyncMagic = require('async-magic');
const _fsMagic = require('fs-magic');
const PromiseResolver = _asyncMagic.PromiseResolver;

(async function(){
    // caches the function with given arguments
    const task = PromiseResolver(_fsMagic.stat, 'file1.txt');
    
    // resolves the promise with predefined arguments
    const stat = await task.resolve();
})();

wait

Description: A Promise.all alias - waits until each promise has been completed or a single error occurs

Syntax: p:Promise = wait(promises:Array)

const _asyncMagic = require('async-magic');
const _fsMagic = require('fs-magic');

// stat multiple files at once
(async function(){
    const stats = await _asyncMagic.wait([
        _fsMagic.stat('file1.txt'),
        _fsMagic.stat('file2.txt'),
        _fsMagic.stat('file3.txt')
    ]);
})();

sleep

Description: Intercept the current function exection for a given time asynchronous (does not stop the global event loop!)

Syntax: p:Promise = sleep(time:int)

const _asyncMagic = require('async-magic');

(async function(){
    console('Hello..');

    // stop function execution for 1s (asynchronous!)
    await _asyncMagic.sleep(1000);

    console.log('World');
})();

Mutex

Description: Mutex lock pattern for asynchronous operations

Syntax: p:Mutex = new Mutex()

const _asyncMagic = require('async-magic');

(async function IOtask(){
   // create Mutex
    const mutex = new _asyncMagic.Mutex();

    // acquire lock
    await mutex.acquire();

    // do something exclusively
    await directIoOperation();

    // unlock
    mutex.release();
})();

FAQ

What is the difference between named and anonymous functions ? (promisify)

Named functions contains its function-name as immutable .name attribute. This is especially useful during debugging, because the stacktrace will display the plain-text function name instead of "anonymous"

const _asyncMagic = require('../async-magic');
const _fs = require('fs');

// create a unnamed (standard) version and a named one
const promisedStat = _asyncMagic.promisify(_fs.stat);
const namedPromisedStat = _asyncMagic.promisify(_fs.stat, 'stat');

// show function names (immutable .name attribute is set)
console.log(promisedStat.name); //=> anonymous
console.log(namedPromisedStat.name); //=> stat

Any Questions ? Report a Bug ? Enhancements ?

Please open a new issue on GitHub

License

async-magic is OpenSource and licensed under the Terms of The MIT License

npkgz/async-magic