Skip to content
Newer
Older
100644 107 lines (66 sloc) 5.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
cead1dc @olegp first commit
authored
8 * run webapps, middleware and libraries written for [RingoJS](http://ringojs.org) and [other implementations](http://wiki.commonjs.org/wiki/Implementations)
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
14 * assert - [Unit Testing/1.0](http://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
29 Using `npm` install a global copy of `node-fibers` as root:
30
31 sudo npm install -g fibers
32
33 To install the latest version of `common-node`, clone the repository (an npm package will be made available once we have a stable release):
34
35 git clone git://github.com/olegp/common-node.git
36
37 Change to the package directory and run the "Hello World" example server:
38
1d7f74a @olegp fixed node-fibers error in README
authored
39 cd common-node; node-fibers examples/hello.js
cead1dc @olegp first commit
authored
40
41 To test that it's working as expected, make an HTTP request from another prompt:
42
43 curl http://localhost:8080/
44
45 To install `common-node` as a global package:
46
47 sudo npm -g install .
48
49 ### Examples
50
c17f26e @olegp fixed broken links
authored
51 A number of examples are available in [common-node/examples](https://github.com/olegp/common-node/tree/master/examples):
cead1dc @olegp first commit
authored
52
53 * `hello.js` - Hello World webapp using JSGI to return a simple text response
54 * `static.js` - streams a static file as a response
55 * `http.js` - makes an HTTP request to another server and returns the result in the response
56 * `sleep.js` - sleeps for one second before returning a response
57 * `spawn.js` - spawns a new fiber which prints to stdout ten seconds after processing a request
58
c17f26e @olegp fixed broken links
authored
59 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
60
61 ### Documentation
62
9bc3aeb @olegp updated docs link
authored
63 The API reference is available at <http://olegp.github.com/common-node/doc/>
cead1dc @olegp first commit
authored
64
65 ### Tests
66
67 To run the unit tests execute the following command:
68
1d7f74a @olegp fixed node-fibers error in README
authored
69 node-fibers test/all.js
cead1dc @olegp first commit
authored
70
44b393c @olegp readme tweaks
authored
71 You can also run individual tests or sets of tests, for example:
cead1dc @olegp first commit
authored
72
1d7f74a @olegp fixed node-fibers error in README
authored
73 node-fibers test/io.js
44b393c @olegp readme tweaks
authored
74 node-fibers test/fs-base/all.js
cead1dc @olegp first commit
authored
75
76 ### Benchmarks
77
c17f26e @olegp fixed broken links
authored
78 Although `common-node` is optimized for developer efficiency rather than performance, a number of benchmarks are included in [common-node/benchmarks](https://github.com/olegp/common-node/tree/master/benchmarks). A `common-node` version and an asynchronous version using Connect of each benchmark are provided. Results of these benchmarks will be included below.
cead1dc @olegp first commit
authored
79
44b393c @olegp readme tweaks
authored
80 * hello - returns a dynamically generated string
81 * static - returns a file served from the file system
82 * http - makes a request to google and returns the response
a8fcfd6 @olegp added contributing section
authored
83
84 ### Contributing
85
86 To contribute to this project, you can start by trying to run the tests on your system and posting your results (even all tests PASS) on the issue tracker.
87 The installation of `node-fibers` has been particularly problematic,
88 so if you run into problems with it, please post an issue on that project's [issue tracker](https://github.com/laverdet/node-fibers).
89
90 If you run into any issues along the way, whether related to using this library
91 in your own project or to the documentation, please post your comments on the issue tracker.
92
93 The issue tracker is also a great place to contribute ideas and find out
94 what development work needs doing.
95
96 Finally, to find specific issues not listed on the tracker, you can run the following command from inside the `common-node` directory.
97
98 grep 'TODO' lib/*
99
44b393c @olegp readme tweaks
authored
100 To contribute code: fork the project, make and commit your changes and send a pull request.
cead1dc @olegp first commit
authored
101
102 ### Acknowledgements
103
104 * 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
105 * 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
106 * everybody on the [CommonJS](http://groups.google.com/group/commonjs) mailing list
Something went wrong with that request. Please try again.