You should be familiar by now with the middlewares in Express. We used them a lot to dry out code, especially for validation and authentication. In Express, middleware is placed between the server that receives the request and the handler that responds to a request. The request flows one way, until it terminates at res.send or something equivalent.

In Koa.js, everything is a middleware, including the handler itself. As a matter of fact, a Koa.js application is just an object, which contains an array of middleware generator functions! The request flows all the way down the stack of middlewares, and back up again. This is best explained with a simple example:

var koa = require('koa'),
var app = koa();

app.use(function *(next){
  var start = new Date();
  yield next;
  var ms = new Date() - start;
  this.set('X-Response-Time', ms + 'ms'),
});

app.use(function *(){
  this.body = 'Hello World';
});

app.listen(3000);

Here we have a Koa.js application with two middlewares. The first middleware adds an X-Response-Time header to the response, whereas the second middleware simply sets the response body to Hello World for each request. The flow is as follows:

To run this app, we can use the following command:

node --harmony app.js

A Koa.js Context is created for each incoming request. Within each middleware, you can access the Context using the this object. It includes the Request and Response object in this.request and this.response, respectively, although most methods and accessors are directly available from the Context.

The most important property is this.body, which sets the response body. The response status is automatically set to 200 when the response body is set. You may override this by setting this.status manually.

Another very useful syntactic sugar is this.throw, which allows you to return an error response by simply calling this.throw(400), or if you want to override the standard HTTP error message, you may pass a second argument with the error message. We will get to Koa.js slick error handling later in this chapter.

Now that we've got the basics down, let's start building a Hacker News API!

var mongoose = require('mongoose'),

var schema = new mongoose.Schema({
  title: { type: String, require: true },
  URL: { type: String, require: true },
  upvotes: { type: Number, require: true, 'default': 0 },
  timestamp: { type: Date, require: true, 'default': Date.now }
});

schema.statics.upvote = function *(linkId) {
  return yield this.findByIdAndUpdate(linkId, {
    $inc: {
      upvotes: 1
    }
  }).exec();
};

var Links = mongoose.model('links', schema);
module.exports = Links;

var model = require('../models/links'),

module.exports = function(app) {
  app.get('/links', function *(next) {
    var links = yield model.find({}).sort({upvotes: 'desc'}).exec();
    this.body = links;
  });

  app.post('/links', function *(next) {
    var link = yield model.create({
      title: this.request.body.title,
      URL: this.request.body.URL
    });
    this.body = link;
  });

  app.delete('/links/:id', function *(next) {
    var link = yield model.remove({ _id: this.params.id }).exec();
    this.body = link;
  });

  app.put('/links/:id/upvote', function *(next) {
    var link = yield model.upvote(this.params.id);
    this.body = link;
  });
};