Repository navigation
docs: recommend helpers that change a draft in place for create() on a draft - #188
Merged
Merged
Conversation
|
Coverage after merging docs/create-on-draft-helpers into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
This was referenced Oct 6, 2026
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.
Refs #160. Part of #168. Replaces #187.
Summary
#186 documented that a helper calling
create()on a draft returns a result whose unchanged values are objects of the base state, so writing to them after the result is assigned back changes the base state. #187 then proposed an opt-incloneDraftBaseoption that deep-copies such a base before drafting it. Measuring the pattern of #160 showed that users do not need the option, and that it is not the approach to recommend:create()only on other values, leaves the base state unchanged and keeps the references of the values it does not change, without any option. It is also the fastest approach below.create()a deep copy itself:create(structuredClone(current(draft)), recipe)does what the option did.makeCreator(), so it could not reach helpers in other packages that importcreate. It would have added a permanent v2 API, 55 B and an error-driven retry insidecreate()for what one line in a helper does.This PR documents both patterns instead; the library code is unchanged.
Changes
docs: recommend helpers that change a draft in place for create() on a draft. README andcreate.md: the "create() on a draft" section now states the problem and shows its example first. It then recommends a helper that changes a draft in place, noting that it changes the outer draft even if the caller discards its result. The other ways follow: make such changes in the helper's recipe or through the outer draft; givecreate()a deep copy withcreate(structuredClone(current(draft)), recipe), which costs a copy per call and new references for unchanged values, whilestructuredCloneturns class instances into plain objects and throws on functions; and enableenableAutoFreezein development.Measurements
The pattern of #160 runs over 1,000 nodes:
draft.nodes = draft.nodes.map(...)with a helper that renames each node, then a write to the helper's result. The table shows the median time in ms, from one process per approach over 3 rounds, onmain:create()on the draft (changes the base state)create()a deep copy of the draftproduce, auto-freeze off / onVerification
strict. Run againstmainin the reproduction of Nested create() on draft element shares references with original base object #160, both leave the base state unchanged and produce the expected state. The in-place helper also keeps the untouched nodes' references, and it works on values outside a recipe.