Routtl (pronounced rout·le)

Lightweight routing primitives.

WIP, don't use in production. Expect occasional breaking changes until we hit stable in 1.0.0.

Usage

import { route, string } from 'routtl';

const helloRoute = route`/hello/${string('world')}`;

const url = helloRoute.encode({ params: { world: 'world' } });
//     ^ '/hello/world'

const data = helloRoute.decode('/hello/world');
//     ^ { params: { world: 'world' } }

Overview

Routtl is a small set of primitives for defining routes and encoding/decoding data to/from that route. It is small (around 800 bytes of JavaScript compressed), has no dependencies, and provides type-safe decoding and encoding. It uses JavaScript's tagged template literals to provide a declarative, composable API for defining routes.

Decoders

Default decoders are provided for primitive JS types (e.g. string, number, boolean, date). A simple Decoder interface is provided to extend or build your own decoding. Additionally, a decoder factory is provided for arrays of arbitrary types.

Built-in decoders include:

• string
• int
• float
• date
• datetime
• array, allows you to define an array of a certain decoder

Decoding Search Params

At the end of a route definition you can define a way to decode a routes search params. It must be the last interpolated value and be proceeded by a ?.

import { route, search, date } from 'routtl';

const searchRoute = route`/?${search({ filter: date })}`;

const url = searchRoute.encode({ search: { filter: new Date('2000-01-01') } });
//     ^ '/?filter=2000-01-01'

Templating HTML

When templating HTML, you can use route.encode() to generate the href for an <a> tag. Here is an example using lit-html as a template engine:

import { route, string } from 'routtl';
import { render, html } from 'lit-html';

const helloRoute = route`/hello/${['world', string]}`;

render(document.body, html`<a href="${helloRoute.encode({ world: 'world' })}">Link</a>`);

Composing

RouteParsers can be composed together as shown here:

import { route, string } from 'routtl';

const helloRoute = route`/hello`;

const worldRoute = route`${helloRoute}/world/${string('id')}`;

const url = helloRoute.encode({ params: { id: 'foo' } });
//     ^ '/hello/world/foo'

Roadmap

• Built-in decoders
• Decoder type safely
• Nest Route Parsers
• Decode query parameters
• Ignore case and other options

Contributing

See the guide.

Inspiration

Lots of inspiration for this project! @ncthbrt was crucial to the early prototypes. vue-router, navaid, typesafe-routes have been influential in the design of these primitives.

There is also an API called URLPattern that has recently emerged from the WHATWG standards body that addresses some of the problems routtl is solving. At the time of this writing its only supported by Chromium browsers. A 3rd party a polyfill is available as well.