@qwik.dev/router 2.0.0-beta.35 → 2.0.0-beta.37

package/lib/index.d.ts

@@ -7,13 +7,15 @@ import { CookieOptions } from '@qwik.dev/router/middleware/request-handler';
 import { CookieValue } from '@qwik.dev/router/middleware/request-handler';
 import { DeferReturn } from '@qwik.dev/router/middleware/request-handler';
 import type { EnvGetter } from '@qwik.dev/router/middleware/request-handler';
+import { InternalRequest } from '@qwik.dev/router/middleware/request-handler';
 import { JSXOutput } from '@qwik.dev/core';
+import { NoSerialize } from '@qwik.dev/core';
 import { QRL } from '@qwik.dev/core';
 import { QRLEventHandlerMulti } from '@qwik.dev/core';
 import { QwikIntrinsicElements } from '@qwik.dev/core';
 import { QwikJSX } from '@qwik.dev/core';
 import { Render } from '@qwik.dev/core/server';
-import { RenderOptions } from '@qwik.dev/core/server';
+import { RenderToStreamOptions } from '@qwik.dev/core/server';
 import { RequestEvent } from '@qwik.dev/router/middleware/request-handler';
 import { RequestEventAction } from '@qwik.dev/router/middleware/request-handler';
 import { RequestEventBase } from '@qwik.dev/router/middleware/request-handler';
@@ -162,15 +164,25 @@ export declare type ActionStore<RETURN, INPUT, OPTIONAL extends boolean = true>
 declare type AnchorAttributes = QwikIntrinsicElements['a'];
 
 /**
- * The cacheKey export type. When exported from a page module alongside eTag, enables in-memory SSR
- * caching.
+ * Cache key function. Used by `routeConfig.cacheKey` (SSR HTML cache) and by `routeLoader$`'s
+ * `cacheKey` option (per-loader JSON cache).
  *
- * - `true`: use the default cache key `status|eTag|pathname`
- * - Function: receives status, eTag, and pathname; returns a cache key string or null (no cache)
+ * - `true`: use the surface's default key.
+ *
+ *   - SSR default: `${status}|${eTag}|${pathname}` when an eTag is set, otherwise
+ *       `${status}|${pathname}`.
+ *   - Loader default: `${pathname}|${filteredSearch}|${loaderId}|${eTag}` when an eTag is set,
+ *       otherwise `${pathname}|${filteredSearch}|${loaderId}`.
+ * - Function: receives the request event and the normalized, unquoted eTag (or an empty string when
+ *   none was provided). Return the cache key string, or `null` or `''` to skip caching for this
+ *   request. Loader callbacks receive the loader-scoped request event, with `url`, `query`, and
+ *   `request.url` filtered by the loader's `search` allowlist.
+ *
+ * Note: valid cacheKeys are non-empty strings.
  *
  * @public
  */
