Easily mix asynchronous and synchronous programming styles in node.js
Easily mix asynchronous and synchronous programming styles in node.js.
A project by Good Eggs at https://github.com/goodeggs/fibrous.
npm install fibrous
Fibrous requires node version 0.6.x or greater.
Would you rather write this:
varUserfindOneidif err return callbackerr;usersetattributes;usersaveif err return callbackerr;console.log"Updated" updated;callbacknull updated;;;;
Or this, which behaves identically to calling code:
var updateUser = fibroususer = UsersyncfindOneid;usersetattributes;updated = usersyncsave;console.log"Updated" updated;return updated;;
Or even better, with coffeescript:
updateUser = fibroususer = UsersyncfindOneidusersetattributesupdated = usersyncsaveconsolelog"Updated"updatedupdated
Using standard node callback-style APIs without fibrous, we write (from the fs docs):
fsreadFile'/etc/passwd'if err throw err;console.logdata;;
Using fibrous, we write:
data = fssyncreadFile'/etc/passwd';console.logdata;
This is the same as writing:
future = fsfuturereadFile'/etc/passwd';data = futurewait;console.logdata;
Or for multiple files read asynchronously:
futures =fsfuturereadFile'/etc/passwd'fsfuturereadFile'/etc/hosts';data = fibrouswaitfutures;console.logdata0 data1;
fs.sync.readFile is not the same as
latter blocks while the former allows the process to continue while
waiting for the file read to complete.
Fibrous uses node-fibers behind the scenes.
sync (which uses
internally) require that they are called within a fiber. Fibrous
provides two easy ways to do this.
Pass any function to
fibrous and it returns a function that
conforms to standard node async APIs with a callback as the last
argument. The callback expects
err as the first argument and the function
result as the second. Any exception thrown will be passed to the
callback as an error.
var asynFunc = fibrousreturn fssyncreadFile'/etc/passwd';;
is functionally equivalent to:
varfsreadFile'/etc/passwd'if err return callbackerr;callbacknull data;;
With coffeescript, the fibrous version is even cleaner:
asyncFunc = fibrous ->fssyncreadFile'/etc/passwd'
fibrous ensures that the passed function is
running in an existing fiber (from higher up the call stack) or will
create a new fiber if one does not already exist.
var express = require'express';var fibrous = require'fibrous';var app = expresscreateServer;appusefibrousmiddleware;appget'/'data = fssyncreadFile'./index.html' 'utf8';ressenddata;;
Fibrous uses the
Future implementation from node-fibers.
future.wait waits for the future to resolve then returns the result while allowing the process
fibrous.wait accepts a single future, multiple future arguments or an array of futures.
It returns the result of the future if passed just one, or an array of
results if passed multiple.
future.get returns the result of the resolved future or throws an
exception if not yet resolved.
In the above examples, if
readFile produces an error, the fibrous versions
wait) will throw an exception. Additionally, the stack
trace will include the stack of the calling code unlike exceptions
typically thrown from within callback.
Fibrous provides a test helper for jasmine-node
that ensures that
afterEach run in a fiber.
Require it in your shared
spec_helper file or in the spec files where
you want to use fibrous.
require'fibrous/lib/jasmine_spec_helper';describe'My Spec'it'tests something asynchronous'data = fssyncreadFile'/etc/password';expectdatalengthtoBeGreaterThan0;;;
If an asynchronous method called through fibrous returns an error, the spec helper will fail the spec.
Fibrous can make it easier to work with asynchronous methods in the
console. It's not convenient to create a fiber to run console commands with
future is still easier than constructing callbacks in the
> fs = require('fs');> require('fibrous');> data = fs.future.readFile('/etc/passwd', 'utf8');> data.get()
In this example,
data.get() will return the result of the future
provided you have waited long enough (not very long) for the future to
Function.prototype so you can
use them directly as in:
readFile = require'fs'readFile;data = readFilesync'/etc/passwd';
Object.prototype correctly so they
are not enumerable.
These proxy methods also ignore all getters, even those that may return functions. If you need to call a getter with fibrous that returns an asynchronous function, you can do:
func = objgetterfuncfuturecallobj args
Some people don't like libraries that mix in to Object.prototype and Function.prototype. If that's how you feel, then fibrous is probably not for you. We've been careful to mix in 'right' so that we don't change property enumeration and find that the benefits of having sync and future available without explicitly wrapping objects or functions are worth the philosophical tradeoffs.
The first time you call
future on an object, it builds the sync
and future proxies so if you add a method to the object later, it will
not be proxied.
git clone git://github.com/goodeggs/fibrous.gitnpm installnpm test
Fibrous is written in coffeescript with
src/ compiled to
Tests are written with jasmine-node in
Run tests with
npm test which will also compile the coffeescript to
Pull requests are welcome. Please provide tests for your changes and features. Thanks!
(The MIT License)
Copyright (c) 2012 Good Eggs, Inc.
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.