siso v7.0.0

siso

siso is a routing utility allowing to map a path to a value

siso stands for "Shit In Shit Out". It allows to build routers without embedding a framework and falling into the gorilla banana problem ;).

It also matches the French "ciseau" word pronunciation which means "chisel".

Siso, works only for fixed length paths nodes which makes it fast. It also do no define the values validation and just takes a function returning a boolean to test the value.

If you plan to use it with OpenAPI, you have to know that the parameters definitions do not match the whole OpenAPI variants yet. It can only be used with the simple style variant and unique primitive values.

Usage

The siso concept is pretty simple. You associate paths patterns to values, then you pass a path in and get values and parameters out. And that's it, fair enough ;).

siso does not decide which separator is used for your paths so that you can use it for any routing concern.

import { Siso } from siso;

const siso = new Siso();

// Associate the '/v1/users' path to the 'user.list' value
siso.register([
  'v1',
  'users',
], 'user.list');

// Associate the '/v1/users/:id' path to the 'user.detail' value
siso.register([
  'v1',
  'users',
  {
    name: 'id',
    type: 'number',
    validate: (str) => /^[0-9]+$/.test(str),
  },
], 'user.detail');

// Find a value for /v1/users/12
siso.find(['v1', 'users', '12']);
// Returns: ['user.detail', {id: 12}]

Note that you can provide any value for a given path. It may be a function, an array, an object or a string depending of your needs.

Despite its simplicity, siso is very opinionated since it won't allow you to define several values for the same path pattern and will throw if such situation happens.

It is very different from the kind of routing systems you probably used before. Frameworks like Express would allow registering several middlewares for the same path, for instance.

My opinion is that it is a bad thing. Every route should have a single handler and higher order functions should be used instead. That way, you have the overhaul workflow of each route in their own controllers. No magic, no need to guess what happens before/after the route handler. Read my blog post on this concern.

siso is just a building block, if you need a higher level way to deal with routers see whook.

API

Siso

Siso

Kind: global class

• Siso
  • new Siso()
  • .register(pathNodes, value) ⇒ void
  • .find(pathNodes) ⇒ void

new Siso()

Create a new Siso instance

Returns: Siso - The Siso instance
Example

import { Siso } from 'siso';

const siso = new Siso();

siso.register(pathNodes, value) ⇒ void

Register a value for given path nodes

Kind: instance method of Siso

Example

import { Siso } from 'siso';

const siso = new Siso();

// Path nodes may be simple strings
siso.register(['v1', 'users'], 'user.list');

// Or dynamic nodes with a name and its corresponding validation function
siso.register([
  'v1',
  'users',
  { name: 'id', validate: (str) => /[a-f0-9]{24}/.test(str), type: 'string' },
], 'user.details');

siso.find(pathNodes) ⇒ void

Find the value for the given path

Kind: instance method of Siso

Example

import { Siso } from 'siso';

const siso = new Siso();

siso.register([
  'v1',
  'users',
  { name: 'userId', pattern: /[a-f0-9]{24}/, type: 'string' },
], 'anotherValue');

siso.find(['v1', 'users', 'abbacacaabbacacaabbacaca']);
// ['anotherValue', { userId: 'abbacacaabbacacaabbacaca' }]

Authors

• Nicolas Froidure

License

MIT