@blacklizard/inertia-express 2.0.0 → 3.0.0

package/dist/index-PWaujyMo.d.ts

@@ -0,0 +1,1133 @@
+//#region src/core/types.d.ts
+/**
+ * Inertia.js v3 protocol types.
+ *
+ * Reference: https://inertiajs.com/the-protocol
+ */
+/**
+ * Free-form bag of page props handed to the client component.
+ */
+type PageProps = Record<string, unknown>;
+/**
+ * The page object returned to the Inertia client (for `X-Inertia` requests)
+ * or embedded into the initial HTML response on first load.
+ */
+interface InertiaPage<TProps extends PageProps = PageProps> {
+  component: string;
+  props: TProps;
+  url: string;
+  version: string | null;
+  /**
+   * v3: instructs the client to clear browser history state on this visit.
+   */
+  clearHistory: boolean;
+  /**
+   * v3: instructs the client to encrypt history state for this page.
+   */
+  encryptHistory: boolean;
+  /**
+   * v3: instructs the client to preserve the URL fragment across this visit.
+   */
+  preserveFragment: boolean;
+  /**
+   * v3: top-level keys of props that came from shared props.
+   */
+  sharedProps?: string[];
+  /**
+   * v3: keys whose props should be merged (appended) on the client rather than replaced.
+   */
+  mergeProps?: string[];
+  /**
+   * v3: keys whose props should be prepended on the client rather than replaced.
+   */
+  prependProps?: string[];
+  /**
+   * v3: keys whose props should be *deep*-merged on the client (recursive merge
+   * rather than shallow append).
+   */
+  deepMergeProps?: string[];
+  /**
+   * v3: dotted `prop.field` paths telling the client which field to match on
+   * when merging arrays of objects (used to dedupe rather than blindly append).
+   */
+  matchPropsOn?: string[];
+  /**
+   * v3: keys whose props should be deferred and fetched in a follow-up partial reload.
+   *    Grouped by deferred-load group name.
+   */
+  deferredProps?: Record<string, string[]>;
+  /**
+   * v3: keys of props whose resolution failed and was rescued by the server.
+   */
+  rescuedProps?: string[];
+  /**
+   * v3: infinite-scroll pagination metadata, keyed by prop path.
+   */
+  scrollProps?: Record<string, ScrollMetadata & {
+    reset: boolean;
+  }>;
+  /**
+   * v3: once-prop metadata, keyed by once key.
+   */
+  onceProps?: Record<string, OnceMetadata>;
+  /**
+   * Read-once flash data, surfaced as a *top-level* page key (sibling to
+   * `props`) rather than a prop — mirroring inertia-laravel's
+   * `Response::resolveFlashData`. Omitted entirely when there is no flash.
+   */
+  flash?: unknown;
+}
+/**
+ * Globally shared props: either a static object merged into every page, or
+ * a (possibly async) function that returns one for the current request.
+ */
+type SharedPropsInput<TReq = unknown> = PageProps | ((req: TReq) => PageProps | Promise<PageProps>);
+/**
+ * Infinite-scroll pagination metadata for one scroll prop.
+ */
+interface ScrollMetadata {
+  pageName: string;
+  previousPage: number | string | null;
+  nextPage: number | string | null;
+  currentPage: number | string | null;
+}
+/**
+ * Metadata for one once-prop: the prop path it resolves and its expiry as a
+ * millisecond epoch timestamp, or `null` when it never expires.
+ */
+interface OnceMetadata {
+  prop: string;
+  expiresAt: number | null;
+}
+/**
+ * Page-level metadata produced while resolving props; every key is omitted
+ * when empty.
+ */
+interface PropsMetadata {
+  sharedProps?: string[];
+  mergeProps?: string[];
+  prependProps?: string[];
+  deepMergeProps?: string[];
+  matchPropsOn?: string[];
+  deferredProps?: Record<string, string[]>;
+  rescuedProps?: string[];
+  scrollProps?: Record<string, ScrollMetadata & {
+    reset: boolean;
+  }>;
+  onceProps?: Record<string, OnceMetadata>;
+}
+/**
+ * Callback invoked when a rescued prop throws during resolution. The hook's
+ * own failures are contained: a synchronous throw or a rejected returned
+ * promise is logged through the default reporter (`console.error`) and never
+ * propagates or surfaces as an unhandled rejection.
+ *
+ * @param error The thrown value.
+ * @param path Dotted path of the prop that failed.
+ */
+type RescueHandler = (error: unknown, path: string) => void;
+/**
+ * Per-response overrides for history-related page flags.
+ */
+interface RenderOptions {
+  /**
+   * Override `clearHistory` for this response.
+   */
+  clearHistory?: boolean;
+  /**
+   * Override `encryptHistory` for this response.
+   */
+  encryptHistory?: boolean;
+  /**
+   * Override `preserveFragment` for this response.
+   */
+  preserveFragment?: boolean;
+}
+/**
+ * Normalized view of an incoming HTTP request from the perspective of the
+ * Inertia v3 protocol. Produced by {@link parseInertiaRequest}.
+ */
+interface InertiaRequestInfo {
+  isInertia: boolean;
+  version: string | null;
+  partialComponent: string | null;
+  partialOnly: string[] | null;
+  partialExcept: string[] | null;
+  errorBag: string | null;
+  resetKeys: string[] | null;
+  /**
+   * Once-prop keys the client already holds (`X-Inertia-Except-Once-Props`);
+   * `[]` when the header is absent.
+   */
+  exceptOnceProps: string[];
+  /**
+   * Infinite-scroll merge direction (`X-Inertia-Infinite-Scroll-Merge-Intent`);
+   * `'prepend'` only on that exact value, otherwise `'append'`.
+   */
+  mergeIntent: 'append' | 'prepend';
+  method: string;
+  url: string;
+}
+/**
+ * Asset version source: a literal string, `null` (disables checks), or a
+ * (possibly async) function that derives a version per request.
+ */
+type VersionResolver<TReq = unknown> = string | null | (() => string | null | Promise<string | null>) | ((req: TReq) => string | null | Promise<string | null>);
+//#endregion
+//#region src/core/cache.d.ts
+/**
+ * Pluggable storage interface for the SSR view cache.
+ *
+ * Implementations live outside the core package — see
+ * `createMemoryCacheStore` in `@blacklizard/inertia-express` and
+ * `createRedisCacheStore` in `@blacklizard/inertia-cache-redis`.
+ *
+ * Values are arbitrary JSON — usually `SsrCacheEntry` (`{ head, body, ... }`).
+ * The store should not interpret them.
+ */
+interface SsrCacheStore {
+  get: (key: string) => Promise<SsrCacheEntry | null>;
+  set: (key: string, value: SsrCacheEntry, ttlSeconds: number) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+}
+/**
+ * What we actually store per cache hit. Includes everything needed to
+ * reconstruct the HTML response without re-running the SSR renderer.
+ */
+interface SsrCacheEntry {
+  head: string | string[];
+  body: string;
+  bodyIsFullRoot?: boolean;
+  /** ISO timestamp when this entry was stored. Useful for debugging. */
+  storedAt: string;
+  /**
+   * The page object the entry was rendered from, kept for inspection and
+   * invalidation tooling. A cache hit renders the page resolved for the
+   * current request, not this one, so per-request fields such as `url` and
+   * once-prop expiry stay current.
+   */
+  page: InertiaPage;
+}
+/**
+ * Stable JSON encoding: keys sorted recursively, undefined dropped, NaN/Inf
+ * normalized. Two equal-by-value objects always produce the same string,
+ * so they hash to the same cache key.
+ *
+ * @param value Arbitrary JSON-shaped input.
+ */
+declare function canonicalStringify(value: unknown): string;
+/**
+ * Inputs to {@link computeSsrCacheKey}.
+ */
+interface ComputeCacheKeyInput {
+  /** Cache namespace, e.g. `"inertia:ssr"`. */
+  prefix: string;
+  /** Asset version. Becomes part of the key so deploys auto-invalidate. */
+  version: string | null;
+  /** Component name being rendered. */
+  component: string;
+  /** Final, fully-resolved props (post shared-merge, post closure and descriptor resolution). */
+  props: PageProps;
+  /** Optional extra discriminator (locale, theme, A/B bucket, etc.). */
+  discriminator?: string;
+}
+/**
+ * Build the cache key for an SSR cache entry.
+ *
+ * Shape: `${prefix}:${version}:${component}:${sha256(props[+discriminator])}`
+ *
+ * Including `version` in the key namespace means a deploy that bumps the
+ * asset version atomically retires every old key — no flush, no race.
+ *
+ * @param input Prefix, version, component, resolved props, optional discriminator.
+ */
+declare function computeSsrCacheKey(input: ComputeCacheKeyInput): string;
+//#endregion
+//#region src/core/dot-props.d.ts
+/**
+ * Unpacks top-level dot-notation keys into nested objects, like `Arr::set`.
+ *
+ * Bare functions along the intermediate segments, and at the dotted key itself, are called and
+ * awaited first. Non-object segments are replaced by fresh objects. Prop descriptors are left as
+ * values for the resolver. The input and the nested objects it holds are never mutated.
+ *
+ * @param props Page props that may contain dotted keys.
+ */
+declare function unpackDotProps(props: PageProps): Promise<PageProps>;
+//#endregion
+//#region src/core/errors.d.ts
+/**
+ * Flat map of `field → first error message`, the shape the Inertia client
+ * expects under `props.errors`.
+ */
+type ValidationErrors = Record<string, string>;
+/**
+ * Apply error-bag scoping to a flat errors object, matching the official
+ * Inertia behavior. When `bag` is set, errors are namespaced under
+ * `props.errors[bag]`. When `bag` is null, errors live at `props.errors`.
+ *
+ * @param errors Flat field-to-message map.
+ * @param bag Optional error-bag name (e.g. `"createUser"`); null for top-level.
+ */
+declare function scopeErrors(errors: ValidationErrors, bag: string | null): PageProps;
+//#endregion
+//#region src/core/headers.d.ts
+/**
+ * Canonical Inertia v3 protocol header names.
+ *
+ * The Inertia client sends these headers on every visit. The server uses
+ * them to decide between a full HTML response and a JSON page response,
+ * and to scope partial reloads.
+ */
+declare const INERTIA_HEADERS: {
+  readonly inertia: "x-inertia";
+  readonly version: "x-inertia-version";
+  readonly partialComponent: "x-inertia-partial-component";
+  readonly partialData: "x-inertia-partial-data";
+  readonly partialExcept: "x-inertia-partial-except";
+  readonly errorBag: "x-inertia-error-bag";
+  readonly reset: "x-inertia-reset";
+  readonly location: "x-inertia-location";
+  readonly exceptOnceProps: "x-inertia-except-once-props";
+  readonly mergeIntent: "x-inertia-infinite-scroll-merge-intent";
+};
+type HeaderRecord = Record<string, string | string[] | undefined>;
+/**
+ * Parse a request's headers into a normalized {@link InertiaRequestInfo}.
+ *
+ * @param input Headers, HTTP method, and request URL. Method is uppercased in
+ *   the returned object; the URL is passed through unchanged.
+ */
+declare function parseInertiaRequest(input: {
+  headers: HeaderRecord;
+  method: string;
+  url: string;
+}): InertiaRequestInfo;
+//#endregion
+//#region src/core/html.d.ts
+/**
+ * Encode an Inertia page object for embedding inside a
+ * `<script type="application/json" data-page="...">` tag — the Inertia v3
+ * initial-page transport that the client reads via `getInitialPageFromDOM`.
+ *
+ * Every `<` is replaced with its JSON unicode escape so the payload cannot
+ * terminate the surrounding `</script>` element or open an HTML comment. The
+ * escape is transparent — JSON.parse decodes it back to `<`.
+ *
+ * @param page Resolved Inertia page object.
+ */
+declare function encodePageScript(page: InertiaPage): string;
+/**
+ * Inputs to {@link renderDefaultHtml}.
+ */
+interface DefaultRootViewInput {
+  page: InertiaPage;
+  /** Optional `<title>` for the document. */
+  title?: string;
+  /** Optional <head> content (meta tags, links, etc.). */
+  head?: string;
+  /** ID of the SPA root element. Defaults to `app`. */
+  rootId?: string;
+  /** Path to the client entry script, e.g. `/assets/app.js`. */
+  scriptSrc?: string;
+  /**
+   * Pre-rendered SSR HTML for the root element's *inner* content. When set,
+   * the inner HTML of the root div is replaced with this string so the
+   * client hydrates over server-rendered markup.
+   */
+  ssrBody?: string;
+  /**
+   * Pre-rendered SSR HTML representing the entire root element. When set,
+   * `ssrBody`, `rootId`, and the page `<script>` tag are ignored — the
+   * provided string is inserted into `<body>` as-is. Use this when your
+   * SSR renderer already returns the full root element + page script (the
+   * Inertia v3 SSR servers do).
+   */
+  ssrFull?: string;
+}
+/**
+ * Minimal default HTML shell for use when no custom root view is provided.
+ * Real apps should plug in a template engine (pug, ejs, react-dom/server,
+ * etc.) and embed `encodePageScript(page)` themselves.
+ *
+ * The initial page object is emitted as a
+ * `<script type="application/json" data-page="...">` tag, the Inertia v3
+ * transport that the client reads on boot.
+ *
+ * @param input Page object plus optional title/head/rootId/scriptSrc/SSR markup
+ *   — see {@link DefaultRootViewInput}.
+ */
+declare function renderDefaultHtml(input: DefaultRootViewInput): string;
+/**
+ * Inputs to {@link renderErrorPage}.
+ */
+interface ErrorPageInput {
+  /** HTTP status code to surface to the user. */
+  status: number;
+  /** Optional message; falls back to a default for the status, then a generic line. */
+  message?: string;
+}
+/**
+ * Render a minimal, SPA-less standalone HTML error page. Used as the hard
+ * fallback when no client `Error` component can be resolved (e.g. a plain
+ * browser load, or an SSR/render failure on the Inertia path), so a user
+ * never receives a raw JSON error or a blank page.
+ *
+ * @param input HTTP status plus an optional override message — see {@link ErrorPageInput}.
+ */
+declare function renderErrorPage(input: ErrorPageInput): string;
+//#endregion
+//#region src/core/page.d.ts
+/**
+ * Inputs to {@link createPage} — the fields of an {@link InertiaPage} plus
+ * optional history flags and the v3 prop metadata produced by the resolver.
+ */
+interface CreatePageInput<TProps extends PageProps = PageProps> {
+  component: string;
+  props: TProps;
+  url: string;
+  version: string | null;
+  clearHistory?: boolean;
+  encryptHistory?: boolean;
+  preserveFragment?: boolean;
+  metadata?: PropsMetadata;
+  flash?: unknown;
+}
+/**
+ * Build a normalized Inertia v3 page object. `clearHistory`, `encryptHistory`
+ * and `preserveFragment` default to `false` and are always present. Each
+ * `metadata` key is copied onto the page only when non-empty so the JSON over
+ * the wire stays compact. `flash` is emitted as a top-level key only when it
+ * carries data (non-nullish, and a non-empty object when object-valued) —
+ * mirroring inertia-laravel's `$flash ? ['flash' => $flash] : []`.
+ *
+ * @param input Required page fields plus the optional v3 extras.
+ */
+declare function createPage<TProps extends PageProps>(input: CreatePageInput<TProps>): InertiaPage<TProps>;
+//#endregion
+//#region src/core/partial-filter.d.ts
+/**
+ * `true` when `path` equals `parent` or lies in its dot-notation subtree.
+ *
+ * @param path Dot-notation prop path to test.
+ * @param parent Dot-notation path that may contain `path`.
+ */
+declare function pathIsSameOrDescendant(path: string, parent: string): boolean;
+/**
+ * `true` when `path` matches an `only` entry or is a descendant of one.
+ *
+ * @param path Dot-notation prop path to test.
+ * @param only Requested partial-reload `only` paths.
+ */
+declare function matchesOnly(path: string, only: string[]): boolean;
+/**
+ * `true` when `path` is a strict ancestor of an `only` entry.
+ *
+ * @param path Dot-notation prop path to test.
+ * @param only Requested partial-reload `only` paths.
+ */
+declare function leadsToOnly(path: string, only: string[]): boolean;
+/**
+ * `true` when `path` equals an `except` entry, is a descendant of one, or is
+ * an ancestor of one. Matching ancestors mirrors the reference Node server,
+ * whose flat filter drops a top-level key whenever any `except` entry lives
+ * under it; inertia-laravel keeps the ancestor and drops only the child.
+ *
+ * @param path Dot-notation prop path to test.
+ * @param except Requested partial-reload `except` paths.
+ */
+declare function matchesExcept(path: string, except: string[]): boolean;
+//#endregion
+//#region src/core/prop-descriptor.d.ts
+/**
+ * The constructor a {@link PropDescriptor} was created by.
+ */
+type PropKind = 'optional' | 'defer' | 'always' | 'merge' | 'once' | 'scroll';
+/**
+ * A prop's raw source: a plain value or a (possibly async) producer.
+ */
+type PropSource<T> = T | (() => T | Promise<T>);
+/**
+ * Options accepted by the `scroll()` prop constructor.
+ */
+interface ScrollOptions<T> {
+  /** Key inside the resolved value that holds the scrolled items. Defaults to `'data'`. */
+  wrapper?: string;
+  /** Pagination metadata, or a function deriving it from the resolved value. */
+  metadata: ScrollMetadata | ((resolved: T) => ScrollMetadata);
+}
+/**
+ * A prop wrapped with resolution and merge behaviour, ported from
+ * inertia-laravel's prop classes and their `MergesProps`, `DefersProps`
+ * and `ResolvesOnce` traits. The descriptor holds the wrapped value by
+ * reference and never mutates it.
+ */
+declare class PropDescriptor<T = unknown> {
+  readonly kind: PropKind;
+  readonly source: PropSource<T>;
+  ignoreFirstLoad: boolean;
+  defers: boolean;
+  group: string;
+  merges: boolean;
+  deep: boolean;
+  appends: boolean;
+  appendPaths: string[];
+  prependPaths: string[];
+  matchOnPaths: string[];
+  resolvesOnce: boolean;
+  onceKey: string | null;
+  ttlSeconds: number | null;
+  expiresAtDate: Date | null;
+  isFresh: boolean;
+  rescues: boolean;
+  isAlways: boolean;
+  isScroll: boolean;
+  wrapper: string;
+  scrollMetadata: ScrollMetadata | ((resolved: T) => ScrollMetadata) | null;
+  /**
+   * Create a descriptor around a prop source.
+   *
+   * @param kind The constructor that produced this descriptor.
+   * @param source The plain value or producer function being wrapped.
+   */
+  constructor(kind: PropKind, source: PropSource<T>);
+  /**
+   * `true` when the prop appends at its root: the append flag is set and no
+   * append/prepend paths were recorded.
+   */
+  get appendsAtRoot(): boolean;
+  /**
+   * `true` when the prop prepends at its root: the append flag is cleared and
+   * no append/prepend paths were recorded.
+   */
+  get prependsAtRoot(): boolean;
+  /**
+   * Mark the prop for a shallow client-side merge.
+   */
+  merge(): this;
+  /**
+   * Mark the prop for a deep client-side merge.
+   */
+  deepMerge(): this;
+  /**
+   * Configure appending. A boolean sets the root append flag; a string
+   * records an append path; a list records each path; a record maps each
+   * path to its match-on field.
+   *
+   * @param path Root flag, path, list of paths, or path-to-matchOn record.
+   * @param matchOn Field to dedupe on, recorded as `path.matchOn` when `path` is a string.
+   */
+  append(path?: boolean | string | string[] | Record<string, string>, matchOn?: string): this;
+  /**
+   * Configure prepending. A boolean clears (or sets) the root append flag; a
+   * string records a prepend path; a list records each path; a record maps
+   * each path to its match-on field.
+   *
+   * @param path Root flag, path, list of paths, or path-to-matchOn record.
+   * @param matchOn Field to dedupe on, recorded as `path.matchOn` when `path` is a string.
+   */
+  prepend(path?: boolean | string | string[] | Record<string, string>, matchOn?: string): this;
+  /**
+   * Replace the match-on paths the client dedupes merged items by.
+   *
+   * @param path A single path or a list of paths.
+   */
+  matchOn(path: string | string[]): this;
+  /**
+   * Defer the prop to a follow-up request.
+   *
+   * @param group Load group; props sharing a group are fetched together. Defaults to `'default'`.
+   */
+  defer(group?: string): this;
+  /**
+   * Toggle once-resolution, optionally setting its key and expiry.
+   *
+   * @param value Whether the prop resolves once. Defaults to `true`.
+   * @param as Custom once key.
+   * @param until TTL in seconds, or an absolute expiry date.
+   */
+  once(value?: boolean, as?: string, until?: number | Date): this;
+  /**
+   * Set the key the client caches a once-prop under.
+   *
+   * @param key The once key.
+   */
+  as(key: string): this;
+  /**
+   * Set the once-prop's expiry, replacing any expiry set by an earlier call.
+   *
+   * @param delay TTL in seconds, or an absolute expiry date.
+   */
+  until(delay: number | Date): this;
+  /**
+   * Force a once-prop to be re-resolved.
+   *
+   * @param value Whether to refresh. Defaults to `true`.
+   */
+  fresh(value?: boolean): this;
+  /**
+   * Opt into rescuing errors thrown while resolving the prop.
+   *
+   * @param value Whether to rescue. Defaults to `true`.
+   */
+  rescue(value?: boolean): this;
+  /**
+   * The once-prop's expiry as a millisecond epoch, or `null` without a TTL or date.
+   *
+   * @param now Current time in milliseconds. Defaults to `Date.now()`.
+   */
+  expiresAt(now?: number): number | null;
+  /**
+   * Resolve the source: call it when it is a function, then await the result.
+   */
+  resolveSource(): Promise<T>;
+  /**
+   * Scroll metadata for a resolved value: the configured object, or the
+   * configured function applied to `resolved`.
+   *
+   * @param resolved The resolved prop value.
+   */
+  metadataFor(resolved: T): ScrollMetadata;
+  /**
+   * `true` when no append or prepend paths were recorded.
+   */
+  private mergesAtRoot;
+  /**
+   * Record `path.matchOn` as a match-on path when `matchOn` is given.
+   *
+   * @param path The append/prepend path.
+   * @param matchOn Field to dedupe on.
+   */
+  private recordMatchOn;
+}
+//#endregion
+//#region src/core/props.d.ts
+/**
+ * Argument accepted by `append()` / `prepend()`: a root flag, a path, a list
+ * of paths, or a path-to-matchOn record.
+ */
+type MergePath = boolean | string | string[] | Record<string, string>;
+/**
+ * Prop omitted from the first load and resolved only when requested.
+ */
+interface OptionalProp<T> {
+  once: (value?: boolean, as?: string, until?: number | Date) => OptionalProp<T>;
+  as: (key: string) => OptionalProp<T>;
+  until: (delay: number | Date) => OptionalProp<T>;
+  fresh: (value?: boolean) => OptionalProp<T>;
+}
+/**
+ * Prop resolved in a follow-up request after the first load.
+ */
+interface DeferProp<T> {
+  merge: () => DeferProp<T>;
+  deepMerge: () => DeferProp<T>;
+  append: (path?: MergePath, matchOn?: string) => DeferProp<T>;
+  prepend: (path?: MergePath, matchOn?: string) => DeferProp<T>;
+  matchOn: (path: string | string[]) => DeferProp<T>;
+  once: (value?: boolean, as?: string, until?: number | Date) => DeferProp<T>;
+  as: (key: string) => DeferProp<T>;
+  until: (delay: number | Date) => DeferProp<T>;
+  fresh: (value?: boolean) => DeferProp<T>;
+  rescue: (value?: boolean) => DeferProp<T>;
+}
+/**
+ * Prop the client merges into its existing value.
+ */
+interface MergeProp<T> {
+  deepMerge: () => MergeProp<T>;
+  append: (path?: MergePath, matchOn?: string) => MergeProp<T>;
+  prepend: (path?: MergePath, matchOn?: string) => MergeProp<T>;
+  matchOn: (path: string | string[]) => MergeProp<T>;
+  once: (value?: boolean, as?: string, until?: number | Date) => MergeProp<T>;
+  as: (key: string) => MergeProp<T>;
+  until: (delay: number | Date) => MergeProp<T>;
+  fresh: (value?: boolean) => MergeProp<T>;
+}
+/**
+ * Prop included on every response, regardless of partial filtering. It has
+ * no chain methods.
+ */
+type AlwaysProp<T> = Pick<PropDescriptor<T>, never>;
+/**
+ * Prop the client resolves once and caches across visits.
+ */
+interface OnceProp<T> {
+  as: (key: string) => OnceProp<T>;
+  until: (delay: number | Date) => OnceProp<T>;
+  fresh: (value?: boolean) => OnceProp<T>;
+}
+/**
+ * Infinite-scroll prop carrying pagination metadata.
+ */
+interface ScrollProp<T> {
+  defer: (group?: string) => ScrollProp<T>;
+  matchOn: (path: string | string[]) => ScrollProp<T>;
+}
+/**
+ * An optional prop: omitted from the first load, resolved when requested.
+ *
+ * @param fn Producer called (and awaited) when the prop is requested.
+ */
+declare function optional<T>(fn: () => T | Promise<T>): OptionalProp<T>;
+/**
+ * A deferred prop: omitted from the first load and fetched by the client in
+ * a follow-up request with the rest of its group.
+ *
+ * @param fn Producer called (and awaited) on the follow-up request.
+ * @param group Load group; props sharing a group are fetched together.
+ */
+declare function defer<T>(fn: () => T | Promise<T>, group?: string): DeferProp<T>;
+/**
+ * An always prop: included on every response, even partial reloads that do
+ * not request it.
+ *
+ * @param value Plain value or producer.
+ */
+declare function always<T>(value: PropSource<T>): AlwaysProp<T>;
+/**
+ * A merge prop: the client appends it to its existing value at the root.
+ * Throws a `TypeError` when given a second argument (the 2.x `matchOn`
+ * form); chain `.matchOn()` instead.
+ *
+ * @param value Plain value or producer.
+ * @param extra Rejected; present only to catch the 2.x call form.
+ */
+declare function merge<T>(value: PropSource<T>, ...extra: never[]): MergeProp<T>;
+/**
+ * A deep-merge prop: the client recursively merges it into its existing value.
+ * Throws a `TypeError` when given a second argument (the 2.x `matchOn`
+ * form); chain `.matchOn()` instead.
+ *
+ * @param value Plain value or producer.
+ * @param extra Rejected; present only to catch the 2.x call form.
+ */
+declare function deepMerge<T>(value: PropSource<T>, ...extra: never[]): MergeProp<T>;
+/**
+ * A once prop: resolved once and cached by the client across visits.
+ *
+ * @param fn Producer called (and awaited) when the client lacks the value.
+ */
+declare function once<T>(fn: () => T | Promise<T>): OnceProp<T>;
+/**
+ * An infinite-scroll prop: merged at its wrapper key and carrying
+ * pagination metadata.
+ *
+ * @param fn Producer called (and awaited) for each page.
+ * @param options Wrapper key (default `'data'`) and pagination metadata.
+ */
+declare function scroll<T>(fn: () => T | Promise<T>, options: ScrollOptions<T>): ScrollProp<T>;
+/**
+ * Type guard: `true` when `value` is a {@link PropDescriptor}.
+ *
+ * @param value Value to test.
+ */
+declare function isPropDescriptor(value: unknown): value is PropDescriptor;
+//#endregion
+//#region src/core/props-resolver.d.ts
+/**
+ * Input to {@link resolveProps}.
+ */
+interface ResolvePropsInput {
+  /** Page props for the component being rendered. */
+  props: PageProps;
+  /** Already-evaluated shared props; page props win on key collision. */
+  shared: PageProps;
+  /** Component being rendered; a partial reload only applies when it matches. */
+  component: string;
+  /** Normalized Inertia request state. */
+  request: InertiaRequestInfo;
+  /** Hook called when a rescued prop throws. */
+  onRescue?: RescueHandler;
+}
+/**
+ * Output of {@link resolveProps}.
+ */
+interface ResolvePropsResult {
+  /** Fully resolved props tree. */
+  props: PageProps;
+  /** Page-level metadata; only non-empty keys are present. */
+  metadata: PropsMetadata;
+}
+/**
+ * Resolves shared and page props for one response, applying partial-reload
+ * filtering and initial-load exclusion and collecting page metadata. Port of
+ * inertia-laravel's `PropsResolver`. Use one instance per response: the
+ * instance accumulates metadata, so {@link PropsResolver.resolve} throws when
+ * called a second time. The resolver only reads descriptors, never writes
+ * them. Metadata maps keyed by user input (`deferredProps`, `scrollProps`,
+ * `onceProps`) have a null prototype, so any key, `__proto__` included, is
+ * stored as an own property.
+ */
+declare class PropsResolver {
+  private readonly request;
+  private readonly component;
+  private readonly onRescue;
+  private readonly isPartial;
+  private readonly isInertia;
+  private readonly only;
+  private readonly except;
+  private readonly sharedPropKeys;
+  private readonly mergeProps;
+  private readonly prependProps;
+  private readonly deepMergeProps;
+  private readonly matchPropsOn;
+  private readonly deferredProps;
+  private readonly rescuedProps;
+  private readonly scrollProps;
+  private readonly onceProps;
+  private used;
+  /**
+   * Create a resolver for one request and component.
+   *
+   * @param request Normalized Inertia request state.
+   * @param component Component being rendered.
+   * @param onRescue Hook called when a rescued prop throws.
+   */
+  constructor(request: InertiaRequestInfo, component: string, onRescue?: RescueHandler);
+  /**
+   * Resolve the given shared and page props, collecting their metadata.
+   *
+   * @param shared Already-evaluated shared props.
+   * @param props Page props; these win over shared props on collision.
+   */
+  resolve(shared: PageProps, props: PageProps): Promise<ResolvePropsResult>;
+  /**
+   * Record the top-level keys of shared props (the segment before the first
+   * `.` for dot-notation keys), deduplicated in first-seen order.
+   *
+   * @param shared Already-evaluated shared props.
+   */
+  private resolveSharedProps;
+  /**
+   * Build the non-empty metadata entries for the page response, in protocol order.
+   */
+  private buildMetadata;
+  /**
+   * Recursively resolve a props node, collecting metadata along the way.
+   * Every included entry that needs resolving is started in insertion order
+   * before any is awaited, so siblings resolve concurrently; each entry is
+   * then settled in insertion order (rescue, one-level unwrap, metadata,
+   * recursion), keeping output key order and metadata order deterministic.
+   * Plain values are copied synchronously, so a node without closures or
+   * descriptors comes back without a promise. Arrays come back as arrays
+   * with excluded entries dropped, so later index-based `except`/`reset`
+   * paths shift down; objects come back as fresh plain objects. When the
+   * original prop was not itself a plain object or array (e.g. a closure
+   * that returned one), its children bypass partial filtering.
+   *
+   * @param node Plain object or array to walk.
+   * @param prefix Dot path of `node`, or `''` at the root.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private walk;
+  /**
+   * Continue a walk asynchronously from the first entry whose outcome is pending.
+   *
+   * @param entries Started entries of the node.
+   * @param index Index of the pending entry.
+   * @param pending Outcome of the entry at `index`.
+   * @param result Node being built; written in place.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private finishWalk;
+  /**
+   * Run the synchronous pre-resolve checks (partial filter, initial-load
+   * exclusion) over a node's entries in insertion order and start resolving
+   * every included entry that needs it.
+   *
+   * @param node Plain object or array to walk.
+   * @param prefix Dot path of `node`, or `''` at the root.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private startEntries;
+  /**
+   * Classify one included entry: excluded from the initial load, pending
+   * resolution (started now), or a plain value copied as is.
+   *
+   * @param key Key of the entry in its parent node.
+   * @param path Dot path of the entry.
+   * @param prop The prop as found in its parent node.
+   */
+  private startEntry;
+  /**
+   * Finish one started entry in insertion order. Returns the value to write,
+   * {@link EXCLUDED}, or a promise of either when the entry needs awaiting.
+   *
+   * @param entry The started entry.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private settleEntry;
+  /**
+   * Await a started resolution, then apply rescue, the one-level descriptor
+   * unwrap (with its own initial-load exclusion) and inclusion.
+   *
+   * @param entry The started entry.
+   * @param pending The entry's resolution.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private settleResolved;
+  /**
+   * Include a resolved prop: check scroll shape, collect metadata, and walk
+   * into plain objects and arrays.
+   *
+   * @param prop The prop that produced `value`.
+   * @param value The prop's resolved value.
+   * @param path Dot path of the prop.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private include;
+  /**
+   * Determine if a prop belongs in the response: always on a full visit;
+   * on a partial reload, when it bypasses filtering or its path matches the request.
+   *
+   * @param prop The prop being considered.
+   * @param path Dot path of the prop.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private shouldIncludeInPartialResponse;
+  /**
+   * Determine if a prop is resolved independently of partial filters:
+   * always props, and children of already-resolved values.
+   *
+   * @param prop The prop being considered.
+   * @param parentWasResolved Whether an ancestor was produced by resolving a closure or descriptor.
+   */
+  private bypassesPartialFiltering;
+  /**
+   * Determine if the path matches the partial request using bidirectional
+   * prefix matching on both the only list and the except list.
+   *
+   * @param path Dot path of the prop.
+   */
+  private pathMatchesPartialRequest;
+  /**
+   * Determine if a prop is excluded from the initial page response: an
+   * optional or deferred descriptor, or a once-prop the client already holds.
+   *
+   * @param prop The prop being considered.
+   * @param path Dot path of the prop.
+   */
+  private isExcludedFromInitialResponse;
+  /**
+   * Collect the metadata of a prop excluded from the initial response
+   * according to why it was excluded.
+   *
+   * @param prop The descriptor being excluded.
+   * @param path Dot path of the prop.
+   */
+  private collectExclusionMetadata;
+  /**
+   * Collect the deferred, merge and once metadata of an excluded
+   * first-load-ignored prop (optional, defer).
+   *
+   * @param prop The descriptor being excluded.
+   * @param path Dot path of the prop.
+   */
+  private collectIgnoredPropMetadata;
+  /**
+   * Collect the deferred-group and merge metadata of an excluded deferred prop.
+   *
+   * @param prop The descriptor being excluded.
+   * @param path Dot path of the prop.
+   */
+  private collectDeferredExclusionMetadata;
+  /**
+   * Determine if a once-prop has already been loaded by the client: it
+   * resolves once, is not forced fresh, and its key (or path) is listed in
+   * the client's except-once header.
+   *
+   * @param prop The descriptor being considered.
+   * @param path Dot path of the prop.
+   */
+  private wasAlreadyLoadedByClient;
+  /**
+   * Resolve a single prop value: a descriptor resolves its source, a bare
+   * function is called, and the result is awaited; anything else passes
+   * through. An error thrown by a rescuable descriptor comes back wrapped in
+   * {@link Rescued}; any other error rejects.
+   *
+   * @param prop The prop to resolve.
+   */
+  private resolveValue;
+  /**
+   * Throw when a scroll prop did not resolve to a plain object holding its
+   * wrapper key as an own property.
+   *
+   * @param prop The prop being included.
+   * @param path Dot path of the prop.
+   * @param resolved The prop's resolved value.
+   */
+  private assertScrollShape;
+  /**
+   * Record a rescued prop: report the error, add its path to `rescuedProps`
+   * and omit it from the response.
+   *
+   * @param error The thrown value.
+   * @param path Dot path of the prop.
+   */
+  private rescue;
+  /**
+   * Call the rescue hook with the failure contained: a synchronous throw or
+   * a rejected returned thenable is logged through the default reporter and
+   * never propagates or surfaces as an unhandled rejection.
+   *
+   * @param error The thrown value.
+   * @param path Dot path of the prop.
+   */
+  private reportRescue;
+  /**
+   * Determine if the value is a prop type that needs further filtering or
+   * metadata collection.
+   *
+   * @param value The resolved value.
+   */
+  private isPropType;
+  /**
+   * Collect metadata for a prop that will be included in the response.
+   *
+   * @param prop The prop being included.
+   * @param path Dot path of the prop.
+   * @param resolved The prop's resolved value.
+   */
+  private collectMetadata;
+  /**
+   * Collect the deferred prop under its group.
+   *
+   * @param path Dot path of the prop.
+   * @param prop The deferred descriptor.
+   */
+  private collectDeferredPropMetadata;
+  /**
+   * Collect the merge strategy for a mergeable prop, unless the client asked
+   * to reset it or a partial request filters it out.
+   *
+   * @param path Dot path of the prop.
+   * @param prop The mergeable descriptor.
+   * @param excluded Whether the prop is being excluded from this response rather than resolved.
+   */
+  private collectMergeableMetadata;
+  /**
+   * The merge layout of a descriptor for this request, read without writing
+   * to the descriptor. A scroll descriptor derives its layout per request:
+   * a root append while it is excluded as deferred, otherwise its wrapper key
+   * appended or prepended according to the client's merge intent (the
+   * read-only equivalent of `ScrollProp::configureMergeIntent`).
+   *
+   * @param prop The mergeable descriptor.
+   * @param excluded Whether the prop is being excluded from this response rather than resolved.
+   */
+  private mergeLayoutFor;
+  /**
+   * Determine if the path should contribute metadata during a partial request.
+   *
+   * @param path Dot path of the prop.
+   */
+  private isIncludedInPartialMetadata;
+  /**
+   * Collect scroll pagination metadata, flagged for reset when the client
+   * asked to reset the prop.
+   *
+   * @param path Dot path of the prop.
+   * @param prop The scroll descriptor.
+   * @param resolved The prop's resolved value.
+   */
+  private collectScrollMetadata;
+  /**
+   * Collect once-prop metadata under its custom key (or path), unless a
+   * partial request filters it out.
+   *
+   * @param path Dot path of the prop.
+   * @param prop The once descriptor.
+   */
+  private collectOnceMetadata;
+}
+/**
+ * Resolve shared and page props for one response.
+ *
+ * @param input Props, shared props, component, request state and rescue hook.
+ */
+declare function resolveProps(input: ResolvePropsInput): Promise<ResolvePropsResult>;
+//#endregion
+//#region src/core/redirects.d.ts
+/**
+ * Status code Inertia uses for "soft" redirects after PUT/PATCH/DELETE so the
+ * follow-up GET is forced to also be a GET on every browser.
+ */
+declare const INERTIA_REDIRECT_STATUS = 303;
+/**
+ * Status code used for the `X-Inertia-Location` external redirect
+ * mechanism. The client intercepts the 409 and performs a window.location
+ * navigation rather than a fetch.
+ */
+declare const INERTIA_LOCATION_STATUS = 409;
+/**
+ * Decide which status code to use for a redirect produced by an Inertia
+ * request. After a non-GET/HEAD form submission the response must be 303
+ * so the client's follow-up request becomes a GET.
+ *
+ * @param method HTTP method of the inbound request (case-insensitive).
+ * @param fallback Status code to use for GET/HEAD/POST. Defaults to 302.
+ */
+declare function inertiaRedirectStatus(method: string, fallback?: number): number;
+//#endregion
+//#region src/core/render.d.ts
+/**
+ * Inputs to {@link buildPage}. `TReq` is the framework's request type so
+ * `shared` (when a function) receives the correct argument shape.
+ */
+interface BuildPageInput<TReq = unknown> {
+  component: string;
+  props: PageProps;
+  request: InertiaRequestInfo;
+  req: TReq;
+  shared: SharedPropsInput<TReq> | undefined;
+  version: string | null;
+  options?: RenderOptions;
+  /**
+   * Read-once flash data to emit as a top-level page key. Resolved by the
+   * caller (e.g. from the session); omitted from the page when nullish/empty.
+   */
+  flash?: unknown;
+  /**
+   * Called with the error and dotted path whenever a rescued prop throws.
+   */
+  onRescue?: RescueHandler;
+}
+/**
+ * Build the final {@link InertiaPage} object given a controller's component
+ * + props, the request info, and configured shared props / version.
+ *
+ * Returned page is suitable for either:
+ *   - JSON serialization on `X-Inertia` requests, or
+ *   - embedding into the root HTML view via a `<script>` page tag.
+ *
+ * @param input Component, props, parsed request, shared resolver, version,
+ *   optional `clearHistory` / `encryptHistory` / `preserveFragment` flags, and
+ *   an optional rescue handler.
+ */
+declare function buildPage<TReq>(input: BuildPageInput<TReq>): Promise<InertiaPage>;
+//#endregion
+//#region src/core/versioning.d.ts
+/**
+ * Resolve a version value (string, async function, or null) against a request.
+ *
+ * Returns `null` when no version is configured — in which case asset version
+ * mismatch detection is disabled.
+ *
+ * @param resolver Static version string, a (possibly async) function, or undefined.
+ * @param req Request passed to the resolver when it is a function.
+ */
+declare function resolveVersion<TReq>(resolver: VersionResolver<TReq> | undefined, req: TReq): Promise<string | null>;
+/**
+ * Returns true if the client's version (`X-Inertia-Version`) does not match
+ * the server's current version. Mismatches on GET requests should trigger a
+ * full reload via the `X-Inertia-Location` mechanism.
+ *
+ * @param serverVersion Currently configured server version; `null` disables checks.
+ * @param clientVersion Value of the `X-Inertia-Version` header; `null` is treated as empty.
+ */
+declare function isVersionMismatch(serverVersion: string | null, clientVersion: string | null): boolean;
+//#endregion
+export { OnceMetadata as $, leadsToOnly as A, renderErrorPage as B, once as C, PropKind as D, PropDescriptor as E, createPage as F, unpackDotProps as G, parseInertiaRequest as H, DefaultRootViewInput as I, SsrCacheStore as J, ComputeCacheKeyInput as K, ErrorPageInput as L, matchesOnly as M, pathIsSameOrDescendant as N, PropSource as O, CreatePageInput as P, InertiaRequestInfo as Q, encodePageScript as R, merge as S, scroll as T, ValidationErrors as U, INERTIA_HEADERS as V, scopeErrors as W, computeSsrCacheKey as X, canonicalStringify as Y, InertiaPage as Z, ScrollProp as _, INERTIA_LOCATION_STATUS as a, SharedPropsInput as at, defer as b, PropsResolver as c, resolveProps as d, PageProps as et, AlwaysProp as f, OptionalProp as g, OnceProp as h, buildPage as i, ScrollMetadata as it, matchesExcept as j, ScrollOptions as k, ResolvePropsInput as l, MergeProp as m, resolveVersion as n, RenderOptions as nt, INERTIA_REDIRECT_STATUS as o, VersionResolver as ot, DeferProp as p, SsrCacheEntry as q, BuildPageInput as r, RescueHandler as rt, inertiaRedirectStatus as s, isVersionMismatch as t, PropsMetadata as tt, ResolvePropsResult as u, always as v, optional as w, isPropDescriptor as x, deepMerge as y, renderDefaultHtml as z };
+//# sourceMappingURL=index-PWaujyMo.d.ts.map