wip: type-safe href

Author: pcattori

packages/react-router-dev/typegen/index.ts

@@ -1,14 +1,17 @@
 import fs from "node:fs";
 
+import ts from "dedent";
 import * as Path from "pathe";
 import pc from "picocolors";
 import type vite from "vite";
 
 import { createConfigLoader } from "../config/config";
+import * as Babel from "../vite/babel";
 
 import { generate } from "./generate";
 import type { Context } from "./context";
 import { getTypesDir, getTypesPath } from "./paths";
+import type { RouteManifest, RouteManifestEntry } from "../config/routes";
 
 export async function run(rootDirectory: string) {
   const ctx = await createContext({ rootDirectory, watch: false });
@@ -81,4 +84,91 @@ async function writeAll(ctx: Context): Promise<void> {
     fs.mkdirSync(Path.dirname(typesPath), { recursive: true });
     fs.writeFileSync(typesPath, content);
   });
+
+  const registerPath = Path.join(typegenDir, "+register.ts");
+  fs.writeFileSync(registerPath, register(ctx));
+}
+
+function register(ctx: Context) {
+  const register = ts`
+    import "react-router";
+
+    declare module "react-router" {
+      interface Register {
+        params: Params;
+      }
+    }
+  `;
+
+  const { t } = Babel;
+
+  const typeParams = t.tsTypeAliasDeclaration(
+    t.identifier("Params"),
+    null,
+    t.tsTypeLiteral(
+      Object.values(ctx.config.routes)
+        .map((route) => {
+          // filter out pathless (layout) routes
+          if (route.id !== "root" && !route.path) return undefined;
+
+          const lineage = getRouteLineage(ctx.config.routes, route);
+          const fullpath =
+            route.id === "root"
+              ? "/"
+              : lineage
+                  .map((route) => route.path)
+                  .filter((path) => path !== undefined)
+                  .join("/");
+          const params = parseParams(fullpath);
+          return t.tsPropertySignature(
+            t.stringLiteral(fullpath),
+            t.tsTypeAnnotation(
+              t.tsTypeLiteral(
+                Object.entries(params).map(([param, isRequired]) => {
+                  const property = t.tsPropertySignature(
+                    t.stringLiteral(param),
+                    t.tsTypeAnnotation(t.tsStringKeyword())
+                  );
+                  property.optional = !isRequired;
+                  return property;
+                })
+              )
+            )
+          );
+        })
+        .filter((x): x is Babel.Babel.TSPropertySignature => x !== undefined)
+    )
+  );
+
+  return [register, Babel.generate(typeParams).code].join("\n\n");
+}
+
+function parseParams(fullpath: string) {
+  const result: Record<string, boolean> = {};
+
+  let segments = fullpath.split("/");
+  segments.forEach((segment) => {
+    const match = segment.match(/^:([\w-]+)(\?)?/);
+    if (!match) return;
+    const param = match[1];
+    const isRequired = match[2] === undefined;
+
+    result[param] ||= isRequired;
+    return;
+  });
+
+  const hasSplat = segments.at(-1) === "*";
+  if (hasSplat) result["*"] = true;
+  return result;
+}
+
+function getRouteLineage(routes: RouteManifest, route: RouteManifestEntry) {
+  const result: RouteManifestEntry[] = [];
+  while (route) {
+    result.push(route);
+    if (!route.parentId) break;
+    route = routes[route.parentId];
+  }
+  result.reverse();
+  return result;
 }

packages/react-router/index.ts

@@ -263,6 +263,9 @@ export type {
   FlashSessionData,
 } from "./lib/server-runtime/sessions";
 
+export type { Register } from "./lib/types/register";
+export { href } from "./lib/href";
+
 ///////////////////////////////////////////////////////////////////////////////
 // DANGER! PLEASE READ ME!
 // We provide these exports as an escape hatch in the event that you need any

packages/react-router/lib/href.ts

@@ -0,0 +1,49 @@
+import type { Register } from "./types/register";
+import type { Equal } from "./types/utils";
+
+type AnyParams = Record<string, Record<string, string | undefined>>;
+type Params = Register extends {
+  params: infer RegisteredParams extends AnyParams;
+}
+  ? RegisteredParams
+  : AnyParams;
+
+type HrefArgs = { [K in keyof Params]: ToHrefArgs<Params[K]> };
+
+// prettier-ignore
+type ToHrefArgs<T> =
+  // path without params -> no `params` arg
+  Equal<T, {}> extends true ? [] :
+  // path with only optional params -> optional `params` arg
+  Partial<T> extends T ? [T] | [] :
+  // otherwise, require `params` arg
+  [T];
+
+/**
+  Returns a resolved URL path for the specified route.
+
+  ```tsx
+  const h = href("/:lang?/about", { lang: "en" })
+  // -> `/en/about`
+
+  <Link to={href("/products/:id", { id: "abc123" })} />
+  ```
+ */
+export function href<Path extends keyof HrefArgs>(
+  path: Path,
+  ...args: HrefArgs[Path]
+): string {
+  let params = args[0];
+  return path
+    .split("/")
+    .map((segment) => {
+      const match = segment.match(/^:([\w-]+)(\?)?/);
+      if (!match) return segment;
+      const param = match[1];
+      if (params === undefined) {
+        throw Error(`Path '${path}' requires params but none were provided`);
+      }
+      return params[param];
+    })
+    .join("/");
+}

packages/react-router/lib/types/register.ts

@@ -0,0 +1,9 @@
+/**
+ * Apps can use this interface to "register" app-wide types for React Router via interface declaration merging and module augmentation.
+ * React Router should handle this for you via type generation.
+ *
+ * For more on declaration merging and module augmentation, see https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation .
+ */
+export interface Register {
+  // params
+}