response-handler v1.3.0

Response Handler

Cuando se envía el resultado de una petición desde un servicio web, ésta debe incluir suficiente información para que sea interpretado adecuadamente por la aplicación cliente.

Esta librería ofrece un mecanismo simple y flexible que permite dar formato a las respuestas de un servicio web creado con express.

Características

• Es posible definir dos tipos de respuestas success y error.
• El formato de la respuesta es personalizable.
• Se puede configurar para que todas las peticiones sean exitosas (status: 200 Ok).

Tipos de errores

Tipos de respuesta exitosa

Función success

Esta función permite crear un middleware que adiciona las propiedades success, success200 y success201 al objeto response de una petición.

function successHandler (data) {
  return data
}
function onSuccess (result, req) {
  // TODO
}
function successFormat (result) {
  return {
    name     : result.name,
    status   : result.status,
    type     : result.type,
    code     : result.code,
    message  : result.message,
    data     : result.data,
    metadata : result.metadata
  }
}

app.use(Response.success({ successHandler, onSuccess, successFormat }))

Respuestas con el método success200

res.success200({ id: 1, titulo: 'El gato negro' })
res.success200({ id: 1, titulo: 'El gato negro' }, 'Libro obtenido exitosamente.')
res.success200([{ id: 1, titulo: 'El gato negro' }], 'Libro obtenido exitosamente.', { count: 1 })

{
  "name": "ResponseHandlerSuccess",
  "status": "success",
  "type": "OK",
  "code": 200,
  "message": "Libro obtenido exitosamente.",
  "data": [
    {
      "id": 1,
      "titulo": "El gato negro"
    }
  ],
  "metadata": {
    "count": 1
  }
}

Función error

Al igual que con la función success, esta función permite crear un middleware que adiciona las propiedades error, error400, error401, etc. al objeto response de una petición.

function errorHandler (data) {
  return data
}
function onError (result, req) {
  // TODO
}
function errorFormat (result) {
  return {
    name    : result.name,
    status  : result.status,
    type    : result.type,
    code    : result.code,
    message : result.message,
    errors  : result.errors,
    parent  : result.parent
  }
}

app.use(Response.error({ errorHandler, onError, errorFormat }))

Respuestas con el método error400

// Errores producidos desde un controlador
res.error400('msg1')
res.error400({ msg: 'msg1', dev: 'dev1' })
res.error400([{ msg: 'msg1', dev: 'dev1' }, { msg: 'msg2', dev: 'dev2' }])

// Errores producidos desde un midleware
throw new BadRequest('msg1')
throw new BadRequest({ msg: 'msg1', dev: 'dev1' })
throw new BadRequest([{ msg: 'msg1', dev: 'dev1' }, { msg: 'msg2', dev: 'dev2' }])

// Errores producidos desde un controlador de errores
function (err, req, res, next) => {
  err = BadRequest.create('msg1')
  err = BadRequest.create({ msg: 'msg1', dev: 'dev1' })
  err = BadRequest.create([{ msg: 'msg1', dev: 'dev1' }, { msg: 'msg2', dev: 'dev2' }])

  res.error(err)
}

{
  "name": "ResponseHandlerError",
  "status": "error",
  "type": "BAD_REQUEST",
  "code": 400,
  "message": "Petición incorrecta",
  "errors": [
    {
      "msg": "msg1",
      "dev": "dev1"
    },
    {
      "msg": "msg2",
      "dev": "dev2"
    }
  ]
}

Instalación

Para instalar sobre un proyecto, ejecutar el siguiente comando:

$ npm install --save response-handler

Ejemplo

const { Response, errors }   = require('response-handler')
const { PreconditionFailed } = errors
const express    = require('express')
const bodyParser = require('body-parser')

const app = express()
app.use(bodyParser.json())

app.use(Response.success())
app.use(Response.error())

app.post('/libros', (req, res, next) => {
  if (!req.body.titulo) {
    throw new PreconditionFailed('Se requiere el título del libro.')
  }
  res.success200(req.body)
})

app.use((err, req, res, next) => {
  res.error(err)
})

app.listen(4000)

Respuesta exitosa

curl -H "Content-Type: application/json" -X POST -d '{ titulo": "El cuervo" }' http://localhost:4000/libros

{
  "name": "ResponseHandlerSuccess",
  "status": "success",
  "type": "OK",
  "code": 200,
  "message": "Tarea completada exitosamente.",
  "data": {
    "titulo": "El gato negro"
  },
  "metadata": null
}

Respuesta con error

curl -H "Content-Type: application/json" -X POST http://localhost:4000/libros

{
  "name": "ResponseHandlerError",
  "status": "error",
  "type": "PRECONDITION_FAILED",
  "code": 412,
  "message": "Condición insuficiente",
  "errors": [
    {
      "msg": "Se requiere el título del libro.",
      "dev": null
    }
  ]
}