@blacklizard/inertia-express 2.0.0 → 3.0.0

package/dist/core/index.d.ts

@@ -1,552 +1,2 @@
-//#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: 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 whose props should be merged (appended) on the client rather than replaced.
-   */
-  mergeProps?: 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[];
-  /**
-   * 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;
-}
-/**
- * A prop value that is evaluated lazily on every visit.
- */
-type LazyProp<T = unknown> = (() => T | Promise<T>) & {
-  __inertia_lazy: true;
-};
-/**
- * A prop value that is only sent on partial reloads when explicitly requested
- * (i.e. its key appears in `X-Inertia-Partial-Data`). On full visits the prop
- * is omitted entirely.
- */
-type OptionalProp<T = unknown> = (() => T | Promise<T>) & {
-  __inertia_optional: true;
-};
-/**
- * A prop that is omitted on the initial visit and instead loaded by an
- * automatic follow-up partial reload after the page mounts. Grouped by
- * `group` so several deferred props can be loaded in a single round-trip.
- */
-type DeferredProp<T = unknown> = (() => T | Promise<T>) & {
-  __inertia_deferred: true;
-  group: string;
-};
-/**
- * A prop that is always included in the response — on full visits and on
- * partial reloads — regardless of `X-Inertia-Partial-Data` /
- * `X-Inertia-Partial-Except` filtering.
- */
-type AlwaysProp<T = unknown> = (() => T | Promise<T>) & {
-  __inertia_always: true;
-};
-/**
- * A prop value the client should *append* to existing data rather than
- * replace (useful for paginated lists).
- */
-type MergeProp<T = unknown> = T & {
-  __inertia_merge: true;
-  __inertia_match_on?: string[];
-};
-/**
- * A prop value the client should recursively *deep*-merge into existing data
- * rather than shallow-append.
- */
-type DeepMergeProp<T = unknown> = T & {
-  __inertia_deep_merge: true;
-  __inertia_match_on?: string[];
-};
-/**
- * Any value accepted as a page prop: a plain JSON value, or one of the
- * wrapper types ({@link LazyProp}, {@link OptionalProp}, {@link DeferredProp},
- * {@link AlwaysProp}, {@link MergeProp}, {@link DeepMergeProp}). Structurally
- * this is `unknown` — the wrappers are documented here for discoverability.
- */
-type PropValue = 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>);
-/**
- * Per-response overrides for history-related page flags.
- */
-interface RenderOptions {
-  /**
-   * Override `clearHistory` for this response.
-   */
-  clearHistory?: boolean;
-  /**
-   * Override `encryptHistory` for this response.
-   */
-  encryptHistory?: 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;
-  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 corresponds to. Lets a custom rootView see
-   * the same structure on a cache hit as on a fresh render.
-   */
-  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-lazy evaluation). */
-  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/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";
-};
-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 v3 prop-key metadata.
- */
-interface CreatePageInput<TProps extends PageProps = PageProps> {
-  component: string;
-  props: TProps;
-  url: string;
-  version: string | null;
-  clearHistory?: boolean;
-  encryptHistory?: boolean;
-  deferredProps?: Record<string, string[]>;
-  mergeProps?: string[];
-  deepMergeProps?: string[];
-  matchPropsOn?: string[];
-  flash?: unknown;
-}
-/**
- * Build a normalized Inertia v3 page object. `clearHistory` and `encryptHistory`
- * default to `false`. Empty/absent `deferredProps` / `mergeProps` /
- * `deepMergeProps` / `matchPropsOn` are dropped 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/props.d.ts
-/**
- * Wrap a value-producing function as a "lazy" prop.
- *
- * Lazy props are evaluated on every visit (full or partial) when included.
- * They are NOT skipped on the initial visit — use {@link optional} for that.
- *
- * @param fn Producer called (and awaited) when the prop is included.
- */
-declare function lazy<T>(fn: () => T | Promise<T>): LazyProp<T>;
-/**
- * Wrap a value-producing function as an "optional" prop.
- *
- * Optional props are omitted from the initial response and only included
- * when explicitly requested via `X-Inertia-Partial-Data`.
- *
- * @param fn Producer called (and awaited) on partial reloads that request the key.
- */
-declare function optional<T>(fn: () => T | Promise<T>): OptionalProp<T>;
-/**
- * Wrap a value-producing function as a "deferred" prop.
- *
- * Deferred props are omitted from the initial visit. The client receives
- * the list of deferred prop keys (grouped by `group`) in the page object
- * and triggers an automatic partial reload to fetch them.
- *
- * @param fn Producer called (and awaited) on the deferred follow-up reload.
- * @param group Load-group name; keys in the same group are fetched in one round-trip.
- */
-declare function defer<T>(fn: () => T | Promise<T>, group?: string): DeferredProp<T>;
-/**
- * Wrap a value-producing function as an "always" prop.
- *
- * Always props are included on every response — full visits and partial
- * reloads alike — regardless of `X-Inertia-Partial-Data` /
- * `X-Inertia-Partial-Except` filtering.
- *
- * @param fn Producer called (and awaited) on every visit.
- */
-declare function always<T>(fn: () => T | Promise<T>): AlwaysProp<T>;
-/**
- * Mark a value as a "merge" prop. The Inertia client will append the new
- * value to the existing prop (typically used for paginated arrays).
- *
- * Pass `matchOn` (a field name or list of field names) to have the client
- * dedupe array items on that field instead of blindly appending.
- *
- * @param value Object or array to tag (mutated in place via non-enumerable properties).
- * @param matchOn Optional field name(s) to dedupe on.
- */
-declare function merge<T extends object>(value: T, matchOn?: string | string[]): MergeProp<T>;
-/**
- * Mark a value as a "deep merge" prop. The Inertia client recursively merges
- * the new value into the existing prop rather than shallow-appending.
- *
- * Pass `matchOn` (a field name or list of field names) to have the client
- * dedupe array items on that field.
- *
- * @param value Object or array to tag (mutated in place via non-enumerable properties).
- * @param matchOn Optional field name(s) to dedupe on.
- */
-declare function deepMerge<T extends object>(value: T, matchOn?: string | string[]): DeepMergeProp<T>;
-/**
- * Inputs to {@link resolveProps}.
- */
-interface ResolvePropsInput {
-  /** Props passed to `res.inertia(component, props)`. */
-  props: PageProps;
-  /** Globally shared props after evaluation. */
-  shared: PageProps;
-  /** The component name being rendered. */
-  component: string;
-  /** Parsed Inertia request info. */
-  request: InertiaRequestInfo;
-}
-/**
- * Result of {@link resolveProps}: the evaluated props plus the per-key
- * metadata the caller needs to populate the page object.
- */
-interface ResolvePropsResult {
-  props: PageProps;
-  /** Deferred prop key map by group, for the initial visit. */
-  deferred: Record<string, string[]>;
-  /** Shallow-merge prop key list. */
-  merge: string[];
-  /** Deep-merge prop key list. */
-  deepMerge: string[];
-  /** Dotted `prop.field` match-on paths for merge/deep-merge props. */
-  matchOn: string[];
-}
-/**
- * Combine shared + page props, then apply partial-reload filtering and
- * lazy/optional/deferred evaluation per the Inertia v3 protocol.
- *
- * Resolution order matches the official adapters:
- * 1. Merge shared and page props (page wins on collision).
- * 2. Determine if this is a partial reload for the same component.
- * 3. For non-partial visits: drop optional and deferred props; keep everything
- *    else (lazy props are evaluated).
- * 4. For partial visits: keep only keys in `partialOnly` (if set), then drop
- *    keys in `partialExcept`. Optional props are now eligible.
- * 5. Evaluate every remaining function-shaped prop
- *    (lazy/optional/deferred/always) by calling it and awaiting the result.
- *    Independent props are evaluated in parallel via `Promise.all`.
- * 6. Collect merge / deep-merge / match-on keys, excluding any key the client
- *    listed in `X-Inertia-Reset` — those props are reset (replaced) rather
- *    than appended.
- *
- * @param input Page + shared props, the component name, and parsed request info.
- */
-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;
-}
-/**
- * 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, and
- *   optional `clearHistory` / `encryptHistory` flags.
- */
-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 { type AlwaysProp, BuildPageInput, ComputeCacheKeyInput, CreatePageInput, type DeepMergeProp, DefaultRootViewInput, type DeferredProp, ErrorPageInput, INERTIA_HEADERS, INERTIA_LOCATION_STATUS, INERTIA_REDIRECT_STATUS, type InertiaPage, type InertiaRequestInfo, type LazyProp, type MergeProp, type OptionalProp, type PageProps, type PropValue, type RenderOptions, ResolvePropsInput, ResolvePropsResult, type SharedPropsInput, SsrCacheEntry, SsrCacheStore, ValidationErrors, type VersionResolver, always, buildPage, canonicalStringify, computeSsrCacheKey, createPage, deepMerge, defer, encodePageScript, inertiaRedirectStatus, isVersionMismatch, lazy, merge, optional, parseInertiaRequest, renderDefaultHtml, renderErrorPage, resolveProps, resolveVersion, scopeErrors };
-//# sourceMappingURL=index.d.ts.map
+import { $ as OnceMetadata, A as leadsToOnly, B as renderErrorPage, C as once, D as PropKind, E as PropDescriptor, F as createPage, G as unpackDotProps, H as parseInertiaRequest, I as DefaultRootViewInput, J as SsrCacheStore, K as ComputeCacheKeyInput, L as ErrorPageInput, M as matchesOnly, N as pathIsSameOrDescendant, O as PropSource, P as CreatePageInput, Q as InertiaRequestInfo, R as encodePageScript, S as merge, T as scroll, U as ValidationErrors, V as INERTIA_HEADERS, W as scopeErrors, X as computeSsrCacheKey, Y as canonicalStringify, Z as InertiaPage, _ as ScrollProp, a as INERTIA_LOCATION_STATUS, at as SharedPropsInput, b as defer, c as PropsResolver, d as resolveProps, et as PageProps, f as AlwaysProp, g as OptionalProp, h as OnceProp, i as buildPage, it as ScrollMetadata, j as matchesExcept, k as ScrollOptions, l as ResolvePropsInput, m as MergeProp, n as resolveVersion, nt as RenderOptions, o as INERTIA_REDIRECT_STATUS, ot as VersionResolver, p as DeferProp, q as SsrCacheEntry, r as BuildPageInput, rt as RescueHandler, s as inertiaRedirectStatus, t as isVersionMismatch, tt as PropsMetadata, u as ResolvePropsResult, v as always, w as optional, x as isPropDescriptor, y as deepMerge, z as renderDefaultHtml } from "../index-PWaujyMo.js";
+export { AlwaysProp, BuildPageInput, ComputeCacheKeyInput, CreatePageInput, DefaultRootViewInput, DeferProp, ErrorPageInput, INERTIA_HEADERS, INERTIA_LOCATION_STATUS, INERTIA_REDIRECT_STATUS, type InertiaPage, type InertiaRequestInfo, MergeProp, type OnceMetadata, OnceProp, OptionalProp, type PageProps, PropDescriptor, type PropKind, type PropSource, type PropsMetadata, PropsResolver, type RenderOptions, type RescueHandler, ResolvePropsInput, ResolvePropsResult, type ScrollMetadata, type ScrollOptions, ScrollProp, type SharedPropsInput, SsrCacheEntry, SsrCacheStore, ValidationErrors, type VersionResolver, always, buildPage, canonicalStringify, computeSsrCacheKey, createPage, deepMerge, defer, encodePageScript, inertiaRedirectStatus, isPropDescriptor, isVersionMismatch, leadsToOnly, matchesExcept, matchesOnly, merge, once, optional, parseInertiaRequest, pathIsSameOrDescendant, renderDefaultHtml, renderErrorPage, resolveProps, resolveVersion, scopeErrors, scroll, unpackDotProps };