@blacklizard/inertia-express 2.0.0 → 3.1.0

package/README.md

@@ -17,10 +17,11 @@ The internal core is framework-agnostic, so future adapters for Fastify, Hono, N
 - Full implementation of the Inertia.js v3 protocol
 - `res.inertia(component, props, options)` Express helper
 - Shared props (static or per-request)
-- Lazy, optional, deferred, always, merge, and deep-merge props
+- Optional, deferred (with rescue), always, merge, deep-merge, once, and infinite-scroll props
+- Live props (`liveProps` channel listeners) and `broadcastProps` payloads for your realtime server
 - Partial reloads (`X-Inertia-Partial-Data` / `X-Inertia-Partial-Except`)
 - Asset version handling and automatic 409 + `X-Inertia-Location` on mismatch
-- Inertia-aware redirects (auto 303 after PUT/PATCH/DELETE)
+- Inertia-aware redirects (auto 303 after PUT/PATCH/DELETE/QUERY, 409 + `X-Inertia-Redirect` for `#fragment` targets, empty 200 → redirect back)
 - External redirects via `res.inertiaLocation()`
 - Validation error helpers
 - Pluggable root view
@@ -88,7 +89,7 @@ Pass options to `inertia({ ... })`:
 | `ssr`              | `SsrRenderer`                         | SSR hook returning `{ head, body }`. See [SSR](#server-side-rendering-ssr).  |
 | `cache`            | `InertiaCacheOptions`                 | View cache for SSR HTML. See [View cache](#view-cache).                      |
 | `edgeCache`        | `EdgeCachePolicy`                     | CDN `Cache-Control` policy. See [Edge caching](#edge-caching-cdn).           |
-| `flashFromSession` | `boolean`                             | Auto-promote `req.session.errors` / `flash` into shared props. Default off.  |
+| `flashFromSession` | `boolean`                             | Surface `req.session.flash` as the top-level `flash` page key. Default off.  |
 
 If no `rootView` is given, the middleware emits a minimal default HTML shell with an empty `<div id="app">` plus the v3 `<script type="application/json" data-page="app">` page tag, so you can wire up a Vite client manually.
 
@@ -121,45 +122,210 @@ inertia({
     auth: { user: req.user ?? null },
     csrf: req.csrfToken?.(),
     flash: req.session?.flash ?? {},
-    errors: req.session?.errors ?? {},
   }),
 });
 ```
 
-## Lazy, optional, deferred, always, and merge props
+Validation errors do not need wiring here: `errors` is shared on every page automatically (see [Validation errors](#validation-errors)).
+
+## Prop helpers
+
+Every prop value is either a plain value, a bare closure (evaluated on each
+response that includes it, awaited if it returns a promise), or a descriptor
+built by one of the constructors below. Descriptors are chainable and mirror
+inertia-laravel's prop classes; the resolver is a port of its `PropsResolver`.
+
+```ts
+import { always, deepMerge, defer, live, merge, once, optional, scroll } from "@blacklizard/inertia-express";
+```
+
+A bare closure replaces 2.x's `lazy()`:
+
+```ts
+app.get("/dashboard", async (req, res) => {
+  await res.inertia("Dashboard", {
+    user: req.user,
+    recent: () => userService.recent(),
+  });
+});
+```
+
+### `optional`
+
+Omitted from the first load; resolved only when a partial reload asks for it.
+
+```ts
+app.get("/reports", async (req, res) => {
+  await res.inertia("Reports", {
+    heavy: optional(() => analytics.expensiveQuery()),
+  });
+});
+```
+
+Laravel: `Inertia::optional()`
+
+### `defer`
+
+Omitted from the first load; the client fetches it in a follow-up request with
+the rest of its group (default `"default"`). `.rescue()` opts in to error
+rescue: if the producer throws, the prop is dropped from the response, its path
+is reported in `rescuedProps`, and the middleware's `onRescue` hook is called.
+
+```ts
+app.get("/dashboard", async (req, res) => {
+  await res.inertia("Dashboard", {
+    stats: defer(() => dashboard.getStats(), "dashboard"),
+    feed: defer(() => feedService.load()).rescue(),
+  });
+});
+```
+
+Laravel: `Inertia::defer()`
+
+### `always`
+
+Included on every response, even partial reloads that do not request it.
+Takes a plain value or a closure.
+
+```ts
+app.get("/inbox", async (req, res) => {
+  await res.inertia("Inbox", {
+    flash: always(() => req.session.flash),
+  });
+});
+```
+
+Laravel: `Inertia::always()`
+
+### `merge` / `deepMerge`
+
+`merge(value)` tells the client to append the prop to its existing value at the
+root; `deepMerge(value)` merges recursively. Chain `.append(path?, matchOn?)`
+or `.prepend(path?, matchOn?)` to target nested paths, and `.matchOn(path)` to
+dedupe items by a key instead of blindly appending. A path argument may be
+`true` (the root, the default), a dotted path string, a list of paths, or a
+`{ path: matchOnKey }` record. A client can send `X-Inertia-Reset: <key>` to
+have a merge prop replaced instead of merged on that visit.
 
 ```ts
-import { lazy, optional, defer, always, merge, deepMerge } from "@blacklizard/inertia-express";
+app.get("/notifications", async (req, res) => {
+  await res.inertia("Notifications", {
+    notifications: merge(() => db.notifications.page(req.query.page)).matchOn("id"),
+    feed: merge(() => feedService.page(req.query.page)).append("data", "id").prepend("pinned"),
+    filters: deepMerge({ sort: { field: "name" } }),
+  });
+});
+```
 
-await res.inertia("Dashboard", {
-  // Always evaluated.
-  user: req.user,
+Laravel: `Inertia::merge()` / `Inertia::deepMerge()`
 
-  // Evaluated on every visit, but the function form lets you defer the work.
-  recent: lazy(() => userService.recent()),
+### `once`
 
-  // Omitted on full visits; only sent if requested via partial reload.
-  heavy: optional(() => analytics.expensiveQuery()),
+Resolved once and cached by the client across visits; later visits skip the
+producer while the client still holds the value. `.as(key)` sets a custom cache
+key (shareable across pages), `.until(delay)` sets an expiry (a number of
+seconds, or a `Date`), and `.fresh()` forces re-resolution on this response.
+`optional`, `defer` and `merge` descriptors also accept `.once()`.
+
+```ts
+app.get("/settings", async (req, res) => {
+  await res.inertia("Settings", {
+    countries: once(() => geo.countries()).as("countries").until(3600),
+    plans: once(() => billing.plans()).until(new Date("2027-01-01")),
+    banner: once(() => cms.banner()).fresh(req.query.refresh === "1"),
+  });
+});
+```
 
-  // Omitted on initial visit; the client automatically requests it via a
-  // follow-up partial reload after mount, grouped by `"dashboard"`.
-  stats: defer(() => dashboard.getStats(), "dashboard"),
+Laravel: `Inertia::once()`
 
-  // Included on every response, even partial reloads that filter it out.
-  flash: always(() => req.session.flash),
+### `scroll`
 
-  // Merge with the existing client-side prop on partial reloads instead of
-  // replacing it. Useful for paginated lists / infinite-scroll feeds. Pass a
-  // match-on field to dedupe array items instead of blindly appending.
-  notifications: merge(await db.notifications.page(req.query.page), "id"),
+An infinite-scroll prop: merged at its `wrapper` key (default `"data"`) and
+emitted with pagination metadata. `metadata` is required — either an object
+`{ pageName, previousPage, nextPage, currentPage }` or a function deriving it
+from the resolved value. The merge direction follows the client's
+`X-Inertia-Infinite-Scroll-Merge-Intent` header (`prepend`, otherwise
+`append`). Chain `.defer(group?)` to load the first page in a follow-up
+request, and `.matchOn(path)` to dedupe.
 
-  // Recursive deep-merge into the existing client-side prop.
-  filters: deepMerge({ sort: { field: "name" } }),
+```ts
+app.get("/posts", async (req, res) => {
+  await res.inertia("Posts", {
+    posts: scroll(() => postService.paginate(req.query.page), {
+      metadata: (page) => ({ pageName: "page", previousPage: page.prev, nextPage: page.next, currentPage: page.current }),
+    }).matchOn("id"),
+    comments: scroll(() => commentService.page(1), { wrapper: "items", metadata: { pageName: "page", previousPage: null, nextPage: 2, currentPage: 1 } }).defer(),
+  });
 });
 ```
 
-A client can send `X-Inertia-Reset: <key>` to have a merge / deep-merge prop
-replaced instead of merged on that visit.
+Laravel: `Inertia::scroll()`
+
+### `live`
+
+A prop the client refreshes when a realtime event arrives. `live(value, { on,
+channel, throttle? })` resolves like a plain prop and lists its channel
+listeners in the page object's `liveProps`; `always`, `optional`, `defer` and
+`once` descriptors accept the same options through `.live(options)`. Merge and
+scroll props cannot be live. Events are strings and channels are explicit: a
+bare string channel is public, and `{ name, type }` sets `private`,
+`presence` or `encrypted-private`. `throttle` is in milliseconds.
+
+`broadcastProps(props, onRescue?)` resolves every prop (no partial or once
+filtering, rescued props omitted) into the `{ __inertia: { props } }` payload
+to send with the event; `resolveBroadcastProps` returns the bare props map. The
+adapter does not open sockets: send the payload with your own realtime server.
+`req.inertia.socketId` carries the `X-Socket-Id` header (`null` when absent) so
+that server can skip the sender.
+
+```ts
+import { broadcastProps, live } from "@blacklizard/inertia-express";
+
+app.get("/leads", async (req, res) => {
+  await res.inertia("Leads/Index", {
+    leads: live(() => loadLeads(), { on: "LeadUpdated", channel: { name: "leads", type: "private" } }),
+  });
+});
+
+// After a lead changes (Socket.IO shown)
+// The client subscribes to the declared event on the declared channel.
+io.to("leads")
+  .except(req.inertia?.socketId ?? [])
+  .emit("LeadUpdated", await broadcastProps({ leads: () => loadLeads() }));
+```
+
+Laravel: `Inertia::live()` / `->live()`
+
+### Rescue hook and fragment preservation
+
+Pass `onRescue: (error, path, req) => …` to `inertia({ … })` to report errors
+from rescued deferred props (the default logs them). Pass
+`{ preserveFragment: true }` as the third argument to `res.inertia()` to have
+the client keep the current URL `#fragment` across that visit.
+
+### Migrating from 2.x
+
+| 2.x | 3.0 |
+|---|---|
+| `lazy(fn)` | `fn` (a bare closure) |
+| `merge(value, matchOn)` | `merge(value).matchOn(matchOn)` |
+| `deepMerge(value, matchOn)` | `deepMerge(value).matchOn(matchOn)` |
+| `defer(fn, group)` | unchanged |
+| `optional(fn)`, `always(fn)` | unchanged |
+| `resolveProps()` → `{ props, deferred, merge, deepMerge, matchOn }` | `{ props, metadata }` |
+| Types `MergeProp<T> = T & {...}` | descriptor types; the page `props` type is unchanged |
+
+Other changes to check when upgrading:
+
+- `merge(value, "id")` and `deepMerge(value, "id")` now throw a `TypeError` instead of silently ignoring the second argument. Use `.matchOn("id")`.
+- Partial reloads follow dotted paths. `only: users.data` on a plain-object `users` now returns just `{ users: { data } }`; children of a closure or descriptor still bypass filtering and come back whole. `except: users.data` drops the whole top-level `users`, as in 2.x and in the upstream reference server; inertia-laravel keeps `users` and drops only the child, and the adapter deliberately differs from it here.
+- Types: `DeferredProp` is renamed to `DeferProp`. `LazyProp`, `DeepMergeProp` and `PropValue` are removed. `MergeProp<T>` is now the descriptor interface returned by `merge()` / `deepMerge()`, not `T & {...}`.
+- Core-entry adapter authors who build these objects by hand: `InertiaPage.preserveFragment` is now required, and `InertiaRequestInfo` gains the required fields `exceptOnceProps` and `mergeIntent`.
+- `sharedProps` (the list of shared top-level keys) is now emitted on every page that has shared props.
+- Descriptors are builders. Create them inside the handler for each request rather than mutating one hoisted to module level; the resolver itself only reads them, so a hoisted descriptor that is never changed after creation is safe to reuse.
+- Sibling props still resolve concurrently, as in 2.x, and the output key order and metadata order are deterministic (insertion order).
+- Errors thrown by the `onRescue` hook (or a rejected promise it returns) are logged with `console.error` and never propagated.
 
 ## Partial reloads
 
@@ -173,18 +339,10 @@ The middleware applies this filtering automatically. Partial reload filtering is
 
 ## Validation errors
 
-The simplest pattern is to share `req.session.errors` from `sharedProps`:
+Record validation errors with `res.inertiaErrors(errors, bag?)`. Errors are stored per bag (`default` when no bag is given); a repeated bag replaces the earlier one and other bags are kept.
 
-```ts
-inertia({
-  sharedProps: (req) => ({ errors: req.session?.errors ?? {} }),
-});
-```
-
-The middleware also exposes `res.inertiaErrors(errors, bag?)`, which:
-
-- Writes errors to `req.session.errors` if a session is present.
-- Otherwise stores them on `res.locals.inertiaErrors` for the same response.
+- With a session, it writes `req.session.inertia.errors[bag] = errors`; the next render reads them and clears them (read-once).
+- Without a session, it writes the same bags map to `res.locals.inertiaErrors` for the current response.
 
 ```ts
 app.post("/users", (req, res) => {
@@ -197,11 +355,22 @@ app.post("/users", (req, res) => {
 });
 ```
 
-You may pass an error bag name to namespace errors under `errors[bag]`.
+The `errors` prop is shared on every page (`{}` when empty, listed in `sharedProps`, kept on partial reloads) whether or not `flashFromSession` is on, so no `sharedProps` wiring is needed. Bags are remapped when the page is read, as in inertia-laravel's `Middleware::resolveValidationErrors`:
+
+- Errors stored without a bag come back flat: `props.errors.email`.
+- If the request carries `X-Inertia-Error-Bag: signup`, those same errors come back as `props.errors.signup.email`.
+- Errors stored under a named bag (`res.inertiaErrors(errors, "createUser")`) come back keyed by name, `props.errors.createUser.email`, when no `default` bag is stored. If a `default` bag is stored as well, only `default` is returned (flat, or under the header name) and the named bags are dropped.
+
+An explicit `errors` key in your shared or page props wins over the shared one.
 
 ## Redirects
 
-For Inertia requests, `res.redirect(url)` after a `PUT`, `PATCH`, or `DELETE` is automatically promoted to status `303`. This is required by the Inertia protocol to ensure the follow-up request is a `GET`.
+For Inertia requests, a `302` from `res.redirect(url)` after a `PUT`, `PATCH`, `DELETE` or `QUERY` is automatically promoted to status `303`. This is required by the Inertia protocol to ensure the follow-up request is a `GET`.
+
+Two more inertia-laravel middleware rules apply to Inertia requests:
+
+- **Fragment redirects** (`Middleware::onRedirectWithFragment`) — a redirect whose URL contains `#` is answered with `409`, `X-Inertia-Redirect: <url>` (encoded like `Location`) and an empty body, so the client can navigate and keep the fragment. Prefetch requests get the normal redirect.
+- **Empty responses** (`Middleware::onEmptyResponse`) — a `200` with an empty body (`res.end()`, `res.send("")`) becomes a redirect back to the `Referer`, or `/` without one (`303` after PUT/PATCH/DELETE/QUERY, `302` otherwise). Responses whose headers were already sent (`res.flushHeaders()`, streaming) and handlers that never respond are not covered.
 
 For external redirects (different host or full reload), use `res.inertiaLocation()`:
 
@@ -213,7 +382,7 @@ For Inertia (XHR) visits this returns `409 X-Inertia-Location: <url>` which the
 
 ## Asset versioning
 
-Pass a `version` resolver. When a client's `X-Inertia-Version` header doesn't match the current value on a `GET`, the middleware responds with `409` + `X-Inertia-Location: <same-url>`, and the Inertia client performs a full reload.
+Pass a `version` resolver. When a client's `X-Inertia-Version` header doesn't match the current value on a `GET`, the middleware responds with `409` + `X-Inertia-Location: <same-url>` and `X-Inertia-Version: <current version>` (inertia-laravel's `Middleware::onVersionChange`), and the Inertia client performs a full reload.
 
 ```ts
 inertia({
@@ -428,13 +597,13 @@ Failures on individual routes never halt the run — inspect `summary.results` t
 
 ## Flash from session
 
-Set `flashFromSession: true` to auto-promote `req.session.errors` and `req.session.flash` into shared props (and clear them after read), so you don't have to wire them into `sharedProps` manually:
+Set `flashFromSession: true` to surface `req.session.flash` as the top-level `flash` page key (a sibling of `props`, read on the client via `usePage().flash`) and clear it after read:
 
 ```ts
 inertia({ flashFromSession: true });
 ```
 
-Off by default — most apps already wire flash/errors via `sharedProps`. Requires a session middleware that exposes `req.session`.
+Off by default. Requires a session middleware that exposes `req.session`. The option gates only `flash`; validation errors are shared as the `errors` prop on every page regardless (see [Validation errors](#validation-errors)).
 
 ## Edge caching (CDN)
 
@@ -537,6 +706,7 @@ For typed page props on the client side, generic `res.inertia<TProps>("Component
 - The default HTML shell is intentionally minimal. Real apps should provide a `rootView`.
 - This adapter does not bundle a session implementation — bring your own (`express-session`, `cookie-session`, etc.).
 - Optimistic-update / `useHttp` server-side helpers are intentionally minimal here; the protocol primitives (`mergeProps`, `deepMergeProps`, `matchPropsOn`, `deferredProps`, `clearHistory`, `encryptHistory`) are exposed.
+- Behaviour that differs from inertia-laravel or from 2.x is listed on the docs site's [Caveats](https://blacklizard.github.io/inertia-express/guide/caveats) page.
 
 ## License