@zerotal/inertia 1.0.0

package/src/props/PropTypes.ts

@@ -0,0 +1,362 @@
+/**
+ * Inertia v3 prop wrappers.
+ *
+ * A page prop can be a plain value, a function (lazy — evaluated only when included), or one of the
+ * wrapper classes below. The {@link resolveProps} pipeline inspects these to decide whether a prop
+ * is included on a given visit, when its value is evaluated, and how the client should merge it.
+ *
+ * Optional/Always/Defer/Merge prop wrappers, adapted to TypeScript.
+ */
+
+/** A prop value: a concrete value, or a (possibly async) factory evaluated on demand. */
+export type PropFactory = () => unknown | Promise<unknown>;
+
+/** Resolved merge configuration contributed by a mergeable prop. */
+export interface MergeConfig {
+  deep: boolean;
+  /** Nested paths to append (relative to the prop key). Empty = append at root. */
+  appendPaths: string[];
+  /** Nested paths to prepend (relative to the prop key). */
+  prependPaths: string[];
+  /** Paths (relative to the prop key) whose last segment is the match field. */
+  matchOn: string[];
+  /** Prepend at the root level instead of appending. */
+  prependRoot: boolean;
+}
+
+/**
+ * Base class for all prop wrappers. Carries the shared `once()` modifier and the mergeable
+ * capability (so both {@link MergeProp} and {@link DeferProp} can be merged on the client).
+ *
+ * @category Props
+ */
+export abstract class InertiaProp {
+  protected _once = false;
+  protected _onceExpiresAt: number | null = null;
+
+  protected _merge = false;
+  protected _deep = false;
+  protected _appendPaths: string[] = [];
+  protected _prependPaths: string[] = [];
+  protected _matchOn: string[] = [];
+  protected _prependRoot = false;
+
+  /** When true, the prop is skipped on full/initial visits and only resolved on partial reloads. */
+  readonly ignoreFirstLoad: boolean = false;
+
+  /** Produce the prop's value (may be async). */
+  abstract resolve(): unknown | Promise<unknown>;
+
+  // ── once() ──────────────────────────────────────────────────────────────────
+
+  /** Resolve only once; the client remembers the value across subsequent navigations. */
+  once(expiresAt: number | null = null): this {
+    this._once = true;
+    this._onceExpiresAt = expiresAt;
+    return this;
+  }
+  get isOnce(): boolean {
+    return this._once;
+  }
+  get onceExpiresAt(): number | null {
+    return this._onceExpiresAt;
+  }
+
+  // ── mergeable ────────────────────────────────────────────────────────────────
+
+  /** Append new items to the existing array at the root level on partial reloads. */
+  merge(): this {
+    this._merge = true;
+    return this;
+  }
+  /** Deep-merge the whole structure into the existing prop value on partial reloads. */
+  deepMerge(): this {
+    this._merge = true;
+    this._deep = true;
+    return this;
+  }
+  /** Append to specific nested path(s) of the prop, replacing the rest. */
+  append(paths?: string | string[]): this {
+    this._merge = true;
+    this._push(this._appendPaths, paths);
+    return this;
+  }
+  /** Prepend at the root (no args) or to specific nested path(s). */
+  prepend(paths?: string | string[]): this {
+    this._merge = true;
+    if (paths === undefined) this._prependRoot = true;
+    else this._push(this._prependPaths, paths);
+    return this;
+  }
+  /** Match existing items by a field (path's last segment) instead of appending duplicates. */
+  matchOn(paths: string | string[]): this {
+    this._push(this._matchOn, paths);
+    return this;
+  }
+
+  get shouldMerge(): boolean {
+    return this._merge;
+  }
+  mergeConfig(): MergeConfig {
+    return {
+      deep: this._deep,
+      appendPaths: this._appendPaths,
+      prependPaths: this._prependPaths,
+      matchOn: this._matchOn,
+      prependRoot: this._prependRoot,
+    };
+  }
+
+  private _push(target: string[], paths?: string | string[]): void {
+    if (paths === undefined) return;
+    if (Array.isArray(paths)) target.push(...paths);
+    else target.push(paths);
+  }
+}
+
+/**
+ * `optional(fn)` — never included unless explicitly requested via a partial reload's `only`.
+ * Also the underlying type returned by `lazy()`.
+ *
+ * @category Props
+ */
+export class OptionalProp extends InertiaProp {
+  override readonly ignoreFirstLoad = true;
+  constructor(private readonly callback: PropFactory) {
+    super();
+  }
+  resolve(): unknown | Promise<unknown> {
+    return this.callback();
+  }
+}
+
+/**
+ * `always(value)` — always included, even when a partial reload's `only`/`except` would exclude it.
+ * Used internally to share `errors`.
+ *
+ * @category Props
+ */
+export class AlwaysProp extends InertiaProp {
+  constructor(private readonly value: unknown | PropFactory) {
+    super();
+  }
+  resolve(): unknown | Promise<unknown> {
+    return typeof this.value === "function" ? (this.value as PropFactory)() : this.value;
+  }
+}
+
+/**
+ * `defer(fn, group?, { rescue })` — excluded from the initial render and listed under
+ * `deferredProps[group]`; the client fetches it in a follow-up partial reload. With `rescue: true`,
+ * a thrown error is swallowed and the key is reported in `rescuedProps`.
+ *
+ * @category Props
+ */
+export class DeferProp extends InertiaProp {
+  override readonly ignoreFirstLoad = true;
+  constructor(
+    private readonly callback: PropFactory,
+    readonly group: string = "default",
+    readonly rescue: boolean = false,
+  ) {
+    super();
+  }
+  resolve(): unknown | Promise<unknown> {
+    return this.callback();
+  }
+}
+
+/**
+ * `merge(value)` / `deepMerge(value)` — the client merges (rather than replaces) the prop on
+ * partial reloads. Chain `.append()`, `.prepend()`, `.matchOn()`, `.deepMerge()`.
+ *
+ * @category Props
+ */
+export class MergeProp extends InertiaProp {
+  constructor(private readonly value: unknown | PropFactory) {
+    super();
+    this._merge = true;
+  }
+  resolve(): unknown | Promise<unknown> {
+    return typeof this.value === "function" ? (this.value as PropFactory)() : this.value;
+  }
+}
+
+/** Minimal paginator shape `scroll()` reads to compute scroll metadata. */
+export interface PaginatorLike {
+  data: unknown[];
+  /** Current page — read from `currentPage` or `page`. */
+  currentPage?: number;
+  page?: number;
+  /** Last page number — read from `lastPage` (or derived from total/perPage). */
+  lastPage?: number;
+  perPage?: number;
+  total?: number;
+}
+
+/** The `scrollProps` config emitted per infinite-scroll prop. */
+export interface ScrollConfig {
+  pageName: string;
+  previousPage: number | null;
+  nextPage: number | null;
+  currentPage: number | null;
+}
+
+/**
+ * `scroll(paginator)` — an infinite-scroll prop. The page's paginated data is merged (the client
+ * appends/prepends new pages) and the page object carries a `scrollProps` entry describing the
+ * current/next/previous page so the `<InfiniteScroll>` component knows when to load more.
+ *
+ * @category Props
+ */
+export class InfiniteScrollProp extends InertiaProp {
+  constructor(
+    private readonly value: PaginatorLike | PropFactory,
+    readonly pageName: string = "page",
+    readonly dataPath: string = "data",
+  ) {
+    super();
+    this._merge = true;
+    this._appendPaths = [dataPath];
+  }
+
+  resolve(): unknown | Promise<unknown> {
+    return typeof this.value === "function" ? (this.value as PropFactory)() : this.value;
+  }
+
+  /** Compute the `scrollProps` entry from the resolved paginator value. */
+  scrollConfig(resolved: unknown): ScrollConfig {
+    const p = (resolved ?? {}) as PaginatorLike;
+    const current = p.currentPage ?? p.page ?? null;
+    const last =
+      p.lastPage ??
+      (p.total != null && p.perPage ? Math.max(1, Math.ceil(p.total / p.perPage)) : null);
+    const nextPage = current != null && last != null && current < last ? current + 1 : null;
+    const previousPage = current != null && current > 1 ? current - 1 : null;
+    return { pageName: this.pageName, previousPage, nextPage, currentPage: current };
+  }
+}
+
+// ── factory helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Never include this prop on a full visit; the callback runs (and the value is sent)
+ * only when a partial reload names the key in its `only` set. Use for expensive data
+ * a page fetches on demand.
+ *
+ * @param callback - Factory producing the prop value (may be async); evaluated only when included.
+ * @returns An {@link OptionalProp} wrapper for the resolver.
+ * @category Props
+ * @example
+ * ```ts
+ * return inertia('Users/Index', {
+ *   users,
+ *   // Only fetched when the client does `router.reload({ only: ['stats'] })`.
+ *   stats: optional(() => computeExpensiveStats()),
+ * });
+ * ```
+ */
+export function optional(callback: PropFactory): OptionalProp {
+  return new OptionalProp(callback);
+}
+
+/**
+ * Alias of {@link optional}, matching Inertia's historical `lazy()` name.
+ *
+ * @param callback - Factory producing the prop value (may be async); evaluated only when included.
+ * @returns An {@link OptionalProp} wrapper.
+ * @category Props
+ */
+export function lazy(callback: PropFactory): OptionalProp {
+  return new OptionalProp(callback);
+}
+
+/**
+ * Always include this prop, even when a partial reload's `only`/`except` would
+ * otherwise exclude it. Used internally to keep the `errors` bag present on every visit.
+ *
+ * @param value - The value, or a factory producing it (evaluated when included).
+ * @returns An {@link AlwaysProp} wrapper.
+ * @category Props
+ */
+export function always(value: unknown | PropFactory): AlwaysProp {
+  return new AlwaysProp(value);
+}
+
+/**
+ * Exclude this prop from the initial render and load it in an automatic follow-up
+ * request, so the page paints immediately and heavier data streams in after. Props
+ * sharing a `group` are fetched together in one request.
+ *
+ * @param callback - Factory producing the prop value (may be async); runs on the deferred request.
+ * @param group - Request group name; props with the same group load in one follow-up request. Default `"default"`.
+ * @param options - `rescue: true` swallows a thrown error and reports the key in `rescuedProps` instead of failing the request.
+ * @returns A {@link DeferProp} wrapper.
+ * @category Props
+ * @example
+ * ```ts
+ * return inertia('Dashboard', {
+ *   user,
+ *   stats:    defer(() => computeStats()),                 // group "default"
+ *   activity: defer(() => recentActivity(), 'secondary'),  // separate request
+ * });
+ * ```
+ */
+export function defer(
+  callback: PropFactory,
+  group = "default",
+  options: { rescue?: boolean } = {},
+): DeferProp {
+  return new DeferProp(callback, group, options.rescue ?? false);
+}
+
+/**
+ * Mark this prop so the client appends (merges) it into the existing value on partial
+ * reloads instead of replacing it — the basis for "load more" lists. Chain
+ * `.append()` / `.prepend()` / `.matchOn()` on the returned wrapper for finer control.
+ *
+ * @param value - The value, or a factory producing it.
+ * @returns A {@link MergeProp} wrapper.
+ * @category Props
+ * @example
+ * ```ts
+ * return inertia('Feed', { posts: merge(() => Post.paginate(15, page)) });
+ * ```
+ */
+export function merge(value: unknown | PropFactory): MergeProp {
+  return new MergeProp(value);
+}
+
+/**
+ * Like {@link merge}, but the client deep-merges the structure into the existing prop
+ * value on partial reloads rather than appending at the root.
+ *
+ * @param value - The value, or a factory producing it.
+ * @returns A {@link MergeProp} wrapper configured for deep merging.
+ * @category Props
+ */
+export function deepMerge(value: unknown | PropFactory): MergeProp {
+  return new MergeProp(value).deepMerge();
+}
+
+/**
+ * Infinite-scroll prop: merges paginated data and emits `scrollProps` so the client
+ * `<InfiniteScroll>` component knows when to load the next/previous page.
+ *
+ * @param value - A paginator (or factory producing one) with `data` plus page metadata.
+ * @param options - `pageName` (query param driving pagination, default `"page"`) and `dataPath` (path to the array to merge, default `"data"`).
+ * @returns An {@link InfiniteScrollProp} wrapper.
+ * @category Props
+ * @example
+ * ```ts
+ * return inertia('Posts/Index', { posts: scroll(() => Post.paginate(15, page)) });
+ * // custom page-query name:
+ * return inertia('Items', { items: scroll(() => Item.paginate(15, page), { pageName: 'p' }) });
+ * ```
+ */
+export function scroll(
+  value: PaginatorLike | PropFactory,
+  options: { pageName?: string; dataPath?: string } = {},
+): InfiniteScrollProp {
+  return new InfiniteScrollProp(value, options.pageName ?? "page", options.dataPath ?? "data");
+}

