Summary

Third step of the @hono/inertia v3 protocol breakdown: ③ Merge props, built on top of the partial reload foundation from #1904.

Adds three helpers — merge(), prepend(), and deepMerge() — that mark a prop for client-side combination on the next partial reload, instead of the default replace behavior. The wrapped value travels as-is; the renderer advertises which keys to combine via the new page.mergeProps / page.prependProps / page.deepMergeProps arrays and emits dot-paths on page.matchPropsOn for the client's dedupe logic.

import { deepMerge, inertia, merge, prepend } from '@hono/inertia'

app.use(inertia())

app.get('/feed', (c) =>
  c.render('Feed', {
    posts: merge(await db.posts.page(n), { matchOn: 'id' }),
    notifications: prepend(await fetchNotifications(), { matchOn: 'id' }),
    conversations: deepMerge(
      { data: await db.messages.page(n), meta: { nextCursor } },
      { matchOn: 'data.id' },
    ),
  }),
)

Protocol behaviour

Merging itself only takes effect on subsequent partial reloads — full page visits always replace props entirely (matches the upstream protocol).

Implementation

• merge<T>(data, { matchOn? }): T, prepend<T>(...), deepMerge<T>(...) return opaque markers (Symbol.for('@hono/inertia/merge')) that the renderer unwraps. The return type is T, so call sites and TypedResponse stay transparent — mirrors the defer() pattern from feat(inertia): add deferred props with defer() #1911.
• matchOn accepts a string or array; entries are emitted as "<propKey>.<field>" on page.matchPropsOn (e.g. merge(posts, { matchOn: 'id' }) ⇒ matchPropsOn: ['posts.id']).
• PageObject gains four optional fields — mergeProps?: string[], prependProps?: string[], deepMergeProps?: string[], matchPropsOn?: string[] — emitted only when at least one prop in the response carries the corresponding marker.

Scope intentionally kept small (single PR per protocol feature, like #1904 / #1911):

• ✅ Top-level `merge()` / `prepend()` / `deepMerge()` markers
• ✅ Single string and array `matchOn`
• ✅ Function value inside `merge()` (resolved via the existing lazy path)
• ✅ Strategy mixing in a single response
• ❌ Nested / dot-path merge markers — separate PR (would need to land alongside dot-path partial reloads)
• ❌ `defer()` inside `merge()` — separate PR (semantics deserve their own design discussion)
• ❌ Infinite scroll markers — separate PR (④ in the breakdown)

Test plan

• `yarn workspace @hono/inertia test` (`40 passed`, 12 new tests covering each helper, single + array `matchOn`, strategy mixing, partial reload behaviour, excluded-prop guard, function-inside-merge, HTML embed, JSON request)
• `eslint packages/inertia` clean
• `prettier --check` clean
• `tsc -b` clean
• `tsdown` build success