@qwik.dev/router 2.0.0-beta.3 → 2.0.0-beta.30

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

@@ -1,7 +1,8 @@
 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';
@@ -11,14 +12,16 @@ 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 { _serialize } from '@qwik.dev/core/internal';
+import { SerializationStrategy } 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 {
 }
 
+/** @internal */
+export declare let _asyncRequestStore: AsyncLocalStorage<RequestEventInternal> | undefined;
+
 /** @public */
 export declare type CacheControl = CacheControlOptions | number | 'day' | 'week' | 'month' | 'year' | 'no-cache' | 'immutable' | 'private';
 
@@ -90,6 +93,27 @@ declare interface CacheControlOptions {
 /** @public */
 declare type CacheControlTarget = 'Cache-Control' | 'CDN-Cache-Control' | 'Cloudflare-CDN-Cache-Control' | 'Vercel-CDN-Cache-Control' | '~ANY-OTHER-STRING' | (string & {});
 
+/**
+ * The cacheKey export type. When exported from a page module alongside eTag, enables in-memory SSR
+ * caching.
+ *
+ * - `true`: use the default cache key `status|eTag|pathname`
+ * - Function: receives status, eTag, and pathname; returns a cache key string or null (no cache)
+ *
+ * @public
+ */
+declare type CacheKeyFn = true | ((status: number, eTag: string, pathname: string) => string | null);
+
+/**
+ * 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;
@@ -118,8 +142,18 @@ declare interface ContentMenu {
 
 declare type ContentModule = PageModule | LayoutModule;
 
+/**
+ * The eTag export type: a static string or a function receiving DocumentHeadProps.
+ *
+ * @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. */
@@ -206,6 +240,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;
 }
@@ -214,10 +251,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[];
@@ -234,50 +268,48 @@ 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;
+})>;
 
 /** @public */
 export declare interface EnvGetter {
@@ -289,50 +321,73 @@ declare type ErrorCodes = ClientErrorCode | ServerErrorCode;
 /** @public */
 export declare function getErrorHtml(status: number, e: any): string;
 
+/**
+ * Return the HTML for a 404 page.
+ *
+ * @internal
+ */
+export declare function getNotFound(prefix: string): string;
+
 /**
  * HTTP Informational Status Codes Status codes in the 1xx range indicate that the server has
  * received and is processing the request, but no response is available yet.
  */
 declare type InformationalCode = 100 | 101 | 102 | 103;
 
+/**
+ * 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 error module loader (nearest _E ancestor), for rendering ServerErrors */
+    $errorLoader$?: ContentModuleLoader;
+}
 
 /** @public */
 export declare const mergeHeadersCookies: (headers: Headers, cookies: Cookie) => Headers;
 
 /** @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>;
 }
 
 /**
@@ -528,12 +583,11 @@ export declare interface RequestEventCommon<PLATFORM = QwikRouterPlatform> exten
     readonly exit: () => AbortMessage;
 }
 
-declare interface RequestEventInternal extends RequestEvent, RequestEventLoader {
-    [RequestEvLoaders]: Record<string, ValueOrPromise<unknown> | undefined>;
-    [RequestEvMode]: ServerRequestMode;
-    [RequestEvTrailingSlash]: boolean;
-    [RequestEvRoute]: LoadedRoute | null;
-    [RequestEvQwikSerializer]: QwikSerializer;
+declare interface RequestEventInternal extends Readonly<RequestEvent>, Readonly<RequestEventLoader> {
+    readonly [RequestEvLoaders]: Record<string, ValueOrPromise<unknown> | undefined>;
+    readonly [RequestEvLoaderSerializationStrategyMap]: Map<string, SerializationStrategy>;
+    readonly [RequestEvMode]: ServerRequestMode;
+    readonly [RequestEvRoute]: LoadedRoute;
     /**
      * Check if this request is already written to.
      *
@@ -558,37 +612,38 @@ export declare interface RequestEventLoader<PLATFORM = QwikRouterPlatform> exten
 
 declare const RequestEvLoaders: unique symbol;
 
-declare const RequestEvMode: unique symbol;
+declare const RequestEvLoaderSerializationStrategyMap: unique symbol;
 
-declare const RequestEvQwikSerializer: unique symbol;
+declare const RequestEvMode: unique symbol;
 
 declare const RequestEvRoute: unique symbol;
 
-declare const RequestEvTrailingSlash: unique symbol;
+/** @internal */
+export declare const RequestEvShareQData = "qData";
 
 /** @public */
 export declare type RequestHandler<PLATFORM = QwikRouterPlatform> = (ev: RequestEvent<PLATFORM>) => Promise<void> | void;
 
 /**
- * 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>>;
 
 /** @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 */
@@ -597,6 +652,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>>;
@@ -638,20 +715,21 @@ 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 */
+    /** @deprecated Not used */
     qwikCityPlan?: QwikCityPlan;
+    /** @deprecated Not used */
     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';
 }
 
 /**
@@ -670,10 +748,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 {