koa-joi-controllers

Controller decorators for Koa using koa-joi-router.

Installation

npm install koa-joi-controllers

If you're using TypeScript, you should also install the type definitions for koa-joi-router:

npm install --save-dev @types/koa-joi-router

Usage

Create a controller class:

import{Get,Controller,KoaController}from'koa-joi-controllers';
@Controller('/v1')exportclassMyControllerextendsKoaController{
@Get('/hello')asynchello(ctx){ctx.body='Hello World';}}

Create a Koa app and configure the routes before running the server:

importKoafrom'koa';// import * as Koa from 'koa'; for TypeScript projectsimport{configureRoutes}from'koa-joi-controllers';constapp=newKoa();configureRoutes(app,[newMyController();],'/api');// optional prefix for all routesapp.listen(3000);// GET /api/v1/hello -> 'Hello World'

Overview

• Defining controllers
• HTTP method decorators
• Request parameters
• Request body
• Joi validation
• Named route parameter middleware
• Multiple middleware support
• Adding metadata
• Adding routes via the router
• Using with JavaScript

Defining controllers

You can create as many controllers as you want. Every controller needs to extend the KoaController class and have the @Controller decorator. The controller decorators accepts a string parameter, which is the prefix of all the routes in the controller class.

@Controller('/koalas')exportclassKoalaControllerextendsKoaController{
@Get()asyncall(ctx){ctx.body=Koala.all();}
@Get('/:id')asyncfindById(ctx){ctx.body=Koala.findById(ctx.params.id);}}

HTTP method decorators

You can define a route with a @Method decorator, where Method is an Http method. (Get, Post, Put, Delete, Head or Options).

The method decorator accepts a string parameter which is the path of the route, which defaults to an empty string if omitted. The route path supports RegExp syntax.

You can add multiple method decorators as long as the path is the same, otherwise an exception is thrown when configuring the routes.

@Post() @Put()// allowedasyncmyFunction(ctx){ctx.body='Success';}
@Get('/options') @Options('/options')// allowedasyncmyFunction(ctx){ctx.body='Success';}
@Delete() @Head('/head')// throws exceptionasyncmyFunction(ctx){ctx.body='Failure';}

Request parameters

Request parameters in the route path can be defined by prefixing them with the ':' symbol, and can be accessed in the params field of the context.

@Get('/users/:userId/koalas/:koalaId')asyncfindById(ctx){constuserId=ctx.params.userId;constkoalaId=ctx.params.koalaId;// do something...}

Request body

A request's body can be found in ctx.request.body, but the request has to be parsed first. In order for the request body to be parsed, you need to specify what type the incoming data is in by using the @Json, @Form or @Multipart decorators.

@Post('/koalas')
@Json()asynccreateKoala(ctx){constbody=ctx.request.body;// incoming JSON data is in ctx.request.bodyctx.body=Koala.create(body);}

Alternatively, you can use the @Validate decorator.

@Post('/koalas')
@Validate({type: 'json',// can also be 'form' or 'multipart'failure: 403// status code if validation fails})asynccreateKoala(ctx){constbody=ctx.request.body;// incoming JSON data is in ctx.request.bodyctx.body=Koala.create(body);}

If the incoming data does not match the expected type, validation will fail and the response status will be set to 400, or the failure value set in the @Validate decorator.

Joi validation

The @Validate decorator can enforce Joi validation on request body parameters. If validation fails, response status is set to 400 and the route handler is never called. If you want to handle the error, you can set the continueOnError (default: false) field to true.

import{Post,Validate,Validator}from'koa-joi-controllers';
@Post('/koalas')
@Validate({type: 'json',body: {name: Validator.Joi.string().max(40),email: Validator.Joi.string().lowercase().email(),password: Validator.Joi.string().max(40),_csrf: Validator.Joi.string().token()},continueOnError: true// ctx.invalid is set to true if validation fails})asynccreateKoala(ctx){if(!ctx.invalid){Koala.create(ctx.request.body);}else{console.log('Validation failed!');}}

Named route parameter middleware

You can define middleware for named route parameters. This is useful for auto-loading or validation.

@Param('id')asyncparam(id,ctx,next){ctx.koala=Koala.findById(id);awaitnext();}
@Get('/:id')asyncfindById(ctx){ctx.body=ctx.koala;// ctx.koala was set by the @Param('id') middlewarectx.status=ctx.koala ? 200 : 404;}

Multiple middleware support

You can use the @Pre and @Chain decorators to add additional middleware to a specific route. The Pre middleware is called first, followed by the Chain middleware (can be multiple).

@Get('/chain')
@Pre(async(ctx,next)=>{ctx.body=[0];awaitnext();})
@Chain(async(ctx,next)=>{ctx.body.push(1);awaitnext();})
@Chain(async(ctx,next)=>{ctx.body.push(2);awaitnext();},async(ctx,next)=>{ctx.body.push(3);awaitnext();})asyncchain(ctx){ctx.body.push(4);}// GET /chain -> [0, 1, 2, 3, 4]

Adding metadata

You can store metadata about a route. This isn't used but is stored along with all other route data.

@Get('/hello')
@Meta({info: 'Hello World example',other: {data: 42}})asynchello(ctx){ctx.body='Hello World';}

Adding routes via the router

If you're looking for functionality that is not available with the current decorators, but is possible with koa-joi-router, you can achieve this by extending the router() method in your controller class.

@Controller()exportclassMyControllerextendsKoaController{router(){letrouter=super.router();// returns router with all routes defined with decorators// add all your routes hererouter.route({path: '/hello',method: 'get',handler: asyncfunction(ctx){ctx.body='Hello World';}});returnrouter;// router must be returned}}

Using with JavaScript

In order to use ES6 imports and decorators in a JavaScript project, some additional configurations need to be made. Install the necessary babel dependencies:

npm install --save-dev @babel/core @babel/preset-env @babel/node @babel/plugin-proposal-decorators

Create a .babelrc file in your project root:

{
"presets": [["@babel/preset-env", {"targets": {"node": true}}]],
"plugins": [["@babel/plugin-proposal-decorators", {"legacy": true}]]
}

Run with:

npx babel-node app.js

License

MIT