@k8ordo/router

Typed paths

Turn a misspelled pattern or param in a link into a type error. You can also use the types derived from the route table in your own code.

On this page

Param checks

ts
href('/products/:id', { id: '42' });
href('/products/:id');
No id: a type error
href('/products/:id', { productId: '42' });
productId is not in the pattern: a type error

href, navigateTo and useParams derive the type of the params from the pattern string they are given. With no setup at all, a missing or misspelled param is a type error.

Registering the route table

src/k8ordo-router.d.ts
import type { routes } from './routes';

declare module '@k8ordo/router' {
  interface Register {
    routes: typeof routes;
  }
}
ts
href('/products/:id', { id: '42' });
href('/prodcuts/:id', { id: '42' });
Not a pattern in the table: a type error

With no setup, any pattern starting with / passes, typos included. Add the route table to the Register interface, and a pattern missing from the table becomes a type error too.

After registering, each API accepts these patterns:

  • href, navigateTo: the patterns a link can point at
  • useParams: the patterns of the table
  • useMatch, matchPath: the patterns of the table, and those followed by /*

Register once, in the application. A library that registered would have every application that uses it checked against its table.

Write the same routes: typeof routes on Register of @k8ordo/state, and the paths handed to its href are checked against this route table. See Links of @k8ordo/state.

Information

Note

Under @k8ordo/framework, this registration is generated into .k8ordo/register.gen.ts. Do not write it yourself. See Routing for the generated files.

Types derived from the table

src/links.ts
import type { RegisteredNavigablePattern } from '@k8ordo/router';

export type SitePath = Exclude<
  Extract<RegisteredNavigablePattern, `/:locale${string}`>,
  `/:locale${string}:${string}`
>;

The SitePath above is the one this site uses: the patterns a link can point at that start with /:locale and have no param besides the locale. If the navigation data names a page missing from the table, it is a type error.

Four types are derived from the registered table.

  • RegisteredPattern: the pattern of every page in the table, /* patterns included
  • RegisteredNavigablePattern: the patterns a link can point at, without those containing /*
  • RegisteredParams<P>: the type of the params a link to pattern P takes
  • RegisteredPageParams<P>: the type of the params the page at pattern P receives

Before registering, the first two are any string starting with /.

Information

Note

Under @k8ordo/framework, links to a page with a paramsSchema, and the page itself, take its params as the type the schema produces. See Parameters.

ts
import type { NavigablePath } from '@k8ordo/router';

type A = NavigablePath<typeof routes, '/products/42'>;
// '/products/42'
type B = NavigablePath<typeof routes, '/products/42/reviews'>;
// never
type C = NavigablePath<typeof routes, '/products/'>;
// never

NavigablePath<typeof routes, Path> gives back the path when one of the patterns a link can point at matches it, and never when none does. Where a pattern has a param such as :id, any one non-empty segment fits.

A path with a trailing slash is refused. Matching treats /products/ as /products, but a link spells each path one way only.

k8ordo

React libraries that use Baseline features without holding back.