Check paths with types

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

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

Unlike a param, a typo in the pattern itself passes with no setup. Register the route table on Register, and a pattern the table lacks is a type error too.

import type { routes } from './routes';

declare module '@k8ordo/router' {
  interface Register {
    routes: typeof routes;
  }
}

href('/products/:id', { id: '42' });
href('/prodcuts/:id', { id: '42' });
Not a pattern in the table: a type error

Before registering, any string starting with / passes. After it, href and navigateTo accept only the patterns a link can point at, and useParams only the table’s patterns. useMatch and matchPath accept the table’s patterns, and those followed by /*.

Register once, in the app. A library that registered would impose its route table on every app that uses it.

The types derived from the route table are yours to use too, for example to limit the destinations a navigation lists to pages the table has.

import type { RegisteredNavigablePattern } from '@k8ordo/router';

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

This is this site’s SitePath: the linkable patterns that start with /:locale and have no param besides the locale. Naming a page the table lacks in the navigation data 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, which leaves out those with /*
• RegisteredParams<P>: the params a link to pattern P takes
• RegisteredPageParams<P>: the params the page at pattern P receives

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

@k8ordo/state’s Register takes the same line. With it, the paths handed to @k8ordo/state’s href are checked against the same route table this router matches against.

import type { routes } from './routes';

declare module '@k8ordo/router' {
  interface Register {
    routes: typeof routes;
  }
}

declare module '@k8ordo/state' {
  interface Register {
    routes: typeof routes;
  }
}

listState.href('/products', { q: 'lamp' }); // '/products?q=lamp'
listState.href('/prodcuts', { q: 'lamp' });
No pattern in the table matches: a type error

@k8ordo/state’s href takes an actual path rather than a pattern, with values where the params go, as in /products/42. Whether it fits any pattern is checked segment by segment.

The check @k8ordo/state uses is a type called NavigablePath. Anything else that takes a path can use the same type.

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 gives back the path when it fits one of the linkable patterns, and never when none fits. 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 path written into a link is kept to one spelling.

It does not build a type listing every path in the table to compare against, because a page such as /:locale would turn that type into /${string}, which takes every path there is.