Permalink
Browse files

Add readme! And move comments there.

  • Loading branch information...
1 parent 1dffe97 commit ae962e79496bd24540896ff3f66431a604dbdb06 @aseemk committed Jun 24, 2012
Showing with 82 additions and 13 deletions.
  1. +82 −0 README.md
  2. +0 −13 index.coffee
View
@@ -0,0 +1,82 @@
+# Express-Streamline
+
+Monkey-patches [Express](http://expressjs.com/) to add support for
+[Streamline](https://github.com/Sage/streamlinejs) syntax in routes.
+
+See the example and details below.
+
+## Installation
+
+```
+npm install express-streamline
+```
+
+## Usage
+
+You can either `require()` Express normally and then monkey-patch it:
+
+```js
+var express = require('express');
+require('express-streamline');
+```
+
+Or just `require()` this module, which returns the monkey-patched Express for
+convenience:
+
+```js
+var express = require('express-streamline');
+```
+
+## Example
+
+```js
+var express = require('express-streamline');
+var app = express.createServer();
+
+// ...
+
+app.get('/user/:id', function (req, res, _) {
+ var user = User.getByUsername(req.params.id, _);
+ var favs = user.getFavorites(_);
+
+ res.render('user', {
+ user: user,
+ favs: favs,
+ });
+});
+```
+
+## Details
+
+Express routes can be asynchronous, and so they take a `next()` callback. But
+this `next()` callback isn't quite like typical Node async callbacks — it
+can't be called to signal successful completion *without triggering the next
+matching route or middleware*.
+
+This doesn't work well with tools like Streamline, which are built for typical
+Node async callbacks. So this plugin simply monkey-patches Express to support
+calling the `next()` callback without error *without triggering the next
+matching route or middleware*.
+
+**Note that this means multiple routes can no longer handle a single URL.**
+In other words, route handlers become the final handlers for any given URL.
+But that's the typical style of writing MVC apps anyway, so this trade-off
+might not be a trade-off to you at all (it isn't in any app I've written).
+
+If you have any questions or comments, don't hesitate to reach out. =)
+
+## TODO
+
+This only patches HTTP servers; patch HTTPS ones too. Is there a way to do
+that in a generic way?
+
+Investigate support for Express 3 / Connect 2.
+
+## License
+
+MIT. © 2012 Aseem Kishore <aseem.kishore@gmail.com>.
+
+## Credits
+
+[TJ Holowaychuk](https://github.com/visionmedia) for the awesome Express, and
+[Bruno Jouhier](https://github.com/bjouhier) for the awesome Streamline.
View
@@ -1,16 +1,3 @@
-# express-streamline.coffee
-# Monkey-patches Express to support Streamline syntax. Require this instead of
-# Express directly. TODO FIXME This doesn't monkey-patch HTTPS servers yet.
-#
-# Specifically, Express's next() callback isn't quite like the regular Node
-# style/convention -- you can't use it to signal completion w/out error.
-# That is, if you call next() at all -- even as next(undefined), which in
-# regular Node convention means "completed w/out error" -- Express goes into
-# error handling mode. And in this case, it chokes handling a null error.
-#
-# As a workaround for this, we wrap Express methods to support regular Node-
-# style callbacks, which lets us use Streamline syntax in our handlers.
-
module.exports = express = require 'express'
# wraps the streamline-style handler (req, res, _) to the style express

0 comments on commit ae962e7

Please sign in to comment.