import { route, stringParser } from "typesafe-routes";

const accountRoute = route("/account/:accountId", {
  accountId: stringParser, // parser implicitly defines the static type (string) of 'accountId'
}, {});

// serialisation:
accountRoute({ accountId: "5c9f1e79e96c" }).$
// => "/account/5c9f1e79e96c"

// parsing:
accountRoute.parseParams({ accountId: "123"}).$
// => { accountId: "123" }

While stringParser is probably the most common parser/serializer there are also intParser, floatParser, dateParser, and booleanParser shipped with the module. But you are not limited to these. If you wish to implement your custom parserserializer just imlement the interface Parser<T>. You can find more details on that topic further down the page.

import { route } from "typesafe-routes";

const detailsRoute = route("/details", {}, {})
const settingsRoute = route("/settings", {}, { detailsRoute });
const accountRoute = route("/account", {}, { settingsRoute });

accountRoute({}).settingsRoute({}).detailsRoute({}).$
// => "/account/settings/details"

Parameters can be suffixed with a question mark (?) to make a parameter optional.

import { route, intParser } from "typesafe-routes";

const userRoute = route("/user/:userId/:groupId?", {
  userId: intParser,
  groupId: intParser // parser is required also required for optional parameters
}, {});

userRoute({ userId: 342 }).$ // groupId is optional
// => "/user/342"
userRoute({ userId: 5453, groupId: 5464 }).$
// => "/user/5453/5464"
userRoute({ groupId: 464 }).$
// => error because userId is missing

// parsing:
userRoute.parseParams({ userId: "65", groupId: "212" });
// returns { userId: 6, groupId: 12 }

Parameters can be prefixed with & to make the parameter a query parameter.

import { route, intParser } from "typesafe-routes";

const usersRoute = route("/users&:start&:limit", {
  start: intParser,
  limit: intParser,
}, {});

usersRoute({ start: 10, limit: 20 }).$
// returns "/users?start=10&limit=20"

When serialising nested routes query params are always being appended to the end of the locator string:

import { route, intParser } from "typesafe-routes";

const settingsRoute = route("/settings&:expertMode", {
  expertMode: booleanParser,
}, {});

const usersRoute = route("/users&:start&:limit", {
  start: intParser,
  limit: intParser,
}, {
  settingsRoute
});

usersRoute({ start: 10, limit: 20 }).settingsRoute({ expertMode: true })$
// returns "/users/settings?expertMode=true&start=10&limit=20"

userRoute.parseParams({ start: "10", limit: "20", expertMode: "false" });
// returns { start: 10, limit: 20, expertMode: false }

If you need to parse/serialize other datatypes than primitive types or dates or the build-in parsers don't meet your requirements for some reason you can create your own parsers with a few lines of code. The Parser<T> interface that helps yo to achieve that is defined as followed:

interface Parser<T> {
  parse: (s: string) => T;
  serialize: (x: T) => string;
}

The next example shows the implementation and usage of a typesafe Vector2D parser/serializer.

import { Parser, route } from "typesafe-routes";

interface Vector2D {
  x: number;
  y: number;
};

const vectorParser: Parser<Vector2D> = {
  serialize: (v) => btoa(JSON.stringify(v)),
  parse: (s) => JSON.parse(atob(s)),
};

const mapRoute = route("/map&:pos", { pos: vectorParser }, {});

mapRoute({ pos: { x: 1, y: 0 }}).$;
// returns "/map?pos=eyJ4IjoxLCJ5IjowfQ%3D%3D"

vectorParser.parseParams({pos: "eyJ4IjoxLCJ5IjowfQ=="})
// returns { pos: { x: 1, y: 0 }}

While library is not limited to react (e.g. express demo code in src/demo proves this statement) I've decided to add a few juicy react-router-specific utilities to this library.

useRouteParams(route: RouteNode)

Internally useRouteParams depends on useParams that will be imported from the optional dependency react-router-dom. However unlike useParams the useRouteParams function is able to parse query strings by utilising qs.

import { route } from "typesafe-routes";
import { useRouteParams } from "typesafe-routes/react-router";

const topicRoute = route("/:topicId&:limit?", {
  topicId: stringParser,
  limit: floatParser,
}, {});

const Component = () => {
  const { topicId, limit } = useRouteParams(topicRoute);

  return <>{...}</>;
}

<Link> and <NavLink>

Same as the original <Link> and <NavLink> from react-router-dom but require the to property to be a route:

import { route } from "typesafe-routes";
import { Link, NavLink } from "typesafe-routes/react-router";

const topicRoute = route("/topic", {}, {});

<Link to={topicRoute({})}>Topic</Link>
<NavLink to={topicRoute({})}>Topic</NavLink>

<Link to="/topic">Topic</Link> // error "to" prop can't be string 
<NavLink to="/topic">Topic</NavLink> // error "to" prop can't be string 

template

typesafe-routes implements a subset of template syntax of react-router and thus is compatible with it. But since specifying additional query params would break the compatibility (react-router doesn't understand the & prefix) the .template property doesn't contain any of such parameters and can be used to define router in your react-router app:

import { route } from "typesafe-routes";

const topicRoute = route("/:topicId&:limit?", {
  topicId: stringParser,
  limit: floatParser,
}, {});

<Route path={topicRoute.template}> // template only contains the "/:topicId" path
  <Topic />
</Route>