1.0.2 • Published 8 years ago

express-res-status v1.0.2

Weekly downloads
90
License
MIT
Repository
github
Last release
8 years ago

express-res-status

Extends res object with semantic method that correspondes to description/message/reason phrase associated with HTTP status code, thus shortening sending HTTP response by using self descriptive methods instead of codes and forcing usage of human readable part of HTTP statuses and adding more meaning to REST API.

Under the hood

Methods are built on top of Express methods .json(), .send(), .end(), so you can treat them the same.

So, invoking a method, e.g res.ok(data), is the same as doing res.status(200).json(data).

If there is an err in the middleware, it will be passed down the stack (calling next(err)), so you can place your err-handler at the end and handle the err.

It uses Node.JS' built-in module http, namely, its STATUS_CODES object, from which it creates methods from description property, and assigns(defines, actually) them to res object.

Why http?

http exports list in a nice, code-desc format, it comes with Node.JS, and parsing from other sources could be planned for some later upgrade

Usage

Use any standard (cannot use custom codes) HTTP code's description/message/reason phrase in a camelCase format, for example:

418 I'm a teapot

would be used as:

res.imATeapot('I\'m a teapot, have some tea... C(_)/¨');

and, instead of:

res.status(200).json(data);

you have:

res.ok(data);

and instead of:

res.status(404).json(errMsg);

you have:

res.notFound(errMsg);

etc.

But, if you still prefer codes, you can use codes as methods:

res[404](errMsg);

or

res[500](errMsg);

etc.

Example usage:

import {Router} from 'express';
import {resStatus} from 'express-res-status';

const route = Router();

// plug-in middleware before your routes
// .json() handler is default,
// pass 'send', 'end' or 'none' to use them,
// read further for explanation
route.use(resStatus());

route.get('/some-api', (req, res, next) => {
		
		if (somethingBackendWise) {

			// return 200 OK + payload
			res.ok(data); // equals: res.status(200).json(data);

		} else {

			// return 404 Not Found + errMsg
			res.notFound(errMsg); // equals: res.status(404).json(errMsg);
		}
	});
	// etc.

Setting response end handlers

You can chose one of Express' response handlers by providing one of the options as endHandler argument:

  • json: default, to use .json(), equals: res.status(code).json(body);
  • send: to use .send(), equals: res.status(code).send(body);
  • end: to use .end(), equals: res.status(code).end(body);
  • none: to only set up status code, it doesn't end response, equals: res.status(code);

usage:

// to use `.send()`, pass 'send' as an arg
// when setting up middleware
app.use(resStatus('send'));
//...and in routes:
res.notFound('whatever you usually send to res.send()');

or

// use your own way
app.use(resStatus('none'));
//...
// not really handy, but still
res.notFound().render('404', {msg: res.notFound.desc});

Middleware helper methods

  • res.resStatusAll - lists all available methods with code and desc
  • res.resStatusCode(code); - returns code and description for provided code (code param can be Number or String)

example:

res.resStatusAll; // array with `{method, code, desc}` fromat
res.resStatusCode(400); //{ method: 'badRequest', code: '400', desc: 'Bad Request' }
// ...and if code is not found...
res.resStatusCode(1337)) // { error: 'No such code' }

resmethod helper methods

  • res.[method].code - gets specific method's HTTP code
  • res.[method].desc - gets specific method's HTTP description

example:

res.ok.code; // 200
res.ok.desc; // 'OK'

Example

See also full full example

run example locally

npm i
npm start

Visit: http://localhost:1337

Enter ?status=ok' or ?status=200 in address bar to get ok method HTTP response, or any other available method as value of status key, as a string or number.

Methods list

Besides using res.resStatusAll:

For (fresh) full list of methods: https://github.com/nodejs/node/blob/master/lib/_http_server.js#L40-L103

develop

npm i
gulp

todo

  • add html and xml handlers
  • add tests for the rest of end handlers
  • handle special cases (like some 1xx, 3xx etc.)
  • fix linting

dump of methods list at the time of creating readme

res[method]CodeDesc/reason phrase
res.continue();100Continue
res.switchingProtocols();101Switching Protocols
res.processing();102Processing
res.ok();200OK
res.created();201Created
res.accepted();202Accepted
res.nonAuthoritativeInformation();203Non-Authoritative Information
res.noContent();204No Content
res.resetContent();205Reset Content
res.partialContent();206Partial Content
res.multiStatus();207Multi-Status
res.alreadyReported();208Already Reported
res.imUsed();226IM Used
res.multipleChoices();300Multiple Choices
res.movedPermanently();301Moved Permanently
res.found();302Found
res.seeOther();303See Other
res.notModified();304Not Modified
res.useProxy();305Use Proxy
res.temporaryRedirect();307Temporary Redirect
res.permanentRedirect();308Permanent Redirect
res.badRequest();400Bad Request
res.unauthorized();401Unauthorized
res.paymentRequired();402Payment Required
res.forbidden();403Forbidden
res.notFound();404Not Found
res.methodNotAllowed();405Method Not Allowed
res.notAcceptable();406Not Acceptable
res.proxyAuthenticationRequired();407Proxy Authentication Required
res.requestTimeout();408Request Timeout
res.conflict();409Conflict
res.gone();410Gone
res.lengthRequired();411Length Required
res.preconditionFailed();412Precondition Failed
res.payloadTooLarge();413Payload Too Large
res.uriTooLong();414URI Too Long
res.unsupportedMediaType();415Unsupported Media Type
res.rangeNotSatisfiable();416Range Not Satisfiable
res.expectationFailed();417Expectation Failed
res.imATeapot();418I\'m a teapot
res.misdirectedRequest();421Misdirected Request
res.unprocessableEntity();422Unprocessable Entity
res.locked();423Locked
res.failedDependency();424Failed Dependency
res.unorderedCollection();425Unordered Collection
res.upgradeRequired();426Upgrade Required
res.preconditionRequired();428Precondition Required
res.tooManyRequests();429Too Many Requests
res.requestHeaderFieldsTooLarge();431Request Header Fields Too Large
res.unavailableForLegalReasons();451Unavailable For Legal Reasons
res.internalServerError();500Internal Server Error
res.notImplemented();501Not Implemented
res.badGateway();502Bad Gateway
res.serviceUnavailable();503Service Unavailable
res.gatewayTimeout();504Gateway Timeout
res.httpVersionNotSupported();505HTTP Version Not Supported
res.variantAlsoNegotiates();506Variant Also Negotiates
res.insufficientStorage();507Insufficient Storage
res.loopDetected();508Loop Detected
res.bandwidthLimitExceeded();509Bandwidth Limit Exceeded
res.notExtended();510Not Extended
res.networkAuthenticationRequired();511Network Authentication Required

License

MIT