Release 2.4.0

ex:

  res.status(500).send("lame")

History.md

@@ -1,5 +1,49 @@
 
-2.3.7 / 2011-05-23 
+2.4.0 / 2011-06-28 
+==================
+
+  * Added chainable `res.status(code)`
+  * Added `res.json()`, an explicit version of `res.send(obj)`
+  * Added simple web-service example
+
+2.3.12 / 2011-06-22 
+==================
+
+  * \#express is now on freenode! come join!
+  * Added `req.get(field, param)`
+  * Added links to Japanese documentation, thanks @hideyukisaito!
+  * Added; the `express(1)` generated app outputs the env
+  * Added `content-negotiation` example
+  * Dependency: connect >= 1.5.1 < 2.0.0
+  * Fixed view layout bug. Closes #720
+  * Fixed; ignore body on 304. Closes #701
+
+2.3.11 / 2011-06-04 
+==================
+
+  * Added `npm test`
+  * Removed generation of dummy test file from `express(1)`
+  * Fixed; `express(1)` adds express as a dep
+  * Fixed; prune on `prepublish`
+
+2.3.10 / 2011-05-27 
+==================
+
+  * Added `req.route`, exposing the current route
+  * Added _package.json_ generation support to `express(1)`
+  * Fixed call to `app.param()` function for optional params. Closes #682
+
+2.3.9 / 2011-05-25 
+==================
+
+  * Fixed bug-ish with `../' in `res.partial()` calls
+
+2.3.8 / 2011-05-24
+==================
+
+  * Fixed `app.options()`
+
+2.3.7 / 2011-05-23
 ==================
 
   * Added route `Collection`, ex: `app.get('/user/:id').remove();`

Readme.md

@@ -20,6 +20,23 @@ or to access the `express(1)` executable install globally:
 
     $ npm install -g express
 
+## Quick Start
+
+ The quickest way to get started with express is to utilize the executable `express(1)` to generate an application as shown below:
+
+ Create the app:
+
+    $ npm install -g express
+    $ express /tmp/foo && cd /tmp/foo
+
+ Install dependencies:
+
+    $ npm install -d
+
+ Start the server:
+
+    $ node app.js
+
 ## Features
 
   * Robust routing
@@ -58,6 +75,7 @@ The following are the major contributors of Express (in no specific order).
 
 ## More Information
 
+  * #express on freenode
   * [express-expose](http://github.com/visionmedia/express-expose) expose objects, functions, modules and more to client-side js with ease
   * [express-configure](http://github.com/visionmedia/express-configuration) async configuration support
   * [express-messages](http://github.com/visionmedia/express-messages) flash notification rendering helper
@@ -67,6 +85,7 @@ The following are the major contributors of Express (in no specific order).
   * Follow [tjholowaychuk](http://twitter.com/tjholowaychuk) on twitter for updates
   * [Google Group](http://groups.google.com/group/express-js) for discussion
   * Visit the [Wiki](http://github.com/visionmedia/express/wiki)
+  * [日本語ドキュメンテーション](http://hideyukisaito.com/doc/expressjs/) by [hideyukisaito](https://github.com/hideyukisaito)
   * Screencast - [Introduction](http://bit.ly/eRYu0O)
   * Screencast - [View Partials](http://bit.ly/dU13Fx)
   * Screencast - [Route Specific Middleware](http://bit.ly/hX4IaH)

bin/express

@@ -11,7 +11,7 @@ var fs = require('fs')
  * Framework version.
  */
 
-var version = '2.3.8';
+var version = '2.4.0';
 
 /**
  * Add session support.
@@ -149,33 +149,6 @@ var stylus = [
   , '  color #00B7FF'
 ].join('\n');
 
-/**
- * App test template.
- */
-
-var appTest = [
-    ""
-  , "// Run $ expresso"
-  , ""
-  , "/**"
-  , " * Module dependencies."
-  , " */"
-  , ""
-  , "var app = require('../app')"
-  , "  , assert = require('assert');"
-  , "",
-  , "module.exports = {"
-  , "  'GET /': function(){"
-  , "    assert.response(app,"
-  , "      { url: '/' },"
-  , "      { status: 200, headers: { 'Content-Type': 'text/html; charset=utf-8' }},"
-  , "      function(res){"
-  , "        assert.includes(res.body, '<title>Express</title>');"
-  , "      });"
-  , "  }"
-  , "};"
-].join('\n');
-
 /**
  * App template.
  */
@@ -218,7 +191,7 @@ var app = [
   , '});'
   , ''
   , 'app.listen(3000);'
-  , 'console.log("Express server listening on port %d", app.address().port);'
+  , 'console.log("Express server listening on port %d in %s mode", app.address().port, app.settings.env);'
   , ''
 ].join('\n');
 
@@ -318,9 +291,6 @@ function createApplicationAt(path) {
           break;
       }
     });
-    mkdir(path + '/test', function(){
-      write(path + '/test/app.test.js', appTest);
-    });
 
     // CSS Engine support
     switch (cssEngine) {
@@ -343,19 +313,21 @@ function createApplicationAt(path) {
     // Template support
     app = app.replace(':TEMPLATE', templateEngine);
 
-    write(path + '/app.js', app);
+    // package.json
+    var json = '{\n';
+    json += '    "name": "application-name"\n';
+    json += '  , "version": "0.0.1"\n';
+    json += '  , "private": true\n';
+    json += '  , "dependencies": {\n';
+    json += '      "express": "' + version + '"\n';
+    if (cssEngine) json += '    , "' + cssEngine + '": ">= 0.0.1"\n';
+    if (templateEngine) json += '    , "' + templateEngine + '": ">= 0.0.1"\n';
+    json += '  }\n';
+    json += '}';
 
-    // Suggestions
-    process.on('exit', function(){
-      if (cssEngine) {
-        console.log('   - make sure you have installed %s: \x1b[33m$ npm install %s\x1b[0m'
-          , cssEngine
-          , cssEngine);
-      }
-      console.log('   - make sure you have installed %s: \x1b[33m$ npm install %s\x1b[0m'
-        , templateEngine
-        , templateEngine);
-    });
+
+    write(path + '/package.json', json);
+    write(path + '/app.js', app);
   });
 }
 

docs/applications.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {

docs/contrib.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {
@@ -192,10 +193,9 @@
 				</ul>
 <h3>Development Dependencies</h3>
 
-<p>Express development dependencies are stored within the <em>./support</em> directory. To
-update them execute:</p>
+<p>First install the dev dependencies by executing the following command in the repo&rsquo;s directory:</p>
 
-<pre><code>$ git submodule update --init
+<pre><code>$ npm install
 </code></pre>
 
 <h3>Running Tests</h3>

docs/executable.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {

docs/guide.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {
@@ -202,6 +203,7 @@
 <li><a href="#req.accepts()">accepts()</a></li>
 <li><a href="#req.is()">is()</a></li>
 <li><a href="#req.param()">param()</a></li>
+<li><a href="#req.get()">get()</a></li>
 <li><a href="#req.flash()">flash()</a></li>
 <li><a href="#req.isxmlhttprequest">isXMLHttpRequest</a></li>
 </ul></li>
@@ -255,6 +257,31 @@
 <pre><code>$ npm install express
 </code></pre>
 
+<p>or to access the <code>express(1)</code> executable install globally:</p>
+
+<pre><code>$ npm install -g express
+</code></pre>
+
+<h2>Quick Start</h2>
+
+<p> The quickest way to get started with express is to utilize the executable <code>express(1)</code> to generate an application as shown below:</p>
+
+<p> Create the app:</p>
+
+<pre><code>$ npm install -g express
+$ express /tmp/foo &amp;&amp; cd /tmp/foo
+</code></pre>
+
+<p> Install dependencies:</p>
+
+<pre><code>$ npm install -d
+</code></pre>
+
+<p> Start the server:</p>
+
+<pre><code>$ node app.js
+</code></pre>
+
 <h3 id="creating-a server">Creating A Server</h3>
 
 <p> To create an instance of the <em>express.HTTPServer</em>, simply invoke the <em>createServer()</em> method. With our instance <em>app</em> we can then define routes based on the HTTP verbs, in this example <em>app.get()</em>.</p>
@@ -505,7 +532,7 @@ var app = express.createServer(
 
 <p>Alternatively we can <em>use()</em> them which is useful when adding middleware within <em>configure()</em> blocks, in a progressive manor.</p>
 
-<pre><code>app.use(express.logger({ format: ':method :uri' }));
+<pre><code>app.use(express.logger({ format: ':method :url' }));
 </code></pre>
 
 <p>Typically with connect middleware you would <em>require(&lsquo;connect&rsquo;)</em> like so:</p>
@@ -772,16 +799,6 @@ is present, which is useful for developing apps that rely heavily on client-side
 });
 </code></pre>
 
-<p>For simple cases such as route placeholder validation and coercion we can simple pass a callback which has an arity of 1 (accepts one argument). Any errors thrown will be passed to <em>next(err)</em>.</p>
-
-<pre><code>app.param('number', function(n){ return parseInt(n, 10); });
-</code></pre>
-
-<p>We may also apply the same callback to several placeholders, for example a route GET <em>/commits/:from-:to</em> are both numbers, so we may define them as an array:</p>
-
-<pre><code>app.param(['from', 'to'], function(n){ return parseInt(n, 10); });
-</code></pre>
-
 <h3 id="view-rendering">View Rendering</h3>
 
 <p>View filenames take the form &ldquo;&lt;name&gt;.&lt;engine&gt;&rdquo;, where &lt;engine&gt; is the name
@@ -916,14 +933,14 @@ app.use(express.session({ secret: "keyboard cat" }));
 
 <p>By default the <em>session</em> middleware uses the memory store bundled with Connect, however many implementations exist. For example <a href="http://github.com/visionmedia/connect-redis">connect-redis</a> supplies a <a href="http://code.google.com/p/redis/">Redis</a> session store and can be used as shown below:</p>
 
-<pre><code>var RedisStore = require('connect-redis');
+<pre><code>var RedisStore = require('connect-redis')(express);
 app.use(express.cookieParser());
 app.use(express.session({ secret: "keyboard cat", store: new RedisStore }));
 </code></pre>
 
 <p>Now the <em>req.session</em> and <em>req.sessionStore</em> properties will be accessible to all routes and subsequent middleware. Properties on <em>req.session</em> are automatically saved on a response, so for example if we wish to shopping cart data:</p>
 
-<pre><code>var RedisStore = require('connect-redis');
+<pre><code>var RedisStore = require('connect-redis')(express);
 app.use(express.bodyParser());
 app.use(express.cookieParser());
 app.use(express.session({ secret: "keyboard cat", store: new RedisStore }));
@@ -1067,6 +1084,18 @@ can perform any request assertion you wish.</p>
 should be an object. This can be done by using
 the _express.bodyParser middleware.</p>
 
+<h3 id="req.get()">req.get(field, param)</h3>
+
+<p> Get <em>field</em>&rsquo;s <em>param</em> value, defaulting to &lsquo;&rsquo; when the <em>param</em>
+ or <em>field</em> is not present.</p>
+
+<pre><code> req.get('content-disposition', 'filename');
+ // =&gt; "something.png"
+
+ req.get('Content-Type', 'boundary');
+ // =&gt; "--foo-bar-baz"
+</code></pre>
+
 <h3 id="req.flash()">req.flash(type[, msg])</h3>
 
 <p>Queue flash <em>msg</em> of the given <em>type</em>.</p>

docs/guide.md

@@ -2,6 +2,27 @@
 
     $ npm install express
 
+or to access the `express(1)` executable install globally:
+
+    $ npm install -g express
+
+## Quick Start
+
+ The quickest way to get started with express is to utilize the executable `express(1)` to generate an application as shown below:
+
+ Create the app:
+
+    $ npm install -g express
+    $ express /tmp/foo && cd /tmp/foo
+
+ Install dependencies:
+
+    $ npm install -d
+
+ Start the server:
+
+    $ node app.js
+
 ### Creating A Server
 
  To create an instance of the _express.HTTPServer_, simply invoke the _createServer()_ method. With our instance _app_ we can then define routes based on the HTTP verbs, in this example _app.get()_.
@@ -594,13 +615,13 @@ Sessions support can be added by using Connect's _session_ middleware. To do so
 
 By default the _session_ middleware uses the memory store bundled with Connect, however many implementations exist. For example [connect-redis](http://github.com/visionmedia/connect-redis) supplies a [Redis](http://code.google.com/p/redis/) session store and can be used as shown below:
 
-    var RedisStore = require('connect-redis');
+    var RedisStore = require('connect-redis')(express);
     app.use(express.cookieParser());
     app.use(express.session({ secret: "keyboard cat", store: new RedisStore }));
 
 Now the _req.session_ and _req.sessionStore_ properties will be accessible to all routes and subsequent middleware. Properties on _req.session_ are automatically saved on a response, so for example if we wish to shopping cart data:
 
-    var RedisStore = require('connect-redis');
+    var RedisStore = require('connect-redis')(express);
     app.use(express.bodyParser());
     app.use(express.cookieParser());
     app.use(express.session({ secret: "keyboard cat", store: new RedisStore }));
@@ -732,6 +753,17 @@ To utilize urlencoded request bodies, _req.body_
 should be an object. This can be done by using
 the _express.bodyParser middleware.
 
+### req.get(field, param)
+
+ Get _field_'s _param_ value, defaulting to '' when the _param_
+ or _field_ is not present.
+
+     req.get('content-disposition', 'filename');
+     // => "something.png"
+
+     req.get('Content-Type', 'boundary');
+     // => "--foo-bar-baz"
+
 ### req.flash(type[, msg])
 
 Queue flash _msg_ of the given _type_.
@@ -883,6 +915,18 @@ it will not be set again.
 
 Note that this method _end()_s the response, so you will want to use node's _res.write()_ for multiple writes or streaming.
 
+### res.json(obj[, headers|status[, status]])
+
+ Send a JSON response with optional _headers_ and _status_. This method
+ is ideal for JSON-only APIs, however _res.send(obj)_ will send JSON as
+ well, though not ideal for cases when you want to send for example a string
+ as JSON, since the default for _res.send(string)_ is text/html.
+
+    res.json(null);
+    res.json({ user: 'tj' });
+    res.json('oh noes!', 500);
+    res.json('I dont have that', 404);
+
 ### res.redirect(url[, status])
 
 Redirect to the given _url_ with a default response _status_ of 302.

docs/index.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {
@@ -239,19 +240,24 @@ app.listen(3000);
 <li><a href="http://github.com/visionmedia/express-messages">express-messages</a> flash message notification rendering</li>
 <li><a href="http://github.com/visionmedia/express-configuration">express-configure</a> async configuration support (load settings from redis etc)</li>
 <li><a href="http://github.com/visionmedia/express-namespace">express-namespace</a> namespaced routing support</li>
+<li><a href="http://github.com/visionmedia/express-expose">express-expose</a> expose objects, functions, modules and more to client-side js</li>
+<li><a href="https://github.com/visionmedia/express-params">express-params</a> app.param() extensions</li>
+<li><a href="https://github.com/LearnBoost/express-mongoose">express-mongoose</a> plugin for easy rendering of Mongoose async Query results</li>
 </ul>
 
 
 <h2>More Information</h2>
 
 <ul>
-<li><a href="http://groups.google.com/group/express-js">Google Group</a> for discussion</li>
+<li>#express on freenode</li>
 <li>Follow <a href="http://twitter.com/tjholowaychuk">tjholowaychuk</a> on twitter for updates</li>
-<li>View the <a href="http://senchalabs.github.com/connect">Connect</a> documentation</li>
-<li>View the <a href="http://wiki.github.com/senchalabs/connect/">Connect Wiki</a> for contrib middleware</li>
-<li>View the <a href="http://github.com/visionmedia/express/tree/master/examples/">examples</a></li>
-<li>View the <a href="http://github.com/visionmedia/express">source</a></li>
-<li>View the <a href="contrib.html">contrib guide</a></li>
+<li><a href="http://groups.google.com/group/express-js">Google Group</a> for discussion</li>
+<li>Visit the <a href="http://github.com/visionmedia/express/wiki">Wiki</a></li>
+<li><a href="http://hideyukisaito.com/doc/expressjs/">日本語ドキュメンテーション</a> by <a href="https://github.com/hideyukisaito">hideyukisaito</a></li>
+<li>Screencast &ndash; <a href="http://bit.ly/eRYu0O">Introduction</a></li>
+<li>Screencast &ndash; <a href="http://bit.ly/dU13Fx">View Partials</a></li>
+<li>Screencast &ndash; <a href="http://bit.ly/hX4IaH">Route Specific Middleware</a></li>
+<li>Screencast &ndash; <a href="http://bit.ly/eNqmVs">Route Path Placeholder Preconditions</a></li>
 </ul>
 
 			</div>

docs/index.md

@@ -40,13 +40,14 @@ The following modules compliment or extend Express directly:
   * [express-messages](http://github.com/visionmedia/express-messages) flash message notification rendering
   * [express-configure](http://github.com/visionmedia/express-configuration) async configuration support (load settings from redis etc)
   * [express-namespace](http://github.com/visionmedia/express-namespace) namespaced routing support
+  * [express-expose](http://github.com/visionmedia/express-expose) expose objects, functions, modules and more to client-side js
+  * [express-params](https://github.com/visionmedia/express-params) app.param() extensions
+  * [express-mongoose](https://github.com/LearnBoost/express-mongoose) plugin for easy rendering of Mongoose async Query results 
 
 ## More Information
 
-  * [Google Group](http://groups.google.com/group/express-js) for discussion
+  * \#express on freenode
   * Follow [tjholowaychuk](http://twitter.com/tjholowaychuk) on twitter for updates
-  * View the [Connect](http://senchalabs.github.com/connect) documentation
-  * View the [Connect Wiki](http://wiki.github.com/senchalabs/connect/) for contrib middleware
-  * View the [examples](http://github.com/visionmedia/express/tree/master/examples/)
-  * View the [source](http://github.com/visionmedia/express)
-  * View the [contrib guide](contrib.html)
+  * [Google Group](http://groups.google.com/group/express-js) for discussion
+  * Visit the [Wiki](http://github.com/visionmedia/express/wiki)
+  * [日本語ドキュメンテーション](http://hideyukisaito.com/doc/expressjs/) by [hideyukisaito](https://github.com/hideyukisaito)

docs/layout/head.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {

docs/migrate.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {
@@ -326,7 +327,7 @@
 
 <h3>partial() locals</h3>
 
-<p> Both <em>res.partial()</em> and the <em>partial()</em> functions accept an single object consisting of both the options and the locals. Previously with Express 1.x you may pass <em>user</em> to a partial, along with <em>date</em> like so:</p>
+<p> Both <em>res.partial()</em> and the <em>partial()</em> functions accept a single object consisting of both the options and the locals. Previously with Express 1.x you may pass <em>user</em> to a partial, along with <em>date</em> like so:</p>
 
 <pre><code>   partial('user', { object: user, locals: { date: new Date }})
 </code></pre>
@@ -367,7 +368,7 @@
 
 <h3>View Partial Lookup</h3>
 
-<p> Previously partials were loaded relative to the now removed <em>view partials</em> directory setting, or by default <em>views/partials</em>, now they are relative to the view calling them, read more on <a href="guide.html#View-Lookup">view lookup</a>.</p>
+<p> Previously partials were loaded relative to the now removed <em>view partials</em> directory setting, or by default <em>views/partials</em>, now they are relative to the view calling them, read more on <a href="guide.html#view-lookup">view lookup</a>.</p>
 
 <h3>Mime Types</h3>
 

docs/migrate.md

@@ -123,7 +123,7 @@ However now we have the alternative _maxAge_ property which may be used to set _
 
 ### partial() locals
 
- Both _res.partial()_ and the _partial()_ functions accept an single object consisting of both the options and the locals. Previously with Express 1.x you may pass _user_ to a partial, along with _date_ like so:
+ Both _res.partial()_ and the _partial()_ functions accept a single object consisting of both the options and the locals. Previously with Express 1.x you may pass _user_ to a partial, along with _date_ like so:
  
        partial('user', { object: user, locals: { date: new Date }})
 
@@ -157,7 +157,7 @@ or perhaps if you preferred not to use the inferred name _user_ you may used a l
 
 ### View Partial Lookup
 
- Previously partials were loaded relative to the now removed _view partials_ directory setting, or by default _views/partials_, now they are relative to the view calling them, read more on [view lookup](guide.html#View-Lookup).
+ Previously partials were loaded relative to the now removed _view partials_ directory setting, or by default _views/partials_, now they are relative to the view calling them, read more on [view lookup](guide.html#view-lookup).
 
 ### Mime Types
 
@@ -174,4 +174,4 @@ or perhaps if you preferred not to use the inferred name _user_ you may used a l
 Previously when using options the `root` option would be used for this:
 
      app.use(express.staticProvider({ root: __dirname + '/public', maxAge: oneYear }));
-     
+

docs/screencasts.html

@@ -1,6 +1,7 @@
 <html>
 	<head>
 		<title>Express - node web framework</title>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
 		<style>
 			#tagline {

examples/auth/app.js

@@ -35,16 +35,15 @@ var users = {
   tj: {
     name: 'tj'
     , salt: 'randomly-generated-salt'
-    , pass: md5('foobar' + 'randomly-generated-salt')
+    , pass: hash('foobar', 'randomly-generated-salt')
   }
 };
 
 // Used to generate a hash of the plain-text password + salt
 
-function md5(str) {
-  return crypto.createHash('md5').update(str).digest('hex');
+function hash(msg, key) {
+  return crypto.createHmac('sha256', key).update(msg).digest('hex');
 }
-
 // Authenticate using our plain-object database of doom!
 
 function authenticate(name, pass, fn) {
@@ -52,9 +51,9 @@ function authenticate(name, pass, fn) {
   // query the db for the given username
   if (!user) return fn(new Error('cannot find user'));
   // apply the same algorithm to the POSTed password, applying
-  // the md5 against the pass / salt, if there is a match we
+  // the hash against the pass / salt, if there is a match we
   // found the user
-  if (user.pass == md5(pass + user.salt)) return fn(null, user);
+  if (user.pass == hash(pass, user.salt)) return fn(null, user);
   // Otherwise password is invalid
   fn(new Error('invalid password'));
 }

examples/content-negotiation/app.js

@@ -0,0 +1,47 @@
+
+/**
+ * Module dependencies.
+ */
+
+var express = require('../../lib/express');
+
+var app = express.createServer();
+
+var users = [
+    { name: 'tobi' }
+  , { name: 'loki' }
+  , { name: 'jane' }
+];
+
+function provides(type) {
+  return function(req, res, next){
+    if (req.accepts(type)) return next();
+    next('route');
+  }
+}
+
+// curl http://localhost:3000/users -H "Accept: application/json"
+
+app.get('/users', provides('json'), function(req, res){
+  res.send(users);
+});
+
+// curl http://localhost:3000/users -H "Accept: text/html"
+
+app.get('/users', provides('html'), function(req, res){
+  res.send('<ul>' + users.map(function(user){
+    return '<li>' + user.name + '</li>';
+  }).join('\n') + '</ul>');
+});
+
+// curl http://localhost:3000/users -H "Accept: text/plain"
+
+app.get('/users', function(req, res, next){
+  res.contentType('txt');
+  res.send(users.map(function(user){
+    return user.name;
+  }).join(', '));
+});
+
+app.listen(3000);
+console.log('Express server listening on port 3000');

examples/cookies/app.js

@@ -11,7 +11,7 @@ var app = express.createServer(
   express.favicon(),
 
   // Custom logger format
-  express.logger({ format: '\x1b[1m:method\x1b[0m \x1b[33m:url\x1b[0m :response-time' }),
+  express.logger({ format: '\x1b[36m:method\x1b[0m \x1b[90m:url\x1b[0m :response-time' }),
 
   // Provides req.cookies
   express.cookieParser(),
@@ -36,9 +36,8 @@ app.get('/forget', function(req, res){
 });
 
 app.post('/', function(req, res){
-  if (req.body.remember) {
-    res.cookie('remember', '1', { path: '/', expires: new Date(Date.now() + 900000), httpOnly: true });
-  }
+  var minute = 60000;
+  if (req.body.remember) res.cookie('remember', 1, { maxAge: minute });
   res.redirect('back');
 });
 

examples/web-service/app.js

@@ -0,0 +1,121 @@
+
+/**
+ * Module dependencies.
+ */
+
+var express = require('../../lib/express');
+
+var app = express.createServer();
+
+// configuration
+
+// if we wanted to supply more than JSON, we could
+// use something similar to the content-negotiation
+// example.
+
+// here we validate the API key,
+// by mounting this middleware to /api/v1
+// meaning only paths prefixed with "/api/v1"
+// will cause this middleware to be invoked
+
+app.use('/api/v1', function(req, res, next){
+  var key = req.query['api-key'];
+
+  // key isnt present
+  if (!key) return next(new Error('api key required'));
+
+  // key is invalid
+  if (!~apiKeys.indexOf(key)) return next(new Error('invalid api key'));
+
+  // all good, store req.key for route access
+  req.key = key;
+  next();
+});
+
+// position our routes above the error handling middleware,
+// and below our API middleware, since we want the API validation
+// to take place BEFORE our routes
+app.use(app.router);
+
+// middleware with an arity of 4 are considered
+// error handling middleware. When you next(err)
+// it will be passed through the defined middleware
+// in order, but ONLY those with an arity of 4, ignoring
+// regular middleware.
+app.use(function(err, req, res, next){
+  // whatever you want here, feel free to populate
+  // properties on `err` to treat it differently in here,
+  // or when you next(err) set res.statusCode= etc.
+  res.send({ error: err.message }, 500);
+});
+
+// our custom JSON 404 middleware. Since it's placed last
+// it will be the last middleware called, if all others
+// invoke next() and do not respond.
+app.use(function(req, res){
+  res.send({ error: "Lame, can't find that" }, 404);
+});
+
+/**
+ * Generate our unique identifier.
+ */
+
+function uid() {
+  return [
+      Math.random() * 0xffff | 0
+    , Math.random() * 0xffff | 0
+    , Math.random() * 0xffff | 0
+    , Date.now()
+  ].join('-');
+}
+
+// map of valid api keys, typically mapped to
+// account info with some sort of database like redis.
+// api keys do _not_ serve as authentication, merely to
+// track API usage or help prevent malicious behavior etc.
+
+var apiKeys = [uid(), uid(), uid()];
+
+console.log('valid keys:\n ', apiKeys.join('\n  '));
+
+// these two objects will serve as our faux database
+
+var repos = [
+    { name: 'express', url: 'http://github.com/visionmedia/express' }
+  , { name: 'stylus', url: 'http://github.com/learnboost/stylus' }
+  , { name: 'cluster', url: 'http://github.com/learnboost/cluster' }
+];
+
+var users = [
+    { name: 'tobi' }
+  , { name: 'loki' }
+  , { name: 'jane' }
+];
+
+var userRepos = {
+    tobi: [repos[0], repos[1]]
+  , loki: [repos[1]]
+  , jane: [repos[2]]
+};
+
+// we now can assume the api key is valid,
+// and simply expose the data
+
+app.get('/api/v1/users', function(req, res, next){
+  res.send(users);
+});
+
+app.get('/api/v1/repos', function(req, res, next){
+  res.send(repos);
+});
+
+app.get('/api/v1/user/:name/repos', function(req, res, next){
+  var name = req.params.name
+    , user = userRepos[name];
+  
+  if (user) res.send(user);
+  else next();
+});
+
+app.listen(3000);
+console.log('Express server listening on port 3000');

lib/express.js

@@ -28,7 +28,7 @@ var exports = module.exports = connect.middleware;
  * Framework version.
  */
 
-exports.version = '2.3.8';
+exports.version = '2.4.0';
 
 /**
  * Shortcut for `new Server(...)`.

lib/request.js

@@ -65,6 +65,28 @@ req.header = function(name, defaultValue){
   }
 };
 
+/**
+ * Get `field`'s `param` value, defaulting to ''.
+ *
+ * Examples:
+ *
+ *     req.get('content-disposition', 'filename');
+ *     // => "something.png"
+ *
+ * @param {String} field
+ * @param {String} param
+ * @return {String}
+ * @api public
+ */
+
+req.get = function(field, param){
+  var val = this.header(field);
+  if (!val) return '';
+  var regexp = new RegExp(param + ' *= *(?:"([^"]+)"|([^;]+))', 'i');
+  if (!regexp.exec(val)) return '';
+  return RegExp.$1 || RegExp.$2;
+};
+
 /**
  * Check if the _Accept_ header is present, and includes the given `type`.
  *
@@ -106,16 +128,14 @@ req.accepts = function(type){
     return true;
   } else if (type) {
     // allow "html" vs "text/html" etc
-    if (type.indexOf('/') < 0) {
-      type = mime.lookup(type);
-    }
+    if (!~type.indexOf('/')) type = mime.lookup(type);
 
     // check if we have a direct match
     if (~accept.indexOf(type)) return true;
 
     // check if we have type/*
     type = type.split('/')[0] + '/*';
-    return accept.indexOf(type) >= 0;
+    return !!~accept.indexOf(type);
   } else {
     return false;
   }

lib/response.js

@@ -106,7 +106,7 @@ res.send = function(body, headers, status){
   }
 
   // strip irrelevant headers
-  if (204 == status) {
+  if (204 == status || 304 == status) {
     this.removeHeader('Content-Type');
     this.removeHeader('Content-Length');
   }
@@ -114,6 +114,43 @@ res.send = function(body, headers, status){
   // respond
   this.statusCode = status;
   this.end('HEAD' == this.req.method ? undefined : body);
+  return this;
+};
+
+/**
+ * Send JSON response with `obj`, optional `headers`, and optional `status`.
+ *
+ * Examples:
+ *
+ *     res.json(null);
+ *     res.json({ user: 'tj' });
+ *     res.json('oh noes!', 500);
+ *     res.json('I dont have that', 404);
+ *
+ * @param {Mixed} obj
+ * @param {Object|Number} headers or status
+ * @param {Number} status
+ * @return {ServerResponse}
+ * @api public
+ */
+
+res.json = function(obj, headers, status){
+  this.charset = this.charset || 'utf-8';
+  this.header('Content-Type', 'application/json');
+  return this.send(JSON.stringify(obj), headers, status);
+};
+
+/**
+ * Set status `code`.
+ *
+ * @param {Number} code
+ * @return {ServerResponse}
+ * @api public
+ */
+
+res.status = function(code){
+  this.statusCode = code;
+  return this;
 };
 
 /**
@@ -190,7 +227,7 @@ res.attachment = function(filename){
  * Transfer the file at the given `path`, with optional 
  * `filename` as an attachment and optional callback `fn(err)`,
  * and optional `fn2(err)` which is invoked when an error has
- * occurred after headers have been sent.
+ * occurred after header has been sent.
  *
  * @param {String} path
  * @param {String|Function} filename or fn
@@ -360,9 +397,7 @@ res.redirect = function(url, status){
   // Relative
   if (!~url.indexOf('://')) {
     // Respect mount-point
-    if (app.route) {
-      url = join(app.route, url);
-    }
+    if (app.route) url = join(app.route, url);
 
     // Absolute
     var host = req.headers.host

lib/router/index.js

@@ -193,7 +193,7 @@ Router.prototype._dispatch = function(req, res, next){
     }
 
     // match route
-    route = self._match(req, i);
+    req.route = route = self._match(req, i);
 
     // implied OPTIONS
     if (!route && 'OPTIONS' == req.method) return self._options(req, res);
@@ -209,8 +209,8 @@ Router.prototype._dispatch = function(req, res, next){
 
     (function param(err) {
       var key = keys[i++]
-        , val = req.params[key]
-        , fn = params[key]
+        , val = key && req.params[key.name]
+        , fn = key && params[key.name]
         , ret;
 
       try {
@@ -218,7 +218,7 @@ Router.prototype._dispatch = function(req, res, next){
           nextRoute();
         } else if (err) {
           next(err);
-        } else if (fn) {
+        } else if (fn && undefined !== val) {
           fn(req, res, param, val);
         } else if (key) {
           param();
@@ -329,7 +329,7 @@ Router.prototype._match = function(req, i){
               ? decodeURIComponent(captures[j])
               : captures[j];
           if (key) {
-            route.params[key] = val;
+            route.params[key.name] = val;
           } else {
             route.params.push(val);
           }

lib/router/route.js

@@ -70,7 +70,7 @@ function normalize(path, keys, sensitive) {
     .concat('/?')
     .replace(/\/\(/g, '(?:/')
     .replace(/(\/)?(\.)?:(\w+)(?:(\(.*?\)))?(\?)?/g, function(_, slash, format, key, capture, optional){
-      keys.push(key);
+      keys.push({ name: key, optional: !! optional });
       slash = slash || '';
       return ''
         + (optional ? '' : slash)

lib/view.js

@@ -93,20 +93,23 @@ exports.compile = function(view, cache, cid, options){
  */
 
 exports.lookup = function(view, options){
-  var orig = view = new View(view, options);
+  var orig = view = new View(view, options)
+    , partial = options.isPartial
+    , layout = options.isLayout;
 
   // Try _ prefix ex: ./views/_<name>.jade
+  // taking precedence over the direct path
   if (partial) {
     view = new View(orig.prefixPath, options);
     if (!view.exists) view = orig;
   }
 
   // Try index ex: ./views/user/index.jade
-  if (!view.exists) view = new View(orig.indexPath, options);
+  if (!layout && !view.exists) view = new View(orig.indexPath, options);
 
   // Try ../<name>/index ex: ../user/index.jade
   // when calling partial('user') within the same dir
-  if (!view.exists && !options.isLayout) view = new View(orig.upIndexPath, options);
+  if (!layout && !view.exists) view = new View(orig.upIndexPath, options);
 
   // Try root ex: <root>/user.jade
   if (!view.exists) view = new View(orig.rootPath, options);
@@ -127,11 +130,6 @@ exports.lookup = function(view, options){
 function renderPartial(res, view, options, parentLocals, parent){
   var collection, object, locals;
 
-  // Inherit parent view extension when not present
-  if (parent && !~view.indexOf('.')) {
-    view += parent.extension;
-  }
-
   if (options) {
     // collection
     if (options.collection) {
@@ -167,7 +165,7 @@ function renderPartial(res, view, options, parentLocals, parent){
   if (locals) merge(options, locals);
 
   // Partials dont need layouts
-  options.renderPartial = true;
+  options.isPartial = true;
   options.layout = false;
 
   // Deduce name from view path
@@ -269,7 +267,7 @@ res.partial = function(view, options, fn){
   parent.dirname = app.set('views') || process.cwd() + '/views';
 
   // utilize "view engine" option
-  if (viewEngine) parent.extension = '.' + viewEngine;
+  if (viewEngine) parent.engine = viewEngine;
 
   // render the partial
   try {
@@ -365,7 +363,7 @@ res._render = function(view, opts, fn, parent, sub){
   // capture attempts
   options.attempts = [];
 
-  var partial = options.renderPartial
+  var partial = options.isPartial
     , layout = options.layout;
 
   // Layout support

package.json

@@ -1,7 +1,7 @@
 {
   "name": "express",
   "description": "Sinatra inspired web development framework",
-  "version": "2.3.8",
+  "version": "2.4.0",
   "author": "TJ Holowaychuk <tj@vision-media.ca>",
   "contributors": [ 
     { "name": "TJ Holowaychuk", "email": "tj@vision-media.ca" }, 
@@ -10,7 +10,7 @@
     { "name": "Guillermo Rauch", "email": "rauchg@gmail.com" }
   ],
   "dependencies": {
-    "connect": ">= 1.4.1 < 2.0.0",
+    "connect": ">= 1.5.1 < 2.0.0",
     "mime": ">= 0.0.1",
     "qs": ">= 0.0.6"
   },
@@ -30,5 +30,9 @@
   "repository": "git://github.com/visionmedia/express",
   "main": "index",
   "bin": { "express": "./bin/express" },
+  "scripts": {
+    "test": "make test",
+    "prepublish" : "npm prune"
+  },
   "engines": { "node": ">= 0.4.1 < 0.5.0" }
 }

test/express.test.js

@@ -461,5 +461,17 @@ module.exports = {
     assert.response(app,
       { url: '/another' },
       { body: 'got /another' });
+  },
+  
+  'invalid chars': function(){
+    var app = express.createServer();
+
+    app.get('/:name', function(req, res, next){
+      res.send('invalid');
+    });
+
+    assert.response(app,
+      { url: '/%a0' },
+      { status: 500 });
   }
 };

test/fixtures/forum/thread.jade

@@ -1 +1,3 @@
-h1 Forum Thread
+h1 Forum Thread
+!= partial('../hello')
+!= partial('../hello.haml')

test/request.test.js

@@ -303,5 +303,36 @@ module.exports = {
     assert.response(app,
       { url: '/incorrect', headers: { Referer: 'expressjs.com' }},
       { body: 'expressjs.com' });
+  },
+  
+  'test #get(field, param)': function(){
+    var app = express.createServer();
+
+    app.get('/', function(req, res, next){
+      req.get('content-disposition', 'filename')
+        .should.equal('foo bar.jpg');
+
+      req.get('Content-Disposition', 'filename')
+        .should.equal('foo bar.jpg');
+
+      req.get('x-content-foo', 'foo').should.equal('bar');
+      req.get('x-content-foo', 'bar').should.equal('foo bar baz');
+      req.get('x-content-foo', 'woot').should.equal('tobi loki jane');
+      req.get('cache-control', 'max-age').should.equal('500');
+
+      req.get('foo').should.equal('');
+      req.get('foo', 'bar').should.equal('');
+      res.end();
+    });
+
+    var fields = {
+        'Content-Disposition': 'attachment; filename="foo bar.jpg"'
+      , 'X-Content-Foo': 'foo=bar; bar=foo bar baz; woot=tobi loki jane;'
+      , 'Cache-Control': 'max-age =   500'
+    };
+
+    assert.response(app,
+      { url: '/', headers: fields },
+      { body: '' });
   }
 };

test/response.test.js

@@ -9,6 +9,57 @@ var express = require('express')
   , should = require('should');
 
 module.exports = {
+  'test #json()': function(){
+    var app = express.createServer()
+      , json = 'application/json; charset=utf-8';
+
+    app.get('/user', function(req, res, next){
+      res.json({ name: 'tj' });
+    });
+
+    app.get('/string', function(req, res, next){
+      res.json('whoop!');
+    });
+
+    app.get('/error', function(req, res, next){
+      res.json('oh noes!', 500);
+    });
+
+    app.get('/headers', function(req, res, next){
+      res.json(undefined, { 'X-Foo': 'bar' }, 302);
+    });
+
+    assert.response(app,
+      { url: '/error' },
+      { body: '"oh noes!"'
+      , status: 500
+      , headers: { 'Content-Type': json }});
+
+    assert.response(app,
+      { url: '/string' },
+      { body: '"whoop!"'
+      , headers: {
+          'Content-Type': json
+        , 'Content-Length': 8
+      }});
+
+    assert.response(app,
+      { url: '/user' },
+      { body: '{"name":"tj"}', headers: { 'Content-Type': json }});
+  },
+
+  'test #status()': function(){
+    var app = express.createServer();
+
+    app.get('/error', function(req, res, next){
+      res.status(500).send('OH NO');
+    });
+
+    assert.response(app,
+      { url: '/error' },
+      { body: 'OH NO', status: 500 });
+  },
+
   'test #send()': function(){
     var app = express.createServer();
   

test/router.test.js

@@ -74,6 +74,38 @@ module.exports = {
     });
   },
 
+  'test precedence': function(){
+    var app = express.createServer();
+
+    var hits = [];
+
+    app.all('*', function(req, res, next){
+      hits.push('all');
+      next();
+    });
+
+    app.get('/foo', function(req, res, next){
+      hits.push('GET /foo');
+      next();
+    });
+    
+    app.get('/foo', function(req, res, next){
+      hits.push('GET /foo2');
+      next();
+    });
+
+    app.put('/foo', function(req, res, next){
+      hits.push('PUT /foo');
+      next();
+    });
+
+    assert.response(app,
+      { url: '/foo' },
+      function(){
+        hits.should.eql(['all', 'GET /foo', 'GET /foo2']);
+      });
+  },
+
   'test named capture groups': function(){
     var app = express.createServer();
 
@@ -106,7 +138,7 @@ module.exports = {
       { body: 'Cannot GET /user/ab' });
   },
   
-  'test .param()': function(){
+  'test app.param()': function(){
     var app = express.createServer();
 
     var users = [
@@ -137,6 +169,35 @@ module.exports = {
       { url: '/user/1' },
       { body: 'user tobi' });
   },
+
+  'test app.param() optional execution': function(beforeExit){
+    var app = express.createServer()
+      , calls = 0;
+
+    var months = ['Jan', 'Feb', 'Mar'];
+
+    app.param('month', function(req, res, next, n){
+      req.params.month = months[n];
+      ++calls;
+      next();
+    });
+
+    app.get('/calendar/:month?', function(req, res, next){
+      res.send(req.params.month || months[0]);
+    });
+
+    assert.response(app,
+      { url: '/calendar' },
+      { body: 'Jan' });
+
+    assert.response(app,
+      { url: '/calendar/1' },
+      { body: 'Feb' });
+
+    beforeExit(function(){
+      calls.should.equal(1);
+    });
+  },
   
   'test OPTIONS': function(){
     var app = express.createServer();
@@ -168,7 +229,7 @@ module.exports = {
     route.path.should.equal('/user/:id');
     route.regexp.should.be.an.instanceof(RegExp);
     route.method.should.equal('get');
-    route.keys.should.eql(['id']);
+    route.keys.should.eql([{ name: 'id', optional: false }]);
 
     app.get('/user').should.have.length(1);
     app.get('/user/:id').should.have.length(1);
@@ -230,7 +291,7 @@ module.exports = {
     route.path.should.equal('/user/:id');
     route.regexp.should.be.an.instanceof(RegExp);
     route.method.should.equal('get');
-    route.keys.should.eql(['id']);
+    route.keys.should.eql([{ name: 'id', optional: false }]);
     //route.params.id.should.equal('12');
 
     app.match.get('/user').should.have.length(1);
@@ -298,5 +359,27 @@ module.exports = {
     assert.response(app,
       { url: '/foo', method: 'OPTIONS' },
       { body: 'whatever', headers: { Allow: 'GET' }});
+  },
+  
+  'test req.route': function(){
+    var app = express.createServer();
+
+    var routes = [];
+
+    app.get('/:foo?', function(req, res, next){
+      routes.push(req.route.path);
+      next();
+    });
+
+    app.get('/foo', function(req, res, next){
+      routes.push(req.route.path);
+      next();
+    });
+
+    assert.response(app,
+      { url: '/foo' },
+      function(){
+        routes.should.eql(['/:foo?', '/foo']);
+      });
   }
 };

test/view.test.js

@@ -668,6 +668,67 @@ module.exports = {
       { body: '<p>two</p>' });
   },
   
+  'test #partial() relative lookup with "view engine"': function(){
+    var app = create();
+    app.set('view engine', 'jade');
+
+    app.get('/', function(req, res, next){
+      res.render('forum/thread', { layout: false });
+    });
+
+    app.get('/2', function(req, res, next){
+      res.render('forum/../forum/thread', { layout: false });
+    });
+
+    assert.response(app,
+      { url: '/2' },
+      { body: '<h1>Forum Thread</h1><p>:(</p>\n<p>Hello World</p>' });
+
+    assert.response(app,
+      { url: '/' },
+      { body: '<h1>Forum Thread</h1><p>:(</p>\n<p>Hello World</p>' });
+  },
+
+  'test #partial() relative lookup without "view engine"': function(){
+    var app = create();
+
+    app.get('/', function(req, res, next){
+      res.render('forum/thread.jade', { layout: false });
+    });
+
+    app.get('/2', function(req, res, next){
+      res.render('forum/../forum/thread.jade', { layout: false });
+    });
+
+    assert.response(app,
+      { url: '/2' },
+      { body: '<h1>Forum Thread</h1><p>:(</p>\n<p>Hello World</p>' });
+
+    assert.response(app,
+      { url: '/' },
+      { body: '<h1>Forum Thread</h1><p>:(</p>\n<p>Hello World</p>' });
+  },
+  
+  'test #partial() relative lookup': function(){
+    var app = create();
+
+    app.get('/', function(req, res, next){
+      res.partial('forum/thread.jade');
+    });
+
+    app.get('/2', function(req, res, next){
+      res.partial('forum/../forum/thread.jade');
+    });
+
+    assert.response(app,
+      { url: '/2' },
+      { body: '<h1>Forum Thread</h1><p>:(</p>\n<p>Hello World</p>' });
+
+    assert.response(app,
+      { url: '/' },
+      { body: '<h1>Forum Thread</h1><p>:(</p>\n<p>Hello World</p>' });
+  },
+
   'test #partial() with several calls': function(){
     var app = create();