Miss any of our Open RFC calls?Watch the recordings here! »

@zarcobox/responser

1.1.0 • Public • Published

Responser

The simplest way to send HTTP responses in express.

vscode suggestions

While creating an API, a programmer should not always need to be concerned about the status code and the data type of your responses. Responser gives you a simple way of returning an REST API base response for each one of the HTTP status codes availables.

License: MIT npm version Build Status Coverage Status Downloads

npm

Installation

The latest version is available at: https://www.npmjs.com/package/@zarcobox/responser

Use your favorite package manager to install. For instance:

  yarn add @zarcobox/responser

Then import it:

import responser from '@zarcobox/responser'

Or, for commonjs:

const responser = require('@zarcobox/responser')

Add responser as an express middleware:

app.use(responser)

And you're good to go!

Usage

Since responser overwrites Express' interface, you can find the responser send_* methods directly in the express response.

Methods accept two parameters:

  • Required: message (string)
  • Optional: data || errors (any | undefiend)

Consider the following code which has a response local variable (the name does not matter given its type is Response):

import { Request, Response } from 'express'
 
class PlanetController {
 
  async index(request: Request, response: Response) {
 
    const planets = [ 'Mercury', 'Venus', 'Earth', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune' ]
 
    return response.send_ok('Planets were found successfully!', {
      planets
    })
  }
}
 
export default new PlanetController()

The above code generates the following response:

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
 
{
  "code": 200,
  "status": "OK",
  "message": "Planets were found successfully!",
  "success": true,
  "data": {
    "planets": [
       "Mercury",
       "Venus",
       "Earth",
       "Mars",
       "Jupiter",
       "Saturn",
       "Uranus",
       "Neptune"
     ]
  }
}

An example of unsuccessful response would be:

import { Request, Response } from 'express'
 
class PlanetController {
 
  async post(request: Request, response: Response) {
 
    const { planetName, planetSize } = request.body
 
    let invalid = []
 
    if(!planetName) invalid.push(
      { name: 'planetName', message: 'The planet name was not given!' }
    )
 
    // ...
 
    if(invalid.length) return response.send_badRequest(
      'The request contains one or more errors!', invalid
    )
 
    // ...
 
  }
}
 
export default new PlanetController()

Which outputs:

  {
    status: 'BAD_REQUEST',
    code: 400,
    message: 'The request contains one or more errors!',
    success: false,
    errors: [
      { name: 'planetName', message: 'The planet name was not given!' }
    ]
  }

Where:

  • code is a number HTTP Status Code;

  • status is a string with the name of the HTTP Status;

  • success is a boolean which is true for 1XX and 2XX HTTP Status Codes;

  • data or errors is the key for your second argument containing the payload. It is undefined if none is given.

Note: data is the key name when success is true while errors is the key when success is false.

Methods

With typescript, you can easily access all methods by typing .send_ in your response variable. The following methods are currently available (method, code and status).

send_accepted                      202 ACCEPTED 
send_badGateway                    502 BAD_GATEWAY 
send_badRequest                    400 BAD_REQUEST 
send_conflict                      409 CONFLICT 
send_continue                      100 CONTINUE 
send_created                       201 CREATED 
send_expectationFailed             417 EXPECTATION_FAILED 
send_failedDependency              424 FAILED_DEPENDENCY 
send_forbidden                     403 FORBIDDEN 
send_gatewayTimeout                504 GATEWAY_TIMEOUT 
send_gone                          410 GONE 
send_httpVersionNotSupported       505 HTTP_VERSION_NOT_SUPPORTED 
send_imATeapot                     418 IM_A_TEAPOT 
send_insufficientSpaceOnResource   419 INSUFFICIENT_SPACE_ON_RESOURCE 
send_insufficientStorage           507 INSUFFICIENT_STORAGE 
send_internalServerError           500 INTERNAL_SERVER_ERROR 
send_lengthRequired                411 LENGTH_REQUIRED 
send_locked                        423 LOCKED 
send_methodFailure                 420 METHOD_FAILURE 
send_methodNotAllowed              405 METHOD_NOT_ALLOWED 
send_movedPermanently              301 MOVED_PERMANENTLY 
send_movedTemporarily              302 MOVED_TEMPORARILY 
send_multiStatus                   207 MULTI_STATUS 
send_multipleChoices               300 MULTIPLE_CHOICES 
send_networkAuthenticationRequired 511 NETWORK_AUTHENTICATION_REQUIRED 
send_noContent                     204 NO_CONTENT 
send_nonAuthoritativeInformation   203 NON_AUTHORITATIVE_INFORMATION 
send_notAcceptable                 406 NOT_ACCEPTABLE 
send_notFound                      404 NOT_FOUND 
send_notImplemented                501 NOT_IMPLEMENTED 
send_notModified                   304 NOT_MODIFIED 
send_ok                            200 OK 
send_partialContent                206 PARTIAL_CONTENT 
send_paymentRequired               402 PAYMENT_REQUIRED 
send_permanentRedirect             308 PERMANENT_REDIRECT 
send_preconditionFailed            412 PRECONDITION_FAILED 
send_preconditionRequired          428 PRECONDITION_REQUIRED 
send_processing                    102 PROCESSING 
send_proxyAuthenticationRequired   407 PROXY_AUTHENTICATION_REQUIRED 
send_requestHeaderFieldsTooLarge   431 REQUEST_HEADER_FIELDS_TOO_LARGE 
send_requestTimeout                408 REQUEST_TIMEOUT 
send_requestTooLong                413 REQUEST_TOO_LONG 
send_requestUriTooLong             414 REQUEST_URI_TOO_LONG 
send_requestedRangeNotSatisfiable  416 REQUESTED_RANGE_NOT_SATISFIABLE 
send_resetContent                  205 RESET_CONTENT 
send_seeOther                      303 SEE_OTHER 
send_serviceUnavailable            503 SERVICE_UNAVAILABLE 
send_switchingProtocols            101 SWITCHING_PROTOCOLS 
send_temporaryRedirect             307 TEMPORARY_REDIRECT 
send_tooManyRequests               429 TOO_MANY_REQUESTS 
send_unauthorized                  401 UNAUTHORIZED 
send_unprocessableEntity           422 UNPROCESSABLE_ENTITY 
send_unsupportedMediaType          415 UNSUPPORTED_MEDIA_TYPE 
send_useProxy                      305 USE_PROXY 

Testing

Run the test suit with yarn test.

Contributing

If you want to contribute in any of theses ways:

  • Give your ideas or feedback
  • Question something
  • Point out a problem or issue
  • Enhance the code or its documentation
  • Help in any other way

You can (and should) open an issue or even a pull request!

Thanks for your interest in contributing to this repo!

Author

Luiz Felipe Zarco (felipezarco@hotmail.com)

License

This code is licensed under the MIT License. See the LICENSE.md file for more info.

Install

npm i @zarcobox/responser

DownloadsWeekly Downloads

10

Version

1.1.0

License

MIT

Unpacked Size

31.3 kB

Total Files

14

Last publish

Collaborators

  • avatar