plugin-nested-docs: option to re-save only children whose breadcrumbs would change, instead of the whole subtree on every publish

Open
#19,682 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
backend, databases

Research direction

Read the nested-docs plugin's resaveChildren implementation and its getParents, populateBreadcrumbs, formatBreadcrumb, generateLabel, and generateURL paths, along with the referenced issues #14943 and #5706. Trace how published children and pending drafts are read and saved, then assess the proposed opt-in behavior against the Postgres reproduction; done means unrelated parent edits avoid descendant writes while breadcrumb changes still cascade correctly.

Written by the indexing model from the issue text.

Description

Bug plugin: nested-docs
Describe the Bug

After every published save, resaveChildren re-saves every child (both its published version and its pending draft), and each re-saved child runs the same hook on its own children. This happens whatever changed. Publishing a change to an unrelated field on a page re-saves its whole subtree, one document after another, inside the parent's transaction.

The cost grows with subtree size, not with what was edited: every descendant gets a new version and runs its full hook and validation chain, all inside the parent's transaction, even when the edit can't affect any breadcrumb.

(This is about cost, not lost saves: publishes we saw fail under this cascade turned out to be #15515.)

Why the full cascade can't simply be dropped

Re-saving a child does more than refresh its breadcrumbs. It runs the child's own hooks and their side effects (revalidation, search indexing, webhooks, a hook that derives a field from the child's ancestors). Some projects may depend on an ancestor's save refreshing those. The plugin can't know, so the full cascade should stay the default.

Proposal: an opt-in, with an exact breadcrumb check

Something like resaveChildren: 'always' | 'whenBreadcrumbsChange' (or a shouldResaveChild({ child, expectedBreadcrumbs, req }) callback), default 'always'. With 'whenBreadcrumbsChange':

  1. Read the published parent and its ancestors once (getParents), as the child's beforeChange hook would.
  2. Read the children (both their published versions and pending drafts) in full.
  3. For each child, compute in memory the breadcrumbs populateBreadcrumbs would write: for each document in [...ancestors, parent, child], formatBreadcrumb over the chain up to it, using the configured generateLabel / generateURL.
  4. Re-save only the children whose stored breadcrumbs (doc id, url, label) differ. Each re-saved child runs the hook in turn, so the cascade reaches exactly the part of the tree a change affects.
  5. When a child's published version is re-saved, re-save its pending draft after it, so the draft stays the newest version (the #14943 situation).

Computing the expected breadcrumbs, rather than checking that a child's stored crumbs start with the parent's, matters. generateLabel / generateURL receive the whole chain, so a child's own crumb can depend on an ancestor field that ancestor's own crumb doesn't show. A prefix check would miss that. Comparing against the children's stored state, rather than diffing the parent against previousDoc the way #5706 does, also covers publishing a draft whose breadcrumbs changed, since draft saves never cascade.

With the option on, the only requirement is that generateLabel / generateURL depend only on their arguments. A save that changes nothing a breadcrumb depends on then does a few reads and no writes.

Given the core nested-docs work in #19277, will the core version avoid the full cascade, or offer something like this?

Reproduction Steps
  1. A collection with versions.drafts and plugin-nested-docs, on a Postgres adapter.
  2. Create a parent with a few dozen published descendants, several levels deep.
  3. Publish a change to any non-breadcrumb field on the parent (for example a checkbox).
  4. Every descendant gets a new version, and the save time grows with the size of the subtree.
Which area(s) are affected?

plugin: nested-docs

Environment Info

Reproduced on payload / @payloadcms/plugin-nested-docs 3.90.0.

Dominant language
TypeScript
Stars
45.8k
Forks
4.4k
Avg merge
2d 16h
Merged PRs (30d)
251

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from payloadcms/payload

All issues in payloadcms/payload

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.