@qwik.dev/router 2.0.0-beta.4 → 2.0.0-beta.40

package/lib/middleware/request-handler/index.d.ts

@@ -1,25 +1,26 @@
 import type { Action } from '@qwik.dev/router';
-import type { _deserialize } from '@qwik.dev/core/internal';
+import type { AsyncLocalStorage } from 'node:async_hooks';
 import type { EnvGetter as EnvGetter_2 } from '@qwik.dev/router/middleware/request-handler';
 import type { FailReturn } from '@qwik.dev/router';
+import type { JSXOutput } from '@qwik.dev/core';
 import type { Loader as Loader_2 } from '@qwik.dev/router';
-import type { QwikCityPlan } from '@qwik.dev/router';
 import type { QwikIntrinsicElements } from '@qwik.dev/core';
-import type { QwikRouterConfig } from '@qwik.dev/router';
 import type { Render } from '@qwik.dev/core/server';
 import type { RenderOptions } from '@qwik.dev/core/server';
 import { RequestEvent as RequestEvent_2 } from '@qwik.dev/router/middleware/request-handler';
 import type { RequestHandler as RequestHandler_2 } from '@qwik.dev/router/middleware/request-handler';
 import type { ResolveSyncValue as ResolveSyncValue_2 } from '@qwik.dev/router/middleware/request-handler';
-import type { SerializationStrategy } from '@qwik.dev/core/internal';
-import type { _serialize } from '@qwik.dev/core/internal';
 import type { ValueOrPromise } from '@qwik.dev/core';
-import type { _verifySerializable } from '@qwik.dev/core/internal';
 
 /** @public */
 export declare class AbortMessage {
+    /** Type-only brand so `Exclude<>` can drop control-flow signals from resolved loader/action data. */
+    readonly __controlFlow: true;
 }
 
+/** @internal */
+export declare let _asyncRequestStore: AsyncLocalStorage<RequestEventInternal> | undefined;
+
 /** @public */
 export declare type CacheControl = CacheControlOptions | number | 'day' | 'week' | 'month' | 'year' | 'no-cache' | 'immutable' | 'private';
 
