express-res-status v1.0.2

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

License

MIT