@pyreon/router 0.13.1 → 0.14.0

package/src/not-found.ts

@@ -0,0 +1,75 @@
+import type { ComponentFn, Props, VNodeChild } from '@pyreon/core'
+import { ErrorBoundary, h } from '@pyreon/core'
+
+// ─── NotFound symbol + throw ────────────────────────────────────────────────
+
+const NOT_FOUND = Symbol.for('pyreon.notFound')
+
+/**
+ * Throw inside a route loader or component to trigger the nearest
+ * NotFoundBoundary. Inspired by Next.js's `notFound()`.
+ *
+ * @example
+ * ```ts
+ * // In a loader:
+ * loader: async ({ params }) => {
+ *   const user = await fetchUser(params.id)
+ *   if (!user) notFound()
+ *   return user
+ * }
+ * ```
+ */
+export function notFound(message?: string): never {
+  const err = new Error(message ?? 'Not Found')
+  ;(err as unknown as Record<symbol, unknown>)[NOT_FOUND] = true
+  throw err
+}
+
+/** Check if an error is a NotFoundError thrown by `notFound()`. */
+export function isNotFoundError(err: unknown): boolean {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    (err as Record<string | symbol, unknown>)[NOT_FOUND] === true
+  )
+}
+
+// ─── NotFoundBoundary ──────────────────────────────────────────────────────
+
+export interface NotFoundBoundaryProps extends Props {
+  /** Component or VNode to render when notFound() is thrown */
+  fallback: ComponentFn | VNodeChild
+  children?: VNodeChild
+}
+
+/**
+ * Catches `notFound()` errors from child route components or loaders
+ * and renders the fallback. Wraps Pyreon's ErrorBoundary with notFound
+ * detection — non-notFound errors propagate to parent error boundaries.
+ *
+ * @example
+ * ```tsx
+ * <NotFoundBoundary fallback={<NotFoundPage />}>
+ *   <RouterView />
+ * </NotFoundBoundary>
+ * ```
+ */
+export const NotFoundBoundary: ComponentFn<NotFoundBoundaryProps> = (props) => {
+  return h(
+    ErrorBoundary,
+    {
+      fallback: (err: unknown, reset: () => void) => {
+        if (!isNotFoundError(err)) {
+          // Re-throw non-notFound errors so they propagate
+          throw err
+        }
+        const fb = props.fallback
+        if (typeof fb === 'function' && fb.length <= 1) {
+          return h(fb as ComponentFn, { error: err, reset })
+        }
+        return fb as VNodeChild
+      },
+    },
+    props.children,
+  )
+}

package/src/router.ts

@@ -29,6 +29,9 @@ const _isBrowser = typeof window !== 'undefined'
 // @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
 const __DEV__ = import.meta.env?.DEV === true
 
+// Dev-time counter sink — see packages/internals/perf-harness for contract.
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
+
 // ─── Router context ───────────────────────────────────────────────────────────
 // Context-based access: isolated per request in SSR (ALS-backed via
 // @pyreon/runtime-server), isolated per component tree in CSR.
