zensen-router

A declarative router for native web components.

Features

• Listens to any changes in the route
• Gives the ability to cancel route changes
• Easy way of parsing route and querystring params
• Conditionally invoke behahvior based on the current route

Install

Using npm:

$ npm install @zensen/router

Using yarn:

$ yarn add @zensen/router

API

Configuring routing settings (hash-based routing is enabled by default)

configure({ useHash: false })

Getting routes with the following window URL:

http://www.my-domain.com/sub-route/#/users/123/photos/456

import { getRoute } from '@zensen/router'

// hash-routing enabled
const route = getRoute() //  /users/123/photos/456

// hash-routing disabled
const route = getRoute() //  /sub-route/#/users/123/photos/456

Navigating to a different route

import { navigate } from '@zensen/router'

// hash-routing enabled
navigate('/users/123') // http://www.my-domain.com/#/users/123

// hash-routing disabled
navigate('/users/123') // http://www.my-domain.com/users/123

Redirecting to a different route

Note: This is just like navigate(), except it doesn't push to the browser's history.

import { redirect } from '@zensen/router'

// hash-routing enabled
redirect('/users/123') // http://www.my-domain.com/#/users/123

// hash-routing disabled
redirect('/users/123') // http://www.my-domain.com/users/123

Getting route params

import { getParams } from '@zensen/router'

// Example window URL:
// http://www.my-domain.com/#/users/123/photos/456
const { userId, photoId } = getParams('/users/:userId/photos/:photoId')

// Example when explicity providing route
const { userId, photoId } = getParams(
  '/users/:userId/photos/:photoId',
  '/users/123/photos/456'
)

Getting querystring params

import { getQuerystring } from '@zensen/router'

// Example window URL:
// http://www.my-domain.com?search=asdf&sort=asc
const { search, sort } = getQuerystring()

// Example when explicity providing route
const { search, sort } = getQuerystring(
  'http://www.my-domain.com?search=asdf&sort=asc'
)

Detecting route changes

import { EVENT_ROUTE_CHANGE } from '@zensen/router'

window.addEventListener(EVENT_ROUTE_CHANGE, e =>
  console.info('changing route:', e.detail)
)

Canceling route changes

import { EVENT_ROUTE_SHOULD_CHANGE } from '@zensen/router'

window.addEventListener(EVENT_ROUTE_SHOULD_CHANGE, e => {
  // block all route changes to /users/
  if (e.detail === '/users/') {
    e.preventDefault()
  }
})

Detecting when route changes are canceled

import { EVENT_ROUTE_CANCEL } from '@zensen/router'

window.addEventListener(EVENT_ROUTE_CANCEL, e =>
  console.info('route change canceled:', e.detail)
)

Matching against a route

import { matchRoute } from '@zensen/router'

// Example window URL:
// http://www.my-domain.com/#/users/123/photos/456?filter=upload-date&sort=asc
const result = matchRoute(
  '/users/:id/',
  (tail, { querystring, params }) => `
    <p>Tail URL: ${tail}</p>
    <p>User: ${params.id}</p>
    <p>Filter: ${querystring.filter}</p>
    <p>Sort: ${querystring.sort}</p>
  `,
  '', // do not explicity provide a route, so that it uses window.location
  false // set to false to allow routes to be longer than paths it's matched against
)

/*
  Result:
    <p>User: 123</p>
    <p>Tail URL: /photos/456</p>
    <p>Filter: upload</p>
    <p>Sort: asc</p>
 */

import { matchRoute } from '@zensen/router'

const result = matchRoute(
  '/photos/:id/',
  (tail, { id }) =>
    `
    <p>Photo: ${id}</p>
    <p>Tail URL: ${tail}</p>
  `,
  '/photos/456' // providing the tail route from the previous example
)

/*
  Result:
    <p>Photo: 456</p>
    <p>Tail URL: /</p>
 */

Matching against multiple possible routes

const items = [
  {
    path: '/users/',
    resolver: tail => `
      <p>Tail Route: ${tail}</p>
    `
  },
  {
    path: '/photos/',
    resolver: tail => `
      <p>Tail Route: ${tail}</p>
    `
  },
  {
    path: '/',
    resolver: () => `<p>404 - Not Found</p>`
  }
]

import { matchRouteSwitch } from '@zensen/router'

// Example window URL:
// http://www.my-domain.com/#/users/123
const result = matchRouteSwitch(items)

/*
  Result:
    <p>Tail Route: /123</p>
 */

import { matchRouteSwitch } from '@zensen/router'

// Example window URL:
// http://www.my-domain.com/#/photos/456
const result = matchRouteSwitch(items)

/*
  Result:
    <p>Tail Route: /456</p>
 */