Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 238 lines (156 sloc) 11.508 kb
cead1dc Oleg Podsechin first commit
authored
1 # Common Node
2
a8fcfd6 Oleg Podsechin 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 Oleg Podsechin first commit
authored
6
8a0c57e Oleg Podsechin Update README.md
authored
7 * write fast CRUD webapps that run on Node.js without messy callbacks and with very little overhead
5f4e6ff Oleg Podsechin added platforms
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), [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 Oleg Podsechin 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
6935f37 Oleg Podsechin Update README.md
authored
12 If you have a spare 20 minutes, you can also check out [this presentation](http://www.slideshare.net/olegp/server-side-javascript-going-all-the-way) (audio included). If you have any questions, you can find help on IRC, channel [#common-node](irc://irc.freenode.net/common-node) on freenode.
172fd1e Oleg Podsechin readme updated
authored
13
6935f37 Oleg Podsechin Update README.md
authored
14 For a real world application using Common Node, take a look at the [Minimal CMS](https://github.com/olegp/mcms).
0263ff2 Oleg Podsechin Update README.md
authored
15
adcc96a Oleg Podsechin README tweaks
authored
16 The following modules are included:
cead1dc Oleg Podsechin first commit
authored
17
dcc22ab Oleg Podsechin fixes #11
authored
18 * assert - [Unit Testing/1.0](http://wiki.commonjs.org/wiki/Unit_Testing/1.0) (available in Node) & a suite for running tests
adcc96a Oleg Podsechin README tweaks
authored
19 * console - [Console](http://wiki.commonjs.org/wiki/Console) - partial implementation available in Node
4591191 Oleg Podsechin updated readme
authored
20 * system - [System/1.0](http://wiki.commonjs.org/wiki/System/1.0)
cead1dc Oleg Podsechin first commit
authored
21 * binary - [Binary/B](http://wiki.commonjs.org/wiki/Binary/B)
22 * io - [IO/A](http://wiki.commonjs.org/wiki/IO/A), including a `ByteArray` backed `MemoryStream`
44b393c Oleg Podsechin readme tweaks
authored
23 * fs - [Filesystem/A](http://wiki.commonjs.org/wiki/Filesystem/A)
da9eee9 Oleg Podsechin references #31
authored
24 * httpserver - [JSGI 0.3](http://wiki.commonjs.org/wiki/JSGI/Level0/A/Draft2) compatible HTTP server
cead1dc Oleg Podsechin first commit
authored
25 * httpclient - [HTTP Client/A](http://wiki.commonjs.org/wiki/HTTP_Client/A)
c1966ec Oleg Podsechin readme updated
authored
26 * subprocess - methods for launching subprocesses modeled after Ringo
e2e7de8 Oleg Podsechin socket skeleton
authored
27 * socket - [Sockets/A](http://wiki.commonjs.org/wiki/Sockets/A) (work in progress)
cead1dc Oleg Podsechin first commit
authored
28
29 ### Installation
30
75b11db Oleg Podsechin Edited README.md via GitHub
authored
31 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). It's also highly recommended that you have your $NODE_PATH variable [set correctly](https://github.com/olegp/common-node/issues/20).
83a5901 Oleg Podsechin Edited README.md via GitHub
authored
32
09ef6ad Oleg Podsechin Update master
authored
33 Install `common-node` as a global package:
cead1dc Oleg Podsechin first commit
authored
34
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
35
36 ```bash
308a273 Oleg Podsechin Update master
authored
37 [sudo] npm -g install common-node
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
38 ```
cead1dc Oleg Podsechin first commit
authored
39
1afece3 Oleg Podsechin npm package created
authored
40 Run the "Hello World" example:
cead1dc Oleg Podsechin first commit
authored
41
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
42
43 ```bash
44 common-node $NODE_PATH/common-node/examples/hello.js
45 ```
cead1dc Oleg Podsechin first commit
authored
46
b49218d Oleg Podsechin published to npm
authored
47 You shouldn't see any output. To test that it's working, make an HTTP request from another prompt:
cead1dc Oleg Podsechin first commit
authored
48
49
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
50 ```bash
51 curl http://localhost:8080/
52 ```
cead1dc Oleg Podsechin first commit
authored
53
54 ### Examples
55
c17f26e Oleg Podsechin fixed broken links
authored
56 A number of examples are available in [common-node/examples](https://github.com/olegp/common-node/tree/master/examples):
cead1dc Oleg Podsechin first commit
authored
57
58 * `hello.js` - Hello World webapp using JSGI to return a simple text response
59 * `static.js` - streams a static file as a response
60 * `http.js` - makes an HTTP request to another server and returns the result in the response
61 * `sleep.js` - sleeps for one second before returning a response
62 * `spawn.js` - spawns a new fiber which prints to stdout ten seconds after processing a request
d75a3bf Oleg Podsechin twitter example
authored
63 * `twitter.js` - an example of using Twitter's streaming API, uses HttpClient & TextStream for reading one line at a time
99d2ce6 Oleg Podsechin Edited README.md via GitHub
authored
64 * `chat.js` - Telnet chat server, compare this to an [async implementation](http://pastebin.com/Rhbbr6Tf)
cead1dc Oleg Podsechin first commit
authored
65
c17f26e Oleg Podsechin fixed broken links
authored
66 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 Oleg Podsechin first commit
authored
67
7516999 Oleg Podsechin Update README.md
authored
68 If you're looking for an Express like framework that works with Common Node, take a look at [Stick](https://github.com/olegp/stick/). There's also the [Notes example webapp](https://github.com/olegp/notes) which uses Stick and a MongoDB data store.
6935f37 Oleg Podsechin Update README.md
authored
69
70 Common Node also works well with [CoffeeScript](http://coffeescript.org/), check out [this example](https://gist.github.com/1447709).
71
cead1dc Oleg Podsechin first commit
authored
72 ### Documentation
73
9bc3aeb Oleg Podsechin updated docs link
authored
74 The API reference is available at <http://olegp.github.com/common-node/doc/>
cead1dc Oleg Podsechin first commit
authored
75
8c77279 Oleg Podsechin doc generation instructions
authored
76 To generate the documentation, install RingoJS and run:
77
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
78
79 ```bash
80 ringo-doc -n "Common Node" -s ./lib -d ./doc --file-urls
81 ```
8c77279 Oleg Podsechin doc generation instructions
authored
82
cead1dc Oleg Podsechin first commit
authored
83 ### Tests
84
04919c5 Oleg Podsechin node-fibers removed
authored
85 To run the unit tests run:
cead1dc Oleg Podsechin first commit
authored
86
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
87
88 ```bash
89 node test/all.js
90 ```
cead1dc Oleg Podsechin first commit
authored
91
44b393c Oleg Podsechin readme tweaks
authored
92 You can also run individual tests or sets of tests, for example:
cead1dc Oleg Podsechin first commit
authored
93
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
94
95 ```bash
96 node test/io.js
97 node test/fs-base/all.js
98 ```
cead1dc Oleg Podsechin first commit
authored
99
100 ### Benchmarks
101
e448d12 Oleg Podsechin benchmark graphs added to readme, minor benchmark fixes
authored
102 Although `common-node` is optimized for development efficiency rather than performance,
103 a number of benchmarks are included in [common-node/benchmarks](https://github.com/olegp/common-node/tree/master/benchmarks).
104 A `common-node` version, an asynchronous Node version using Connect & a RingoJS version of each benchmark is provided.
105 The scripts are based on the [Ringo/Node benchmark scripts](https://github.com/hns/ringo-node-benchmark), with a couple of additions.
cead1dc Oleg Podsechin first commit
authored
106
e448d12 Oleg Podsechin benchmark graphs added to readme, minor benchmark fixes
authored
107 The benchmarks have the following dependencies:
108
109 * `connect` for Node which can be installed via npm
99a8a57 Oleg Podsechin markdown errors fixed
authored
110 * `ringo` which can be installed by following the instructions in the [RingoJS repository](https://github.com/ringo/ringojs)
e448d12 Oleg Podsechin benchmark graphs added to readme, minor benchmark fixes
authored
111 * `ab` - installed with `sudo apt-get install apache2-utils` on Debian/Ubuntu
112 * `gnuplot` - installed with `sudo apt-get install gnuplot-nox`
113
114 To run them and generate graphs, execute the following command:
115
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
116
117 ```bash
118 cd benchmarks/; ./run; ./graph
119 ```
120
e448d12 Oleg Podsechin benchmark graphs added to readme, minor benchmark fixes
authored
121 This will generate PNG images of the graphs in `benchmarks/results/graphs/`. Some results are provided below:
122
848482b Oleg Podsechin fixes #6
authored
123 * [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 Oleg Podsechin markdown errors fixed
authored
124 * [hello-world](http://olegp.github.com/common-node/graphs/hello-world.png) - returns a dynamically generated string
125 * [no-alloc](http://olegp.github.com/common-node/graphs/no-alloc.png)
126 * [parse-json](http://olegp.github.com/common-node/graphs/parse-json.png)
ac0fef6 Oleg Podsechin added set timeout benchmark
authored
127 * [set-timeout](http://olegp.github.com/common-node/graphs/set-timeout.png) - sleep for 100ms before returning a response
99a8a57 Oleg Podsechin markdown errors fixed
authored
128 * [static-file](http://olegp.github.com/common-node/graphs/static-file.png) - returns a file served from the file system
129 * [string-alloc](http://olegp.github.com/common-node/graphs/string-alloc.png)
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
130
848482b Oleg Podsechin fixes #6
authored
131 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 Oleg Podsechin benchmark graphs added to readme, minor benchmark fixes
authored
132 Any patches or suggestions on how to improve performance would be greatly appreciated.
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
133
fdcf32f Oleg Podsechin added embedding section
authored
134 ### Embedding
135
04739d8 Oleg Podsechin Update README.md
authored
136 You can use Common Node without invoking the `common-node` binary. There are two ways to do this:
137
138 * the bootstrapped approach allows you to run your Common Node code as is, but prevents you from accessing core Node modules such as `fs` (by over-riding that with Common Node's `fs` module instead)
139 * the mixed mode approach allows you to use Commo Node along side your existing Node specific code
140
141 #### Bootstrapped
142
143 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:
144
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
145
146 ```js
147 require('common-node').run('./main');
148 ```
04739d8 Oleg Podsechin Update README.md
authored
149
150 Then, instead of starting your app with `common-node main.js`, run `node index.js`.
151
152 #### Mixed Mode
153
154 To use Common Node alongside your existing Node code, you will need to:
fdcf32f Oleg Podsechin added embedding section
authored
155
04919c5 Oleg Podsechin node-fibers removed
authored
156 * run your app with `node` instead of `common-node`
f47d75f Oleg Podsechin updated embedding instructions
authored
157 * 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)
9ff9525 Oleg Podsechin Update README.md
authored
158 * make sure any synchronous code is inside a fiber that has been created with `spawn` (in the example below each call of exports.app runs in a new fiber)
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
159
fa856a4 Oleg Podsechin fixed markdown syntax in example
authored
160 For example the following modified version of `examples/http.js` can be run directly via `node http.js`
e256406 Oleg Podsechin updated bootstrap script
authored
161
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
162
163 ```js
164 var HttpClient = require('common-node').httpclient.HttpClient;
165
166 exports.app = function(request) {
167 return {
168 status: 200,
169 headers: {},
170 body: new HttpClient({
171 url: 'http://google.com'
172 }).finish().body
173 };
174 };
175
176 if (require.main == module) {
177 require('common-node').run(exports);
178 }
179 ```
fdcf32f Oleg Podsechin added embedding section
authored
180
a8fcfd6 Oleg Podsechin added contributing section
authored
181 ### Contributing
182
34f7847 Oleg Podsechin install from git instructions
authored
183 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:
184
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
185
186 ```bash
187 npm install -g https://github.com/olegp/common-node/tarball/master
188 ```
a8fcfd6 Oleg Podsechin added contributing section
authored
189
190 If you run into any issues along the way, whether related to using this library
3f98e1f Oleg Podsechin platform list expanded
authored
191 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 Oleg Podsechin added contributing section
authored
192
1a1fcb9 Oleg Podsechin Merge branch 'master' of git@github.com:olegp/common-node.git
authored
193 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](https://github.com/olegp/common-node/wiki).
d8986b8 Oleg Podsechin twitter example added, encourage users to test existing ringo/narhwal
authored
194
fae6021 Oleg Podsechin TODO link
authored
195 To find specific issues not listed on the tracker, you can run the following command from inside the `common-node` directory.
a8fcfd6 Oleg Podsechin added contributing section
authored
196
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
197
198 ```bash
199 grep 'TODO' lib/*
200 ```
a8fcfd6 Oleg Podsechin added contributing section
authored
201
44b393c Oleg Podsechin readme tweaks
authored
202 To contribute code: fork the project, make and commit your changes and send a pull request.
cead1dc Oleg Podsechin first commit
authored
203
fae6021 Oleg Podsechin TODO link
authored
204 A number of higher level goals, such as descriptions of packages that would complement Common Node are listed on the [TODO wiki page](https://github.com/olegp/common-node/wiki/TODO).
205
cead1dc Oleg Podsechin first commit
authored
206 ### Acknowledgements
207
4921b38 Oleg Podsechin Update README.md
authored
208 * Marcel Laverdet for [node-fibers](https://github.com/laverdet/node-fibers)
cead1dc Oleg Podsechin first commit
authored
209 * 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
210 * 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 Oleg Podsechin license added
authored
211 * everybody on the [CommonJS](http://groups.google.com/group/commonjs) mailing list
70caff0 Akzhan Abdulin Use GFM in README.
akzhan authored
212
213 ### License
950f757 Oleg Podsechin license added
authored
214
215 (The MIT License)
216
107f711 Oleg Podsechin Update README.md
authored
217 Copyright (c) 2011+ Oleg Podsechin
950f757 Oleg Podsechin license added
authored
218
219 Permission is hereby granted, free of charge, to any person obtaining
220 a copy of this software and associated documentation files (the
221 'Software'), to deal in the Software without restriction, including
222 without limitation the rights to use, copy, modify, merge, publish,
223 distribute, sublicense, and/or sell copies of the Software, and to
224 permit persons to whom the Software is furnished to do so, subject to
225 the following conditions:
226
227 The above copyright notice and this permission notice shall be
228 included in all copies or substantial portions of the Software.
229
230 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
231 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
232 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
233 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
234 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
235 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
236 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
237
Something went wrong with that request. Please try again.