Restless

Express.js api, validations and more.

1. Easy to write and read
2. Declarative
3. Type safe

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

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' }

Api

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:

1. Return value of the previous function (undefined in case of the first one)
2. 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

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 with the exception of body and query which correspond to the request body and parsed query string respectively.

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

Example:

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

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.

asString

Accepts any value that is a string. Returns a string.

asString('asd') // OK 'asd'
asString(123) // FAIL (not a string)

asNumber

Accepts any value that is a number or a string that represents a number. Returns a number.

asNumber(123) // OK 123
asNumber('0.2') // OK 0.2
asNumber('boo') // FAIL (not a number)
asNumber({}) // FAIL (not a number)

asBoolean

Accepts any value that is a number or a string that represents a boolean ("true" or "false"). Returns a number.

asBoolean(true) // OK true
asBoolean('false') // OK false
asBoolean('boo') // FAIL (not a boolean)
asBoolean(123) // FAIL (not a boolean)

asMatching

This higher-order sanitizer accepts values that are strings matching the regex provided as an argument. You can pass a custom message to it.

const sanitizer = asMatching(/aaa/, 'custom message')

sanitizer('aaa') // OK 'aaa'
sanitizer(123) // FAIL (custom message)
sanitizer('b') // FAIL (custom message)

asObject

This higher-order sanitizer requires a schema in the form of an object. Values of the schema are sanitizers used to sanitize the values of the input. Returns an object with keys and values matching the schema.

const sanitizer = asObject({ foo: asNumber, bar: asString })

sanitizer({ foo: 1, bar: 'a' }) // OK { foo: 1, bar: 'a' }
sanitizer(123) // FAIL (not an object)
sanitizer({}) // FAIL (missing values)
sanitizer({ foo: true, bar: 'a' ) // FAIL (foo is not a number)

asArray

This higher-order sanitizer accepts any value that is an array of items that are sanitized through the sanitizer passed as argument.

const sanitizer = asArray(asNumber)

sanitizer([123, '45']) // OK [123, 45]
sanitizer(123) // FAIL (not an array)
sanitizer([123, 'foo']) // FAIL (2nd element does not sanitize as a number)

asOptional

This higher-order sanitizer accepts undefined or null or any value that is sanitized through the sanitizer passed as argument.

const sanitizer = asOptional(asString)

sanitizer('abcdef') // OK 'abcdef'
sanitizer(null) // OK null
sanitizer(undefined) // OK undefined
sanitizer(123) // FAIL (not a string or null or undefined)

asChecked

This higher-order sanitizer accepts any value that is sanitized through the sanitizer passed as argument and satisfies the predicate passed as the second argument.

const sanitizer = asChecked(asString, x => x.length > 3)

sanitizer('abcdef') // OK 'abcdef'
sanitizer(123) // FAIL (not a string)
sanitizer('a') // FAIL (too short)