Home

Awesome

Common Node

This package implements a number of CommonJS proposals on top of Node.js using node-fibers. Fibers are used to emulate multi-threading within a single process, allowing one to use a synchronous programming style and as a result:

For an example of a production app using Common Node, check out StartHQ.

If you have a spare 20 minutes, you can also check out this presentation (audio included). If you have any questions about Common Node, or mongo-sync, stick and other libraries built on top of it, please post them to the Common Node mailing list or IRC, channel #common-node on Freenode.

For a real world application using Common Node, take a look at the Minimal CMS.

The following modules are included:

Installation

If you don't already have them, install Node version 0.10.0 or later (previous versions for Node going back as far as 0.4.0 are also available in NPM) and Node Package Manager. It's also highly recommended that you have your $NODE_PATH variable set correctly.

Install common-node as a global package:

[sudo] npm -g install common-node

Run the "Hello World" example:

common-node $NODE_PATH/common-node/examples/hello.js

You shouldn't see any output. To test that it's working, make an HTTP request from another prompt:

curl http://localhost:8080/

Note: by default the port used is 8080 - to change this add the port number you want as the last command line argument.

Examples

A number of examples are available in common-node/examples:

For more usage examples, please refer to the tests in the common-node/test directory.

If you're looking for an Express like framework that works with Common Node, take a look at Stick. There's also the Notes example webapp which uses Stick and a MongoDB data store.

Common Node also works well with CoffeeScript, check out this example.

Documentation

The API reference is available at http://olegp.github.com/common-node/doc/

To generate the documentation, install RingoJS and run:

ringo-doc -n "Common Node" -s ./lib -d ./doc --file-urls

Tests

Build Status

To run the unit tests run:

node test/all.js

You can also run individual tests or sets of tests, for example:

node test/io.js
node test/fs-base/all.js

Benchmarks

Although common-node is optimized for development efficiency rather than performance, a number of benchmarks are included in common-node/benchmarks. A common-node version, an asynchronous Node version using Connect & a RingoJS version of each benchmark is provided. The scripts are based on the Ringo/Node benchmark scripts, with a couple of additions.

The benchmarks have the following dependencies:

To run them and generate graphs, execute the following command:

cd benchmarks/; ./run; ./graph

This will generate PNG images of the graphs in benchmarks/results/graphs/. Some results are provided below:

As you can see from the results and given no profiling or optimization work has been done so far, there's room for improvement. Any patches or suggestions on how to improve performance would be greatly appreciated.

Embedding

You can use Common Node without invoking the common-node binary. There are two ways to do this:

Bootstrapped

To bootstrap Common Node & assuming your app's entry point is in main.js, simply add an index.js with the following contents to the same directory:

require('common-node').run('./main');

Then, instead of starting your app with common-node main.js, run node index.js.

Mixed Mode

To use Common Node alongside your existing Node code, you will need to:

For example the following modified version of examples/http.js can be run directly via node http.js

var HttpClient = require('common-node').httpclient.HttpClient;

exports.app = function(request) {
  return {
    status: 200,
    headers: {},
    body: new HttpClient({
      url: 'http://google.com'
    }).finish().body
  };
};

if (require.main == module) {
  require('common-node').run(exports);
}

Contributing

To contribute to this project, you can start by trying to run the tests on your system and posting any failures on the issue tracker. It is advised that you use the version in master for doing this, which you can install via:

npm install -g https://github.com/olegp/common-node/tarball/master

If you run into any issues along the way, whether related to using this library in your own project or to the documentation, please post your comments on the issue tracker. The tracker is also a great place to contribute ideas and find out what needs doing.

If you're coming from Ringo or Narwhal, please try running the tests for some of your existing packages. If the tests pass and the package is compatible with Common Node, feel free to add it to the wiki.

To find specific issues not listed on the tracker, you can run the following command from inside the common-node directory.

grep 'TODO' lib/*

To contribute code: fork the project, make and commit your changes and send a pull request.

A number of higher level goals, such as descriptions of packages that would complement Common Node are listed on the TODO wiki page.

Maintainers

Acknowledgements

License

(The MIT License)

Copyright (c) 2011+ Oleg Podsechin

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.