@pyreon/router 0.13.0 → 0.14.0

package/src/tests/router.test.ts

@@ -1,6 +1,7 @@
 import { h, popContext } from '@pyreon/core'
 import { mount } from '@pyreon/runtime-dom'
 import type { ResolvedRoute, RouteRecord } from '../index'
+import { isNotFoundError, NotFoundBoundary, notFound } from '../not-found'
 import {
   createRouter,
   hydrateLoaderData,
@@ -21,6 +22,7 @@ import {
   useSearchParams,
   useTransition,
   useTypedSearchParams,
+  useValidatedSearch,
 } from '../index'
 import type { RouteMiddleware } from '../index'
 import {
@@ -358,10 +360,13 @@ describe('router navigation', () => {
     expect(router.currentRoute().query.q).toBe('hello')
   })
 
-  test('push with unknown named route falls back to /', async () => {
+  test('push with unknown named route falls back to / and warns', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
     const router = createRouter({ routes, url: '/about' })
     await router.push({ name: 'nonexistent' })
     expect(router.currentRoute().path).toBe('/')
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Unknown route name "nonexistent"'))
+    warnSpy.mockRestore()
   })
 
   test('back() does not throw in SSR (no window)', () => {
@@ -4267,6 +4272,21 @@ describe('useTypedSearchParams', () => {
     router.destroy()
   })
 
+  it('guards NaN: non-numeric string coerces to 0 instead of NaN', () => {
+    const router = createRouter({ routes: tspRoutes, url: '/search?page=abc' })
+    const ctr = document.createElement('div')
+    let result: { page: number } | undefined
+    const TestComp = () => {
+      const [params] = useTypedSearchParams({ page: 'number' })
+      result = params() as { page: number }
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), ctr)
+    expect(result!.page).toBe(0) // not NaN
+    expect(Number.isNaN(result!.page)).toBe(false)
+    router.destroy()
+  })
+
   it('defaults boolean to false when missing from URL', () => {
     const router = createRouter({ routes: tspRoutes, url: '/search' })
     const ctr = document.createElement('div')
@@ -4722,3 +4742,519 @@ describe('View Transitions API', () => {
     router.destroy()
   })
 })
+
+// ─── Type-level tests for Router<TNames> ──────────────────────────────────────
+
+describe('Router<TNames> type safety', () => {
+  test('createRouter<TNames> returns typed router', () => {
+    type Names = 'home' | 'about' | 'user'
+    const router = createRouter<Names>({
+      routes: [
+        { path: '/', name: 'home', component: Home },
+        { path: '/about', name: 'about', component: Home },
+        { path: '/user/:id', name: 'user', component: Home },
+      ],
+    })
+
+    // This compiles — valid name
+    router.push({ name: 'home' })
+    router.push({ name: 'about' })
+    router.push({ name: 'user', params: { id: '1' } })
+
+    // Type assertion: the router accepts the union type
+    const _typeCheck: Names = 'home'
+    void _typeCheck
+
+    router.destroy()
+  })
+
+  test('_middlewareData is typed on ResolvedRoute', () => {
+    const route: ResolvedRoute = {
+      path: '/',
+      params: {},
+      query: {},
+      hash: '',
+      matched: [],
+      meta: {},
+      _middlewareData: { user: { name: 'Alice' } },
+    }
+    expect(route._middlewareData?.user).toEqual({ name: 'Alice' })
+  })
+})
+
+// ─── notFound() + isNotFoundError ─────────────────────────────────────────────
+
+describe('notFound()', () => {
+
+  test('throws an Error with NOT_FOUND brand', () => {
+    expect(() => notFound()).toThrow('Not Found')
+    expect(() => notFound('User not found')).toThrow('User not found')
+  })
+
+  test('isNotFoundError detects branded errors', () => {
+    try {
+      notFound('test')
+    } catch (err) {
+      expect(isNotFoundError(err)).toBe(true)
+      expect(err instanceof Error).toBe(true)
+    }
+  })
+
+  test('isNotFoundError returns false for regular errors', () => {
+    expect(isNotFoundError(new Error('regular'))).toBe(false)
+    expect(isNotFoundError(null)).toBe(false)
+    expect(isNotFoundError('string')).toBe(false)
+  })
+})
+
+// ─── Prefetch intent mode ────────────────────────────────────────────────────
+
+describe('RouterLink prefetch="intent"', () => {
+  test('focus triggers prefetch in intent mode (default)', async () => {
+    const loaderCalled = vi.fn().mockResolvedValue({ data: 'prefetched' })
+    const intRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      { path: '/target', component: Home, loader: loaderCalled },
+    ]
+    const router = createRouter({ routes: intRoutes, url: '/' })
+    const ctr = document.createElement('div')
+    mount(h(RouterProvider, { router }, h(RouterLink, { to: '/target' })), ctr)
+
+    const link = ctr.querySelector('a')!
+    // Focus triggers prefetch in intent mode
+    link.dispatchEvent(new Event('focus', { bubbles: true }))
+    await new Promise<void>((r) => queueMicrotask(r))
+
+    expect(loaderCalled).toHaveBeenCalled()
+    router.destroy()
+  })
+
+  test('focus does NOT trigger prefetch in "none" mode', async () => {
+    const loaderCalled = vi.fn().mockResolvedValue({ data: 'x' })
+    const intRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      { path: '/target', component: Home, loader: loaderCalled },
+    ]
+    const router = createRouter({ routes: intRoutes, url: '/' })
+    const ctr = document.createElement('div')
+    mount(h(RouterProvider, { router }, h(RouterLink, { to: '/target', prefetch: 'none' })), ctr)
+
+    const link = ctr.querySelector('a')!
+    link.dispatchEvent(new Event('focus', { bubbles: true }))
+    await new Promise<void>((r) => queueMicrotask(r))
+
+    expect(loaderCalled).not.toHaveBeenCalled()
+    router.destroy()
+  })
+})
+
+// ─── NotFoundBoundary e2e ────────────────────────────────────────────────────
+
+describe('NotFoundBoundary e2e', () => {
+  test('notFound() in component triggers NotFoundBoundary fallback', () => {
+    const ThrowNotFound = () => {
+      notFound('User not found')
+      return null // unreachable
+    }
+    const nfRoutes: RouteRecord[] = [
+      { path: '/missing', component: ThrowNotFound },
+    ]
+    const router = createRouter({ routes: nfRoutes, url: '/missing' })
+    const ctr = document.createElement('div')
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    mount(
+      h(RouterProvider, { router },
+        h(NotFoundBoundary, {
+          fallback: h('div', { id: 'not-found' }, '404 Not Found'),
+        }, h(RouterView, {})),
+      ),
+      ctr,
+    )
+
+    expect(ctr.querySelector('#not-found')?.textContent).toBe('404 Not Found')
+    errorSpy.mockRestore()
+    router.destroy()
+  })
+})
+
+// ─── pendingComponent e2e ────────────────────────────────────────────────────
+
+describe('pendingComponent', () => {
+  test('pendingComponent shows immediately when pendingMs=0', async () => {
+    let resolveLoader: (v: unknown) => void
+    const loaderPromise = new Promise((r) => { resolveLoader = r })
+    const PendingComp = () => h('div', { id: 'pending' }, 'Loading...')
+    const RealComp = () => h('div', { id: 'real' }, 'Loaded')
+
+    const pendRoutes: RouteRecord[] = [
+      {
+        path: '/slow',
+        component: RealComp,
+        loader: () => loaderPromise,
+        pendingComponent: PendingComp,
+        pendingMs: 0,
+        pendingMinMs: 0,
+      },
+    ]
+    const router = createRouter({ routes: pendRoutes, url: '/slow' })
+    const ctr = document.createElement('div')
+    mount(h(RouterProvider, { router }, h(RouterView, {})), ctr)
+
+    // Pending should show immediately
+    await new Promise<void>((r) => queueMicrotask(r))
+    expect(ctr.querySelector('#pending')).not.toBeNull()
+
+    // Resolve the loader
+    resolveLoader!({ data: 'done' })
+    await new Promise<void>((r) => queueMicrotask(r))
+    await new Promise<void>((r) => setTimeout(r, 50))
+
+    router.destroy()
+  })
+
+  test('pendingMinMs keeps pending visible even after loader resolves', async () => {
+    let resolveLoader: (v: unknown) => void
+    const loaderPromise = new Promise((r) => { resolveLoader = r })
+    const PendingComp = () => h('div', { id: 'pending-min' }, 'Loading...')
+    const RealComp = () => h('div', { id: 'real-min' }, 'Loaded')
+
+    const pendRoutes: RouteRecord[] = [
+      {
+        path: '/mintime',
+        component: RealComp,
+        loader: () => loaderPromise,
+        pendingComponent: PendingComp,
+        pendingMs: 0,       // show pending immediately
+        pendingMinMs: 300,  // keep for at least 300ms
+      },
+    ]
+    const router = createRouter({ routes: pendRoutes, url: '/mintime' })
+    const ctr = document.createElement('div')
+    mount(h(RouterProvider, { router }, h(RouterView, {})), ctr)
+
+    // Pending should show immediately
+    await new Promise<void>((r) => queueMicrotask(r))
+    expect(ctr.querySelector('#pending-min')).not.toBeNull()
+
+    // Resolve loader quickly (after ~50ms — well before pendingMinMs)
+    await new Promise<void>((r) => setTimeout(r, 50))
+    resolveLoader!({ data: 'done' })
+
+    // Trigger reactive update
+    await new Promise<void>((r) => queueMicrotask(r))
+    await new Promise<void>((r) => setTimeout(r, 50))
+
+    // Pending should STILL be visible — pendingMinMs hasn't elapsed
+    expect(ctr.querySelector('#pending-min')).not.toBeNull()
+    expect(ctr.querySelector('#real-min')).toBeNull()
+
+    // Wait for pendingMinMs to elapse
+    await new Promise<void>((r) => setTimeout(r, 300))
+
+    // Now the real component should show
+    // (need to trigger a reactive re-render — read loadingSignal)
+    await new Promise<void>((r) => queueMicrotask(r))
+    await new Promise<void>((r) => setTimeout(r, 50))
+
+    // The pending phase should have transitioned to ready
+    // Note: the signal-based state machine sets phase to 'ready' after minTimer fires
+    router.destroy()
+  }, 10000)
+
+  test('pendingMs delays showing pending — data arriving before delay skips pending', async () => {
+    let resolveLoader: (v: unknown) => void
+    const loaderPromise = new Promise((r) => { resolveLoader = r })
+    const PendingComp = () => h('div', { id: 'pending-delay' }, 'Loading...')
+    const RealComp = () => h('div', { id: 'real-delay' }, 'Loaded')
+
+    const pendRoutes: RouteRecord[] = [
+      {
+        path: '/delayed',
+        component: RealComp,
+        loader: () => loaderPromise,
+        pendingComponent: PendingComp,
+        pendingMs: 500,     // wait 500ms before showing pending
+        pendingMinMs: 0,
+      },
+    ]
+    const router = createRouter({ routes: pendRoutes, url: '/delayed' })
+    const ctr = document.createElement('div')
+    mount(h(RouterProvider, { router }, h(RouterView, {})), ctr)
+
+    await new Promise<void>((r) => queueMicrotask(r))
+
+    // Before pendingMs: nothing should show (hidden phase)
+    expect(ctr.querySelector('#pending-delay')).toBeNull()
+
+    // Resolve before pendingMs elapses — should skip pending entirely
+    resolveLoader!({ data: 'fast' })
+    await new Promise<void>((r) => queueMicrotask(r))
+    await new Promise<void>((r) => setTimeout(r, 50))
+
+    // Pending should never have appeared
+    expect(ctr.querySelector('#pending-delay')).toBeNull()
+
+    router.destroy()
+  })
+
+  test('pendingComponent type accepted on RouteRecord', () => {
+    const PendingComp = () => h('div', null, 'Loading...')
+    const routeWithPending: RouteRecord = {
+      path: '/slow',
+      component: Home,
+      loader: async () => ({}),
+      pendingComponent: PendingComp,
+      pendingMs: 200,
+      pendingMinMs: 500,
+    }
+    expect(routeWithPending.pendingComponent).toBe(PendingComp)
+    expect(routeWithPending.pendingMs).toBe(200)
+    expect(routeWithPending.pendingMinMs).toBe(500)
+  })
+})
+
+// ─── validateSearch + useValidatedSearch ──────────────────────────────────────
+
+describe('validateSearch', () => {
+  test('resolveRoute runs validateSearch on matched route', () => {
+    const vsRoutes: RouteRecord[] = [
+      {
+        path: '/search',
+        component: Home,
+        validateSearch: (raw) => ({
+          page: Number(raw.page) || 1,
+          q: raw.q ?? '',
+        }),
+      },
+    ]
+    const router = createRouter({ routes: vsRoutes, url: '/search?page=3&q=hello' })
+    const route = router.currentRoute()
+    expect(route.search).toEqual({ page: 3, q: 'hello' })
+    router.destroy()
+  })
+
+  test('validateSearch defaults when params missing', () => {
+    const vsRoutes: RouteRecord[] = [
+      {
+        path: '/search',
+        component: Home,
+        validateSearch: (raw) => ({
+          page: Number(raw.page) || 1,
+          q: raw.q ?? '',
+        }),
+      },
+    ]
+    const router = createRouter({ routes: vsRoutes, url: '/search' })
+    const route = router.currentRoute()
+    expect(route.search).toEqual({ page: 1, q: '' })
+    router.destroy()
+  })
+
+  test('validateSearch error falls back to raw query', () => {
+    const vsRoutes: RouteRecord[] = [
+      {
+        path: '/broken',
+        component: Home,
+        validateSearch: () => { throw new Error('schema fail') },
+      },
+    ]
+    const router = createRouter({ routes: vsRoutes, url: '/broken?foo=bar' })
+    const route = router.currentRoute()
+    expect(route.search).toEqual({ foo: 'bar' })
+    router.destroy()
+  })
+
+  test('routes without validateSearch have empty search', () => {
+    const router = createRouter({ routes, url: '/about' })
+    const route = router.currentRoute()
+    expect(route.search).toEqual({})
+    router.destroy()
+  })
+
+  test('useValidatedSearch returns typed accessor with structural sharing', () => {
+    const vsRoutes: RouteRecord[] = [
+      {
+        path: '/items',
+        component: Home,
+        validateSearch: (raw) => ({
+          page: Number(raw.page) || 1,
+        }),
+      },
+    ]
+    const router = createRouter({ routes: vsRoutes, url: '/items?page=5' })
+    const ctr = document.createElement('div')
+    let searchResult: Record<string, unknown> | undefined
+    const TestComp = () => {
+      const search = useValidatedSearch<{ page: number }>()
+      searchResult = search()
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), ctr)
+    expect(searchResult).toEqual({ page: 5 })
+    router.destroy()
+  })
+})
+
+// ─── Loader cache ───────────────────────────────────────────────────────────
+
+describe('loader cache', () => {
+  test('cached loader data is reused on second navigation (same params)', async () => {
+    let callCount = 0
+    const cacheRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/user/:id',
+        component: Home,
+        loader: async ({ params }) => {
+          callCount++
+          return { id: params.id, name: `User ${params.id}` }
+        },
+      },
+    ]
+    const router = createRouter({ routes: cacheRoutes, url: '/' })
+
+    await router.push('/user/42')
+    expect(callCount).toBe(1)
+
+    // Navigate away then back — same params, cache hit
+    await router.push('/')
+    await router.push('/user/42')
+    expect(callCount).toBe(1) // NOT called again — cache hit
+
+    router.destroy()
+  })
+
+  test('different params produce different cache keys → loader runs again', async () => {
+    let callCount = 0
+    const cacheRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/user/:id',
+        component: Home,
+        loader: async () => { callCount++; return {} },
+      },
+    ]
+    const router = createRouter({ routes: cacheRoutes, url: '/' })
+
+    await router.push('/user/1')
+    expect(callCount).toBe(1)
+
+    await router.push('/user/2')
+    expect(callCount).toBe(2) // different key → fresh load
+
+    router.destroy()
+  })
+
+  test('custom loaderKey controls cache identity', async () => {
+    let callCount = 0
+    const cacheRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/items',
+        component: Home,
+        loaderKey: ({ query }) => `items-page-${query.page ?? '1'}`,
+        loader: async () => { callCount++; return [] },
+      },
+    ]
+    const router = createRouter({ routes: cacheRoutes, url: '/' })
+
+    await router.push('/items?page=1')
+    expect(callCount).toBe(1)
+
+    // Same page → cache hit
+    await router.push('/')
+    await router.push('/items?page=1')
+    expect(callCount).toBe(1)
+
+    // Different page → cache miss
+    await router.push('/items?page=2')
+    expect(callCount).toBe(2)
+
+    router.destroy()
+  })
+
+  test('gcTime=0 disables caching', async () => {
+    let callCount = 0
+    const cacheRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/data',
+        component: Home,
+        gcTime: 0,
+        loader: async () => { callCount++; return {} },
+      },
+    ]
+    const router = createRouter({ routes: cacheRoutes, url: '/' })
+
+    await router.push('/data')
+    expect(callCount).toBe(1)
+
+    await router.push('/')
+    await router.push('/data')
+    expect(callCount).toBe(2) // no cache — always runs
+
+    router.destroy()
+  })
+
+  test('invalidateLoader() clears cache', async () => {
+    let callCount = 0
+    const cacheRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/data',
+        component: Home,
+        loader: async () => { callCount++; return {} },
+      },
+    ]
+    const router = createRouter({ routes: cacheRoutes, url: '/' })
+
+    await router.push('/data')
+    expect(callCount).toBe(1)
+
+    // Invalidate all
+    router.invalidateLoader()
+
+    await router.push('/')
+    await router.push('/data')
+    expect(callCount).toBe(2) // cache was cleared → runs again
+
+    router.destroy()
+  })
+
+  test('invalidateLoader(key) clears specific cache entry', async () => {
+    let dataCallCount = 0
+    let itemsCallCount = 0
+    const cacheRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/data',
+        component: Home,
+        loaderKey: () => 'data-key',
+        loader: async () => { dataCallCount++; return {} },
+      },
+      {
+        path: '/items',
+        component: Home,
+        loaderKey: () => 'items-key',
+        loader: async () => { itemsCallCount++; return [] },
+      },
+    ]
+    const router = createRouter({ routes: cacheRoutes, url: '/' })
+
+    await router.push('/data')
+    await router.push('/items')
+    expect(dataCallCount).toBe(1)
+    expect(itemsCallCount).toBe(1)
+
+    // Invalidate only 'data-key'
+    router.invalidateLoader('data-key')
+
+    await router.push('/data')
+    await router.push('/items')
+    expect(dataCallCount).toBe(2) // re-fetched
+    expect(itemsCallCount).toBe(1) // still cached
+
+    router.destroy()
+  })
+})

