gen-sync is a simple library that allows you to call any asynchronous function in a synchronous way using generators introduced in nodejs 4.X.X and above. This library is lightweight, non blocking, and requires no changes to existing asynchronous functions to use.
Sync Reference
sync([function run], continue, context)
return the response of the asyncronous function
[function run]: a function used to execute a target asyncronous function
continue: a boolean to determin if the whole Sync process should exit, default is false. When an error occurs an event is triggered, this is where the error is handled. This is the default behavior in gen-sync, if you'd like to overwrite this behavior, set this parameter to true
context: this is a class instance used to bind to the target asyncronous function (optional)
[[function async]]: a list of asyncronous functions to run in parallel
[function gather]: a function that is executed when the results of one of the async functions returns (optional)
continue: a boolean to determin if the whole Sync process should exit, default is false. When an error occurs an event is triggered, this is where the error is handled. This is the default behavior in gen-sync, if you'd like to overwrite this behavior, set this parameter to true
cb
A generic callback you can use in any target asyncronous function, its tied to the current gen-sync instance (see example below)
throw(err, _continue)
used to manually emit an error (see examples below)
err: a string or Error instance represtending the error
continue: a boolean to determin if the whole Sync process should exit, default is false. When an error occurs an event is triggered, this is where the error is handled. This is the default behavior in gen-sync, if you'd like to overwrite this behavior, set this parameter to true
next(response)
used to manually trigger the next yield execution (see examples below)
Sync events
.on('err', function(err){})
When an error occurs within an asyncronous function, the process is stopped and an error is emmitted to this event
async.each events
.on('data', function(data, index){})
When an asyncronous function results come in, this event is emitted
.on('end', function(data, index){})
When all asyncronous functions are complted, this even is emitted
Basic Usage (See "Error Handling" before getting started)
//since the only argument is the callback, gen-sync will handle it behind the scenes
var response =yieldasyncfunction()
console.log(response)//my response!
})
Error Handling
Errors are handled in multiple ways in gen-sync, the default behavior is to emit the error and stop any further execution of code within the Sync process. The library knows if an error occured if one of the arguments returned from an async function is an instance of the internal "Error" class within nodejs.
There are ways to overwrite this default behavior to suit ones needs, see below
Making things synchronous is awesome and can make code much more readable, but what's so great about javascript is it's asynchronous nature, sometimes we want to run multiple asynchronous functions at the same time, because we don't care what async function finishes first, we just care when a group of async functions are done executing.