@curi/router

Arguments

Arguments

import { browser } from "@hickory/browser";

let router = createRouter(browser, routes);

let routes = prepareRoutes([
  { name: "Home", path: "" },
  { name: "About", path: "about" }
]);

let router = createRouter(browser, routes);

import { createRouter, scroll } from "@curi/router";

let router = createRouter(browser, routes, {
  sideEffects: [scroll()]
});

let client = new ApolloClient();
let router = createRouter(browser, routes, {
  external: { client, greeting: "Hi!" }
});

let routes = prepareRoutes([
  {
    name: "User",
    path: "user/:id",
    resolve(match, external) {
      // use the external object to make a query
      return external.client.query();
    }
  }
]);

let routes = prepareRoutes([
  {
    name: "Old",
    path: "old/:id",
    respond({ params }) {
      // setup a redirect to the "New" route
      return {
        redirect: {
          name: "New",
          params
        }
      };
    }
  },
  {
    name: "New",
    path: "new/:id"
  }
]);

let router = createRouter(browser, routes, {
  invisibleRedirects: false
});
// navigating to "/old/2" will automatically redirect
// to "/new/2" without emitting a response for the Old route

Router

The router has a number of properties for you to use when rendering your application.

router.url({
  name: "User",
  params: { id: 1 },
  hash: "other"
});

router.navigate({ url: "/photos/123/456" });
// navigates to "/photos/123/456"
// using default "anchor" method

router.once(({ response }) => {
  // render the application based on the response
});

router.once(responseHandler, {
  initial: false
});

router.observe(({ response }) => {
  // render the application based on the response
});

let stopObserving = router.observe(fn);
// the router will call the response handler for all responses

stopObserving();
// the router no longer calls the response handler

router.observe(responseHandler, {
  initial: false
});

let stopCancelling = router.cancel(fn);
// fn will be called for async navigation

stopCancelling();
// fn will no longer be called

router.cancel(fn => {
  if (fn === undefined) {
    // the navigation has finished/been cancelled
  } else {
    // calling fn will cancel the navigation
  }
});

let router = createRouter(browser, routes);
let tooSoon = router.current();
// tooSoon.response === undefined
// tooSoon.navigation === undefined

router.once(({ response, navigation }) => {
  let perfect = router.current();
  // perfect.response === response
  // perfect.navigation === navigation
});

route.name

A string that will be used to identify a route. This must be unique for every route.

[
  { name: 'Home' },
  { name: 'Album' },
  { name: 'Not Found' }
];

route.path

A string pattern describing what the route matches. path strings should not have a leading slash.

[
  { path: "" }, // yes
  { path: "/" }, // no
]

A route's path is used to check if it matches a location's pathname. When the path matches, the route is selected.

Path matching is done using regular expressions compiled by path-to-regexp. A path can include parameters, which are dynamic variables that are parsed from a location's pathname. For advanced path formatting, please read path-to-regexp's documentaion.

[
  { name: 'Home', path: '' },
  // when the pathname is a/yo, albumID = "yo"
  { name: 'Album', path: 'a/:albumID' },
  // the path (.*) matches every pathname
  { name: 'Not Found', path: '(.*)' }
];

// don't include a leading forward slash
// { name: 'Home', path: '/' }

route.resolve

The resolve property is a function that returns a Promise. It is used to run asynchronous actions for a route prior to rendering.

A route with a resolve function is asynchronous, while one with no resolve functions is synchronous. You can read more about this in the sync or async guide.

Every time that a route with a resolve function matches, the route's resolve function will be called. Simple caching can be done with the once function from @curi/helpers, while more advanced caching is left to the user.

The function will be passed an object with the matched route properties: name, params, partials, and location.

let about = {
  name: 'About',
  path: 'about',
  resolve({ name, params, partials, location }) {
    return Promise.resolve("hurray!");
  }
};

The value returned by the resolve function will be passed to the route's respond function through its resolved property. If there is an uncaught error, resolved will be null and the error will be passed.

