@troyio/vite-file-router 0.3.2 → 0.4.1

package/dist/scanner.d.ts

@@ -24,6 +24,11 @@ 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 type PageRoute = {
+    pattern: string;
+    node: Node;
+};
+export declare function collectPageRoutes(node: Node, segments?: string[], root?: boolean): PageRoute[];
+export declare function collectPageRoutePatterns(node: Node): 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.3.2",
+  "version": "0.4.1",
   "description": "File-system routing plugin for Vite",
   "type": "module",
   "private": false,

package/types/index.d.ts

@@ -1,60 +1,143 @@
-/// <reference path="./virtual-routes.d.ts" />
-
-export { routes } from "../dist/index.js";
-export type {
-  RouteConventions,
-  RouteFileKind,
-  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 `:${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 RouteRequiresRequiredParameters<Path extends string> =
-  Path extends unknown ? ({} extends RouteParameters<Path> ? 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]
-      : true extends RouteRequiresRequiredParameters<Path>
-        ? [params: RouteParameters<Path>]
-        : [params?: RouteParameters<Path>]
-    : [];
+/// <reference path="./virtual-routes.d.ts" />
+
+import type { useRouteLoaderData } from "react-router";
+
+export { routes } from "../dist/index.js";
+export type {
+  RouteConventions,
+  RouteFileKind,
+  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 `:${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 RouteRequiresRequiredParameters<Path extends string> =
+  Path extends unknown ? ({} extends RouteParameters<Path> ? 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]
+      : true extends RouteRequiresRequiredParameters<Path>
+        ? [params: RouteParameters<Path>]
+        : [params?: RouteParameters<Path>]
+    : [];
+
+/**
+ * Filled in by the generated route declarations (`src/route-types.d.ts` by
+ * default) through module augmentation. While it is empty, route patterns and
+ * loader keys fall back to `string` and loader data to `unknown`.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by generated code
+export interface Register {}
+
+type RegisteredRoutes = Register extends { routes: infer Routes }
+  ? Routes
+  : never;
+type RegisteredLoaders = Register extends { loaders: infer Loaders }
+  ? Loaders
+  : never;
+type IsRegistered = [RegisteredRoutes] extends [never] ? false : true;
+
+/** A page route pattern discovered from the routes directory. */
+export type RoutePattern = IsRegistered extends true
+  ? Extract<keyof RegisteredRoutes, string>
+  : string;
+
+type PatternsWithLoaders = {
+  [Pattern in keyof RegisteredRoutes]: RegisteredRoutes[Pattern] extends {
+    loader: null;
+  }
+    ? never
+    : Pattern;
+}[keyof RegisteredRoutes];
+
+/**
+ * A page pattern whose directory has a loader, or a loader route ID such as
+ * `"file-route:src/pages/dashboard"`.
+ */
+export type RouteLoaderKey = IsRegistered extends true
+  ? Extract<PatternsWithLoaders | keyof RegisteredLoaders, string>
+  : string;
+
+type LoaderModuleFor<Key> = Key extends keyof RegisteredLoaders
+  ? RegisteredLoaders[Key]
+  : Key extends keyof RegisteredRoutes
+    ? RegisteredRoutes[Key] extends {
+        loader: infer Id extends keyof RegisteredLoaders;
+      }
+      ? RegisteredLoaders[Id]
+      : never
+    : never;
+
+/**
+ * The data a route's loader returns, typed the same way as React Router's
+ * `useRouteLoaderData<typeof loader>()`.
+ */
+export type RouteLoaderData<Key extends string> = IsRegistered extends true
+  ? LoaderModuleFor<Key> extends { loader: infer Loader }
+    ? NonNullable<ReturnType<typeof useRouteLoaderData<Loader>>>
+    : never
+  : unknown;
+
+type Simplify<Value> = { [Key in keyof Value]: Value[Key] } & {};
+
+type RouteParamsForSegment<Segment extends string> =
+  Segment extends `:${infer Name}?`
+    ? { [Key in Name]?: string | undefined }
+    : Segment extends `:${infer Name}`
+      ? { [Key in Name]: string }
+      : Segment extends "*"
+        ? { "*": string }
+        : {};
+
+type RouteParamsIntersection<Path extends string> =
+  Path extends `${infer Segment}/${infer Rest}`
+    ? RouteParamsForSegment<Segment> & RouteParamsIntersection<Rest>
+    : RouteParamsForSegment<Path>;
+
+/**
+ * The params React Router's `useParams()` returns for a route pattern, such
+ * as `RouteParams<"/users/:id">` → `{ id: string }`.
+ */
+export type RouteParams<Path extends string> = Path extends unknown
+  ? Simplify<RouteParamsIntersection<Path>>
+  : never;

package/types/virtual-routes.d.ts

@@ -1,19 +1,46 @@
-declare module "virtual:routes" {
-  import type { RouteObject } from "react-router";
-  export const routes: RouteObject[];
-}
-
-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;
-}
+declare module "virtual:routes" {
+  import type { Location, RouteObject } from "react-router";
+  export const routes: RouteObject[];
+  /**
+   * Imports the page, layout, and loader modules for the routes that match a
+   * URL, so a later navigation renders without waiting for them. Resolves to
+   * `false` when no route matches.
+   */
+  export function preloadRoute(
+    to: string | Partial<Location>,
+    basename?: string,
+  ): Promise<boolean>;
+}
+
+declare module "virtual:route-manifest" {
+  import type { RouteManifestNode } from "@troyio/vite-file-router";
+  export const routeManifest: RouteManifestNode;
+}
+
+declare module "virtual:route-helpers" {
+  import type {
+    RouteLoaderData,
+    RouteLoaderKey,
+    RouteParams,
+    RoutePathArguments,
+    RoutePattern,
+  } from "@troyio/vite-file-router";
+
+  export const routePatterns: readonly RoutePattern[];
+  export function routePath<const Path extends RoutePattern>(
+    pattern: Path,
+    ...args: RoutePathArguments<Path>
+  ): string;
+  /** React Router's `useParams()`, typed for the given page pattern. */
+  export function useRouteParams<const Path extends RoutePattern>(
+    pattern: Path,
+  ): RouteParams<Path>;
+  /**
+   * React Router's `useRouteLoaderData()`, typed from the loader module. Pass
+   * a page pattern to read the loader in that page's directory, or a loader
+   * route ID to read any matched loader.
+   */
+  export function useRouteData<const Key extends RouteLoaderKey>(
+    key: Key,
+  ): RouteLoaderData<Key> | undefined;
+}