README
koa-boom
Koa middleware adding a custom boom method to the context.
When use it?
You can use this module if you need to use the Sigfox way of formatting errors using Boom.
Features
- Mount a custom boom method to the context. ctx.status & ctx.body are filled by the Boom error content
- Exports a boom helper that can be used by providing it the context. That can be a great alternative to using the middleware
- Accepts a custom function taking the koa context as a parameter, it allows you to define when a validation error should be returned depending on the context.
- By default, a status 400 is considered as a validation error by koa-boom and add the formatted error to ctx.body.validation
Install
npm install @sigfox/koa-boom
Usage
As a middleware:
const Koa = require('koa');
const koaBoom = require('@sigfox/koa-boom');
const app = new Koa()
.use(koaBoom())
.use(async ctx => {
return ctx.boom(boom.badRequest('invalid query'));
})
.listen();
// it will set the body with:
// {
// statusCode: 400,
// error: 'Bad Request',
// message: 'invalid query'
// }
app.use(async ctx => {
return ctx.boom(boom.badRequest('device does not exist', 'message.deviceId'));
});
// it will set the body with:
// {
// statusCode: 400,
// error: 'Bad Request',
// message: 'device does not exist',
// validation: [{
// message: 'device does not exist',
// path: 'message.deviceId',
// type: 'custom',
// context: { key: 'deviceId' }
// }]
// }
app.use(async ctx => {
return ctx.boom(
boom.badRequest('device does not exist', {
field: 'message.deviceId',
type: 'unknown',
value: 'XXXX'
})
);
});
// it will set the body with:
// {
// statusCode: 400,
// error: 'Bad Request',
// message: 'device does not exist',
// validation: [{
// message: 'device does not exist',
// path: 'message.deviceId',
// type: 'unknown',
// context: { key: 'deviceId', value: 'XXXX' }
// }]
// }
app.use(async ctx => {
return ctx.boom(
boom.badRequest('device does not exist', [
{
message: 'device does not exist',
path: 'message.deviceId',
type: 'unknown',
context: { key: 'deviceId', value: 'XXXX' }
}
])
);
});
// it will set the body with:
// {
// statusCode: 400,
// error: 'Bad Request',
// message: 'device does not exist',
// validation: [{
// message: 'device does not exist',
// path: 'message.deviceId',
// type: 'unknown',
// context: { key: 'deviceId', value: 'XXXX' }
// }]
// }
with custom validation
const Koa = require('koa');
const koaBoom = require('@sigfox/koa-boom');
const isValidationError = (ctx) => !![400, 423].includes(ctx.status);
const app = new Koa()
.use(koaBoom(isValidationError)
.use(async ctx => {
return ctx.boom(boom.badData('invalid query'));
})
.listen();
// it will set the body with:
// {
// statusCode: 422,
// error: 'Unprocessable Entity',
// message: 'invalid query'
// }
As a helper:
const Koa = require('koa');
const boom = require('boom');
const { boomHelper } = require('koa-boom');
const app = new Koa()
.use(async ctx => {
return boomHelper(ctx, boom.badRequest('invalid query'));
})
.listen();
with custom validation
const Koa = require('koa');
const boom = require('boom');
const { boomHelper } = require('koa-boom');
const isValidationError = ctx => !![400, 423].includes(ctx.status);
const app = new Koa()
.use(async ctx => {
return boomHelper(ctx, boom.badData('invalid query'), isValidationError);
})
.listen();
Test
npm test
Licence
This project is licensed under the MIT License - see the LICENSE file for details.