pika-serville is an ES6 module fork of Serville. It matches the original Serville module described below, except that it is loaded via module import instead of Node's commonjs require(). See the updated code snippets below for the new import syntax.

Serville is a fast, tiny, and opinionated HTTP library for NodeJS.

Serville is perfect for your REST API - it serves up JSON, and it does it well! It takes just minutes to set it up and give it a whirl.

Set It Up:

npm i --save pika-serville

import Serville from 'pika-serville';

const app = Serville();
app.listen('8080');

app.at('/', (q) => ({ message: "Hello!" }));
// GET localhost:8080/
// => { "message": "Hello!" }

URL Parameters:

URL parameters can be specified by putting a colon before their name in the path. Their values will show up later in the params property.

app.at('/say/:text', (q) => ({ text: q.params.text }));
// GET localhost:8080/say/hello
// => { "text": "hello" }

Optional Trailing Slash:

Want to allow an optional trailing slash at the end of a URL? Add a question mark after it to make it optional!

app.at('/either/way/?', (q) => ({ message: "Hey there! "}));
// GET localhost:8080/either/way
// => { "message": "Hey there!" }
// GET localhost:8080/either/way/
// => { "message": "Hey there!" }

Returning Promises:

Instead of returning an object, you can also return a promise. This is useful for asynchronous operations.

app.at('/delay/:secs', (q) => {
  return new Promise((res) => {
    setTimeout(() => {
      resolve({ result: "DONE" });
    }, q.params.secs * 1000);
  })
});
// GET localhost:8080/delay/10
// (10 second delay)
// => { "result": "done" }

GET and POST queries:

GET and POST query data is stored in the query property.

app.at('/echo', (q) => ({ text: q.query.text }));
// GET localhost:8080/echo?text=Hello!
// => { "text": "Hello!" }
// POST localhost:8080/echo
// POST body: text=Hello!
// => { "text": "Hello!" }

Regular Expression Matching:

You can also match paths as regular expressions! The match property will contain the results of running RegExp.match(path) with your regex.

app.at(/^\/my-name-is-(.+)$/, (q) => (
  { message: `Hello, ${q.match[1]}!` }
));
// GET localhost:8080/my-name-is-Patricia
// => { "message": "Hello, Patricia!" }

Differentiating request types:

The get, post, put, and delete functions can be used to add bindings for specific request methods.

app.get('/method', () => ({ message: 'GET request!' }));
app.post('/method', () => ({ message: 'POST request!' }));
// GET localhost:8080/method
// => { "message": "GET request!" }
// POST localhost:8080/method
// => { "message": "POST request!" }

You can also specify several methods as a third array argument to at.

app.at('/method', () => ({message: 'PUT or DELETE request!'}), ['PUT', 'DELETE']);
// PUT localhost:8080/method
// => { "message": "PUT or DELETE request!" }
// DELETE localhost:8080/method
// => { "message": "PUT or DELETE request!" }

By default, all possible methods will be accepted:

app.at('/method', () => ({message: 'Something Else!'}));
// TRACE localhost:8080/method
// => { "message": "Something Else!" }

HTTP Request Headers:

The HTTP request headers are present in the headers property.

app.at('/agent', (q) => ({ agent: q.headers['user-agent'] }));

Handling Node HTTP Server Errors:

Sometimes, node encounters HTTP errors. Use catch to add a binding for when these errors occur.

app.catch((err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});

Handling Error Logging:

Want to control where the server logs data? Use the log function to specify a custom logger for error messages and other output. The default logger is simply console.log.

app.log((msg) => console.log(`Serville Error: ${msg}`));

Don't Crash on Binding Errors:

By default, when an uncaught error occurs in your binding code, the server will immediately crash. You can force the server to keep running as if nothing has happened using crashOnBindError.

app.crashOnBindError = false;

Please note that it is considered safer to crash when an unknown error occurs - it is not recommended to turn this option off.

Notes

• The NPM package does not include the project sources or certain files from the repository. This is to save space. If you want to save even more space, simply download serville.js and put it in your project instead. It's minified!

• Serville doesn't yet have full code-coverage unit testing and there may be some quirks or bugs. If you find anything, please submit an issue!

Contributing

Fork and clone this repository to get started, then run npm i to install dev dependencies. There's no formal contribution procedure (yet), feel free to submit PRs and issues as you see fit. Contributions are very much welcomed!

Just note that you can't work directly on the master branch, as it is protected. We recommend editing code on your own branch, then merging into develop. You may only merge with master after your PR is approved and continuous integration checks pass.

The source code for the library is in dev/serville.js. Modify the testing script in dev/test.js to try out your changes and new features. You can run these tests with npm run dev.

To build the current version of the server to serville.js, simply run npm run build.