docs: correct "swallows" framing for mutationFn throws#116
Merged
Conversation
The react-call skill and CONTEXT.md described the useMutationFlow Trigger as "swallowing" a thrown mutationFn. That contradicts the actual code and ADR-0016: the Trigger chains only `.finally()` (no `.catch()`), so an uncaught throw escapes as an unhandled promise rejection. The Call stays open on failure because `call.end()` is never reached, not because the throw is silenced. - skills/react-call/references/mutation-flow.md: reframe the passage and teach the pattern — try/catch inside the mutationFn, return without end. - CONTEXT.md: fix the example dialogue (the glossary entries were already neutral; the dialogue was the spot ADR-0016 missed). - ADR-0016: add a dated correction note recording that CONTEXT.md's example dialogue was the overlooked source of the propagated wording.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The react-call skill (
skills/react-call/references/mutation-flow.md) andCONTEXT.mddescribed theuseMutationFlowTrigger as "swallowing" a thrownmutationFn. That is wrong.Why it's wrong
The Trigger chains only
.finally()— no.catch()(packages/react-call/src/mutation-flow/index.ts:72). This is a deliberate decision recorded in ADR-0016: an uncaught throw frommutationFnescapes as an unhandled promise rejection. The Call stays open on failure becausecall.end()is never reached (a Stack/lifecycle property), not because the throw is silenced.Root cause
ADR-0016 reversed the "swallow" framing everywhere it looked — source JSDoc, README, changelog — but its Consequences claimed "
CONTEXT.mdis unchanged". That was only true of the glossary entries; the example dialogue still said the Trigger "swallows the throw". When the consumer-usage skill was later published (ADR-0021), that residual wording was copied into it.Changes
skills/react-call/references/mutation-flow.md— reframe the passage and teach the pattern:try/catchinside themutationFn, show your error UI, thenreturnwithout callingend. No ADR citation (the skill ships to consumers withoutdocs/adr/).CONTEXT.md— fix the example dialogue to thecall.end()-grounded explanation.docs/adr/0016-*— dated correction note recording that the example dialogue was the overlooked source of the propagated wording.Audit
Cross-checked the rest of the skill against source — version (
2.0.2/ v2.x),CallContextshape, error strings (No <Root> found!,Multiple instances of <Root> found!), thehostAPI, public exports, and SSR/lazy — all accurate. "swallows" was the only factual defect.Notes
Docs-only; no changeset (the skill is git-hash versioned per ADR-0021, and neither file ships in the npm package).
check:typespasses.