Restar

Web library for rest api, async/await supported, simplistic with zero dependencies.

Installation

npm i restar -S

Benefits

• respond elegantly

app.get('/hello', () => {
  // return 'hello';
  return { s: 'hello' };
});

• comprehensible middleware

app.use(req => {
  req.startAt = Date.now();
});
 
app.get('/hello', () => {
  return 'hello';
});
 
app.end((req, res) => {
  res.setHeader('X-Response-Time', `${Date.now() - req.startAt}ms`);
});
 
/* only /hello set response time */
// app.end('/hello', (req, res) => {
//   res.setHeader('X-Response-Time', `${Date.now() - req.startAt}ms`);
// });

• error handling elegantly

app.get('/test', () => {
  throw new Error('test err');
});
 
app.catch(e => (req, res) => {
  return e.message || 'an error';
});
 
/* catch errors with route*/
// app.catch('/test', e => (req, res) => {
//   return e.message + '2' || 'an error';
// });

• async/await supported

app.get('/sleep', async () => {
  await sleep();
  return 'sleep 1s';
});
 
function sleep(delay = 1000) {
  return new Promise(resolve => setTimeout(resolve, delay));
}

• mount static directory with route

const serveStatic = require('serve-static');
app.use(serveStatic(path.join(__dirname, 'public')));
/*serve static with route*/
// app.use('/doc', routeStatic('/doc'), serveStatic(path.join(__dirname, '../public', 'doc')));
 
function routeStatic(path) {
  return function(req, res, next) {
    const tail = req.url.split(path)[1];
    if (!tail.includes('/')) {
      res.statusCode = 302;
      res.setHeader('Location', (path + '/' + tail).replace('//', '/'));
      res.end();
    } else {
      req.url = req.url.replace(path, '');
      next();
    }
  };
}

Usage

const Restar = require('restar');
let app = new Restar();
 
// use a global plugin
app.use((req, res) => {
  res.setHeader('X-Powered-By', 'Restar');
});
 
// equal to res.json({ name: 'restar' }) in express
app.get('/test', () => ({ name: 'restar' }));
 
// you can retrieve parameters by deconstructing
// (req,res)-({query,body})-({param:assign(query,body)})
app.post('/test', ({ param: { name } }) => {
  return name || null;
});
 
app.get(
  '/sleep',
  async () => {
    await sleep();
  },
  () => 'sleep 1s'
);
 
function sleep(delay = 1000) {
  return new Promise(resolve => setTimeout(resolve, delay));
}
 
app.listen(3000);

Async handler

app.[get|post|put|head|delete|options|all](handler1,handler2...)

handler(req?:IncomingMessage,res?:ServerResponse) : void|string|json|Buffer|ReadStream

app.get('/sleep', async () => {
  await sleep();
  return 'sleep 1s';
});
 
function sleep(delay = 1000) {
  return new Promise(resolve => setTimeout(resolve, delay));
}

API

app.use((req,res,next?)=>{})

Like express middleware

const serveStatic = require('serve-static');
app.use(serveStatic(path.join(__dirname, 'public')));

app.end((req,res,next?)=>{})

Like express middleware, execute after route handling

app.end((req, res) => {
  res.setHeader('X-Response-Time', `${Date.now() - req.startAt}ms`);
});

app.catch(e=>(req,res,next?)=>{})

Error handling

app.catch(e => () => {
  return e.message || 'an error';
});

Examples

Looking for more usages and examples

https://github.com/cooperhsiung/restar-examples

Boilerplate

Restar app boilerplate

https://github.com/cooperhsiung/restar-kit

Caveats

path-to-regex is unsupported

• any urls like http://localhost:3000/user/1 could be converted to http://localhost:3000/user?id=1

• when existing massive routes, it will hurt the preformance with path-to-regex

In view of the above, in most cases we may not need path-to-regex in restful web application

License

MIT