@@ -91,6 +92,47 @@ declare interface CacheControlOptions {
 /** @public */
 declare type CacheControlTarget = 'Cache-Control' | 'CDN-Cache-Control' | 'Cloudflare-CDN-Cache-Control' | 'Vercel-CDN-Cache-Control' | '~ANY-OTHER-STRING' | (string & {});
 
+/**
+ * Cache key function. Used by `routeConfig.cacheKey` (SSR HTML cache) and by `routeLoader$`'s
+ * `cacheKey` option (per-loader JSON 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
+ */
+declare type CacheKeyFn = true | ((requestEv: RequestEvent_2, eTag: string) => string | null);
+
+/**
+ * Clear the in-memory loader cache. Call after deployments or data changes.
+ *
+ * When `cacheKey` is provided, only that single entry is removed; otherwise the entire cache is
+ * cleared.
+ *
+ * @public
+ */
+export declare function clearLoaderCache(cacheKey?: string): void;
+
+/**
+ * Clear the in-memory SSR cache. Call after deployments or data changes.
+ *
+ * When `cacheKey` is provided, only that single entry is removed; otherwise the entire cache is
+ * cleared.
+ *
+ * @public
+ */
+export declare function clearSsrCache(cacheKey?: string): void;
+
 /** @public */
 export declare interface ClientConn {
     ip?: string;
@@ -119,8 +161,29 @@ declare interface ContentMenu {
 
 declare type ContentModule = PageModule | LayoutModule;
 
+/**
+ * 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
+ */
+declare type ContentModuleETag = string | ((props: DocumentHeadProps) => string | null);
+
+/** @public */
 declare type ContentModuleHead = DocumentHead | ResolvedDocumentHead;
 
+declare type ContentModuleLoader = () => ValueOrPromise<ContentModule>;
+
 /** @public */
 export declare interface Cookie {
     /** Gets a `Request` cookie header value by name. */
@@ -207,6 +270,9 @@ declare type DocumentHead = DocumentHeadValue | ((props: DocumentHeadProps) => D
 /** @public */
 declare interface DocumentHeadProps extends RouteLocation {
     readonly head: ResolvedDocumentHead;
+    /** The HTTP status code of the response (e.g. 200, 404). */
+    readonly status: number;
+    /** @deprecated This is not necessary, it works correctly without */
     readonly withLocale: <T>(fn: () => T) => T;
     readonly resolveValue: ResolveSyncValue_2;
 }
@@ -215,10 +281,7 @@ declare interface DocumentHeadProps extends RouteLocation {
 declare interface DocumentHeadValue<FrontMatter extends Record<string, any> = Record<string, unknown>> {
     /** Sets `document.title`. */
     readonly title?: string;
-    /**
-     * Used to manually set meta tags in the head. Additionally, the `data` property could be used to
-     * set arbitrary data which the `<head>` component could later use to generate `<meta>` tags.
-     */
+    /** Used to manually set meta tags in the head. */
     readonly meta?: readonly DocumentMeta[];
     /** Used to manually append `<link>` elements to the `<head>`. */
     readonly links?: readonly DocumentLink[];
@@ -235,50 +298,50 @@ declare interface DocumentHeadValue<FrontMatter extends Record<string, any> = Re
 }
 
 /** @public */
-declare interface DocumentLink {
-    as?: string;
-    crossorigin?: string;
-    disabled?: boolean;
-    href?: string;
-    hreflang?: string;
-    id?: string;
-    imagesizes?: string;
-    imagesrcset?: string;
-    integrity?: string;
-    media?: string;
-    prefetch?: string;
-    referrerpolicy?: string;
-    rel?: string;
-    sizes?: string;
-    title?: string;
-    type?: string;
-    key?: string;
-}
+declare type DocumentLink = QwikIntrinsicElements['link'];
 
 /** @public */
-declare interface DocumentMeta {
-    readonly content?: string;
-    readonly httpEquiv?: string;
-    readonly name?: string;
-    readonly property?: string;
-    readonly key?: string;
-    readonly itemprop?: string;
-    readonly media?: string;
-}
+declare type DocumentMeta = QwikIntrinsicElements['meta'];
 
-/** @beta */
-declare interface DocumentScript {
-    readonly script?: string;
-    readonly props?: Readonly<QwikIntrinsicElements['script']>;
-    readonly key?: string;
-}
+/** @public */
+declare type DocumentScript = ((Omit<QwikIntrinsicElements['script'], 'dangerouslySetInnerHTML'> & {
+    props?: never;
+}) | {
+    key?: string;
+    /**
+     * The props of the script element. @deprecated Prefer setting the properties directly instead
+     * of using this property.
+     */
+    props: Readonly<QwikIntrinsicElements['script']>;
+}) & ({
+    /** The inline script content. */
+    script?: string;
+    dangerouslySetInnerHTML?: never;
+} | {
+    dangerouslySetInnerHTML?: string;
+    script?: never;
+});
 
 /** @public */
-declare interface DocumentStyle {
-    readonly style: string;
-    readonly props?: Readonly<QwikIntrinsicElements['style']>;
-    readonly key?: string;
-}
+declare type DocumentStyle = Readonly<((Omit<QwikIntrinsicElements['style'], 'dangerouslySetInnerHTML'> & {
+    props?: never;
+}) | {
+    key?: string;
+    /**
+     * The props of the style element. @deprecated Prefer setting the properties directly
+     * instead of using this property.
+     */
+    props: Readonly<QwikIntrinsicElements['style']>;
+}) & ({
+    /** The inline style content. */
+    style?: string;
+    dangerouslySetInnerHTML?: never;
+} | {
+    dangerouslySetInnerHTML?: string;
+    style?: never;
+})>;
+
+declare type EndpointModuleLoader = () => ValueOrPromise<RouteModule>;
 
 /** @public */
 export declare interface EnvGetter {
@@ -296,44 +359,73 @@ export declare function getErrorHtml(status: number, e: any): string;
  */
 declare type InformationalCode = 100 | 101 | 102 | 103;
 
+/**
+ * Internal JSON request kind handled by Qwik Router, or `false` for normal page requests.
+ *
+ * @public
+ */
+export declare type InternalRequest = false | 'loader' | 'action';
+
+/**
+ * Decide whether a given request path is a static path, for optimizing file access.
+ *
+ * @internal
+ */
+export declare function isStaticPath(method: string, url: URL): boolean;
+
 declare interface LayoutModule extends RouteModule {
-    readonly default: unknown;
+    readonly default?: (props: Record<string, never>) => JSXOutput;
+    readonly routeConfig?: RouteConfig;
     readonly head?: ContentModuleHead;
 }
 
-declare type LoadedRoute = [
-routeName: string,
-params: PathParams,
-mods: (RouteModule | ContentModule)[],
-menu: ContentMenu | undefined,
-routeBundleNames: string[] | undefined
-];
+/** The route to render */
+declare interface LoadedRoute {
+    /** The canonical path of the route, e.g. `/products/[id]` */
+    $routeName$: string;
+    /** The route parameters, e.g. `{ id: '123' }` */
+    $params$: PathParams;
+    /** The modules associated with this route (on 404, contains only the error component) */
+    $mods$: (RouteModule | ContentModule)[];
+    /** The menu associated with this route */
+    $menu$?: ContentMenu | undefined;
+    /** The bundle names for this route */
+    $routeBundleNames$?: string[] | undefined;
+    /** Whether this route is a not-found (404) route */
+    $notFound$?: boolean;
+    /** The nearest _E (error.tsx) boundary's chain to render on a thrown ServerError (in its layouts). */
+    $errorLoader$?: ModuleLoader[];
+    /** 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 */
 export declare const mergeHeadersCookies: (headers: Headers, cookies: Cookie) => Headers;
 
+declare type ModuleLoader = ContentModuleLoader | EndpointModuleLoader;
+
 /** @public */
-declare interface PageModule extends RouteModule {
-    readonly default: unknown;
+declare type PageModule = RouteModule & {
+    readonly default: (props: Record<string, never>) => JSXOutput;
+    readonly routeConfig?: RouteConfig;
     readonly head?: ContentModuleHead;
+    readonly eTag?: ContentModuleETag;
+    readonly cacheKey?: CacheKeyFn;
     readonly headings?: ContentHeading[];
     readonly onStaticGenerate?: StaticGenerateHandler;
-}
+};
 
 /** @public */
 declare type PathParams = Record<string, string>;
 
+declare type QwikRouterCompletion = Error | undefined | object;
+
 declare interface QwikRouterRun<T> {
     response: Promise<T | null>;
     requestEv: RequestEvent_2;
-    completion: Promise<unknown>;
-}
-
-/** @public */
-declare interface QwikSerializer {
-    _deserialize: typeof _deserialize;
-    _serialize: typeof _serialize;
-    _verifySerializable: typeof _verifySerializable;
+    completion: Promise<QwikRouterCompletion>;
 }
 
 /**
@@ -412,6 +504,14 @@ export declare interface RequestEventBase<PLATFORM = QwikRouterPlatform> {
     readonly query: URLSearchParams;
     /** HTTP request URL. */
     readonly url: URL;
+    /**
+     * Identifies Qwik Router internal JSON requests, such as route loader fetches and fetch-based
+     * action submissions. Returns `false` for normal page requests.
+     *
+     * Check this before applying broad rewrite rules so internal JSON requests keep their routing
+     * behavior.
+     */
+    readonly internalRequest: InternalRequest;
     /**
      * The original HTTP request URL.
      *
@@ -529,13 +629,9 @@ export declare interface RequestEventCommon<PLATFORM = QwikRouterPlatform> exten
     readonly exit: () => AbortMessage;
 }
 
-declare interface RequestEventInternal extends RequestEvent, RequestEventLoader {
-    [RequestEvLoaders]: Record<string, ValueOrPromise<unknown> | undefined>;
-    [RequestEvLoaderSerializationStrategyMap]: Map<string, SerializationStrategy>;
-    [RequestEvMode]: ServerRequestMode;
-    [RequestEvTrailingSlash]: boolean;
-    [RequestEvRoute]: LoadedRoute | null;
-    [RequestEvQwikSerializer]: QwikSerializer;
+declare interface RequestEventInternal extends Readonly<RequestEvent>, Readonly<RequestEventLoader> {
+    readonly [RequestEvMode]: ServerRequestMode;
+    readonly [RequestEvRoute]: LoadedRoute;
     /**
      * Check if this request is already written to.
      *
@@ -558,44 +654,36 @@ export declare interface RequestEventLoader<PLATFORM = QwikRouterPlatform> exten
     defer: <T>(returnData: Promise<T> | (() => Promise<T>)) => DeferReturn<T>;
 }
 
-declare const RequestEvLoaders: unique symbol;
-
-declare const RequestEvLoaderSerializationStrategyMap: unique symbol;
-
 declare const RequestEvMode: unique symbol;
 
-declare const RequestEvQwikSerializer: unique symbol;
-
 declare const RequestEvRoute: unique symbol;
 
-/** @internal */
-export declare const RequestEvShareQData = "qData";
-
-declare const RequestEvTrailingSlash: unique symbol;
-
 /** @public */
-export declare type RequestHandler<PLATFORM = QwikRouterPlatform> = (ev: RequestEvent<PLATFORM>) => Promise<void> | void;
+export declare type RequestHandler<PLATFORM = QwikRouterPlatform> = (ev: RequestEvent<PLATFORM>) => Promise<void | AbortMessage | ServerError> | void | AbortMessage | ServerError;
 
 /**
- * The request handler for QwikRouter. Called by every integration.
+ * The request handler for QwikRouter. Called by every adapter.
  *
  * @public
  */
-export declare function requestHandler<T = unknown>(serverRequestEv: ServerRequestEvent<T>, opts: ServerRenderOptions, qwikSerializer: QwikSerializer): Promise<QwikRouterRun<T> | null>;
+export declare function requestHandler<T = unknown>(serverRequestEv: ServerRequestEvent<T>, opts: ServerRenderOptions): Promise<QwikRouterRun<T> | null>;
 
 /** @public */
-declare type ResolvedDocumentHead<FrontMatter extends Record<string, any> = Record<string, unknown>> = Required<DocumentHeadValue<FrontMatter>>;
+declare type ResolvedDocumentHead<FrontMatter extends Record<string, any> = Record<string, unknown>> = Required<DocumentHeadValue<FrontMatter>> & {
+    /** The build's manifest hash, used for per-loader data URLs. Always defined (`'dev'` in dev). */
+    readonly manifestHash: string;
+};
 
 /** @public */
 export declare interface ResolveSyncValue {
+    <T, INPUT, OPTIONAL extends boolean>(action: Action<T, INPUT, OPTIONAL>): Awaited<T> | undefined;
     <T>(loader: Loader_2<T>): Awaited<T> extends () => any ? never : Awaited<T>;
-    <T>(action: Action<T>): Awaited<T> | undefined;
 }
 
 /** @public */
 export declare interface ResolveValue {
+    <T, INPUT, OPTIONAL extends boolean>(action: Action<T, INPUT, OPTIONAL>): Promise<T | undefined>;
     <T>(loader: Loader_2<T>): Awaited<T> extends () => any ? never : Promise<T>;
-    <T>(action: Action<T>): Promise<T | undefined>;
 }
 
 /** @public */
@@ -604,6 +692,28 @@ export declare class RewriteMessage extends AbortMessage {
     constructor(pathname: string);
 }
 
+/**
+ * Unified route configuration export. Groups head, eTag, and cacheKey with the same resolution
+ * rules as DocumentHead: can be a static object or a function receiving DocumentHeadProps.
+ *
+ * When a module exports `routeConfig`, the separate `head`, `eTag`, and `cacheKey` exports are
+ * ignored for that module.
+ *
+ * @public
+ */
+declare type RouteConfig = RouteConfigValue | ((props: DocumentHeadProps) => RouteConfigValue);
+
+/**
+ * The value shape returned by a routeConfig export (object form or function return).
+ *
+ * @public
+ */
+declare interface RouteConfigValue {
+    readonly head?: DocumentHeadValue;
+    readonly eTag?: ContentModuleETag;
+    readonly cacheKey?: CacheKeyFn;
+}
+
 /** @public */
 declare interface RouteLocation {
     readonly params: Readonly<Record<string, string>>;
@@ -645,20 +755,17 @@ declare type ServerErrorCode = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 5
 /** @public */
 export declare interface ServerRenderOptions extends RenderOptions {
     render: Render;
-    /** @deprecated Use `QwikRouterConfig` instead. Will be removed in V3 */
-    qwikCityPlan?: QwikCityPlan;
-    qwikRouterConfig?: QwikRouterConfig;
     /**
      * Protection against cross-site request forgery (CSRF) attacks.
      *
      * When `true`, for every incoming POST, PUT, PATCH, or DELETE form submissions, the request
-     * origin is checked to match the server's origin.
+     * origin is checked to match the server's origin. `lax-proto` is for SSL-terminating proxies
      *
      * Be careful when disabling this option as it may lead to CSRF attacks.
      *
      * Defaults to `true`.
      */
-    checkOrigin?: boolean;
+    checkOrigin?: boolean | 'lax-proto';
 }
 
 /**
@@ -677,10 +784,10 @@ export declare interface ServerRequestEvent<T = unknown> {
 }
 
 /** @public */
-export declare type ServerRequestMode = 'dev' | 'static' | 'server';
+export declare type ServerRequestMode = 'static' | 'server';
 
 /** @public */
-export declare type ServerResponseHandler<T = any> = (status: number, headers: Headers, cookies: Cookie, resolve: (response: T) => void, requestEv: RequestEventInternal) => WritableStream<Uint8Array>;
+export declare type ServerResponseHandler<T = any> = (status: number, headers: Headers, cookies: Cookie, resolve: (response: T) => void, requestEv: RequestEvent) => WritableStream<Uint8Array>;
 
 /** @public */
 declare interface StaticGenerate {