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' }

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

License

MIT