koa-controller-register

An ES6 decorator based router for Koa, with automatic controller registration.

Instead of manually wiring up each route, you describe them with decorators on a controller class and pass the controllers to useControllers once.

Features

• Define routes with @Controller, @Get, @Post, ... decorators
• Auto-register controllers into a Koa application
• Class-level and method-level middleware support
• Written in TypeScript with full type definitions

Install

$ npm install koa-controller-register

Peer dependencies (already used by your app):

$ npm install koa reflect-metadata

Setup

Enable decorators in your tsconfig.json:

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Import reflect-metadata once at the entry of your application:

import 'reflect-metadata'

Quick Start

// ping.controller.ts
import { Context } from 'koa'
import { Controller, Get } from 'koa-controller-register'

@Controller('/')
export default class PingController {
    @Get('/ping')
    async ping(ctx: Context) {
        ctx.body = 'pong'
    }
}

// index.ts
import 'reflect-metadata'
import Application from 'koa'
import { useControllers } from 'koa-controller-register'
import PingController from './ping.controller'

const app = new Application()

useControllers(app, PingController)

app.listen(8080)

Now GET /ping responds with pong.

Decorators

Class decorators

| Decorator | Description | | ------------------ | -------------------------------------------- | | @Controller(prefix?, middlewares?) | Register a class as a controller, with an optional URL prefix and middlewares. Default prefix is /. | | @Middlewares(...middlewares) | Apply middlewares to all routes of the controller. |

Method decorators

| Decorator | Description | | ------------------ | -------------------------------------------- | | @Get(path?, middlewares?) | Register a GET route. Default path is /. | | @Post(path?, middlewares?) | Register a POST route. Default path is /. | | @Put(path?, middlewares?) | Register a PUT route. Default path is /. | | @Delete(path?, middlewares?) | Register a DELETE route. Default path is /. | | @Patch(path?, middlewares?) | Register a PATCH route. Default path is /. | | @All(path?, middlewares?) | Register a route for all HTTP methods. Default path is /. | | @Before(...middlewares) | Apply middlewares to a single route. |

Middleware

There are three places middlewares can be applied:

import { Before, Controller, Get, Middlewares } from 'koa-controller-register'

// 1. Controller-level, applied to every route
@Controller('/api')
@Middlewares(authentication)

// 2. Per-route via @Before
class UserController {
    @Get('/profile')
    @Before(loadUser)
    async profile(ctx: Context) {
        ctx.body = ctx.state.user
    }
}

Alternatively, middlewares can be passed directly to the HTTP method decorator:

@Controller('/api')
class UserController {
    @Get('/profile', loadUser)
    async profile(ctx: Context) {
        ctx.body = ctx.state.user
    }
}

Middleware execution order: class-level middlewares run first, then the route middlewares, then the handler.

Full example

// middlewares.ts
import { Context, Next } from 'koa'

export async function middleware0(ctx: Context, next: Next) {
    console.log('middleware 0')
    await next()
}

export async function middleware1(ctx: Context, next: Next) {
    console.log('middleware 1')
    await next()
}

// ping.controller.ts
import { Context } from 'koa'
import { Before, Controller, Get, Middlewares } from 'koa-controller-register'
import { middleware0, middleware1 } from './middlewares'

@Controller('/')
@Middlewares(middleware0)
export default class PingController {
    @Get('/ping')
    async ping(ctx: Context) {
        ctx.body = 'pong' // will print "middleware 0"
    }

    @Get('/example')
    @Before(middleware1)
    async test(ctx: Context) {
        ctx.body = 'test' // will print "middleware 0\n middleware 1"
    }
}

// index.ts
import 'reflect-metadata'
import Application from 'koa'
import { useControllers } from 'koa-controller-register'
import PingController from './ping.controller'

const app = new Application()

useControllers(app, PingController)

app.listen(8080)

API

useControllers(app, ...controllers)

Registers one or more controller classes into the Koa application.

useControllers(app, PingController, UserController)

• app: Application — the Koa application instance
• controllers: Array<new () => void> — controller classes (variadic)

Each controller generates a separate router; routes are mounted with router.routes() and router.allowedMethods().

License

BSD