Skip to content
Newer
Older
100644 169 lines (113 sloc) 8.69 KB
cead1dc @olegp first commit
authored Jun 14, 2011
1 # Common Node
2
a8fcfd6 @olegp added contributing section
authored Jun 17, 2011
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 Jun 14, 2011
6
44b393c @olegp readme tweaks
authored Jun 17, 2011
7 * write fast CRUD webapps that run on Node.js without messy callbacks
5f4e6ff @olegp added platforms
authored Jun 25, 2011
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), [Erbix](http://www.erbix.com/), [Wakanda](http://www.wakanda.org/), [v8cgi](http://code.google.com/p/v8cgi/) and [other implementations](http://wiki.commonjs.org/wiki/Implementations)
cead1dc @olegp first commit
authored Jun 14, 2011
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 Jun 14, 2011
12 The following modules are included:
cead1dc @olegp first commit
authored Jun 14, 2011
13
1b94d5b @olegp jsgi https support added, need to test
authored Jun 17, 2011
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 Jun 14, 2011
15 * console - [Console](http://wiki.commonjs.org/wiki/Console) - partial implementation available in Node
4591191 @olegp updated readme
authored Aug 31, 2011
16 * system - [System/1.0](http://wiki.commonjs.org/wiki/System/1.0)
cead1dc @olegp first commit
authored Jun 14, 2011
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 Jun 17, 2011
19 * fs - [Filesystem/A](http://wiki.commonjs.org/wiki/Filesystem/A)
cead1dc @olegp first commit
authored Jun 14, 2011
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)
d8986b8 @olegp twitter example added, encourage users to test existing ringo/narhwal
authored Aug 24, 2011
22 * subprocess - methods for launching subprocesses modeled after Ringo (work in progress)
cead1dc @olegp first commit
authored Jun 14, 2011
23
24 ### Installation
25
e256406 @olegp updated bootstrap script
authored Aug 29, 2011
26 If you don't already have them, [install Node version 0.5.2 or later](https://github.com/joyent/node/wiki/Installation) (for Node 0.4.X check out the v0.4 branch of Common Node) and [Node Package Manager](http://npmjs.org). Install `common-node` as a global package:
cead1dc @olegp first commit
authored Jun 14, 2011
27
b49218d @olegp published to npm
authored Aug 29, 2011
28 sudo npm -g install common-node
cead1dc @olegp first commit
authored Jun 14, 2011
29
1afece3 @olegp npm package created
authored Jun 19, 2011
30 Run the "Hello World" example:
cead1dc @olegp first commit
authored Jun 14, 2011
31
e7c7c0b @olegp example launch fix
authored Aug 29, 2011
32 common-node $NODE_PATH/common-node/examples/hello.js
cead1dc @olegp first commit
authored Jun 14, 2011
33
b49218d @olegp published to npm
authored Aug 29, 2011
34 You shouldn't see any output. To test that it's working, make an HTTP request from another prompt:
cead1dc @olegp first commit
authored Jun 14, 2011
35
1afece3 @olegp npm package created
authored Jun 18, 2011
36 curl http://localhost:8080/
cead1dc @olegp first commit
authored Jun 14, 2011
37
38
39 ### Examples
40
c17f26e @olegp fixed broken links
authored Jun 14, 2011
41 A number of examples are available in [common-node/examples](https://github.com/olegp/common-node/tree/master/examples):
cead1dc @olegp first commit
authored Jun 14, 2011
42
43 * `hello.js` - Hello World webapp using JSGI to return a simple text response
44 * `static.js` - streams a static file as a response
45 * `http.js` - makes an HTTP request to another server and returns the result in the response
46 * `sleep.js` - sleeps for one second before returning a response
47 * `spawn.js` - spawns a new fiber which prints to stdout ten seconds after processing a request
d75a3bf @olegp twitter example
authored Aug 29, 2011
48 * `twitter.js` - an example of using Twitter's streaming API, uses HttpClient & TextStream for reading one line at a time
cead1dc @olegp first commit
authored Jun 14, 2011
49
c17f26e @olegp fixed broken links
authored Jun 14, 2011
50 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 Jun 14, 2011
51
52 ### Documentation
53
9bc3aeb @olegp updated docs link
authored Jun 14, 2011
54 The API reference is available at <http://olegp.github.com/common-node/doc/>
cead1dc @olegp first commit
authored Jun 14, 2011
55
56 ### Tests
57
04919c5 @olegp node-fibers removed
authored Aug 29, 2011
58 To run the unit tests run:
cead1dc @olegp first commit
authored Jun 14, 2011
59
04919c5 @olegp node-fibers removed
authored Aug 29, 2011
60 node test/all.js
cead1dc @olegp first commit
authored Jun 14, 2011
61
44b393c @olegp readme tweaks
authored Jun 17, 2011
62 You can also run individual tests or sets of tests, for example:
cead1dc @olegp first commit
authored Jun 14, 2011
63
04919c5 @olegp node-fibers removed
authored Aug 29, 2011
64 node test/io.js
65 node test/fs-base/all.js
cead1dc @olegp first commit
authored Jun 14, 2011
66
67 ### Benchmarks
68
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored Jun 19, 2011
69 Although `common-node` is optimized for development efficiency rather than performance,
70 a number of benchmarks are included in [common-node/benchmarks](https://github.com/olegp/common-node/tree/master/benchmarks).
71 A `common-node` version, an asynchronous Node version using Connect & a RingoJS version of each benchmark is provided.
72 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 Jun 14, 2011
73
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored Jun 19, 2011
74 The benchmarks have the following dependencies:
75
76 * `connect` for Node which can be installed via npm
99a8a57 @olegp markdown errors fixed
authored Jun 20, 2011
77 * `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 Jun 19, 2011
78 * `ab` - installed with `sudo apt-get install apache2-utils` on Debian/Ubuntu
79 * `gnuplot` - installed with `sudo apt-get install gnuplot-nox`
80
81 To run them and generate graphs, execute the following command:
82
56df9d3 @olegp running benchmarks
authored Jun 20, 2011
83 cd benchmarks/; ./run; ./graph
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored Jun 19, 2011
84
85 This will generate PNG images of the graphs in `benchmarks/results/graphs/`. Some results are provided below:
86
848482b @olegp fixes #6
authored Jun 24, 2011
87 * [buffer-alloc](http://olegp.github.com/common-node/graphs/buffer-alloc.png) - creates a number of byte arrays per request; the difference in performance compared to Node is due to the [array being cleared](https://github.com/olegp/common-node/issues/6)
99a8a57 @olegp markdown errors fixed
authored Jun 19, 2011
88 * [hello-world](http://olegp.github.com/common-node/graphs/hello-world.png) - returns a dynamically generated string
89 * [no-alloc](http://olegp.github.com/common-node/graphs/no-alloc.png)
90 * [parse-json](http://olegp.github.com/common-node/graphs/parse-json.png)
ac0fef6 @olegp added set timeout benchmark
authored Jun 22, 2011
91 * [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 Jun 19, 2011
92 * [static-file](http://olegp.github.com/common-node/graphs/static-file.png) - returns a file served from the file system
93 * [string-alloc](http://olegp.github.com/common-node/graphs/string-alloc.png)
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored Jun 19, 2011
94
848482b @olegp fixes #6
authored Jun 24, 2011
95 As you can see from the results and given no profiling or optimization work has been done so far, there's room for improvement.
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored Jun 19, 2011
96 Any patches or suggestions on how to improve performance would be greatly appreciated.
a8fcfd6 @olegp added contributing section
authored Jun 17, 2011
97
fdcf32f @olegp added embedding section
authored Jun 19, 2011
98 ### Embedding
99
04919c5 @olegp node-fibers removed
authored Aug 29, 2011
100 To use the package in your existing app, you will need to:
fdcf32f @olegp added embedding section
authored Jun 18, 2011
101
04919c5 @olegp node-fibers removed
authored Aug 29, 2011
102 * run your app with `node` instead of `common-node`
f47d75f @olegp updated embedding instructions
authored Aug 29, 2011
103 * change the way in which you require modules from `var io = require('io');` to `var io = require('common-node').io;` or update your NODE_PATH to include `common-node/lib` (see `bin/common-node` for an example)
e256406 @olegp updated bootstrap script
authored Aug 29, 2011
104
fa856a4 @olegp fixed markdown syntax in example
authored Aug 29, 2011
105 For example the following modified version of `examples/http.js` can be run directly via `node http.js`
e256406 @olegp updated bootstrap script
authored Aug 29, 2011
106
da9d696 @olegp udpated example
authored Aug 29, 2011
107 var HttpClient = require('common-node').httpclient.HttpClient;
fa856a4 @olegp fixed markdown syntax in example
authored Aug 29, 2011
108
109 exports.app = function(request) {
110 return {
111 status: 200,
112 headers: {},
113 body: new HttpClient({
114 url: 'http://google.com'
115 }).finish().body
116 };
117 };
118
119 if(require.main == module) {
120 require('common-node').run(exports);
121 }
fdcf32f @olegp added embedding section
authored Jun 18, 2011
122
a8fcfd6 @olegp added contributing section
authored Jun 17, 2011
123 ### Contributing
124
1b94d5b @olegp jsgi https support added, need to test
authored Jun 17, 2011
125 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 Jun 17, 2011
126
127 If you run into any issues along the way, whether related to using this library
3f98e1f @olegp platform list expanded
authored Jun 21, 2011
128 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 Jun 17, 2011
129
d8986b8 @olegp twitter example added, encourage users to test existing ringo/narhwal
authored Aug 24, 2011
130 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](https://github.com/olegp/common-node/wiki).
131
a8fcfd6 @olegp added contributing section
authored Jun 17, 2011
132 Finally, to find specific issues not listed on the tracker, you can run the following command from inside the `common-node` directory.
133
134 grep 'TODO' lib/*
135
44b393c @olegp readme tweaks
authored Jun 17, 2011
136 To contribute code: fork the project, make and commit your changes and send a pull request.
cead1dc @olegp first commit
authored Jun 14, 2011
137
138 ### Acknowledgements
139
140 * 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
141 * 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 Jun 19, 2011
142 * everybody on the [CommonJS](http://groups.google.com/group/commonjs) mailing list
143
144 ### License
145
146 (The MIT License)
147
148 Copyright (c) 2011 Oleg Podsechin
149
150 Permission is hereby granted, free of charge, to any person obtaining
151 a copy of this software and associated documentation files (the
152 'Software'), to deal in the Software without restriction, including
153 without limitation the rights to use, copy, modify, merge, publish,
154 distribute, sublicense, and/or sell copies of the Software, and to
155 permit persons to whom the Software is furnished to do so, subject to
156 the following conditions:
157
158 The above copyright notice and this permission notice shall be
159 included in all copies or substantial portions of the Software.
160
161 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
162 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
163 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
164 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
165 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
166 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
167 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
168
Something went wrong with that request. Please try again.