@troyio/vite-file-router 0.2.6 → 0.2.7

package/README.md

@@ -197,8 +197,36 @@ remain in the tree. React Router's generated `routes` remain the runtime source
 of truth.
 
 The development server watches the configured directory. Adding, removing,
-renaming, or editing route files invalidates both virtual modules and reloads
-the app without requiring a server restart.
+renaming, or editing route files invalidates all generated virtual modules and
+reloads the app without requiring a server restart.
+
+### Typed route helpers
+
+Import `routePath` from `virtual:route-helpers` to build paths for discovered
+pages. The helper is compatible with React Router's `Link`, `NavLink`,
+`navigate`, and `redirect` APIs. Dynamic parameter names and required values are
+checked from the path literal; values are URL-encoded. Splat values use the
+React Router `"*"` parameter and are encoded segment-by-segment so `/`
+separators are preserved:
+
+```tsx
+import { Link } from "react-router";
+import { routePath } from "virtual:route-helpers";
+
+export function UserLink({ userId }: { userId: string }) {
+  return (
+    <Link to={routePath("/users/:userId", { userId })}>
+      View user
+    </Link>
+  );
+}
+
+const docsPath = routePath("/docs/*", { "*": "guides/getting-started" });
+```
+
+Static routes need no parameter object: `routePath("/")`. Unknown route
+patterns and missing or extra parameters are rejected at runtime. The generated
+`routePatterns` export contains the discovered page paths.
 
 ### TypeScript setup
 

package/dist/index.js

@@ -14,6 +14,12 @@ function getRouteSegment(name) {
 	if (name.startsWith("[...") && name.endsWith("]")) return "*";
 	return name.replace(/^\[(.+)\]$/, ":$1");
 }
