@restless/restless

Restless

Express.js api, validations and more.

• Easy to write and read
• Declarative
• Type safe

import express from 'express'
import { asyncHandler, responseOf, sanitize } from '@restless/restless'
import { asNumber } from '@restless/sanitizers'

const app = express()
app.get('/add/:a/:b', asyncHandler(
  sanitize({
    a: asNumber,
    b: asNumber
  }),
  ({ a, b }) => responseOf(a + b)
))

Later:

GET /add/1/2 -> 200: 3
GET /add/foo/2 -> 400: { path: 'params.a', expected: 'number' }

Installation

npm install @restless/restless
yarn add @restless/restless

Api

• asyncHandler
• responseOf
• responseOfBuffer
• sanitize
• SanitizeError

asyncHandler

This function is essentially an async pipe. It takes a set of possibly async functions that are called with the return value of the previous function. It returns an express middleware that should be passed as a route handler to express.

Every function passed to asyncHandler takes two arguments:

• Return value of the previous function (undefined in case of the first one)
• The express Request object

Example:

import express from 'express'
import { asyncHandler, responseOf } from '@restless/restless'

const app = express()
app.get('/:foo', asyncHandler(
  (_, request) => request.params.foo,
  (foo) => responseOf(`Param foo is: ${foo}`)
))

Response functions

These are simple higher-order helper functions used to construct express responses. The asyncHandler requires that the last function passed to it returns a response function.

responseOf

Used to send json data:

responseOf({ foo: 'bar' }) // default 200 status
responseOf({ error: 'NOT_FOUND' }, 404) // custom status-code

responseOfBuffer

Used to send binary data from Buffer, use the first argument to specify data type:

responseOfBuffer('png', Buffer.from('ABC', 'ascii')) // default 200 status
responseOfBuffer('jpeg', Buffer.from('ABC', 'ascii'), 404) // custom status-code

Custom responses

In order to create a custom response all you need to do is write a custom function for it. Let's see how to create a response function for rendering views. First we need to consult the express documentation. There we see that in order to send a rendered view to the client we must call res.render. Writing a function for restless is now a piece of cake:

import { ResponseFunction } from '@restless/restless'
import { Response } from 'express'

export const responseOfView = (view: string, locals?: any, status = 200): ResponseFunction =>
  res => res
    .status(status)
    .render(view, locals)

Sanitization

This library exports all sanitizers from the @restless/sanitizers library.

sanitize

The sanitize function is a transformer. It transforms the request into an object that matches a schema you provide.

The keys in the provided schema correspond to the url parameters or the values on the request object from express. This means that if you try to sanitize a request to /users/:id calling sanitize({ id: ..., body: ... }) will check the req.params.id and req.body.

sanitize returns a function that is to be passed to asyncHandler.

Example:

import express from 'express'
import { asyncHandler, responseOf, sanitize } from '@restless/restless'
import { asObject, asNumber } from '@restless/sanitizers'

const app = express()
app.get('/:foo', asyncHandler(
  sanitize({
    foo: asNumber,
    body: asObject({
      bar: asNumber
    }),
    query: asObject({
      baz: asNumber
    })
  })
  (data) => responseOf(data)
))

For this declaration a valid request is as follows:

GET /123?baz=456 '{"bar":789}'

SanitizeError

This is the error that is thrown when sanitize function receives data that does not match the schema.