feat: add PrefetchContext to PrefetchFunc signature

PrefetchFunc now receives a PrefetchContext object with params, url,
and controller instead of a bare NavigationPrecommitController. This
enables data prefetching during route navigation by providing route
parameters and destination URL to prefetch handlers.

BREAKING CHANGE: PrefetchFunc signature changed from
(controller: NavigationPrecommitController) => void | Promise<void>
to (context: PrefetchContext) => void | Promise<void>.
Consumers must destructure { params, url, controller } from the
context object instead of receiving the controller directly.

Author: ConsoleTVs

src/react/ExampleMain.tsx

@@ -20,8 +20,8 @@ const router = createRouter(function (route) {
   route('/').render(HelloWorld)
 
   route('/other')
-    .prefetch(function (controller) {
-      console.log('PREFETCHING ROUTE', controller)
+    .prefetch(function ({ params, url, controller }) {
+      console.log('PREFETCHING ROUTE', { params, url, controller })
 
       return new Promise(function (r) {
         setTimeout(r, 2000)

src/react/components/Router.tsx

@@ -200,7 +200,12 @@ export function Router(options: RouterProps) {
       return
     }
 
-    const precommitHandler = createPrecommitHandler(match.handler.prefetch)
+    const precommitHandler = createPrecommitHandler({
+      prefetch: match.handler.prefetch,
+      params: match.params,
+      url: new URL(event.destination.url),
+    })
+
     const handler = createHandler(function () {
       setCurrent({
         match,
@@ -226,7 +231,7 @@ export function Router(options: RouterProps) {
 
   const CurrentComponent = current.match.handler.component
   const middlewares = current.match.handler.middlewares
-
+1
   return (
     <TransitionContext value={transition}>
       <NavigationContext value={navigation}>

src/react/createRouter.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, vi } from 'vitest'
 import { createRouter, type RouteFactory } from './createRouter'
 import { type ComponentType } from 'react'
-import { type MiddlewareProps, type PrefetchFunc } from './router'
+import { type MiddlewareProps, type PrefetchContext, type PrefetchFunc } from './router'
 
 /**
  * Stub component used in tests where a real React component
@@ -34,15 +34,19 @@ function createMiddleware(): ComponentType<MiddlewareProps> {
 }
 
 /**
- * Creates a mock NavigationPrecommitController with spy
- * methods. Each test that needs one creates its own to
+ * Creates a mock PrefetchContext with spy methods on the
+ * controller. Each test that needs one creates its own to
  * avoid shared state between concurrent tests.
  */
-function createMockController() {
+function createMockContext(): PrefetchContext {
   return {
-    redirect: vi.fn(),
-    addHandler: vi.fn(),
-  } as unknown as NavigationPrecommitController
+    params: {},
+    url: new URL('http://localhost/'),
+    controller: {
+      redirect: vi.fn(),
+      addHandler: vi.fn(),
+    } as unknown as NavigationPrecommitController,
+  }
 }
 
 describe('createRouter', { concurrent: true }, function () {
@@ -210,9 +214,9 @@ describe('createRouter', { concurrent: true }, function () {
           .render(Stub)
       })
 
-      const controller = createMockController()
+      const context = createMockContext()
 
-      await router.match('/')?.handler.prefetch?.(controller)
+      await router.match('/')?.handler.prefetch?.(context)
 
       expect(order).toStrictEqual([1, 2])
     })
@@ -271,11 +275,11 @@ describe('createRouter', { concurrent: true }, function () {
         route('/old').redirect('/new')
       })
 
-      const controller = createMockController()
+      const context = createMockContext()
 
-      router.match('/old')?.handler.prefetch?.(controller)
+      router.match('/old')?.handler.prefetch?.(context)
 
-      expect(controller.redirect).toHaveBeenCalledWith('/new')
+      expect(context.controller.redirect).toHaveBeenCalledWith('/new')
     })
 
     it('uses a fallback component that renders null', function ({ expect }) {
@@ -306,11 +310,11 @@ describe('createRouter', { concurrent: true }, function () {
         app('/legacy').redirect('/new-page')
       })
 
-      const controller = createMockController()
+      const context = createMockContext()
 
-      router.match('/app/legacy')?.handler.prefetch?.(controller)
+      router.match('/app/legacy')?.handler.prefetch?.(context)
 
-      expect(controller.redirect).toHaveBeenCalledWith('/new-page')
+      expect(context.controller.redirect).toHaveBeenCalledWith('/new-page')
     })
   })
 
@@ -392,9 +396,9 @@ describe('createRouter', { concurrent: true }, function () {
         prefetched('/page').prefetch(routePrefetch).render(Stub)
       })
 
-      const controller = createMockController()
+      const context = createMockContext()
 
-      await router.match('/page')?.handler.prefetch?.(controller)
+      await router.match('/page')?.handler.prefetch?.(context)
 
       expect(order).toStrictEqual([1, 2])
     })
@@ -408,11 +412,11 @@ describe('createRouter', { concurrent: true }, function () {
         prefetched('/page').render(Stub)
       })
 
-      const controller = createMockController()
+      const context = createMockContext()
 
-      await router.match('/page')?.handler.prefetch?.(controller)
+      await router.match('/page')?.handler.prefetch?.(context)
 
-      expect(groupPrefetch).toHaveBeenCalledWith(controller)
+      expect(groupPrefetch).toHaveBeenCalledWith(context)
     })
   })
 
@@ -462,9 +466,9 @@ describe('createRouter', { concurrent: true }, function () {
         inner('/deep').prefetch(third).render(Stub)
       })
 
-      const controller = createMockController()
+      const context = createMockContext()
 
-      await router.match('/deep')?.handler.prefetch?.(controller)
+      await router.match('/deep')?.handler.prefetch?.(context)
 
       expect(order).toStrictEqual([1, 2, 3])
     })

src/react/createRouter.ts

@@ -4,6 +4,7 @@ import {
   type FormHandler,
   type Handler,
   type MiddlewareProps,
+  type PrefetchContext,
   type PrefetchFunc,
 } from 'router/react:router'
 
@@ -269,9 +270,9 @@ function chainPrefetches(
     return prefetches[0]
   }
 
-  return async function (controller: NavigationPrecommitController) {
+  return async function (context: PrefetchContext) {
     for (const fn of prefetches) {
-      await fn(controller)
+      await fn(context)
     }
   }
 }
@@ -410,8 +411,8 @@ function createRouteFactory(
         const handler: Handler = {
           component: RedirectFallback,
           middlewares: resolveMiddlewares(),
-          prefetch: function (controller) {
-            controller.redirect(target)
+          prefetch: function (context) {
+            context.controller.redirect(target)
           },
           scroll: state.scroll,
           focusReset: state.focusReset,

src/react/hooks/useNavigationHandlers.test.ts

@@ -45,7 +45,10 @@ describe('useNavigationHandlers', { concurrent: true }, function () {
 
     onTestFinished(unmount)
 
-    const result = current.createPrecommitHandler()
+    const result = current.createPrecommitHandler({
+      params: {},
+      url: new URL('http://localhost/'),
+    })
 
     expect(result).toBeUndefined()
   })
@@ -65,12 +68,16 @@ describe('useNavigationHandlers', { concurrent: true }, function () {
     onTestFinished(unmount)
 
     const prefetchSpy = vi.fn()
-    const handler = current.createPrecommitHandler(prefetchSpy)
+    const handler = current.createPrecommitHandler({
+      prefetch: prefetchSpy,
+      params: {},
+      url: new URL('http://localhost/'),
+    })
 
     expect(typeof handler).toBe('function')
   })
 
-  it('createPrecommitHandler calls the prefetch function with the controller', async function ({ expect, onTestFinished }) {
+  it('createPrecommitHandler calls the prefetch function with a PrefetchContext', async function ({ expect, onTestFinished }) {
     /**
      * Stub startTransition for the prefetch invocation test.
      */
@@ -85,7 +92,14 @@ describe('useNavigationHandlers', { concurrent: true }, function () {
     onTestFinished(unmount)
 
     const prefetchSpy = vi.fn()
-    const handler = current.createPrecommitHandler(prefetchSpy)!
+    const params = { id: '42' }
+    const url = new URL('http://localhost/user/42')
+
+    const handler = current.createPrecommitHandler({
+      prefetch: prefetchSpy,
+      params,
+      url,
+    })!
 
     const mockController = {
       redirect: vi.fn(),
@@ -94,7 +108,13 @@ describe('useNavigationHandlers', { concurrent: true }, function () {
 
     await handler(mockController)
 
-    expect(prefetchSpy).toHaveBeenCalledWith(mockController)
+    expect(prefetchSpy).toHaveBeenCalledTimes(1)
+
+    const context = prefetchSpy.mock.calls[0][0]
+
+    expect(context.params).toBe(params)
+    expect(context.url).toBe(url)
+    expect(context.controller).toBe(mockController)
   })
 
   it('createHandler returns a function that wraps callback in startTransition', function ({ expect, onTestFinished }) {

src/react/hooks/useNavigationHandlers.ts

@@ -1,6 +1,29 @@
 import { type TransitionFunction, use, useTransition } from 'react'
 import { TransitionContext } from 'router/react:context/TransitionContext'
-import { type PrefetchFunc } from 'router/react:router'
+import { type PrefetchFunc, type PrefetchContext } from 'router/react:router'
+
+/**
+ * Options for creating a precommit handler that forwards
+ * route context to the prefetch function.
+ */
+export interface PrecommitHandlerOptions {
+  /**
+   * The prefetch function from the matched route handler.
+   * When undefined, no precommit handler is created.
+   */
+  readonly prefetch?: PrefetchFunc
+
+  /**
+   * Dynamic route parameters extracted from the matched
+   * URL pattern.
+   */
+  readonly params: Record<string, string>
+
+  /**
+   * The destination URL being navigated to.
+   */
+  readonly url: URL
+}
 
 /**
  * Creates handler functions for the Navigation API's
@@ -35,18 +58,27 @@ export function useNavigationHandlers(
   const [, startTransition] = contextTransition
 
   /**
-   * Creates a precommit handler that receives the
-   * NavigationPrecommitController and forwards it to
-   * the route's prefetch function. Runs before the URL
-   * commits, so no React state transitions are needed here.
+   * Creates a precommit handler that constructs a
+   * `PrefetchContext` from the matched route information
+   * and forwards it to the route's prefetch function.
+   * Runs before the URL commits, so no React state
+   * transitions are needed here.
    */
-  function createPrecommitHandler(prefetch?: PrefetchFunc) {
-    if (prefetch === undefined) {
+  function createPrecommitHandler(options: PrecommitHandlerOptions) {
+    if (options.prefetch === undefined) {
       return undefined
     }
 
+    const prefetch = options.prefetch
+
     return async function (controller: NavigationPrecommitController) {
-      await prefetch(controller)
+      const context: PrefetchContext = {
+        params: options.params,
+        url: options.url,
+        controller,
+      }
+
+      await prefetch(context)
     }
   }
 

src/react/hooks/usePrefetch.test.ts

@@ -28,7 +28,7 @@ describe('usePrefetch', { concurrent: true }, function () {
     expect(typeof current).toBe('function')
   })
 
-  it('calls the matched route prefetch handler with a stub controller', function ({ expect, onTestFinished }) {
+  it('calls the matched route prefetch handler with a PrefetchContext', function ({ expect, onTestFinished }) {
     const prefetchSpy = vi.fn()
     const matcher = createMatcher<Handler>()
 
@@ -47,10 +47,13 @@ describe('usePrefetch', { concurrent: true }, function () {
 
     expect(prefetchSpy).toHaveBeenCalledTimes(1)
 
-    const controller = prefetchSpy.mock.calls[0][0]
+    const context = prefetchSpy.mock.calls[0][0]
 
-    expect(typeof controller.redirect).toBe('function')
-    expect(typeof controller.addHandler).toBe('function')
+    expect(context.params).toStrictEqual({})
+    expect(context.url).toBeInstanceOf(URL)
+    expect(context.url.pathname).toBe('/about')
+    expect(typeof context.controller.redirect).toBe('function')
+    expect(typeof context.controller.addHandler).toBe('function')
   })
 
   it('returns undefined when no route matches', function ({ expect, onTestFinished }) {

src/react/hooks/usePrefetch.ts

@@ -1,6 +1,6 @@
 import { use } from 'react'
 import { MatcherContext } from 'router/react:context/MatcherContext'
-import { type Handler } from 'router/react:router'
+import { type Handler, type PrefetchContext } from 'router/react:router'
 import { type Matcher } from 'router:matcher'
 
 /**
@@ -34,16 +34,17 @@ export function usePrefetch(options?: PrefetchOptions) {
   /**
    * Triggers prefetch for the given URL by matching it against
    * registered routes and calling the route's prefetch function
-   * with a stub controller. Extracts the pathname from the URL
-   * before matching to handle both absolute and relative URLs.
+   * with a context containing the matched params, the parsed
+   * URL, and a stub controller. Extracts the pathname from the
+   * URL before matching to handle both absolute and relative URLs.
    *
    * @param url - The URL or path to prefetch data for.
    * @returns The prefetch promise, or undefined if no prefetch
    *   handler is registered for the matched route.
    */
   return function (url: string) {
-    const pathname = new URL(url, 'http://localhost').pathname
-    const match = matcher.match(pathname)
+    const parsed = new URL(url, 'http://localhost')
+    const match = matcher.match(parsed.pathname)
 
     if (match?.handler.prefetch === undefined) {
       return
@@ -59,6 +60,12 @@ export function usePrefetch(options?: PrefetchOptions) {
       addHandler() {},
     }
 
-    return match.handler.prefetch(stubController)
+    const context: PrefetchContext = {
+      params: match.params,
+      url: parsed,
+      controller: stubController,
+    }
+
+    return match.handler.prefetch(context)
   }
 }