added: ctx.state as the recommended namespace for passing information through middleware and routes.

docs/api/context.md

@@ -50,6 +50,14 @@ app.use(function *(){
 
   A koa `Response` object.
 
+### ctx.state
+
+  The recommended namespace for passing information through middleware and to your frontend views.
+
+```js
+this.state.user = yield User.find(id);
+```
+
 ### ctx.app
 
   Application instance reference.

lib/application.js

@@ -146,6 +146,7 @@ app.createContext = function(req, res){
   context.originalUrl = request.originalUrl = req.url;
   context.cookies = new Cookies(req, res, this.keys);
   context.accept = request.accept = accepts(req);
+  context.state = {};
   return context;
 };
 

test/context/state.js

@@ -0,0 +1,21 @@
+
+var request = require('supertest');
+var assert = require('assert');
+var koa = require('../..');
+
+describe('ctx.state', function() {
+  it('should provide a ctx.state namespace', function(done) {
+    var app = koa();
+
+    app.use(function *() {
+      assert.deepEqual(this.state, {});
+    });
+
+    var server = app.listen();
+
+    request(server)
+    .get('/')
+    .expect(404)
+    .end(done);
+  })
+})