Sirver NPM | npm.io

Sir 🎩 ver

A tiny, very polite, server for building simple async HTTP services.

Install

npm i -S sirver

API

The following methods are exposed:

method	arguments	returns	description
sir	Yes	Object	Creates and returns an instance of the http.Server Object.
bodyParser	Yes	Promise	Parses and returns an incoming HTTP JSON request body as a JavaScript Object.

sir(requestHandler)

Creates and returns an instance of the http.Server Object.

Arguments

argument	type	required	description
requestHandler	Function	Yes	This handler is invoked upon every incoming HTTP request and exposes the http.incomingMessage and http.serverResponse Objects. The `requestHandler` supports `async-await`, see this example for more information.

Response convenience methods

The requestHandler exposes a couple of convenience methods on the http.serverResponse Object:

res.status(code:Number): code is a valid http status code.
res.html(html:String): html is a valid HTML document representation.
res.json(data:Object): data is a valid JavaScript Object, which can be parsed to JSON.

See the examples section for more information.

Returns

http.Server

bodyParser(request, limit)

Parses and returns an incoming HTTP JSON request body as a JavaScript Object.

Arguments

argument	type	required	description
request	Object	Yes	The http.incomingMessage Object, exposed by requestHandler. See this example for more information.
limit	Number or String	No	The byte limit of the body. This is the number of bytes or any string format supported by bytes, for example `1000`, `'500kb'` or `'3mb'`. If the body ends up being larger than this limit, a `413` error code is returned. Defaults to 1 MB.

Note that the raw-body module is used for body parsing functionality.

Returns

Promise

Examples

Basic

'use strict';

const { sir } = require('sirver');

const server = sir((req, res) => {
	res.end('ok');
});

server.listen(7777);

JSON

'use strict';

const { sir } = require('sirver');

const server = sir((req, res) => {
	res.json({ status: 'ok' });
});

server.listen(7777);

HTML

'use strict';

const { sir } = require('sirver');

const server = sir((req, res) => {
	res.html(`
		<!DOCTYPE html>

		<html>
			<head>
				<title>HTML</title>
			</head>

			<body>
				<h1>Hello World!</h1>
			</body>
		</html>
	`);
});

server.listen(7777);

Async

'use strict';

const { sir } = require('sirver');

const server = sir(async (req, res) => {
	const _async = () => new Promise(
		(resolve, reject) => {
			setTimeout(
				() => resolve({ status: 'async' }),
				2e3
			)
		}
	);

	const data = await _async();

	res.json(data);
});

server.listen(7777);

Parsing request body

'use strict';

const { sir, bodyParser } = require('sirver');

const server = sir(async (req, res) => {
	const body = await bodyParser(req);

	console.log('request body: ', body);

	res.end();
});

server.listen(7777);

Custom response codes

'use strict';

const { sir, bodyParser } = require('sirver');

const server = sir(async (req, res) => {
	const { name } = await bodyParser(req);

	if (!name) {
		return res
			.status(400)
			.json({ error: 'Name is required' });
	}

	res.json({ name });
});

server.listen(7777);

Route handling

'use strict';

const url = require('url');
const { sir, bodyParser } = require('sirver');

const server = sir(async (req, res) => {
	try {
		const { method } = req;
		const { pathname } = url.parse(req.url);

		if (method === 'GET' && pathname === '/') {
			return res.json({
				status: 'ok for route "/"'
			});
		}

		if (method === 'POST' && pathname === '/run') {
			return res.json({
				status: 'ok for route "/run"'
			});
		}

		res.status(404).json({
			error: 'The requested route doesn\'t exist.'
		});
	} catch (err) {
		res.status(err.code || 500).json({
			error: err.toString()
		});
	}
});

server.listen(7777);