Koa Router Metadata

Use ES7 decorators on classes and methods to generate a koa-router.

Installation

$ npm install koa-router-metadata --save

Usage

This library supports ES7 decorators proposal which is supported by babel and typescript. To use it with babel you should enable experimental es7.decorators feature in babel as described here. To use it with typescripts you should enable experimentalDecorators and emitDecoratorMetadata in tsconfig.json

 @route(HttpMethod, path)
 @middleware(myMiddleware, anotherMiddleware, ...)
 // optional middleware is added before the target method. 

Inside the target method

this.request is what you'd normally find under this with koa. this.status is a shortcut for this.request.status. You may access methods and properties of this class with this, e.g. let pong = await this.ping(). Arguments of the method will be assigned the values, according to the @mapRequestParameters() definition provided.

Example

Define your routes like this:

// my-router.js:

import {router, Router, route, HttpMethod, mapRequestParameters, jsonParam, jsonObject, urlParam, qsParam, formParam, formObject, middleware, respondWithReturnValue} from 'koa-router-metadata';

@router('/api')
export default class Ping extends Router {
  @route(HttpMethod.GET, '/ping')
  @respondWithReturnValue
  async ping() {
      this.status = 200;
      return 'pong';
  }

  @route(HttpMethod.GET, '/params/:one')
  @mapRequestParameters(urlParam('one'), qsParam('two'))
  @respondWithReturnValue
  async params(one, two) {
      // this.request is what you'd normally find under *this* of koa's request
      // this.status is a shortcut for this.request.status
      // you may access methods and properties of this class with *this*, e.g. *let pong = await this.ping()*
      // variables *one* and *two* will be assigned the values according to the @mapRequestParameters definition
      this.status = 200;
      return `${one} ${two}`;
  }
  
  @route(HttpMethod.GET, '/auth')
  @middleware(isAuthenticated)
  @respondWithReturnValue
  async ping() {
      this.status = 200;
      return 'pong';
  }

  @route(HttpMethod.POST, '/json')
  @mapRequestParameters(jsonParam('one'))
  @respondWithReturnValue
  async json(one) {
      this.status = 201;
      return `${one}`;
  }

  @route(HttpMethod.POST, '/form')
  @mapRequestParameters(formParam('one'))
  @respondWithReturnValue
  async form(one) {
      this.status = 201;
      return `${one}`;
  }

  @route(HttpMethod.PUT, '/put')
  async put() {
      this.status = 202;
  }
}

Now load the routes onto a koa-router:

import Koa from 'koa';
import KoaRouter from 'koa-router';
import initializeMetadataRouting from 'koa-router-metadata';

// import the above router class
import './my-router.js'

let app = new Koa();
let myRouter = new KoaRouter();
app.use(router.middleware());
app.listen(9999);

// load all classes decorated with router()
initializeMetadataRouting(myRouter);

Advantages and alternatives

The advantage of using my package for your routes is that it wraps the request into the instance of a routing class, making it possible to call other functions in your class using this. You also get to re-use your functions outside of your router if you decorate with @respondWithReturnValue and @mapRequestParameters(). This makes your classes portable and enables you to unit-test your methods directly, without going through koa or any other middleware.

I've recently discovered xmlking's koa-router-decorators. It seems we wrote these packages at the same time without knowing of each other, hence two different projects instead of forks. xmlking's package is much simpler though, only providing routes to static methods.

Development

You need babel installed globally

npm install -g babel

build

npm run build

test

npm test

publish to npm registry

npm publish