Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 157 lines (102 sloc) 8.13 kb
cead1dc @olegp first commit
authored
1 # Common Node
2
a8fcfd6 @olegp added contributing section
authored
3 This package implements a number of [CommonJS](http://www.commonjs.org)
4 proposals on top of [Node.js](http://nodejs.org) using
5 [node-fibers](https://github.com/laverdet/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:
cead1dc @olegp first commit
authored
6
44b393c @olegp readme tweaks
authored
7 * write fast CRUD webapps that run on Node.js without messy callbacks
3f98e1f @olegp platform list expanded
authored
8 * run [webapps, middleware and libraries](https://github.com/olegp/common-node/wiki) written for [RingoJS](http://ringojs.org), [Narwhal](http://narwhaljs.org/), [Akshell](http://www.akshell.com) and [other implementations](http://wiki.commonjs.org/wiki/Implementations)
cead1dc @olegp first commit
authored
9 * mix & match synchronous/asynchronous styles and use the best tool for the job by writing maintainable business logic in a synchronous manner
10 * write concise, legible shell scripts
11
adcc96a @olegp README tweaks
authored
12 The following modules are included:
cead1dc @olegp first commit
authored
13
1b94d5b @olegp jsgi https support added, need to test
authored
14 * assert - [Unit Testing/1.0](httprin://wiki.commonjs.org/wiki/Unit_Testing/1.0) & a suite for running tests
adcc96a @olegp README tweaks
authored
15 * console - [Console](http://wiki.commonjs.org/wiki/Console) - partial implementation available in Node
ff206b3 @olegp README updated
authored
16 * system - [System/1.0](http://wiki.commonjs.org/wiki/System/1.0) & methods for managing "threads" and child processes
cead1dc @olegp first commit
authored
17 * binary - [Binary/B](http://wiki.commonjs.org/wiki/Binary/B)
18 * io - [IO/A](http://wiki.commonjs.org/wiki/IO/A), including a `ByteArray` backed `MemoryStream`
44b393c @olegp readme tweaks
authored
19 * fs - [Filesystem/A](http://wiki.commonjs.org/wiki/Filesystem/A)
cead1dc @olegp first commit
authored
20 * jsgi - [JSGI 0.3](http://wiki.commonjs.org/wiki/JSGI/Level0/A/Draft2)
21 * httpclient - [HTTP Client/A](http://wiki.commonjs.org/wiki/HTTP_Client/A)
22
23 ### Installation
24
adcc96a @olegp README tweaks
authored
25 If you don't already have them, [install Node](https://github.com/joyent/node/wiki/Installation) and the [Node Package Manager npm](http://npmjs.org):
cead1dc @olegp first commit
authored
26
27 curl http://npmjs.org/install.sh | sh
28
1afece3 @olegp npm package created
authored
29 Clone the repository (an npm package will be made available once we have a stable release):
cead1dc @olegp first commit
authored
30
31 git clone git://github.com/olegp/common-node.git
1afece3 @olegp npm package created
authored
32
33 To install `node-fibers` & `common-node` as global packages:
cead1dc @olegp first commit
authored
34
1afece3 @olegp npm package created
authored
35 sudo npm -g install fibers common-node
cead1dc @olegp first commit
authored
36
1afece3 @olegp npm package created
authored
37 Run the "Hello World" example:
cead1dc @olegp first commit
authored
38
1afece3 @olegp npm package created
authored
39 common-node common-node/examples/hello.js
cead1dc @olegp first commit
authored
40
1afece3 @olegp npm package created
authored
41 To test that it's working, make an HTTP request from another prompt:
cead1dc @olegp first commit
authored
42
1afece3 @olegp npm package created
authored
43 curl http://localhost:8080/
cead1dc @olegp first commit
authored
44
45
46 ### Examples
47
c17f26e @olegp fixed broken links
authored
48 A number of examples are available in [common-node/examples](https://github.com/olegp/common-node/tree/master/examples):
cead1dc @olegp first commit
authored
49
50 * `hello.js` - Hello World webapp using JSGI to return a simple text response
51 * `static.js` - streams a static file as a response
52 * `http.js` - makes an HTTP request to another server and returns the result in the response
53 * `sleep.js` - sleeps for one second before returning a response
54 * `spawn.js` - spawns a new fiber which prints to stdout ten seconds after processing a request
55
c17f26e @olegp fixed broken links
authored
56 For more usage examples, please refer to the tests in the [common-node/test](https://github.com/olegp/common-node/tree/master/test) directory.
cead1dc @olegp first commit
authored
57
58 ### Documentation
59
9bc3aeb @olegp updated docs link
authored
60 The API reference is available at <http://olegp.github.com/common-node/doc/>
cead1dc @olegp first commit
authored
61
62 ### Tests
63
64 To run the unit tests execute the following command:
65
1d7f74a @olegp fixed node-fibers error in README
authored
66 node-fibers test/all.js
cead1dc @olegp first commit
authored
67
44b393c @olegp readme tweaks
authored
68 You can also run individual tests or sets of tests, for example:
cead1dc @olegp first commit
authored
69
1d7f74a @olegp fixed node-fibers error in README
authored
70 node-fibers test/io.js
44b393c @olegp readme tweaks
authored
71 node-fibers test/fs-base/all.js
cead1dc @olegp first commit
authored
72
73 ### Benchmarks
74
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
75 Although `common-node` is optimized for development efficiency rather than performance,
76 a number of benchmarks are included in [common-node/benchmarks](https://github.com/olegp/common-node/tree/master/benchmarks).
77 A `common-node` version, an asynchronous Node version using Connect & a RingoJS version of each benchmark is provided.
78 The scripts are based on the [Ringo/Node benchmark scripts](https://github.com/hns/ringo-node-benchmark), with a couple of additions.
cead1dc @olegp first commit
authored
79
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
80 The benchmarks have the following dependencies:
81
82 * `connect` for Node which can be installed via npm
99a8a57 @olegp markdown errors fixed
authored
83 * `ringo` which can be installed by following the instructions in the [RingoJS repository](https://github.com/ringo/ringojs)
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
84 * `ab` - installed with `sudo apt-get install apache2-utils` on Debian/Ubuntu
85 * `gnuplot` - installed with `sudo apt-get install gnuplot-nox`
86
87 To run them and generate graphs, execute the following command:
88
56df9d3 @olegp running benchmarks
authored
89 cd benchmarks/; ./run; ./graph
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
90
91 This will generate PNG images of the graphs in `benchmarks/results/graphs/`. Some results are provided below:
92
99a8a57 @olegp markdown errors fixed
authored
93 * [buffer-alloc](http://olegp.github.com/common-node/graphs/buffer-alloc.png)
94 * [hello-world](http://olegp.github.com/common-node/graphs/hello-world.png) - returns a dynamically generated string
95 * [no-alloc](http://olegp.github.com/common-node/graphs/no-alloc.png)
96 * [parse-json](http://olegp.github.com/common-node/graphs/parse-json.png)
ac0fef6 @olegp added set timeout benchmark
authored
97 * [set-timeout](http://olegp.github.com/common-node/graphs/set-timeout.png) - sleep for 100ms before returning a response
99a8a57 @olegp markdown errors fixed
authored
98 * [static-file](http://olegp.github.com/common-node/graphs/static-file.png) - returns a file served from the file system
99 * [string-alloc](http://olegp.github.com/common-node/graphs/string-alloc.png)
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
100
101 As you can see from the results and given no profiling or optimization work has been so far, there's room for improvement.
102 Any patches or suggestions on how to improve performance would be greatly appreciated.
a8fcfd6 @olegp added contributing section
authored
103
fdcf32f @olegp added embedding section
authored
104 ### Embedding
105
106 To use the package in your async app, you will need to:
107
108 * run your app with `node-fibers` instead of `node`
3282b05 @olegp embedding doc fix
authored
109 * 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')));`
fdcf32f @olegp added embedding section
authored
110
a8fcfd6 @olegp added contributing section
authored
111 ### Contributing
112
1b94d5b @olegp jsgi https support added, need to test
authored
113 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.
a8fcfd6 @olegp added contributing section
authored
114 The installation of `node-fibers` has been particularly problematic,
1b94d5b @olegp jsgi https support added, need to test
authored
115 so if you run into problems with it, please post an issue on that project's [issue tracker](https://github.com/laverdet/node-fibers/issues/).
a8fcfd6 @olegp added contributing section
authored
116
117 If you run into any issues along the way, whether related to using this library
3f98e1f @olegp platform list expanded
authored
118 in your own project or to the documentation, please post your comments on the [issue tracker](https://github.com/olegp/common-node/issues/). The tracker is also a great place to contribute ideas and find out what needs doing.
a8fcfd6 @olegp added contributing section
authored
119
120 Finally, to find specific issues not listed on the tracker, you can run the following command from inside the `common-node` directory.
121
122 grep 'TODO' lib/*
123
44b393c @olegp readme tweaks
authored
124 To contribute code: fork the project, make and commit your changes and send a pull request.
cead1dc @olegp first commit
authored
125
126 ### Acknowledgements
127
128 * Hannes Wallnoefer and others from [RingoJS](http://ringojs.org) - this project uses a number of its tests & the Ringo code was used as a starting point for some modules
129 * Kris Kowal, Tom Robinson, Isaac Schlueter for [Narwhal](http://narwhaljs.org/) - this project used a number of its modules as a starting point and some methods in e.g. Binary have been copied as is
950f757 @olegp license added
authored
130 * everybody on the [CommonJS](http://groups.google.com/group/commonjs) mailing list
131
132 ### License
133
134 (The MIT License)
135
136 Copyright (c) 2011 Oleg Podsechin
137
138 Permission is hereby granted, free of charge, to any person obtaining
139 a copy of this software and associated documentation files (the
140 'Software'), to deal in the Software without restriction, including
141 without limitation the rights to use, copy, modify, merge, publish,
142 distribute, sublicense, and/or sell copies of the Software, and to
143 permit persons to whom the Software is furnished to do so, subject to
144 the following conditions:
145
146 The above copyright notice and this permission notice shall be
147 included in all copies or substantial portions of the Software.
148
149 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
150 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
151 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
152 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
153 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
154 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
155 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
156
Something went wrong with that request. Please try again.