package/src/props/resolveProps.ts

@@ -0,0 +1,189 @@
+import {
+  InertiaProp,
+  AlwaysProp,
+  DeferProp,
+  InfiniteScrollProp,
+  type PropFactory,
+  type ScrollConfig,
+} from "./PropTypes.ts";
+
+/** The resolved props plus the page-object metadata the client needs to merge/defer correctly. */
+export interface ResolvedPage {
+  props: Record<string, unknown>;
+  deferredProps?: Record<string, string[]>;
+  mergeProps?: string[];
+  prependProps?: string[];
+  deepMergeProps?: string[];
+  matchPropsOn?: string[];
+  scrollProps?: Record<string, ScrollConfig>;
+  onceProps?: Record<string, { prop: string; expiresAt: number | null }>;
+  rescuedProps?: string[];
+}
+
+function parseList(value: string | null): string[] {
+  if (!value) return [];
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+async function evaluate(value: unknown): Promise<unknown> {
+  if (value instanceof InertiaProp) return await value.resolve();
+  if (typeof value === "function") return await (value as PropFactory)();
+  return value;
+}
+
+/**
+ * Resolve a raw prop map against the current request into the props payload plus page-object
+ * metadata, implementing the Inertia v3 prop protocol:
+ *
+ * - **Partial reloads**: when `X-Inertia-Partial-Component` matches `component`, only the props in
+ *   `X-Inertia-Partial-Data` (`only`) are returned, or everything except `X-Inertia-Partial-Except`
+ *   (`except`, which takes precedence).
+ * - **Lazy evaluation**: function and wrapper props are only evaluated when actually included.
+ * - **optional/defer** (`ignoreFirstLoad`): omitted from full visits; included only when named in a
+ *   partial reload's `only`. Deferred props are advertised in `deferredProps[group]` on first load.
+ * - **always**: always included, regardless of only/except.
+ * - **merge/deepMerge**: included normally, but advertised in `mergeProps`/`deepMergeProps`/
+ *   `prependProps`/`matchPropsOn` so the client merges instead of replacing. Suppressed for keys in
+ *   `X-Inertia-Reset`.
+ * - **once**: advertised in `onceProps`; skipped (not re-resolved) when already loaded on the client
+ *   per `X-Inertia-Except-Once-Props`, unless explicitly requested via `only`.
+ * - **rescue**: a deferred prop with `rescue: true` that throws is omitted and reported in
+ *   `rescuedProps`.
+ *
+ * @param raw - The merged raw prop map (shared props + controller props), values possibly wrapped.
+ * @param headers - The incoming request headers, read for the `X-Inertia-Partial-*` / reset / once / scroll-intent directives.
+ * @param component - The page component name, compared against `X-Inertia-Partial-Component` to detect a partial reload.
+ * @returns The resolved props plus the merge/defer/scroll/once metadata for the page object.
+ * @internal Prop-protocol engine behind {@link buildPageObject}; not part of the app-facing API.
+ */
+export async function resolveProps(
+  raw: Record<string, unknown>,
+  headers: Headers,
+  component: string,
+): Promise<ResolvedPage> {
+  const isPartial = headers.get("X-Inertia-Partial-Component") === component;
+  const only = parseList(headers.get("X-Inertia-Partial-Data"));
+  const except = parseList(headers.get("X-Inertia-Partial-Except"));
+  const reset = new Set(parseList(headers.get("X-Inertia-Reset")));
+  const onceLoaded = new Set(parseList(headers.get("X-Inertia-Except-Once-Props")));
+  const scrollIntent = headers.get("X-Inertia-Infinite-Scroll-Merge-Intent"); // "prepend" | "append"
+
+  const keys = Object.keys(raw);
+  const propOf = (key: string): InertiaProp | undefined => {
+    const v = raw[key];
+    return v instanceof InertiaProp ? v : undefined;
+  };
+
+  // ── 1. Decide which keys are included ────────────────────────────────────────
+  const included: string[] = [];
+  for (const key of keys) {
+    const prop = propOf(key);
+
+    // always() props bypass all filtering.
+    if (prop instanceof AlwaysProp) {
+      included.push(key);
+      continue;
+    }
+
+    if (isPartial && (only.length || except.length)) {
+      if (except.length) {
+        // except takes precedence; exclude listed keys and never auto-include ignoreFirstLoad props.
+        if (!except.includes(key) && !prop?.ignoreFirstLoad) included.push(key);
+      } else if (only.includes(key)) {
+        // only: include exactly these (optional/deferred props become available here).
+        included.push(key);
+      }
+      continue;
+    }
+
+    // Full/initial visit (or partial reload with no only/except): everything except
+    // ignoreFirstLoad props (optional/deferred), which load on a later request.
+    if (!prop?.ignoreFirstLoad) included.push(key);
+  }
+
+  // ── 2. Resolve included values + collect once metadata ───────────────────────
+  const props: Record<string, unknown> = {};
+  const rescuedProps: string[] = [];
+  const onceProps: Record<string, { prop: string; expiresAt: number | null }> = {};
+
+  for (const key of included) {
+    const prop = propOf(key);
+
+    if (prop?.isOnce) {
+      onceProps[key] = { prop: key, expiresAt: prop.onceExpiresAt };
+      // Already on the client and not explicitly re-requested → skip resolving, reuse client value.
+      if (onceLoaded.has(key) && !only.includes(key)) continue;
+    }
+
+    try {
+      props[key] = await evaluate(raw[key]);
+    } catch (err) {
+      if (prop instanceof DeferProp && prop.rescue) {
+        rescuedProps.push(key);
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  // ── 3. Deferred-prop advertisement (initial visit only) ──────────────────────
+  const deferredProps: Record<string, string[]> = {};
+  if (!isPartial) {
+    for (const key of keys) {
+      const v = raw[key];
+      if (v instanceof DeferProp) (deferredProps[v.group] ??= []).push(key);
+    }
+  }
+
+  // ── 4. Merge advertisement (for included, non-reset mergeable props) ─────────
+  const mergeProps: string[] = [];
+  const prependProps: string[] = [];
+  const deepMergeProps: string[] = [];
+  const matchPropsOn: string[] = [];
+
+  for (const key of included) {
+    const prop = propOf(key);
+    if (!prop?.shouldMerge || reset.has(key)) continue;
+    // Skip merge advertisement for once props that were reused (not in props).
+    if (prop.isOnce && !(key in props)) continue;
+
+    const cfg = prop.mergeConfig();
+    const target = cfg.deep ? deepMergeProps : mergeProps;
+    const hasNested = cfg.appendPaths.length > 0 || cfg.prependPaths.length > 0 || cfg.prependRoot;
+
+    // Infinite-scroll props follow the client's merge intent: append by default, prepend when the
+    // user scrolled up (X-Inertia-Infinite-Scroll-Merge-Intent: prepend).
+    const appendTarget =
+      prop instanceof InfiniteScrollProp && scrollIntent === "prepend" ? prependProps : target;
+
+    if (!hasNested) target.push(key);
+    for (const p of cfg.appendPaths) appendTarget.push(`${key}.${p}`);
+    for (const p of cfg.prependPaths) prependProps.push(`${key}.${p}`);
+    if (cfg.prependRoot) prependProps.push(key);
+    for (const p of cfg.matchOn) matchPropsOn.push(`${key}.${p}`);
+  }
+
+  // ── 4b. Infinite-scroll metadata ─────────────────────────────────────────────
+  const scrollProps: Record<string, ScrollConfig> = {};
+  for (const key of included) {
+    const prop = propOf(key);
+    if (prop instanceof InfiniteScrollProp && key in props) {
+      scrollProps[key] = prop.scrollConfig(props[key]);
+    }
+  }
+
+  // ── 5. Assemble, omitting empty metadata ─────────────────────────────────────
+  const out: ResolvedPage = { props };
+  if (Object.keys(deferredProps).length) out.deferredProps = deferredProps;
+  if (mergeProps.length) out.mergeProps = mergeProps;
+  if (prependProps.length) out.prependProps = prependProps;
+  if (deepMergeProps.length) out.deepMergeProps = deepMergeProps;
+  if (matchPropsOn.length) out.matchPropsOn = matchPropsOn;
+  if (Object.keys(scrollProps).length) out.scrollProps = scrollProps;
+  if (Object.keys(onceProps).length) out.onceProps = onceProps;
+  if (rescuedProps.length) out.rescuedProps = rescuedProps;
+  return out;
+}