@pyreon/router 0.13.1 → 0.15.0

package/src/tests/router.test.ts

@@ -1,6 +1,8 @@
 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 { getRedirectInfo, redirect } from '../redirect'
 import {
   createRouter,
   hydrateLoaderData,
@@ -21,6 +23,7 @@ import {
   useSearchParams,
   useTransition,
   useTypedSearchParams,
+  useValidatedSearch,
 } from '../index'
 import type { RouteMiddleware } from '../index'
 import {
@@ -358,10 +361,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 +4273,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 +4743,667 @@ 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()
+  })
+})
+
+// ─── redirect() — loader-thrown redirects propagate through the navigate flow
+
+describe('redirect() from loader', () => {
+  test('throws and triggers router.replace to the target path', async () => {
+    const Home = () => h('div', null, 'home')
+    const Login = () => h('div', null, 'login')
+    const Protected = () => h('div', null, 'protected')
+
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      { path: '/login', component: Login },
+      {
+        path: '/app',
+        component: Protected,
+        loader: async () => {
+          // No session — redirect to /login
+          redirect('/login')
+        },
+      },
+    ]
+
+    const router = createRouter({ routes, url: '/' })
+    await router.push('/app')
+
+    expect(router.currentRoute().path).toBe('/login')
+    router.destroy()
+  })
+
+  test("doesn't fire when loader resolves normally", async () => {
+    const Home = () => h('div', null, 'home')
+    const Protected = () => h('div', null, 'protected')
+
+    let loaderRan = false
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/app',
+        component: Protected,
+        loader: async () => {
+          loaderRan = true
+          return { user: 'me' }
+        },
+      },
+    ]
+
+    const router = createRouter({ routes, url: '/' })
+    await router.push('/app')
+
+    expect(loaderRan).toBe(true)
+    expect(router.currentRoute().path).toBe('/app')
+    router.destroy()
+  })
+
+  test('parent layout loader can redirect, blocking the child page', async () => {
+    const Home = () => h('div', null, 'home')
+    const Login = () => h('div', null, 'login')
+    const Layout = () => h('div', null, 'layout')
+    const Page = () => h('div', null, 'page')
+
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      { path: '/login', component: Login },
+      {
+        path: '/app',
+        component: Layout,
+        loader: async () => {
+          redirect('/login')
+        },
+        children: [
+          {
+            // Relative path — `createRouter` joins it with the parent. fs-router
+            // emits absolute paths instead, but the routing semantics at runtime
+            // are identical via `resolveRoute`.
+            path: 'dashboard',
+            component: Page,
+            loader: async () => ({ data: 'page-data' }),
+          },
+        ],
+      },
+    ]
+
+    const router = createRouter({ routes, url: '/' })
+    await router.push('/app/dashboard')
+
+    // The contract: navigation lands on the redirect target, NOT the child page.
+    expect(router.currentRoute().path).toBe('/login')
+    router.destroy()
+  })
+
+  test('redirect() with custom status preserves the status on the thrown error', async () => {
+    // The router doesn't surface the status itself (it just calls .replace),
+    // but the SSR handler reads it via getRedirectInfo. Verify the throw path
+    // captures the status the same way the helper unit tests do.
+    const Home = () => h('div', null, 'home')
+    const Login = () => h('div', null, 'login')
+
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      { path: '/login', component: Login },
+      {
+        path: '/old',
+        component: Home,
+        loader: async () => {
+          redirect('/login', 308)
+        },
+      },
+    ]
+
+    const router = createRouter({ routes, url: '/' })
+    await router.push('/old')
+    expect(router.currentRoute().path).toBe('/login')
+    router.destroy()
+  })
+
+  test('redirect from prefetchLoaderData propagates as a thrown RedirectError (SSR contract)', async () => {
+    const Home = () => h('div', null, 'home')
+    const Protected = () => h('div', null, 'protected')
+
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/app',
+        component: Protected,
+        loader: async () => {
+          redirect('/login')
+        },
+      },
+    ]
+
+    const router = createRouter({ routes, url: '/' })
+
+    let caught: unknown
+    try {
+      await prefetchLoaderData(router as never, '/app')
+    } catch (err) {
+      caught = err
+    }
+
+    // The SSR handler catches this thrown error and converts it to a 302/307.
+    // The contract here is just "the throw propagates" — the conversion is
+    // tested in the server package's handler tests.
+    expect(caught).toBeDefined()
+    const info = getRedirectInfo(caught)
+    expect(info?.url).toBe('/login')
+    router.destroy()
+  })
+})