@pyreon/router 0.13.1 → 0.15.0

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-import * as _pyreon_core0 from "@pyreon/core";
+import * as _$_pyreon_core0 from "@pyreon/core";
 import { ComponentFn, ComponentFn as ComponentFn$1, Props, VNodeChild } from "@pyreon/core";
 import { Computed, Signal } from "@pyreon/reactivity";
 
@@ -47,6 +47,15 @@ interface ResolvedRoute<P extends Record<string, string | undefined> = Record<st
   /** 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;
 }
 declare const LAZY_SYMBOL: unique symbol;
 interface LazyComponent {
@@ -102,6 +111,21 @@ interface LoaderContext {
   query: Record<string, string>;
   /** Aborted when a newer navigation supersedes this one */
   signal: AbortSignal;
+  /**
+   * The incoming HTTP `Request` — populated only when the loader runs during
+   * SSR (via `prefetchLoaderData`); `undefined` on every CSR navigation.
+   * Lets server-side loaders read cookies / auth headers and decide whether
+   * to `throw redirect('/login')` BEFORE the layout renders.
+   *
+   * @example
+   * loader: ({ request }) => {
+   *   const cookie = request?.headers.get('cookie') ?? ''
+   *   const sid = cookie.match(/sid=([^;]+)/)?.[1]
+   *   if (!sid) redirect('/login')
+   *   return { sid }
+   * }
+   */
+  request?: Request;
 }
 type RouteLoaderFn = (ctx: LoaderContext) => Promise<unknown>;
 interface RouteRecord<TPath extends string = string> {
@@ -144,8 +168,58 @@ 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$1;
+  /**
+   * 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$1;
+  /** 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[];
 }
@@ -254,7 +328,14 @@ interface Router<TNames extends string = string> {
    * separately when creating the router (`createRouter({ url, ... })`) or
    * call this for the same `url` you initialised the router with.
    */
-  preload(path: string): Promise<void>;
+  preload(path: string, request?: Request): 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;
 }
@@ -290,6 +371,25 @@ 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, signal }.
+   * Tracking the signal lets dedup skip an in-flight entry whose signal is
+   * already aborted — otherwise nav-2 would inherit nav-1's aborted promise
+   * (`router.push` aborts the previous nav's controller before starting the
+   * next, so back-to-back nav to the same path could resolve nav-2 against
+   * nav-1's aborted fetch).
+   */
+  _loaderInflight: Map<string, {
+    promise: Promise<unknown>;
+    signal: AbortSignal;
+  }>;
 }
 //#endregion
 //#region src/components.d.ts
@@ -338,15 +438,97 @@ interface RouterLinkProps extends Props {
   exact?: boolean;
   /**
    * Prefetch strategy for loader data:
-   *   - "hover" (default) — prefetch when the user hovers over the link
+   *   - "intent" (default) — prefetch on hover AND focus (covers mouse + keyboard)
+   *   - "hover" — prefetch on hover only
    *   - "viewport" — prefetch when the link scrolls into the viewport
    *   - "none" — no prefetching
    */
-  prefetch?: 'hover' | 'viewport' | 'none';
+  prefetch?: 'intent' | 'hover' | 'viewport' | 'none';
   children?: VNodeChild | null;
 }
 declare const RouterLink: ComponentFn<RouterLinkProps>;
 //#endregion