package/src/types.ts

@@ -69,6 +69,15 @@ export interface ResolvedRoute<
   /** All matched records from root to leaf (one per nesting level) */
   matched: RouteRecord[]
   meta: RouteMeta
+  /**
+   * Validated search params — populated when the matched route has `validateSearch`.
+   * Contains the typed result of `validateSearch(query)`. Use `useValidatedSearch()`
+   * to access this in components with full type inference.
+   * Empty object `{}` when no `validateSearch` is configured.
+   */
+  search?: Record<string, unknown> | undefined
+  /** Middleware data attached during navigation (populated by middleware chain) */
+  _middlewareData?: Record<string, unknown> | undefined
 }
 
 // ─── Lazy component ───────────────────────────────────────────────────────────
@@ -203,8 +212,58 @@ export interface RouteRecord<TPath extends string = string> {
    * Only applies when navigating to a route that already has cached loader data.
    */
   staleWhileRevalidate?: boolean
+  /**
+   * Cache key function for loader data. Returns a string key derived from
+   * route params/query. When the key matches cached data, the loader is
+   * skipped (cache hit). Default: `path + JSON.stringify(params)`.
+   *
+   * @example
+   * ```ts
+   * loaderKey: ({ params }) => `user-${params.id}`
+   * ```
+   */
+  loaderKey?: (ctx: Pick<LoaderContext, 'params' | 'query'>) => string
+  /**
+   * Time in ms to keep cached loader data before garbage collection.
+   * Default: 300000 (5 minutes). Set to 0 to disable caching.
+   * Stale data is still served immediately if `staleWhileRevalidate` is true.
+   */
+  gcTime?: number
   /** Component rendered when this route's loader throws an error */
   errorComponent?: ComponentFn
+  /**
+   * Component rendered while this route's loader is running.
+   * Only shown after `pendingMs` (default: 0) to avoid flash on fast loads.
+   * Once shown, displayed for at least `pendingMinMs` (default: 200) to avoid flicker.
+   */
+  pendingComponent?: ComponentFn
+  /** Delay in ms before showing pendingComponent (default: 0). Prevents flash on fast loaders. */
+  pendingMs?: number
+  /** Minimum display time in ms for pendingComponent once shown (default: 200). Prevents flicker. */
+  pendingMinMs?: number
+  /**
+   * Validate and transform raw query string parameters into typed values.
+   * Receives the raw `Record<string, string>` from the URL and returns
+   * a typed object. The validated result is available via `useValidatedSearch()`.
+   *
+   * Accepts any function — use Zod `.parse`, Valibot, or a plain function:
+   *
+   * @example
+   * ```ts
+   * // Plain function:
+   * validateSearch: (raw) => ({
+   *   page: Number(raw.page) || 1,
+   *   q: raw.q ?? '',
+   * })
+   *
+   * // With Zod:
+   * validateSearch: z.object({
+   *   page: z.coerce.number().default(1),
+   *   q: z.string().default(''),
+   * }).parse
+   * ```
+   */
+  validateSearch?: (raw: Record<string, string>) => Record<string, unknown>
   /** Per-route middleware — runs before guards, can accumulate context data. */
   middleware?: RouteMiddleware | RouteMiddleware[]
 }
@@ -325,6 +384,13 @@ export interface Router<TNames extends string = string> {
    * call this for the same `url` you initialised the router with.
    */
   preload(path: string): Promise<void>
+  /**
+   * Invalidate cached loader data. Forces loaders to re-run on next navigation.
+   * - No args: invalidate ALL cached loader data
+   * - String: invalidate by cache key (as returned by `loaderKey`)
+   * - Function: invalidate entries where the predicate returns true
+   */
+  invalidateLoader(keyOrPredicate?: string | ((key: string) => boolean)): void
   /** Remove all event listeners, clear caches, and abort in-flight navigations. */
   destroy(): void
 }
@@ -365,4 +431,10 @@ export interface RouterInstance extends Router {
   _readyResolve: (() => void) | null
   /** The isReady() promise instance */
   _readyPromise: Promise<void>
+  /** Timestamp when the current navigation started — used for pendingMs timing */
+  _navigationStartTime: number
+  /** Key-based loader cache: cacheKey → { data, timestamp } */
+  _loaderCache: Map<string, { data: unknown; timestamp: number }>
+  /** In-flight loader dedup: cacheKey → Promise */
+  _loaderInflight: Map<string, Promise<unknown>>
 }