@spa-tools/core-router

State Interpolation

The @spa-tools/core-router package makes passing and consuming state in routing flows so easy that you could say it's auto-magic.

import { CoreRouter, routesFactory } from '@spa-tools/core-router';

const createMyRoutes = routesFactory();

// here we create two routes, one for navigating to all products using
// query template params for sorting while the other route is for navigating
// to products for a category via a path param with no query params, yet
// we will demo how the same sort state can be auto-interpolated into the
// path without explicit query templating
const myRoutes = createMyRoutes({
  productsRoute: {
    // here we explicitly define sort query params in the path
    path: '/products?sortBy=:sortBy&sortDir=:sortDir',
    // here we configure this route so the router removes any query params
    // that do not get interpolated from the route state (i.e. orphaned
    // query params); this is useful for keeping the URL clean and free of
    // unnecessary query params that still contain placeholder tokens
    removeUnusedQueryParams: true,
  },
  productsByCategoryRoute: {
    // here we define a path param for the category but we
    // do NOT specify the sort query params in the path
    path: '/products/category/:category',
    // here we configure this route so the router adds any unused state
    // to the query string; this will enable us to include the same sort
    // state in the URL without explicitly defining it in the path
    addUnusedStateToQueryString: true,
  },
});

// here we create a new instance of the CoreRouter class and pass in
// our routes object; we also pass in an object that implements the
// router lifecycle callback onRouteChange so we can log outcomes
const myRouter = CoreRouter.initialize(myRoutes, {
  onRouteChange: () => {
    // this is where we would perform any post-processing logic, which
    // typically means rendering the requested route. How to do this
    // ranges based on the UI framework being used, so here we simply
    // log path info to the console.
    //
    // If you're using React or want to create an abstraction for a
    // different rendering package/framework, you should definitely
    // check out the Core React Router abstraction, which has the
    // rendering logic sweetly baked in.
    console.log(
      `Route change with interpolated path: ${window.location.pathname + window.location.search + window.location.hash}`
    );
  },
});

// here we navigate to the products route with sort state
// so you should see the sort info interpolated in the path
// (check console and browser URL)
myRouter.navigate(myRoutes.productsRoute, {
  sortBy: 'price',
  sortDir: 'asc',
});

// here we navigate to the same products route but this time without
// any sort state, so the sort query params should now be auto-removed
// from the interpolated path (check console and browser URL)
myRouter.navigate(myRoutes.productsRoute);

// here we navigate to the products-by-category route with sort state
// so you should see both the category and sort info auto-interpolated
// in the path (check console and browser URL)
myRouter.navigate(myRoutes.productsByCategoryRoute, {
  category: 'electronics',
  sortBy: 'price',
  sortDir: 'desc',
});