+//#region src/not-found.d.ts
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function notFound(message?: string): never;
+/** Check if an error is a NotFoundError thrown by `notFound()`. */
+declare function isNotFoundError(err: unknown): boolean;
+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>
+ * ```
+ */
+declare const NotFoundBoundary: ComponentFn<NotFoundBoundaryProps>;
+//#endregion
+//#region src/redirect.d.ts
+/** Standard redirect status codes. 307/308 preserve the request method, 302/303 don't. */
+type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+interface RedirectInfo {
+  url: string;
+  status: RedirectStatus;
+}
+/**
+ * Throw inside a route loader to redirect the navigation server-side
+ * (during SSR returns a 302/307 `Location:` response) and client-side
+ * (during CSR triggers `router.replace()` before the layout renders).
+ *
+ * The auth-gate use case: replaces the fragile `onMount + router.push()`
+ * workaround. `onMount` doesn't fire reliably under nested-layout dev SSR +
+ * hydration — so the layout renders briefly before the push happens, leaking
+ * authenticated UI to unauthenticated users. `redirect()` runs in the loader
+ * BEFORE the layout's component is invoked, so the unauthenticated UI never
+ * mounts in the first place.
+ *
+ * @example
+ * ```ts
+ * // src/routes/app/_layout.tsx
+ * export const loader = async ({ request }) => {
+ *   const session = await getSession(request)
+ *   if (!session) redirect('/login')
+ *   return { user: session.user }
+ * }
+ * ```
+ *
+ * @param url - Target URL (typically a path like `/login` or absolute URL for cross-origin).
+ * @param status - HTTP redirect status. Default `307` (Temporary Redirect, method-preserving).
+ *   Use `301`/`308` for permanent moves, `302`/`303` to force GET on the target.
+ */
+declare function redirect(url: string, status?: RedirectStatus): never;
+/** Check if an error is a RedirectError thrown by `redirect()`. */
+declare function isRedirectError(err: unknown): boolean;
+/**
+ * Extract the redirect URL and status from a thrown RedirectError. Returns
+ * `null` if `err` isn't a RedirectError. Used by the router's loader-runner
+ * (CSR) and the SSR handler to convert the thrown error into the right kind
+ * of response (a `router.replace()` call or a `302`/`307` Response).
+ */
+declare function getRedirectInfo(err: unknown): RedirectInfo | null;
+//#endregion
 //#region src/loader.d.ts
 /**
  * Returns the data resolved by the current route's `loader` function.
@@ -365,12 +547,18 @@ declare function useLoaderData<T = unknown>(): T;
  * SSR helper: pre-run all loaders for the given path before rendering.
  * Call this before `renderToString` so route components can read data via `useLoaderData()`.
  *
+ * The optional `request` is forwarded to each loader's `LoaderContext.request`,
+ * letting server-side loaders read cookies / auth headers and `throw redirect()`
+ * before the layout renders. A loader that throws `redirect()` propagates the
+ * thrown error here — the SSR handler's `catch` converts it into a 302/307
+ * `Location:` Response.
+ *
  * @example
  * const router = createRouter({ routes, url: req.url })
- * await prefetchLoaderData(router, req.url)
+ * await prefetchLoaderData(router, req.url, request)
  * const html = await renderToString(h(App, { router }))
  */
-declare function prefetchLoaderData(router: RouterInstance, path: string): Promise<void>;
+declare function prefetchLoaderData(router: RouterInstance, path: string, request?: Request): Promise<void>;
 /**
  * Serialize loader data to a JSON-safe plain object for embedding in SSR HTML.
  * Keys are route path patterns (stable across server and client).
@@ -399,10 +587,6 @@ declare function serializeLoaderData(router: RouterInstance): Record<string, unk
 declare function hydrateLoaderData(router: RouterInstance, serialized: Record<string, unknown>): void;
 //#endregion
 //#region src/match.d.ts
-/**
- * Parse a query string into key-value pairs. Duplicate keys are overwritten
- * (last value wins). Use `parseQueryMulti` to preserve duplicates as arrays.
- */
 declare function parseQuery(qs: string): Record<string, string>;
 /**
  * Parse a query string preserving duplicate keys as arrays.
@@ -424,7 +608,7 @@ declare function buildPath(pattern: string, params: Record<string, string>): str
 declare function findRouteByName(name: string, routes: RouteRecord[]): RouteRecord | null;
 //#endregion
 //#region src/router.d.ts
-declare const RouterContext: _pyreon_core0.Context<RouterInstance | null>;
+declare const RouterContext: _$_pyreon_core0.Context<RouterInstance | null>;
 declare function useRouter(): Router;
 declare function useRoute<TPath extends string = string>(): () => ResolvedRoute<ExtractParams<TPath> & Record<string, string>, Record<string, string>>;
 /**
@@ -526,6 +710,27 @@ declare function useSearchParams<T extends Record<string, string>>(defaults?: T)
  * ```
  */
 declare function useTypedSearchParams<T extends SearchParamSchema>(schema: T): [get: () => InferSearchParams<T>, set: (updates: Partial<InferSearchParams<T>>) => Promise<void>];
+/**
+ * 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
+ * ```
+ */
+declare function useValidatedSearch<T extends Record<string, unknown> = Record<string, unknown>>(): () => T;
 /**
  * Returns true while a navigation is in progress (guards + loaders running).
  * Use this to show loading indicators during route transitions.
@@ -556,7 +761,7 @@ declare function useTransition(): () => boolean;
  * ```
  */
 declare function useMiddlewareData(): () => Record<string, unknown>;
-declare function createRouter(options: RouterOptions | RouteRecord[]): Router;
+declare function createRouter<TNames extends string = string>(options: RouterOptions | RouteRecord[]): Router<TNames>;
 //#endregion
-export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteMiddleware, type RouteMiddlewareContext, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams };
+export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, NotFoundBoundary, type NotFoundBoundaryProps, type RedirectStatus, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteMiddleware, type RouteMiddlewareContext, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, getRedirectInfo, hydrateLoaderData, isNotFoundError, isRedirectError, lazy, notFound, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, redirect, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams, useValidatedSearch };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/router",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Official router for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/router#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "!lib/**/*.map",
     "src",
     "README.md",
     "LICENSE"
@@ -43,14 +44,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.13.1",
-    "@pyreon/reactivity": "^0.13.1",
-    "@pyreon/runtime-dom": "^0.13.1"
+    "@pyreon/core": "^0.15.0",
+    "@pyreon/reactivity": "^0.15.0",
+    "@pyreon/runtime-dom": "^0.15.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/test-utils": "^0.13.1",
+    "@pyreon/test-utils": "^0.13.2",
     "@vitest/browser-playwright": "^4.1.4",
     "happy-dom": "^20.8.3"
   }