async-future
Advanced tools
Readme
async-futureA simple, powerful library for managing asynchronous control flow and saner handling of asynchronous exceptions in node.js and the browser.
Simple return with error handling
var Future = require('async-future') // node.js and webpack
var f = new Future
asynchronousFunction(function(result) {
if(error) f.throw(error)
else f.return(result)
})
f.then(function(result) {
useThe(result)
}).catch(function(e) {
console.error("Oh no! "+error)
}).done()
Immediates, familar try-catch-finally semantics, and Future.wrap
var f2 = Future(45) // you can create immediately-resolved futures for convenience
var f3 = Future(undefined) // note that undefined has to be explicitly passed in
// so "Future()" won't work the same way
var futureFn2 = Future.wrap(asyncFn2) // turns an asynchronous function into a function
// that returns a future
f2.then(function(result) {
console.log(result) // prints 45
return Future(true) // returning a future passes the result of the future (in this
// case 45) to the next `then` statement
}).then(function(result2) {
console.log(result2) // prints true
return futureFn2(result2) // using the wrapped function is just like using the
// unwrapped function, but without the callback parameter
}).finally(function() {
// this is ran regardless of whether an exception was thrown above ^
}).catch(function(e){ // unlike try-catch semantics, `catch` should come after `finally`
}).done() // ensures that any exception still in the pipes here is asynchronously thrown
// (instead of being lost). This is equivalent to 'detatch' in fibers/future
function asyncFn2(parameter, /*more parameters if you want, */ callback) {
try {
callback(undefined, doStuff(parameter))
} catch(e) {
callback(e)
}
}
npm install async-future
var Future = require('async-future')
The most important part of async-future is future-chains.
These are chains that have try-catch-finally style semantics, but are asynchronous.
Future-chains consist of chains of then, catch, and finally calls and must always eventually end in a done call. When an exception is thrown (or an error-resolved future is returned) from a previous link in the chain, the error propagates down the chain to the first catch it comes across, skipping any thens and running any finallys.
The methods then, catch, and finally return a new Future that is resolved when their callback completes. The future returned by all three of these methods will resolve with an error if an exception is thrown from the callbacks.
The future returned by the methods then and catch will resolve to the following return values (non-errors):
undefined, if the callback returns undefined (ie nothing), orFuture object, it resolves to the value that future resolves toOther than undefined, you may not return a value that isn't a Future object from these callbacks.
f.then(<callback>) - executes <callback> if f is returned from. <callback> gets the return value of f as its only parameter. Returns a future that resolves when then completes or if f is resolved with an error. Does not execute the callback if f resolves to an error, but instead resolves its return value with the error from f.
f.catch(<callback>) - executes <callback> if f is thrown from. <callback> gets the error value of f as its only parameter. Returns a future that resolves when its callback completes or when f is returned from. Does not execute the callback if f resolves to a return value, but instead resolves its return value with the return value of f.
f.finally(<callback>) - executes a callback when f resolves, regardless of whether f was resolved with a return value or an error. The callback takes no arguments. Returns a future that resolves when <callback> completes or when the future it returns completes. If the future <callback> returns resolves to an exception, the future returned from finally will too. If the future <callback> returns resolves to a return value, or if <callback> returns undefined, the future finally returns will resolves to the same result as f.
f.done() - marks a future chain as done, which means that if any subsequent exceptions happen,
it will be thrown asynchronously (and likely caught by a domain if its node.js, or by window.onerror in browsers).
Every future or future-chain that won't have one of the chain-methods (or the resolver method) called on it,
should call .done(), so that thrown exceptions won't get lost.
Summary
| . | then | catch | finally |
|---|---|---|---|
| parameter | value of calling future | exception from calling future | none |
| returned future resolves to | returned future's value | returned future's value | thrown exception or calling future's value |
| exceptions thrown in callback | propogate | propogate | propogate |
f.return(<value>) - resolves a future with a return value (undefined if a value isn't passed)
f.throw(<exception>) - resolves a future with an exception
f.resolver() - returns an errback from a future. This is useful for using functions that require an errback-style callback (a function that takes two parameters, (error, result))
f.resolved() - returns true if the future has already been resolved, false otherwise.
Future.all(<futures> - returns a future that resolves when all futures inside resolve (or throws an error when one of the futures returns an error).
Future.wrap(<fn>) - wraps a function that takes an errback so that it returns a future instead of calling an errback.
Example:
function a(x, errback) {
if(x === false)
errback(Error('x isnt true : ('))
else
errback(undefined, x)
}
var aFuture = Future.wrap(a)
// prints 5
aFuture(5).then(function(result) {
console.log(result)
}).done()
// prints an exception
aFuture(false).then(function(result) {
console.log(result) // never gets here
}).done()
Future.wrap(<object>, <method) - wraps a method that takes an errback so that it returns a future instead of calling an errback. Example:
var wrappedMethod = Future.wrap(object, 'methodName')Future.error(<handler>) - sets up a function that is called when an unhandled error happens. <handler> gets one parameter, the unhandled exception. Unhandled errors happen when done is called and an exception is thrown from the future.
Future.debug - if true, gives each future a unique id (default is false)
finally where exceptions and results weren't being correctly passed throughthen callback was resolvedthen callback, where exceptions weren't being properly propogateddone method when a future with an error is returned from a then callbackAnything helps:
How to submit pull requests:
npm install at its rootReleased under the MIT license: http://opensource.org/licenses/MIT
FAQs
A powerful and yet simple futures library for javascript in node.js and in-browser.
We found that async-future demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Application Security
New SEC disclosure rules aim to enforce timely cyber incident reporting, but fear of job loss and inadequate resources lead to significant underreporting.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).
Security News
LDAPjs, an LDAP Client and Server API for Node.js, was decommissioned after its maintainer received an abusive email from a user, raising concerns about this form of abuse as a potential attack vector.