-export declare type CacheKeyFn = true | ((status: number, eTag: string, pathname: string) => string | null);
+export declare type CacheKeyFn = true | ((requestEv: RequestEvent, eTag: string) => string | null);
 
 /** @public */
 export declare interface ContentHeading {
@@ -189,7 +201,18 @@ export declare interface ContentMenu {
 declare type ContentModule = PageModule | LayoutModule;
 
 /**
- * The eTag export type: a static string or a function receiving DocumentHeadProps.
+ * The eTag export type for routeConfig.
+ *
+ * - `string` — static ETag value.
+ * - `(props: DocumentHeadProps) => string | null` — compute the ETag from route context (params, URL,
+ *   loaded data via `resolveValue`, etc.). Return `null` to skip eTag for this request.
+ *
+ * Qwik normalizes eTag values by stripping weak-form `W/` prefixes, quotes, and forbidden chars,
+ * then sends a strong `ETag` header. Values that normalize to an empty string are treated as
+ * absent.
+ *
+ * When set (and a value is produced), the server includes an `ETag` header and returns `304` if
+ * `If-None-Match` matches.
  *
  * @public
  */
@@ -357,10 +380,10 @@ declare type EndpointModuleLoader = () => ValueOrPromise<RouteModule>;
 declare interface EndpointResponse {
     status: number;
     statusMessage?: string;
-    loaders: Record<string, unknown>;
-    loadersSerializationStrategy: Map<string, SerializationStrategy>;
     formData?: FormData;
     action?: string;
+    actionResult?: unknown;
+    loaderHashes?: string[];
 }
 
 /** @public */
@@ -433,6 +456,8 @@ export declare type HttpErrorProps = {
     message: string;
 };
 
+export { InternalRequest }
+
 declare type IsAny<Type> = 0 extends 1 & Type ? true : false;
 
 /** @public */
@@ -511,6 +536,10 @@ declare interface LoadedRoute {
     $notFound$?: boolean;
     /** The error module loader (nearest _E ancestor), for rendering ServerErrors */
     $errorLoader$?: ContentModuleLoader;
+    /** Merged array of routeLoader$ hashes from all matched nodes (layouts + page) */
+    $loaders$?: string[];
+    /** Runtime-only mapping of routeLoader$ hashes to the matched pathname used for q-loader fetches */
+    $loaderPaths$?: Record<string, string>;
 }
 
 /** @public */
@@ -537,9 +566,79 @@ declare type LoaderConstructorQRL = {
 
 /** @public */
 declare type LoaderOptions = {
+    /** @deprecated Unused */
     readonly id?: string;
     readonly validation?: DataValidator[];
     readonly serializationStrategy?: SerializationStrategy;
+    /**
+     * Time in milliseconds after which the loader data is considered stale. The server derives
+     * `Cache-Control: max-age` seconds from this value on loader responses.
+     *
+     * On the client, the loader's AsyncSignal `expires` is set to this value. If `poll` is true, the
+     * signal auto-refetches when expired. If `poll` is false (default), the data is marked stale but
+     * not auto-refetched.
+     */
+    readonly expires?: number;
+    /**
+     * When true AND `expires` is set, the loader data is automatically refetched when it expires
+     * (polling behavior). When false (default), expired data is marked stale but not auto-refetched.
+     */
+    readonly poll?: boolean;
+    /**
+     * Enable ETag-based caching for this loader's JSON responses.
+     *
+     * - `string` — static ETag value; if `If-None-Match` matches, the loader is skipped entirely
+     * - `(ev: RequestEvent) => string | null` — compute the ETag from the request context (params, URL,
+     *   headers, etc.); if `If-None-Match` matches, the loader is skipped entirely. Return null to
+     *   skip eTag for this request.
+     *
+     * Qwik normalizes eTag values by stripping weak-form `W/` prefixes, quotes, and forbidden chars,
+     * then sends a strong `ETag` header. Values that normalize to an empty string are treated as
+     * absent.
+     *
+     * When set, the server includes an `ETag` header on `q-loader-*.json` responses and returns `304`
+     * if the client sends a matching `If-None-Match` header.
+     *
+     * For auto-computed eTags, use `cacheKey` instead — on cache write the eTag is hashed from the
+     * serialized response and stored alongside it, so subsequent hits get the same eTag.
+     */
+    readonly eTag?: string | ((ev: RequestEvent) => string | null);
+    /**
+     * Enable in-memory server-side caching of this loader's serialized JSON response.
+     *
+     * - `true` — use the default key `${pathname}|${filteredSearch}|${loaderId}` (suffixed with
+     *   `|${eTag}` when an eTag is set).
+     * - Function `(requestEv, eTag) => string | null` — return a custom key, or `null` to skip caching
+     *   this request.
+     *
+     * On cache miss the loader runs, the serialized response is stored alongside its eTag (computed
+     * from the data when no `eTag` option is set), and the response is sent. On cache hit the stored
+     * `{ eTag, data }` pair is served directly — `If-None-Match` is checked against the stored eTag
+     * and a `304` is returned when it matches.
+     */
+    readonly cacheKey?: CacheKeyFn;
+    /**
+     * Allowlist of URL search parameter names that this loader depends on.
+     *
+     * When set, the loader only re-fetches when the listed search params change — other param changes
+     * are ignored. Only the listed params are sent in the loader JSON request URL. During SSR and
+     * loader JSON requests, the loader receives a request event with `url`, `query`, and
+     * `request.url` filtered to the same params.
+     *
+     * When not set, the `qwikRouter()` plugin option `strictLoaders` determines the behavior. If
+     * `strictLoaders` is `true` (this is the default), no search params are sent and changes do not
+     * trigger a re-fetch. If `strictLoaders` is `false`, all search params are sent and any change
+     * triggers a re-fetch.
+     */
+    readonly search?: string[];
+    /**
+     * When true (default), the previous value is kept while the loader re-fetches after navigation,
+     * so components see stale data until the new response arrives.
+     *
+     * When false, the value is cleared on re-fetch, causing reads to suspend (show a loading
+     * boundary). This is useful when showing old data during navigation would be confusing.
+     */
+    readonly allowStale?: boolean;
 };
 
 /** @public */
@@ -673,6 +772,8 @@ export declare interface QwikRouterEnvData {
     params: PathParams;
     response: EndpointResponse;
     loadedRoute: LoadedRoute;
+    routeLoaderCtx: RouteLoaderCtx;
+    loaderValues: Record<string, unknown>;
 }
 
 /** @public */
@@ -754,12 +855,12 @@ export declare interface QwikRouterProps {
 export declare const QwikRouterProvider: Component<QwikRouterProps>;
 
 /** @public */
-export declare type RendererOptions = Omit<RenderOptions, 'serverData'> & {
+export declare type RendererOptions = Omit<RenderToStreamOptions, 'serverData'> & {
     serverData: ServerData;
 };
 
 /** @public */
-export declare type RendererOutputOptions = Omit<RenderOptions, 'serverData'> & {
+export declare type RendererOutputOptions = Omit<RenderToStreamOptions, 'serverData'> & {
     serverData: ServerData & {
         documentHead?: DocumentHeadValue;
     } & Record<string, unknown>;
@@ -783,7 +884,26 @@ export declare type ResolvedDocumentHead<FrontMatter extends Record<string, any>
     readonly manifestHash: string;
 };
 
-/** @public */
+/**
+ * Define a route action that handles form submissions or programmatic invocations.
+ *
+ * Actions run on the server when submitted from the client. The result is returned as an
+ * `ActionStore` with `.value` for success data and `.error` for errors (including validation errors
+ * from `zod$`/`valibot$` where `.fieldErrors` etc. are accessible directly on `.error`).
+ *
+ * By default, after an action completes, ALL current route loaders are invalidated on the client
+ * and re-fetched as needed (so that the browser cache is correct). This can be controlled with:
+ *
+ * - `invalidate: [loader1, loader2]`: Only invalidate specific loaders. The client re-fetches them
+ *   individually. Other loaders keep their current data.
+ * - `invalidate: []`: No loaders are invalidated. The action response only contains the action
+ *   result. Use this when the action doesn't affect any loader data.
+ *
+ * The `strictLoaders` Vite plugin option applies `invalidate: []` globally for all actions that
+ * don't specify an explicit `invalidate` option.
+ *
+ * @public
+ */
 export declare const routeAction$: ActionConstructor;
 
 /* Excluded from this release type: routeActionQrl */
@@ -857,13 +977,59 @@ export declare interface RouteData {
     _M?: RouteData[];
     /** Menu loader for this subtree (from menu.md). Runtime uses nearest ancestor during traversal. */
     _N?: MenuModuleLoader;
+    /** Array of routeLoader$ hashes for this node's loaders */
+    _R?: string[];
     /** Child route segments (any key not starting with `_`) */
     [part: string]: RouteData | RouteData[] | ModuleLoader[] | ContentModuleLoader | MenuModuleLoader | string[] | string | undefined;
 }
 
-/** @public */
+/**
+ * Define a route loader that fetches data before the route renders.
+ *
+ * Route loaders run on the server during SSR and return data as an `AsyncSignal`. On the client,
+ * loaders automatically re-fetch when the route changes (SPA navigation). Each loader gets its own
+ * JSON endpoint (`q-loader-{id}.{hash}.json`), so only the loaders present on the target route are
+ * fetched.
+ *
+ * **Important:** Route loader data uses Qwik's custom serialization format, not standard JSON. This
+ * means the data supports features like circular references, Dates, and other non-JSON types, but
+ * it cannot be consumed by external clients expecting plain JSON.
+ *
+ * ## Options
+ *
+ * - `search: string[]`: Allowlist of URL search params the loader depends on. Only listed params are
+ *   sent in the request and changes to other params are ignored. During SSR and loader JSON
+ *   requests, the loader's request event is filtered to those params too. `search: []` means no
+ *   search params are sent and only route path changes trigger a re-fetch.
+ * - `allowStale: false`: Clears the previous value when re-fetching, so components see a loading
+ *   state instead of stale data during navigation. Useful when old data would be confusing.
+ * - `eTag`: Enable ETag-based caching. Can be `true` (auto-hash), a string, or a function.
+ * - `expires` / `poll`: Control client-side caching and polling behavior.
+ *
+ * The `strictLoaders` Vite plugin option applies `search: []` globally for all loaders that don't
+ * specify an explicit `search` option.
+ *
+ * @public
+ */
 export declare const routeLoader$: LoaderConstructor;
 
+/**
+ * Reactive context for route loaders. On the server this is stored in sharedMap, on the client it's
+ * a store that gets updated on navigation.
+ *
+ * - `loaderPaths`: loader ID → fetch path (the longest route path for that loader)
+ * - `pagePathname` / `pageSearch`: client-only navigation state used for loader invalidation and
+ *   q-loader fetches. They are intentionally omitted from SSR state and fall back to `location`
+ *   until the first SPA navigation.
+ */
+declare type RouteLoaderCtx = {
+    loaderPaths: Record<string, string | undefined>;
+    pagePathname?: string;
+    pageSearch?: string;
+    /** SPA navigation function. Client-only and intentionally omitted from SSR state. */
+    goto?: NoSerialize<RouteNavigate>;
+};
+
 /* Excluded from this release type: routeLoaderQrl */
 
 /** @public */
@@ -911,6 +1077,7 @@ declare interface ServerConfig {
 export declare type ServerData = {
     url: string;
     requestHeaders: Record<string, string>;
+    renderMode: 'static' | 'server';
     locale: string | undefined;
     nonce: string | undefined;
     containerAttributes: Record<string, string> & {