koa-controllers

Koa controllers with TypeScript Decorators.

Prerequisites

koa 2 or above.

Node >= 7.6.0

Table of Contents

• Installation
• Usage
  • Router Documentation
  • Load Controllers
  • Controller
  • Inject context
  • Inject request parameters
    • Optional parameter
    • String parameter
    • Number parameter
    • Enum parameter
    • Multipart file parameter
    • Multiple multipart files parameter
    • Other RequestParam options
  • Validation
  • Before Middleware

Installation

npm install koa-controllers --save

or with yarn:

yarn add koa-controllers

reflect-metadata shim is required:

npm install reflect-metadata --save

and make sure to import it before you use koa-controllers:

import "reflect-metadata";

Usage

Router Documentation

Load Controllers

Supported request method:

@Get('/')
@Post('/')

Load all controller modules:

import * as Koa from 'koa';
import { useControllers } from 'koa-controllers';

const app = new Koa();
useControllers(app, __dirname + '/controllers/*.js', {
    multipart: {
        dest: './uploads'
    }
});
app.listen(3000);

Controller

Controller files in controllers directory:

import { Controller, Get, Ctx } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public async index( @Ctx ctx: any) {
        await ctx.render('/index');
    }
}

Inject context

import { Controller, Get, Ctx } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public async index( @Ctx ctx: any) {
        await ctx.render('/index');
    }
}

Inject request parameters

Optional parameter

import { Controller, Get, RequestParam } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('username', { required: false }) username: string) {
        console.log(username);
    }
}

String parameter

import { Controller, Get, RequestParam } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('username') username: string) {
        console.log(username);
    }
}

Number parameter

import { Controller, Get, RequestParam } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('count') count: number) {
        console.log(count);
    }
}

Enum parameter

import { Controller, Get, RequestParam } from 'koa-controllers';

enum Color {
    Red,
    Blue
}

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('color', { enum: Color }) color: Color) {
        console.log(color);
    }
}

Multipart file parameter

import { Controller, Get, RequestParam, MultipartFile } from 'koa-controllers';

enum Color {
    Red,
    Blue
}

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('avatar', { file: true }) avatar: MultipartFile) {
        console.log(avatar);
    }
}

Multiple multipart files parameter

import { Controller, Get, RequestParam, MultipartFile } from 'koa-controllers';

enum Color {
    Red,
    Blue
}

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('photos', { file: true, multiple: true }) photos: MultipartFile[]) {
        console.log(photos);
    }
}

Other RequestParam options

{
    required: false, // Defaults to true
    default: any // The default value to use as a fallback when the request parameter is not provided or has an empty value.
                 // Supplying a default value implicitly sets required to false.
}

Validation

@ReuestParam support validation.

Limit number value minimum and maximum:

import { Controller, Get, RequestParam } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('count', { min: 5, max: 10 }) count: number) {
        console.log(count);
    }
}

Limit string minimum and maximum length:

import { Controller, Get, RequestParam } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('username', { min: 5, max: 10 }) username: string) {
        console.log(username);
    }
}

Check string is email:

import { Controller, Get, RequestParam } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    public index(@RequestParam('email', { email: true }) email: string) {
        console.log(email);
    }
}

Before Middleware

import { Controller, Before, Get, Middleware } from 'koa-controllers';

@Controller
export class MyController {
    @Get('/')
    @Before(Authenticate)
    public index(@Ctx ctx: any) {
        console.log(ctx.user);
    }
}

class Authenticate implements Middleware {
    public middleware = async (ctx: any, next: any) => {
        const user = await getUser(ctx);
        if (user == null) {
            ctx.redirect('/signin');
        } else {
            ctx.user = user;
            await next();   // Notice: Don't forget `await`, or you will get '404 NOT FOUND'.
        }
    }
}

LICENSE

koa-controllers is primarily distributed under the terms of the MIT license. See LICENSE for details.