Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

213 lines (148 sloc) 7.43 KB


streamline.js is a language tool to simplify asynchronous Javascript programming.

Instead of writing hairy code like:

function lineCount(path, callback) {
  fs.readFile(path, "utf8", function(err, data) {
    if (err) { callback(err); return; }
    callback(null, data.split('\n').length);

Streamline.js lets you write:

function lineCount(path, _) {
  return fs.readFile(path, "utf8", _).split('\n').length;

You just have to follow a simple rule:

Replace all callbacks by an underscore and write your code as if all functions were synchronous.

Streamline will transform the code and generate the callbacks for you!

And streamline is not limited to a subset of Javascript. You can use all the flow control features of Javascript in your asynchronous code: conditionals, loops, try/catch/finally blocks, anonymous functions, this, etc.

Streamline also provides futures, and additional builtin functions for asynchronous programming.


The easiest way to install streamline.js is with NPM:

npm install streamline -g

The -g option installs it globally. You can also install it locally, without -g but then the _node and _coffee commands will not be in your default PATH.

Note: If you encounter a permission error when installing on UNIX systems, you should retry with sudo.

The global installation option makes _node globally accessible but it does not expose the Javascript support modules (runtime.js, flows.js, etc.) globally. If you need these modules anywhere in your development tree, for example because you use streamline in shell scripts (see below), you should npm link streamline to the root of your development tree:

cd $myworkdir
npm link streamline

If you want to use the fibers option (see below), you must also install the fibers library:

npm install fibers [-g]

Hello World

Streamline modules have ._js or ._coffee extensions and you run them with the _node or _coffee loader.


echo "console.log('hello ...');" > hello._js
echo "setTimeout(_, 1000);" >> hello._js
echo "console.log('... world');" >> hello._js
_node hello


echo "console.log 'hello ...'" > hello._coffee
echo "setTimeout _, 1000" >> hello._coffee
echo "console.log '... world'" >> hello._coffee
_coffee hello

You can also create standalone shell utilities:

echo "#!/usr/bin/env _node" >
cat hello._js >>
chmod +x


echo "#!/usr/bin/env _coffee" >
cat hello._coffee >>
chmod +x

You can also create your own loader and run your program with node or coffee. See the loader example

Generation options

Streamline gives you the choice between generating regular callback-based asynchronous code, or generating code that takes advantage of the fibers library.

The callback option produces code that does not have any special runtime dependencies. You may even use it to generate asynchronous code for the browser.

The fibers option produces simpler code but requires that you install the fibers library (easy: npm install fibers). This option gives superior development experience: line numbers are always preserved in the transformed code; you can step with the debugger through asynchronous calls without having to go through complex callbacks, etc. It may also generate more efficient code (to be confirmed by benchmarks).

The fibers option can be activated by passing --fibers to the _node command or by setting the fibers option when registering streamline (see the register(options) function in streamline/lib/compiler/register).

Interoperability with standard node.js code

You can call standard node functions from streamline code. For example the fs.readFile function:

function lineCount(path, _) {
  return fs.readFile(path, "utf8", _).split('\n').length;

You can also call streamline functions as if they were standard node functions. For example:

lineCount("", function(err, result) {
  if (err) return console.error("ERROR: " + err.message);
  console.log("README has " + result + " lines.");

And you can mix streamline functions, classical callback based code and synchrononous functions in the same file. Streamline will only transform the functions that have the special _ parameter.

Note: this works with both transformation options. Even if you use the fibers option, you can seamlessly call standard callback based node APIs and the asynchronous functions that you create with streamline have the standard node callback signature.

On-line demo

You can test streamline.js directly with the on-line demo

Browser-side use

The streamline compiler generates vanilla Javascript code that may be run browser-side too.

You can also transform the code in the browser with the transform API. See examples/streamlineMe for an example.

The streamline-require package contains a small infrastructure to load streamline and regular JS modules from the browser.


The examples/diskUsage directory contains a simple example that traverses directories to compute disk usage. You can run it as follows:

node-streamline diskUsage
node diskUsage # requires r/w access to the examples directory

The diskUsage2.js example is a faster variant that parallelizes I/O operations with futures. You'll also find CoffeeScript versions of these examples.


The functions generated by streamline return a future if you call them without a callback. This gives you an easy way to run several asynchronous operations in parallel and resynchronize later. See the futures wiki page for details.

The following subdirectories contain various modules that have been written with streamline.js:

  • lib/util: utilities for array manipulation, semaphores, etc.
  • lib/streams: pull-mode API for node.js streams.
  • lib/tools: small tools (doc generator for file).

Related Packages

The following packages use streamline.js:


The API is documented here.
The wiki give more information on advanced topics.

For support and discussion, please join the streamline.js Google Group.


See the AUTHORS file.

Special thanks to Marcel Laverdet who contributed the fibers implementation.


This work is licensed under the MIT license.

Jump to Line
Something went wrong with that request. Please try again.