let about = {
  name: 'About',
  path: 'about',
  resolve({ name, params, partials, location }) {
    return Promise.resolve("hurray!");
  },
  respond({ resolved, error }) {
    if (error) {
      // there was an uncaught error in the resolve function
    }
  }
};

route.respond

A function for modifying the response object.

The object returned by a route's respond function will be merged with the route's intrinsic match properties to create the response object.

Only valid properties will be merged onto the response; everything else will be ignored. The valid properties are:

{
  respond: ({ match, resolved, error }) => {
    // ...
  }
}

// attach resolved data to the response
let user = {
  name: 'User',
  path: ':id',
  resolve({ params, location }) {
    return fetch(`/api/users/${params.id}`)
      .then(resp => JSON.parse(resp));
  },
  respond: ({ resolved }) => {
    return {
      data: resolved
    };
  }
}

// check if any of a route's resolve functions threw
let user = {
  name: 'User',
  path: ':id',
  resolve({ params, location }) {
    return fetch(`/api/users/${params.id}`)
      .then(resp => JSON.parse(resp));
  },
  respond: ({ error, resolved }) => {
    if (error) {
      return {
        meta: {
          error
        }
      };
    }
    return {
      data: resolved.data
    };
  }
}

import Home from "./components/Home";
let routes = prepareRoutes([
  {
    name: "Home",
    path: "",
    respond() {
      return { body: Home };
    }
  },
  // ...
]);
// response = { body: Home, ... }

{
  respond(){
    return {
      meta: {
        title: "Some Page",
        description: "This is some page",
        status: 200
      }
    };
  }
}

{
  respond() {
    return { data: Math.random() };
  }
}
// response = { data: 0.8651606708109429, ... }

[
  {
    name: "Old Photo",
    path: "photo/:id",
    respond({ params }) {
      return {
        redirect: { name: "Photo", params }
      };
    }
  },
  {
    name: "New Photo",
    path: "p/:id"
  }
]
// when the user navigates to /photo/1:
// response = { redirect: { pathname: "/p/1", ... } }

{
  name: "Redirects",
  path: "redirects",
  respond() {
    return {
      redirect: {
        externalURL: "https://example.com"
      }
    }
  }
}

children

An optional array of route objects for creating nested routes.

Any child routes will be matched relative to their parent route's path. This means that if a parent route's path string is "one" and a child route's path string is "two", the child will match a location whose pathname is /one/two.

// '/a/Coloring+Book/All+Night' will be matched
// by the "Song" route, with the params
// { album: 'Coloring+Book', title: 'All+Night' }
{
  name: 'Album',
  path: 'a/:album',
  children: [
    {
      name: 'Song',
      path: ':title'
    }
  ]
}

params

When path-to-regexp matches paths, all parameters are extracted as strings. The params object is used to specify functions to transform the extracted value.

Properties of the route.params object are the names of params to be parsed. The paired value should be a function that takes a string (the value from the pathname) and returns a new value (transformed using the function you provide).

By default, each param is decoded using decodeURIComponent. A param function can be used to leave the param in its encoded form or to parse an integer param into a number.

let routes = prepareRoutes([
  {
    name: 'Number',
    path: 'number/:num',
    params: {
      num: n => parseInt(n, 10)
    }
  }
]);

// when the user visits /number/1,
// response.params will be { num: 1 }
// instead of { num: "1" }

Unnamed params are referred to by their index in the path.

let routes = prepareRoutes([
  {
    name: 'Not Found',
    path: '(.*)',
    params: {
      // skip decoding the unmatched value
      0: value => value
    }
  }
]);

pathOptions

An object for configuring how the path-to-regexp handles the path.

{
  name: "My Route",
  path: "my/:item",
  pathOptions: {
    match: {
      sensitive: false
    },
    compile: {
      encode: (value, token) => value
    }
  }
}

extra

If you have any additional properties that you want attached to a route, use the extra property. You will be able to use route.extra in any custom route interactions.

let routes = prepareRoutes([
  {
    name: 'A Route',
    path: 'a-route',
    extra: {
      transition: 'fade'
    }
  },
  {
    name: 'B Route',
    path: 'b-route',
    extra: {
      enter: 'slide-right'
    }
  }
]);