Koa JSON Error

Error handler for pure Koa >=2.0.0 JSON apps where showing the stack trace is cool!

npm install --save koa-json-error

Versions >=3.0.0 support Koa ^2.0.0. For earlier versions of Koa, please use previous releases.

Requirements

• node >=6.0.0
• koa >=2.2.0

Starting from 3.2.0, this package supports node >=6.0.0 to match Koa requirements.

API

'use strict';
const koa = require('koa');
const error = require('koa-json-error')

let app = new Koa();
app.use(error())

If you don't really feel that showing the stack trace is that cool, you can customize the way errors are shown on responses. There's a basic and more advanced, granular approach to this.

Basic usage

You can provide a single formatter function as an argument on middleware initialization. It receives the original raised error and it is expected to return a formatted response.

Here's a simple example:

'use strict';
const koa = require('koa');
const error = require('koa-json-error')

function formatError(err) {
    return {
        // Copy some attributes from
        // the original error
        status: err.status,
        message: err.message,

        // ...or add some custom ones
        success: false,
        reason: 'Unexpected'
    }
}

let app = new Koa();
app.use(error(formatError));

This basic configuration is essentially the same (and serves as a shorthand for) the following:

'use strict';
let app = new Koa();
app.use(error({
    preFormat: null,
    format: formatError
}));

See section below.

Advanced usage

You can also customize errors on responses through a series of three formatter functions, specified in an options object. They receive the raw error object and return a formatted response. This gives you fine-grained control over the final output and allows for different formats on various environments.

You may pass in the options object as argument to the middleware. These are the available settings.

options.preFormat (Function)

Perform some task before calling options.format. Must be a function with the original err as its only argument.

Defaults to:

(err) => Object.assign({}, err)

Which sets all enumerable properties of err onto the formatted object.

options.format (Function)

Runs inmediatly after options.preFormat. It receives two arguments: the original err and the output of options.preFormat. It should return a newly formatted error.

Defaults to adding the following non-enumerable properties to the output:

const DEFAULT_PROPERTIES = [
  'name',
  'message',
  'stack',
  'type'
];

It also defines a status property like so:

obj.status = err.status || err.statusCode || 500;

options.postFormat (Function)

Runs inmediatly after options.format. It receives two arguments: the original err and the output of options.format. It should return a newly formatted error.

The default is a no-op (final output is defined by options.format).

This option is useful when you want to preserve the default functionality and extend it in some way.

For example,

'use strict';
const _ = require('lodash');
const koa = require('koa');
const error = require('koa-json-error')

let options = {
    // Avoid showing the stacktrace in 'production' env
    postFormat: (e, obj) => process.env.NODE_ENV === 'production' ? _.omit(obj, 'stack') : obj
};
let app = new Koa();
app.use(error(options));

Modifying the error inside the *format functions will mutate the original object. Be aware of that if any other Koa middleware runs after this one.