express-api-responder

A small Express.js Middleware for conveniently formatting JSON responses. This package builds into the Express.js response object and allows you to return data in the following:

• A response after a successful request
• Paginated data for a list
• An error for a bad request or other errors
• No content after a deletion
• Signing a request with a JWT auth token
• Catch a server error and return an error message without important knowledge of the system

Setup

npm install express-responder --save

Can be used by your whole app or a router

var repsonder = require('express-responder');
app.use(responder());
//or
var router = express.Router();
router.use(responder({}));
 
//How to use
router.get('/messages', function(req, res) {
  res.success({hello: 'world'});
})

Outputs 200

{
  "hello": "world"
}

Return Success Response

Returns a JSON body. By default returns HTTP status code 200 but a code can be passed.

res.success({item1: 'Hello', item2: false}, 201);

Output 200

{
  "item1": "Hello",
  "item2": false
}

Return Error Response

Returns a JSON body with a message field for error handling. Defaults the HTTP status code to 400. The message also defaults to a description based on the code

res.error('Cant find your message', 404);
//Or default to the code descriptor
res.error(null, 404);

Output 404

{
  "message": "Cant find your message"
}

or

{
  "message": "Not Found"
}

Paginated Responses

Returns a JSON object with a list of data as well as some useful fields. Defaults 200 HTTP status code

var data = [{name: 'Eric'}, {name: 'Dufresne'}, ...];
var totalCount = 50;
var page = 1;
var limit = 25;
res.paginate(data, totalCount, page, limit);

Output: 200

{
  "list": [
    {
      "name": "Eric"
    },
    {
      "name": "Dufresne"
    }
  ],
  "limit": 25,
  "page": 1,
  "count": "50",
  "pages": 2
}

Catch Internal Server Error

Returns an error message based on the HTTP status code given for an unexpected error. Defaults to HTTP status code 500 but a code can be passed.

res.catch(err);

In production environment 500

{
  "message": "Internal Server Error"
}

if not in a production environment 500

{
  "message": "Table \"messages\" doesn't exist..."
}

Signing Responses

Must provide a JWT secret or private key to the responder options.

app.use(responder({
  signing: {
    jwtSecret: 'some-super-secret'
  }
}));
 
res.sign({hello: 'world', id: 32});

Response 200

{
  "data": {
    "id": 32,
    "hello": "world"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoZWxsbyI6IndvcmxkIiwiaWQiOjMyLCJpYXQiOjE1MTUzNzI0NzN9.uU_9EoOSodk6tR4LdzxYaAVefkVjXtdxfCfSM_OynKo"
}

No Content

res.noContent();

Extra Options

You can include the status code as well as a success flag in all the JSON responses by passing extra options to the middleware.

app.use(responder({
  includeCode: 'status',
  includeSuccess: 'success'
}));
 
res.error(null, 409);

Response 409

{
  "success": false,
  "status": 409,
  "message": "Conflict"
}

Run Tests

Tests use a mock server with the middleware in place. Can run using mocha as well as with istanbul

npm run test
npm run cover