@@ -253,9 +256,7 @@ export type SearchParamSchema = {
 
 /** Infer the typed result from a search param schema. */
 type InferSearchParams<T extends SearchParamSchema> = {
-  [K in keyof T]: T[K] extends 'number' ? number
-    : T[K] extends 'boolean' ? boolean
-    : string
+  [K in keyof T]: T[K] extends 'number' ? number : T[K] extends 'boolean' ? boolean : string
 }
 
 /**
@@ -316,15 +317,20 @@ export function useSearchParams<T extends Record<string, string>>(
  */
 export function useTypedSearchParams<T extends SearchParamSchema>(
   schema: T,
-): [get: () => InferSearchParams<T>, set: (updates: Partial<InferSearchParams<T>>) => Promise<void>] {
+): [
+  get: () => InferSearchParams<T>,
+  set: (updates: Partial<InferSearchParams<T>>) => Promise<void>,
+] {
   const router = _getRouter()
   const get = (): InferSearchParams<T> => {
     const query = router.currentRoute().query
     const result: Record<string, unknown> = {}
     for (const [key, type] of Object.entries(schema)) {
       const raw = query[key]
-      if (type === 'number') result[key] = raw !== undefined ? Number(raw) : 0
-      else if (type === 'boolean') result[key] = raw === 'true' || raw === '1'
+      if (type === 'number') {
+        const n = raw !== undefined ? Number(raw) : 0
+        result[key] = Number.isNaN(n) ? 0 : n
+      } else if (type === 'boolean') result[key] = raw === 'true' || raw === '1'
       else result[key] = raw ?? ''
     }
     return result as InferSearchParams<T>
@@ -341,6 +347,53 @@ export function useTypedSearchParams<T extends SearchParamSchema>(
   return [get, set]
 }
 
+/**
+ * Read the validated search params from the current route's `validateSearch`.
+ * Returns a reactive accessor that re-evaluates when the route changes.
+ *
+ * The generic `T` should match the return type of your `validateSearch` function.
+ *
+ * @example
+ * ```tsx
+ * // Route config:
+ * { path: '/search', validateSearch: (raw) => ({
+ *   page: Number(raw.page) || 1,
+ *   q: raw.q ?? '',
+ * }), component: SearchPage }
+ *
+ * // In SearchPage:
+ * const search = useValidatedSearch<{ page: number; q: string }>()
+ * // search().page — typed as number
+ * // search().q — typed as string
+ * ```
+ */
+export function useValidatedSearch<
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(): () => T {
+  const router = _getRouter()
+  // Structural sharing: cache the previous result and return it if
+  // shallow-equal to the new one. Prevents downstream re-renders when
+  // unrelated query params change but the validated subset didn't.
+  let prev: T | null = null
+  return () => {
+    const next = router.currentRoute().search as T
+    if (prev && shallowEqual(prev, next)) return prev
+    prev = next
+    return next
+  }
+}
+
+/** Shallow equality check for plain objects — keys + strict value comparison. */
+function shallowEqual<T extends Record<string, unknown>>(a: T, b: T): boolean {
+  const keysA = Object.keys(a)
+  const keysB = Object.keys(b)
+  if (keysA.length !== keysB.length) return false
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false
+  }
+  return true
+}
+
 function _getRouter(): RouterInstance {
   const router = (useContext(RouterContext) ?? _activeRouter) as RouterInstance | null
   if (!router)
@@ -385,12 +438,14 @@ export function useTransition(): () => boolean {
  */
 export function useMiddlewareData(): () => Record<string, unknown> {
   const router = _getRouter()
-  return () => (router.currentRoute() as any)._middlewareData ?? {}
+  return () => router.currentRoute()._middlewareData ?? {}
 }
 
 // ─── Factory ──────────────────────────────────────────────────────────────────
 
-export function createRouter(options: RouterOptions | RouteRecord[]): Router {
+export function createRouter<TNames extends string = string>(
+  options: RouterOptions | RouteRecord[],
+): Router<TNames> {
   const opts: RouterOptions = Array.isArray(options) ? { routes: options } : options
   const {
     routes,
@@ -558,6 +613,68 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     return runGlobalGuards(guards, to, from, gen)
   }
 
+  /** Default cache key: path + serialized params */
+  function defaultLoaderKey(
+    record: RouteRecord,
+    ctx: Pick<LoaderContext, 'params' | 'query'>,
+  ): string {
+    return `${record.path}:${JSON.stringify(ctx.params)}`
+  }
+
+  /** Get cache key for a route record + context. */
+  function getCacheKey(record: RouteRecord, ctx: Pick<LoaderContext, 'params' | 'query'>): string {
+    return record.loaderKey ? record.loaderKey(ctx) : defaultLoaderKey(record, ctx)
+  }
+
+  /** Check if a cached entry is still fresh (not expired by gcTime). */
+  function isCacheFresh(entry: { timestamp: number }, record: RouteRecord): boolean {
+    const gcTime = record.gcTime ?? 300_000 // 5 min default
+    if (gcTime === 0) return false // caching disabled
+    return Date.now() - entry.timestamp < gcTime
+  }
+
+  /**
+   * Execute a loader with cache + dedup:
+   * 1. Cache hit + fresh → return cached data (skip loader entirely)
+   * 2. In-flight for same key → dedup (return existing promise)
+   * 3. Otherwise → run loader, cache result, clean up in-flight
+   */
+  function executeLoader(record: RouteRecord, loaderCtx: LoaderContext): Promise<unknown> {
+    if (!record.loader) return Promise.resolve(undefined)
+
+    const key = getCacheKey(record, loaderCtx)
+
+    // 1. Cache hit — skip for SWR routes (they always revalidate via the SWR path)
+    if (!record.staleWhileRevalidate) {
+      const cached = router._loaderCache.get(key)
+      if (cached && isCacheFresh(cached, record)) {
+        if (__DEV__) _countSink.__pyreon_count__?.('router.loaderCache.hit')
+        return Promise.resolve(cached.data)
+      }
+    }
+
+    // 2. Dedup in-flight
+    const inflight = router._loaderInflight.get(key)
+    if (inflight) return inflight
+
+    // 3. Execute
+    if (__DEV__) _countSink.__pyreon_count__?.('router.loaderRun')
+    const promise = record
+      .loader(loaderCtx)
+      .then((data) => {
+        router._loaderCache.set(key, { data, timestamp: Date.now() })
+        router._loaderInflight.delete(key)
+        return data
+      })
+      .catch((err) => {
+        router._loaderInflight.delete(key)
+        throw err
+      })
+
+    router._loaderInflight.set(key, promise)
+    return promise
+  }
+
   async function runBlockingLoaders(
     records: RouteRecord[],
     to: ResolvedRoute,
@@ -565,9 +682,7 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     ac: AbortController,
   ): Promise<boolean> {
     const loaderCtx: LoaderContext = { params: to.params, query: to.query, signal: ac.signal }
-    const results = await Promise.allSettled(
-      records.map((r) => (r.loader ? r.loader(loaderCtx) : Promise.resolve(undefined))),
-    )
+    const results = await Promise.allSettled(records.map((r) => executeLoader(r, loaderCtx)))
     if (gen !== _navGen) return false
     for (let i = 0; i < records.length; i++) {
       const result = results[i]
@@ -583,10 +698,14 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     const loaderCtx: LoaderContext = { params: to.params, query: to.query, signal: ac.signal }
     for (const r of records) {
       if (!r.loader) continue
+      // Bypass cache for revalidation — always fetch fresh
       r.loader(loaderCtx)
         .then((data) => {
           if (!ac.signal.aborted) {
             router._loaderData.set(r, data)
+            // Update cache with fresh data
+            const key = getCacheKey(r, loaderCtx)
+            router._loaderCache.set(key, { data, timestamp: Date.now() })
             // Bump loadingSignal to trigger reactive re-render with fresh data
             loadingSignal.update((n) => n + 1)
             loadingSignal.update((n) => n - 1)
@@ -645,9 +764,10 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
 
     // Use View Transitions API when available and not explicitly disabled.
     // Route meta can opt out: meta: { viewTransition: false }
-    const useVT = _isBrowser
-      && to.meta.viewTransition !== false
-      && typeof (document as any).startViewTransition === 'function'
+    const useVT =
+      _isBrowser &&
+      to.meta.viewTransition !== false &&
+      typeof (document as any).startViewTransition === 'function'
 
     if (useVT) {
       // `startViewTransition(cb)` runs `cb` inside an async transition. Its
@@ -670,10 +790,11 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
         ready?: Promise<void>
         finished?: Promise<void>
       }
-      const vt = (document as { startViewTransition?: (cb: () => void) => ViewTransitionLike | undefined })
-        .startViewTransition!(() => {
-          doCommit()
-        })
+      const vt = (
+        document as { startViewTransition?: (cb: () => void) => ViewTransitionLike | undefined }
+      ).startViewTransition!(() => {
+        doCommit()
+      })
       // `startViewTransition` may return `undefined` in test doubles
       // that shim it with a bare `(cb) => cb()`. Guard accordingly.
       if (vt) {
@@ -734,7 +855,9 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     to: ResolvedRoute,
     from: ResolvedRoute,
     gen: number,
-  ): Promise<{ action: 'continue' } | { action: 'cancel' } | { action: 'redirect'; target: string }> {
+  ): Promise<
+    { action: 'continue' } | { action: 'cancel' } | { action: 'redirect'; target: string }
+  > {
     const ctx: RouteMiddlewareContext = { to, from, data: {} }
 
     for (const record of to.matched) {
@@ -749,11 +872,13 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     }
 
     // Store middleware data on the resolved route for component access
-    ;(to as any)._middlewareData = ctx.data
+    to._middlewareData = ctx.data
     return { action: 'continue' }
   }
 
   async function navigate(rawPath: string, replace: boolean, redirectDepth = 0): Promise<void> {
+    if (__DEV__) _countSink.__pyreon_count__?.('router.navigate')
+    router._navigationStartTime = Date.now()
     if (redirectDepth > 10) {
       if (__DEV__) {
         // oxlint-disable-next-line no-console
@@ -847,6 +972,9 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     _readyPromise,
     _onError: onError,
     _maxCacheSize: maxCacheSize,
+    _navigationStartTime: Date.now(),
+    _loaderCache: new Map(),
+    _loaderInflight: new Map(),
 
     async push(
       location:
@@ -958,6 +1086,27 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
       )
     },
 
+    invalidateLoader(keyOrPredicate?: string | ((key: string) => boolean)) {
+      if (!keyOrPredicate) {
+        // Invalidate all
+        router._loaderCache.clear()
+        router._loaderInflight.clear()
+        return
+      }
+      if (typeof keyOrPredicate === 'string') {
+        router._loaderCache.delete(keyOrPredicate)
+        router._loaderInflight.delete(keyOrPredicate)
+        return
+      }
+      // Predicate
+      for (const key of [...router._loaderCache.keys()]) {
+        if (keyOrPredicate(key)) {
+          router._loaderCache.delete(key)
+          router._loaderInflight.delete(key)
+        }
+      }
+    },
+
     destroy() {
       if (_popstateHandler) window.removeEventListener('popstate', _popstateHandler)
       if (_hashchangeHandler) window.removeEventListener('hashchange', _hashchangeHandler)
@@ -968,6 +1117,8 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
       router._blockers.clear()
       componentCache.clear()
       router._loaderData.clear()
+      router._loaderCache.clear()
+      router._loaderInflight.clear()
       router._abortController?.abort()
       router._abortController = null
       // Clear global ref so stale router doesn't survive in SSR or re-creation
@@ -986,7 +1137,7 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     }
   })
 
-  return router
+  return router as unknown as Router<TNames>
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -1014,6 +1165,13 @@ function resolveNamedPath(
 ): string {
   const record = index.get(name)
   if (!record) {
+    if (__DEV__) {
+      // oxlint-disable-next-line no-console
+      console.warn(
+        `[Pyreon Router] Unknown route name "${name}". ` +
+          `Available names: ${[...index.keys()].join(', ') || '(none)'}. Falling back to "/".`,
+      )
+    }
     return '/'
   }
   let path = buildPath(record.path, params)

package/src/tests/match.test.ts

@@ -465,3 +465,34 @@ describe('resolveRoute — wildcard patterns', () => {
     expect(r.matched[r.matched.length - 1]?.component).toBe(NotFound)
   })
 })
+
+// ─── + as space in query parsing (application/x-www-form-urlencoded) ────────
+
+describe('parseQuery — + as space', () => {
+  it('decodes + as space in values', () => {
+    expect(parseQuery('name=john+doe')).toEqual({ name: 'john doe' })
+  })
+
+  it('decodes + as space in keys', () => {
+    expect(parseQuery('first+name=Alice')).toEqual({ 'first name': 'Alice' })
+  })
+
+  it('handles mixed + and %20', () => {
+    expect(parseQuery('a=hello+world&b=foo%20bar')).toEqual({
+      a: 'hello world',
+      b: 'foo bar',
+    })
+  })
+
+  it('handles multiple + in a value', () => {
+    expect(parseQuery('q=one+two+three')).toEqual({ q: 'one two three' })
+  })
+})
+
+describe('parseQueryMulti — + as space', () => {
+  it('decodes + as space in values', () => {
+    expect(parseQueryMulti('tag=hello+world&tag=foo+bar')).toEqual({
+      tag: ['hello world', 'foo bar'],
+    })
+  })
+})