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