+function collectPageRoutePatterns(node, segments = [], root = true) {
+	const routeSegments = root || node.routeGroup ? segments : [...segments, getRouteSegment(node.name)];
+	const patterns = node.page ? [`/${routeSegments.join("/")}`] : [];
+	for (const child of node.children) patterns.push(...collectPageRoutePatterns(child, routeSegments, false));
+	return patterns;
+}
 function scan(directory, conventions = DEFAULT_CONVENTIONS) {
 	const node = {
 		name: path.basename(directory),
@@ -210,6 +216,8 @@ var ROUTES_MODULE_ID = "virtual:routes";
 var ROUTES_RESOLVED_ID = `\0${ROUTES_MODULE_ID}`;
 var MANIFEST_MODULE_ID = "virtual:route-manifest";
 var MANIFEST_RESOLVED_ID = `\0${MANIFEST_MODULE_ID}`;
+var ROUTE_HELPERS_MODULE_ID = "virtual:route-helpers";
+var ROUTE_HELPERS_RESOLVED_ID = `\0${ROUTE_HELPERS_MODULE_ID}`;
 function resolveOptions(input) {
 	const options = typeof input === "string" ? { directory: input } : input;
 	if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("routes() expects a directory string or options object.");
@@ -281,6 +289,49 @@ function routes(input = "src/pages") {
 		const manifest = createRouteManifest(scan(root, options.conventions), projectRoot);
 		return format(`export const routeManifest = ${JSON.stringify(manifest, null, 2)};`, { parser: "typescript" });
 	}
+	async function executeRouteHelpers() {
+		const tree = scan(root, options.conventions);
+		const patterns = [...new Set(collectPageRoutePatterns(tree))].sort();
+		const code = `
+      export const routePatterns = ${JSON.stringify(patterns)};
+
+      export function routePath(pattern, ...args) {
+        if (!routePatterns.includes(pattern)) {
+          throw new TypeError(\`Unknown route pattern "\${pattern}".\`);
+        }
+
+        const params = args[0] ?? {};
+        const parameterNames = [...pattern.matchAll(/:([^/]+)|\\*/g)].map(
+          ([, name]) => name ?? "*",
+        );
+        for (const key of Object.keys(params)) {
+          if (!parameterNames.includes(key)) {
+            throw new TypeError(\`Unknown route parameter "\${key}" for "\${pattern}".\`);
+          }
+        }
+        return pattern.replace(/:([^/]+)|\\*/g, (token, name) => {
+          const key = name ?? "*";
+          if (!Object.hasOwn(params, key)) {
+            throw new TypeError(\`Missing route parameter "\${key}" for "\${pattern}".\`);
+          }
+          const value = String(params[key]);
+          if (key !== "*" && value.length === 0) {
+            throw new TypeError(
+              'Route parameter "' +
+                key +
+                '" for "' +
+                pattern +
+                '" cannot be empty.',
+            );
+          }
+          return key === "*"
+            ? value.split("/").map(encodeURIComponent).join("/")
+            : encodeURIComponent(value);
+        });
+      }
+    `;
+		return format(code, { parser: "typescript" });
+	}
 	return {
 		name: "routes",
 		configResolved(config) {
@@ -291,10 +342,12 @@ function routes(input = "src/pages") {
 		resolveId: (id) => {
 			if (id === ROUTES_MODULE_ID) return ROUTES_RESOLVED_ID;
 			if (id === MANIFEST_MODULE_ID) return MANIFEST_RESOLVED_ID;
+			if (id === ROUTE_HELPERS_MODULE_ID) return ROUTE_HELPERS_RESOLVED_ID;
 		},
 		load: (id) => {
 			if (id === ROUTES_RESOLVED_ID) return execute();
 			if (id === MANIFEST_RESOLVED_ID) return executeManifest();
+			if (id === ROUTE_HELPERS_RESOLVED_ID) return executeRouteHelpers();
 		},
 		configureServer: (server) => {
 			server.watcher.add(root);
@@ -309,7 +362,11 @@ function routes(input = "src/pages") {
 				const location = path.resolve(file);
 				const relative = path.relative(root, location);
 				if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return;
-				for (const id of [ROUTES_RESOLVED_ID, MANIFEST_RESOLVED_ID]) {
+				for (const id of [
+					ROUTES_RESOLVED_ID,
+					MANIFEST_RESOLVED_ID,
+					ROUTE_HELPERS_RESOLVED_ID
+				]) {
 					const module = server.moduleGraph.getModuleById(id);
 					if (module) server.moduleGraph.invalidateModule(module);
 				}

package/dist/scanner.d.ts

@@ -21,5 +21,6 @@ export type RouteManifestNode = {
 };
 export declare const DEFAULT_CONVENTIONS: Record<RouteFileKind, string>;
 export declare function getRouteSegment(name: string): string;
+export declare function collectPageRoutePatterns(node: Node, segments?: string[], root?: boolean): string[];
 export declare function scan(directory: string, conventions?: Record<RouteFileKind, string>): Node;
 export declare function createRouteManifest(node: Node, projectRoot: string, parentPath?: string, root?: boolean): RouteManifestNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@troyio/vite-file-router",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "File-system routing plugin for Vite",
   "type": "module",
   "private": false,

package/types/index.d.ts

@@ -7,3 +7,47 @@ export type {
   RouteManifestNode,
   RoutesOptions,
 } from "../dist/index.js";
+
+export type RouteParameterValue = string | number;
+
+type RouteParametersForSegment<Segment extends string> =
+  Segment extends `:${infer Name}`
+    ? { [Key in Name]: RouteParameterValue }
+    : Segment extends "*"
+      ? { "*": RouteParameterValue }
+      : {};
+
+export type RouteParameters<Path extends string> =
+  Path extends `${infer Segment}/${infer Rest}`
+    ? RouteParametersForSegment<Segment> & RouteParameters<Rest>
+    : RouteParametersForSegment<Path>;
+
+type RouteParameterShapes<Path extends string> =
+  Path extends unknown ? RouteParameters<Path> : never;
+
+type UnionToIntersection<Union> = (
+  Union extends unknown ? (value: Union) => void : never
+) extends (value: infer Intersection) => void
+  ? Intersection
+  : never;
+
+type RouteRequiresParameters<Path extends string> =
+  Path extends unknown
+    ? keyof RouteParameters<Path> extends never
+      ? false
+      : true
+    : never;
+
+type HasParameterShapeMismatch<Path extends string> =
+  [RouteParameterShapes<Path>] extends [
+    UnionToIntersection<RouteParameterShapes<Path>>,
+  ]
+    ? false
+    : true;
+
+export type RoutePathArguments<Path extends string> =
+  true extends RouteRequiresParameters<Path>
+    ? HasParameterShapeMismatch<Path> extends true
+      ? [params: never]
+      : [params: RouteParameters<Path>]
+    : [];

package/types/virtual-routes.d.ts

@@ -7,3 +7,13 @@ declare module "virtual:route-manifest" {
   import type { RouteManifestNode } from "@troyio/vite-file-router";
   export const routeManifest: RouteManifestNode;
 }
+
+declare module "virtual:route-helpers" {
+  import type { RoutePathArguments } from "@troyio/vite-file-router";
+
+  export const routePatterns: readonly string[];
+  export function routePath<const Path extends string>(
+    pattern: Path,
+    ...args: RoutePathArguments<Path>
+  ): string;
+}