Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 190 lines (125 sloc) 10.579 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
8a0c57e @olegp Update README.md
authored
7 * write fast CRUD webapps that run on Node.js without messy callbacks and with very little overhead
5f4e6ff @olegp 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 @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
6935f37 @olegp 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 @olegp readme updated
authored
13
6935f37 @olegp 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 @olegp Update README.md
authored
15
adcc96a @olegp README tweaks
authored
16 The following modules are included:
cead1dc @olegp first commit
authored
17
dcc22ab @olegp 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 @olegp README tweaks
authored
19 * console - [Console](http://wiki.commonjs.org/wiki/Console) - partial implementation available in Node
4591191 @olegp updated readme
authored
20 * system - [System/1.0](http://wiki.commonjs.org/wiki/System/1.0)
cead1dc @olegp 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 @olegp readme tweaks
authored
23 * fs - [Filesystem/A](http://wiki.commonjs.org/wiki/Filesystem/A)
cead1dc @olegp first commit
authored
24 * jsgi - [JSGI 0.3](http://wiki.commonjs.org/wiki/JSGI/Level0/A/Draft2)
25 * httpclient - [HTTP Client/A](http://wiki.commonjs.org/wiki/HTTP_Client/A)
c1966ec @olegp readme updated
authored
26 * subprocess - methods for launching subprocesses modeled after Ringo
e2e7de8 @olegp socket skeleton
authored
27 * socket - [Sockets/A](http://wiki.commonjs.org/wiki/Sockets/A) (work in progress)
cead1dc @olegp first commit
authored
28
29 ### Installation
30
75b11db @olegp 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 @olegp Edited README.md via GitHub
authored
32
6935f37 @olegp Update README.md
authored
33 Install `common-node` as a global package (use `sudo` if you're on Ubuntu):
cead1dc @olegp first commit
authored
34
6935f37 @olegp Update README.md
authored
35 npm -g install 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
e7c7c0b @olegp example launch fix
authored
39 common-node $NODE_PATH/common-node/examples/hello.js
cead1dc @olegp first commit
authored
40
b49218d @olegp published to npm
authored
41 You shouldn't see any output. 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
d75a3bf @olegp twitter example
authored
55 * `twitter.js` - an example of using Twitter's streaming API, uses HttpClient & TextStream for reading one line at a time
99d2ce6 @olegp Edited README.md via GitHub
authored
56 * `chat.js` - Telnet chat server, compare this to an [async implementation](http://pastebin.com/Rhbbr6Tf)
cead1dc @olegp first commit
authored
57
c17f26e @olegp fixed broken links
authored
58 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
59
6935f37 @olegp Update README.md
authored
60 If you're looking for an Express like framework that works with Common Node, take a look at [Stick](https://github.com/olegp/stick/), in particular the [skeleton app](https://github.com/olegp/stick/tree/master/examples/skeleton) in examples.
61
62 Common Node also works well with [CoffeeScript](http://coffeescript.org/), check out [this example](https://gist.github.com/1447709).
63
cead1dc @olegp first commit
authored
64 ### Documentation
65
9bc3aeb @olegp updated docs link
authored
66 The API reference is available at <http://olegp.github.com/common-node/doc/>
cead1dc @olegp first commit
authored
67
8c77279 @olegp doc generation instructions
authored
68 To generate the documentation, install RingoJS and run:
69
70 ringo-doc -n "Common Node" -s ./lib -d ./doc --file-urls
71
cead1dc @olegp first commit
authored
72 ### Tests
73
04919c5 @olegp node-fibers removed
authored
74 To run the unit tests run:
cead1dc @olegp first commit
authored
75
04919c5 @olegp node-fibers removed
authored
76 node test/all.js
cead1dc @olegp first commit
authored
77
44b393c @olegp readme tweaks
authored
78 You can also run individual tests or sets of tests, for example:
cead1dc @olegp first commit
authored
79
04919c5 @olegp node-fibers removed
authored
80 node test/io.js
81 node test/fs-base/all.js
cead1dc @olegp first commit
authored
82
83 ### Benchmarks
84
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
85 Although `common-node` is optimized for development efficiency rather than performance,
86 a number of benchmarks are included in [common-node/benchmarks](https://github.com/olegp/common-node/tree/master/benchmarks).
87 A `common-node` version, an asynchronous Node version using Connect & a RingoJS version of each benchmark is provided.
88 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
89
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
90 The benchmarks have the following dependencies:
91
92 * `connect` for Node which can be installed via npm
99a8a57 @olegp markdown errors fixed
authored
93 * `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
94 * `ab` - installed with `sudo apt-get install apache2-utils` on Debian/Ubuntu
95 * `gnuplot` - installed with `sudo apt-get install gnuplot-nox`
96
97 To run them and generate graphs, execute the following command:
98
56df9d3 @olegp running benchmarks
authored
99 cd benchmarks/; ./run; ./graph
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
100
101 This will generate PNG images of the graphs in `benchmarks/results/graphs/`. Some results are provided below:
102
848482b @olegp fixes #6
authored
103 * [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
104 * [hello-world](http://olegp.github.com/common-node/graphs/hello-world.png) - returns a dynamically generated string
105 * [no-alloc](http://olegp.github.com/common-node/graphs/no-alloc.png)
106 * [parse-json](http://olegp.github.com/common-node/graphs/parse-json.png)
ac0fef6 @olegp added set timeout benchmark
authored
107 * [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
108 * [static-file](http://olegp.github.com/common-node/graphs/static-file.png) - returns a file served from the file system
109 * [string-alloc](http://olegp.github.com/common-node/graphs/string-alloc.png)
e448d12 @olegp benchmark graphs added to readme, minor benchmark fixes
authored
110
848482b @olegp fixes #6
authored
111 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
112 Any patches or suggestions on how to improve performance would be greatly appreciated.
a8fcfd6 @olegp added contributing section
authored
113
fdcf32f @olegp added embedding section
authored
114 ### Embedding
115
04919c5 @olegp node-fibers removed
authored
116 To use the package in your existing app, you will need to:
fdcf32f @olegp added embedding section
authored
117
04919c5 @olegp node-fibers removed
authored
118 * run your app with `node` instead of `common-node`
f47d75f @olegp updated embedding instructions
authored
119 * 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
120
fa856a4 @olegp fixed markdown syntax in example
authored
121 For example the following modified version of `examples/http.js` can be run directly via `node http.js`
e256406 @olegp updated bootstrap script
authored
122
da9d696 @olegp udpated example
authored
123 var HttpClient = require('common-node').httpclient.HttpClient;
fa856a4 @olegp fixed markdown syntax in example
authored
124
125 exports.app = function(request) {
126 return {
127 status: 200,
128 headers: {},
129 body: new HttpClient({
130 url: 'http://google.com'
131 }).finish().body
132 };
133 };
134
135 if(require.main == module) {
136 require('common-node').run(exports);
137 }
fdcf32f @olegp added embedding section
authored
138
a8fcfd6 @olegp added contributing section
authored
139 ### Contributing
140
34f7847 @olegp install from git instructions
authored
141 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:
142
143 npm install -g https://github.com/olegp/common-node/tarball/master
a8fcfd6 @olegp added contributing section
authored
144
145 If you run into any issues along the way, whether related to using this library
3f98e1f @olegp platform list expanded
authored
146 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
147
1a1fcb9 @olegp Merge branch 'master' of git@github.com:olegp/common-node.git
authored
148 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 @olegp twitter example added, encourage users to test existing ringo/narhwal
authored
149
fae6021 @olegp TODO link
authored
150 To find specific issues not listed on the tracker, you can run the following command from inside the `common-node` directory.
a8fcfd6 @olegp added contributing section
authored
151
152 grep 'TODO' lib/*
153
44b393c @olegp readme tweaks
authored
154 To contribute code: fork the project, make and commit your changes and send a pull request.
cead1dc @olegp first commit
authored
155
fae6021 @olegp TODO link
authored
156 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).
157
cead1dc @olegp first commit
authored
158 ### Acknowledgements
159
4921b38 @olegp Update README.md
authored
160 * Marcel Laverdet for [node-fibers](https://github.com/laverdet/node-fibers)
cead1dc @olegp first commit
authored
161 * 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
162 * 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
163 * everybody on the [CommonJS](http://groups.google.com/group/commonjs) mailing list
164
165 ### License
166
167 (The MIT License)
168
169 Copyright (c) 2011 Oleg Podsechin
170
171 Permission is hereby granted, free of charge, to any person obtaining
172 a copy of this software and associated documentation files (the
173 'Software'), to deal in the Software without restriction, including
174 without limitation the rights to use, copy, modify, merge, publish,
175 distribute, sublicense, and/or sell copies of the Software, and to
176 permit persons to whom the Software is furnished to do so, subject to
177 the following conditions:
178
179 The above copyright notice and this permission notice shall be
180 included in all copies or substantial portions of the Software.
181
182 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
183 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
184 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
185 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
186 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
187 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
188 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
189
Something went wrong with that request. Please try again.