Unleash awesomeness. Private packages, team management tools, and powerful integrations. Get started with npm Orgs »

@thi.ng/router

1.0.3 • Public • Published

@thi.ng/router

npm version npm downloads Twitter Follow

This project is part of the @thi.ng/umbrella monorepo.

About

Generic router for browser & non-browser based applications with support for:

  • Declarative route definitions
  • Parametric routes, each param with optional value coercion & validation
  • Route authentication handler to enable/disable routes based on other state factors
  • Fallback route
  • Enforced initial route (optional)
  • Route formatting (with params)
  • HTML5 history & hash fragment support

Installation

yarn add @thi.ng/router

New since 2018-03-15: You can now create a preconfigured app skeleton using @thi.ng/atom, @thi.ng/hdom & @thi.ng/router using the create-hdom-app project generator:

yarn create hdom-app my-app
 
cd my-app
yarn install
yarn start

Dependencies

Usage examples

A complete, full commented demo app is here:

Source | Live demo

import { HTMLRouter, EV_ROUTE_CHANGED } from "@thi.ng/router";
 
// router configuration
const config = {
 
    // use hash fragment for routes
    useFragment: true,
 
    // fallback route (when no other matches)
    defaultRouteID: "home",
 
    // optional enforced route when router starts
    initialRouteID: "home",
 
    // Optional route path component separator. Default: `/`
    separator: "/",
 
    // Route prefix. Default: `/`. All routes to be parsed by `route()`
    // are assumed to have this prefix. All routes returned by
    // `format()` will include this prefix.
    prefix: "/",
 
    // actual route defs
    // these are checked in given order
    // IMPORTANT: rules with common prefixes MUST be specified in
    // order of highest precision / longest path
    routes: [
        {
            // each route MUST have an ID
            id: "home",
            // optional title for UI purposes (no internal function)
            title: "Home page",
            // this array defines the route path items
            match: ["home"]
        },
        {
            id: "user-profile",
            // this rule is parametric
            // variable items are prefixed with `?`
            match: ["users", "?id"],
            // coercion & validation handlers for "?id" param
            // coercion fn is applied BEFORE validator
            validate: {
                id: {
                    coerce: (x) => parseInt(x),
                    check: (x)=> x > 0 && x < 100
                }
            }
        },
        {
            id: "image",
            // this route has 2 params and matches (for example):
            // "/images/07a9d87b-c07a-42e3-82cf-baea2f94facc/xl"
            match: ["images", "?id", "?size"],
            validate: {
                id: {
                    check: (x)=> isUUID(x)
                },
                size: {
                    check: (x)=> /^(s|m|l|xl)$/.test(x)
                }
            },
            // enable auth for this route
            // (see info about authenticator functions below)
            auth: true
        },
        {
            id: "group-list",
            // matches only: "/users" or "/images"
            match: ["?type"],
            validate: {
                type: {
                    check: (x) => /^(users|images)$/.test(x)
                }
            },
            auth: true
        },
    ]
};
 
 
// `HTMLRouter` ONLY works in browser environments
// for non-browser use cases use `BasicRouter`
const router = new HTMLRouter(config);
router.addListener(EV_ROUTE_CHANGED, console.log);
 
router.start();

See further comments in source code

Authors

  • Karsten Schmidt

License

© 2014-2018 Karsten Schmidt // Apache Software License 2.0

install

npm i @thi.ng/router

Downloadsweekly downloads

39

version

1.0.3

license

Apache-2.0

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability