@qwik.dev/router 2.0.0-beta.28 → 2.0.0-beta.29

package/lib/index.d.ts

@@ -1,13 +1,13 @@
 /// <reference path="./modules.d.ts" />
 
-import type { AsyncSignal } from '@qwik.dev/core/internal';
+import type { AsyncSignal } from '@qwik.dev/core';
 import { Component } from '@qwik.dev/core';
 import { Cookie } from '@qwik.dev/router/middleware/request-handler';
 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 { JSXOutput as JSXOutput_2 } from '@qwik.dev/core';
+import { JSXOutput } from '@qwik.dev/core';
 import { QRL } from '@qwik.dev/core';
 import { QRLEventHandlerMulti } from '@qwik.dev/core';
 import { QwikIntrinsicElements } from '@qwik.dev/core';
@@ -161,6 +161,17 @@ 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.
+ *
+ * - `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
+ */
+export declare type CacheKeyFn = true | ((status: number, eTag: string, pathname: string) => string | null);
+
 /** @public */
 export declare interface ContentHeading {
     readonly text: string;
@@ -177,9 +188,17 @@ export declare interface ContentMenu {
 
 declare type ContentModule = PageModule | LayoutModule;
 
-declare type ContentModuleHead = DocumentHead | ResolvedDocumentHead;
+/**
+ * The eTag export type: a static string or a function receiving DocumentHeadProps.
+ *
+ * @public
+ */
+export declare type ContentModuleETag = string | ((props: DocumentHeadProps) => string | null);
+
+/** @public */
+export declare type ContentModuleHead = DocumentHead | ResolvedDocumentHead;
 
-declare type ContentModuleLoader = () => Promise<ContentModule>;
+declare type ContentModuleLoader = () => ValueOrPromise<ContentModule>;
 
 /** @public */
 declare interface ContentState {
@@ -221,7 +240,7 @@ export { CookieValue }
  * @public
  */
 export declare const createRenderer: (getOptions: (options: RendererOptions) => {
-    jsx: JSXOutput_2;
+    jsx: JSXOutput;
     options: RendererOutputOptions;
 }) => Render;
 
@@ -232,20 +251,14 @@ export declare type DataValidator<T extends Record<string, any> = {}> = {
 
 export { DeferReturn }
 
-/** @public */
-declare interface DevJSX {
-    fileName: string;
-    lineNumber: number;
-    columnNumber: number;
-    stack?: string;
-}
-
 /** @public */
 export declare type DocumentHead = DocumentHeadValue | ((props: DocumentHeadProps) => DocumentHeadValue);
 
 /** @public */
 export 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;
@@ -339,10 +352,11 @@ export declare type DocumentStyle = Readonly<((Omit<QwikIntrinsicElements['style
     style?: never;
 })>;
 
-declare type EndpointModuleLoader = () => Promise<RouteModule>;
+declare type EndpointModuleLoader = () => ValueOrPromise<RouteModule>;
 
 declare interface EndpointResponse {
     status: number;
+    statusMessage?: string;
     loaders: Record<string, unknown>;
     loadersSerializationStrategy: Map<string, SerializationStrategy>;
     formData?: FormData;
@@ -368,7 +382,7 @@ export declare type FailOfRest<REST extends readonly DataValidator[]> = REST ext
 export declare type FailReturn<T> = T & Failed;
 
 /** @public */
-export declare const Form: <O, I>({ action, spaReset, reloadDocument, onSubmit$, ...rest }: FormProps<O, I>, key: string | null) => JSXOutput_2;
+export declare const Form: <O, I>({ action, spaReset, reloadDocument, onSubmit$, ...rest }: FormProps<O, I>, key: string | null) => JSXOutput;
 
 /** @public */
 export declare interface FormProps<O, I> extends Omit<QwikJSX.IntrinsicElements['form'], 'action' | 'method'> {
@@ -399,17 +413,6 @@ export declare interface FormSubmitSuccessDetail<T> {
     value: T;
 }
 
-/**
- * Any function taking a props object that returns JSXOutput.
- *
- * The `key`, `flags` and `dev` parameters are for internal use.
- *
- * @public
- */
-declare type FunctionComponent<P = unknown> = {
-    renderFn(props: P, key: string | null, flags: number, dev?: DevJSX): JSXOutput;
-}['renderFn'];
-
 /** @public */
 export declare type GetValidatorInputType<VALIDATOR extends TypedDataValidator> = VALIDATOR extends ValibotDataValidator<infer TYPE> ? v.InferInput<TYPE> : VALIDATOR extends ZodDataValidator<infer TYPE> ? z_2.input<TYPE> : never;
 
@@ -424,6 +427,14 @@ export declare const globalAction$: ActionConstructor;
 
 /* Excluded from this release type: globalActionQrl */
 
+/** @public */
+export declare type HttpErrorProps = {
+    /** The HTTP status code, e.g. 404 */
+    status: number;
+    /** The error message, e.g. "Not Found" */
+    message: string;
+};
+
 declare type IsAny<Type> = 0 extends 1 & Type ? true : false;
 
 /** @public */
@@ -436,31 +447,9 @@ export declare type JSONValue = string | number | boolean | {
     [x: string]: JSONValue;
 } | Array<JSONValue>;
 
-/** @public */
-declare type JSXChildren = string | number | boolean | null | undefined | Function | RegExp | JSXChildren[] | Promise<JSXChildren> | Signal_2<JSXChildren> | JSXNode;
-
-/**
- * A JSX Node, an internal structure. You probably want to use `JSXOutput` instead.
- *
- * @public
- */
-declare interface JSXNode<T extends string | FunctionComponent | unknown = unknown> {
-    type: T;
-    props: T extends FunctionComponent<infer P> ? P : Record<any, unknown>;
-    children: JSXChildren | null;
-    key: string | null;
-    dev?: DevJSX;
-}
-
-/**
- * Any valid output for a component
- *
- * @public
- */
-declare type JSXOutput = JSXNode | string | number | boolean | null | undefined | JSXOutput[];
-
 declare interface LayoutModule extends RouteModule {
-    readonly default: unknown;
+    readonly default?: (props: Record<string, never>) => JSXOutput;
+    readonly routeConfig?: RouteConfig;
     readonly head?: ContentModuleHead;
 }
 
@@ -491,13 +480,23 @@ export declare interface LinkProps extends AnchorAttributes {
     scroll?: boolean;
 }
 
-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 */
 declare type Loader_2<RETURN> = {
@@ -531,9 +530,6 @@ declare type LoaderOptions = {
 /** @public */
 export declare type LoaderSignal<TYPE> = (TYPE extends () => ValueOrPromise<infer VALIDATOR> ? Signal<ValueOrPromise<VALIDATOR>> : Signal<TYPE>) & Pick<AsyncSignal, 'promise' | 'loading' | 'error'>;
 
-/** @public */
-export declare type MenuData = [pathname: string, menuLoader: MenuModuleLoader];
-
 declare interface MenuModule {
     readonly default: ContentMenu;
 }
@@ -555,12 +551,15 @@ export { NavigationType_2 as NavigationType }
 export declare function omitProps<T, KEYS extends keyof T>(obj: T, keys: KEYS[]): Omit<T, KEYS>;
 
 /** @public */
-export declare interface PageModule extends RouteModule {
-    readonly default: unknown;
+export 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 */
 export declare type PathParams = Record<string, string>;
@@ -620,12 +619,13 @@ export declare const QwikCityProvider: Component<QwikRouterProps>;
 
 /** @public */
 export declare interface QwikRouterConfig {
-    readonly routes: RouteData[];
+    readonly routes: RouteData;
     readonly serverPlugins?: RouteModule[];
     readonly basePathname?: string;
-    readonly menus?: MenuData[];
     readonly trailingSlash?: boolean;
     readonly cacheModules?: boolean;
+    /** When true, return null instead of rendering the 404 page, letting the adapter handle it */
+    readonly fallthrough?: boolean;
 }
 
 /** @public */
@@ -634,7 +634,7 @@ export declare interface QwikRouterEnvData {
     ev: RequestEvent;
     params: PathParams;
     response: EndpointResponse;
-    loadedRoute: LoadedRoute | null;
+    loadedRoute: LoadedRoute;
 }
 
 /** @public */
@@ -752,18 +752,73 @@ declare type RouteActionResolver = {
     result: unknown;
 };
 
-/** @public */
-export declare type RouteData = [
-routeName: string,
-moduleLoaders: ModuleLoader[]
-] | [
-routeName: string,
-moduleLoaders: ModuleLoader[],
-/** The actual src/routes pathname, not rewritten */
-originalPathname: string,
-/** The bundles that contain the loaders */
-routeBundleNames: 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
+ */
+export declare type RouteConfig = RouteConfigValue | ((props: DocumentHeadProps) => RouteConfigValue);
+
+/**
+ * The value shape returned by a routeConfig export (object form or function return).
+ *
+ * @public
+ */
+export declare interface RouteConfigValue {
+    readonly head?: DocumentHeadValue;
+    readonly eTag?: ContentModuleETag;
+    readonly cacheKey?: CacheKeyFn;
+}
+
+/**
+ * A nested route trie structure. The root represents `/` and each level represents a URL segment.
+ *
+ * Keys starting with `_` are metadata; all other keys are child route segments.
+ *
+ * - Use `_W` as the key for a single dynamic segment (param); `_P` on that node names the param.
+ * - Use `_A` as the key for a rest/catch-all segment; `_P` on that node names the param.
+ * - For infix params like `pre[slug]post`, use `_W` with `_0` (prefix) and `_9` (suffix).
+ * - Use `_M` for an array of group (pathless layout) nodes, sorted by group name.
+ *
+ * When matching, exact segments are tried first (case-insensitive), then `_W` (with optional
+ * prefix/suffix), then `_A`. When no route matches, the closest `_E` (error.tsx) or `_4` (404.tsx)
+ * loader in the ancestor chain is used to render the error page.
+ *
+ * @public
+ */
+export declare interface RouteData {
+    /** This node's layout loader (single). Runtime accumulates these during trie traversal. */
+    _L?: ContentModuleLoader;
+    /**
+     * This node's index/page loader. Single = normal (runtime prepends gathered _L). Array = override
+     * (layout stop / named layout — IS the complete chain).
+     */
+    _I?: ContentModuleLoader | ModuleLoader[];
+    /** Rewrite/goto target path. Matcher re-walks trie from root using this path's keys. */
+    _G?: string;
+    /** The JS bundle names for this route (SSR only) */
+    _B?: string[];
+    /** The not-found (404) module loader for this subtree */
+    _4?: ContentModuleLoader;
+    /** The error page module loader for this subtree (error.tsx, takes precedence over _4) */
+    _E?: ContentModuleLoader;
+    /** The parameter name when this node is reached via `_W` or `_A` from the parent */
+    _P?: string;
+    /** Prefix for infix params (e.g. "pre" for `pre[slug]post`) — only on `_W` nodes */
+    _0?: string;
+    /** Suffix for infix params (e.g. "post" for `pre[slug]post`) — only on `_W` nodes */
+    _9?: string;
+    /** Group (pathless layout) nodes merged into this level, sorted by group name */
+    _M?: RouteData[];
+    /** Menu loader for this subtree (from menu.md). Runtime uses nearest ancestor during traversal. */
+    _N?: MenuModuleLoader;
+    /** Child route segments (any key not starting with `_`) */
+    [part: string]: RouteData | RouteData[] | ModuleLoader[] | ContentModuleLoader | MenuModuleLoader | string[] | string | undefined;
+}
 
 /** @public */
 export declare const routeLoader$: LoaderConstructor;
@@ -856,30 +911,6 @@ export declare const ServiceWorkerRegister: (props: {
     nonce?: string;
 }) => JSXOutput;
 
-/**
- * A signal is a reactive value which can be read and written. When the signal is written, all tasks
- * which are tracking the signal will be re-run and all components that read the signal will be
- * re-rendered.
- *
- * Furthermore, when a signal value is passed as a prop to a component, the optimizer will
- * automatically forward the signal. This means that `return <div title={signal.value}>hi</div>`
- * will update the `title` attribute when the signal changes without having to re-render the
- * component.
- *
- * @public
- */
-declare interface Signal_2<T = any> {
-    /** Reading from this subscribes to updates; writing to this triggers updates. */
-    value: T;
-    /** Reading from this does not subscribe to updates; writing to this does not trigger updates. */
-    untrackedValue: T;
-    /**
-     * Use this to trigger running subscribers, for example when the value mutated but remained the
-     * same object.
-     */
-    trigger(): void;
-}
-
 /** @public */
 export declare interface StaticGenerate {
     params?: PathParams[];
@@ -916,6 +947,9 @@ export declare const useContent: () => ContentState;
  */
 export declare const useDocumentHead: <FrontMatter extends Record<string, unknown> = Record<string, any>>() => Required<ResolvedDocumentHead<FrontMatter>>;
 
+/** @public */
+export declare const useHttpStatus: () => HttpErrorProps;
+
 /** @public */
 export declare const useLocation: () => RouteLocation;