Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Branch: v0.4
Fetching contributors…

Cannot retrieve contributors at this time

161 lines (105 sloc) 8.9 kB

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:

The following modules are included:

  • assert - Unit Testing/1.0 & a suite for running tests
  • console - Console - partial implementation available in Node
  • system - System/1.0 & methods for managing "threads" and child processes
  • binary - Binary/B
  • io - IO/A, including a ByteArray backed MemoryStream
  • fs - Filesystem/A
  • jsgi - JSGI 0.3
  • httpclient - HTTP Client/A
  • subprocess - methods for launching subprocesses modeled after Ringo (work in progress)

Installation

If you don't already have them, install Node version 4.8.X and the Node Package Manager npm:

curl http://npmjs.org/install.sh | sh

Clone the repository (an npm package will be made available once we have a stable release):

git clone git://github.com/olegp/common-node.git

To install node-fibers & common-node as global packages:

sudo npm -g install fibers common-node  

Run the "Hello World" example:

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

To test that it's working, make an HTTP request from another prompt:

curl http://localhost:8080/

Examples

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

  • hello.js - Hello World webapp using JSGI to return a simple text response
  • static.js - streams a static file as a response
  • http.js - makes an HTTP request to another server and returns the result in the response
  • sleep.js - sleeps for one second before returning a response
  • spawn.js - spawns a new fiber which prints to stdout ten seconds after processing a request & twitter.js - an example of using Twitter's streaming API, uses HttpClient & TextStream for reading one line at a time

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

Documentation

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

Tests

To run the unit tests execute the following command:

node-fibers test/all.js

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

node-fibers test/io.js
node-fibers 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:

  • connect for Node which can be installed via npm
  • ringo which can be installed by following the instructions in the RingoJS repository
  • ab - installed with sudo apt-get install apache2-utils on Debian/Ubuntu
  • gnuplot - installed with sudo apt-get install gnuplot-nox

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

To use the package in your async app, you will need to:

  • run your app with node-fibers instead of node
  • change the way in which you require modules from var io = require('io'); to var io = require('common-node').io; or run the following on initialization: require.paths.push(require('path').dirname(require.resolve('common-node')));

Contributing

To contribute to this project, you can start by trying to run the tests on your system and posting your results (even if all tests pass) on the issue tracker. The installation of node-fibers has been particularly problematic, so if you run into problems with it, please post an issue on that project's issue tracker.

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 packages is compatible with Common Node, feel free to add it to the wiki.

Finally, 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.

Acknowledgements

  • Hannes Wallnoefer and others from RingoJS - this project uses a number of its tests & the Ringo code was used as a starting point for some modules
  • Kris Kowal, Tom Robinson, Isaac Schlueter for Narwhal - this project used a number of its modules as a starting point and some methods in e.g. Binary have been copied as is
  • everybody on the CommonJS mailing list

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.

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