Chasten - Whither API Reference docs

This is whither's API reference, which is delibterately terse. The alternative is the more voluminous conceptual introduction, which has greater detail and usage guidance.

The NPM package @chasten/whither exports the following properties.

compile

Signature

(API specification) -> router

Description

Takes an API specification and returns a router. A router is needed to perform routing using byName and byUrl.

Example

const { compile } = require('@chasten/whither');

const apiSpecification = {
  '/users': {
    'GET': {
      'id': 'show-all-users',
    },
    'POST': {
      'id': 'create-user',
    },
  },
  '/users/*': {
    'DELETE': {
      'id': 'delete-user',
    },
    'PATCH': {
      'id': 'update-user',
    },
  },
};

const router = compile(apiSpecification);

byName

Signature

(router, id, ...pathArgs) -> destination.

Description

Takes a router, the ID of a destination, and zero or more (however many are required) pathArgs as arguments. Returns an object describing the destination of a request.

Example

const { byName } = require('@chasten/whither');
const router = require('./my-router');

byName(router, 'delete-user');
// Error: Route 'delete-user' has template '/users/*', which has 1
//        wildcard URL part, but you supplied 0.

byName(router, 'delete-user', '12345')
// { url: '/users/12345',
//   method: 'DELETE',
//   urlTemplate: '/users/*',
//   wildcardCount: 1,
//   id: 'delete-user' }

byUrl

Signature

(router, method, path) -> destination.

Description

Takes a router, an HTTP method, and an HTTP path as arguments. Returns an object describing the destination of a request.

Example

const { byUrl } = require('@chasten/whither');
const router = require('./my-router');

byUrl(routes, 'PATCH', '/squires/sancho-panza')
// undefined

byUrl(routes, 'PATCH', '/users/don-quixote')
// { url: '/users/don-quixote',
//   method: 'PATCH',
//   urlTemplate: '/users/*',
//   wildcardCount: 1,
//   id: 'update-user' }

HANDLER

Signature

Type: Symbol

Description

Use this symbol as key in a route destination to attach a handler for the route. Parfay will take care of calling this handler if used with whither's handler function.

Example

const { HANDLER, handler } = require('@chasten/whither');

const apiSpecification = {
  '/200-okay': {
    'GET': {
      [HANDLER]: (request) => ({ 'status': 200 }),
      'id': '200 Okay',
    },
  },
};

const router = compile(apiSpecification);
const handlerWithRouting = handler(router);

ROUTE

Signature

Type: Symbol

Description

This symbol will be used as the key to store a copy of the route destination in the request object, so your handler and middlewares can use this information if they need it.

Example

const { HANDLER, ROUTE, handler } = require('@chasten/whither');

const apiSpecification = {
  '/route-info': {
    'GET': {
      [HANDLER]: (request) => ({
        'body': JSON.stringify(request[ROUTE]),
        'headers': { 'Content-Type': 'application/json' },
        'status': 200,
      }),
      'id': '200 Okay',
    },
  },
};

const router = compile(apiSpecification);
const handlerWithRouting = handler(router);