Skip to content

Store: replace ReadWriteNode/UnfrozenInternalNode with plain nodes, hidden state and a dirty-read lock - #6063

Open
William Wong (compulim) with Copilot wants to merge 7 commits into
feat-new-storefrom
copilot/simplify-node-structures
Open

William Wong (compulim) with Copilot wants to merge 7 commits into
feat-new-storefrom
copilot/simplify-node-structures

Conversation

Copilot AI commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

The node model from #6053 had three kinds of node: FrozenInternalNode, UnfrozenInternalNode and the ReadWriteNode class. Repeated upserts on a large parent also cost O(children) per call. This PR keeps nodes plain at every boundary userland sees. Store-only data goes into hidden private fields, and hasPart/isPartOf are updated by delta instead of being recomputed.

Node model

  • Plain nodes everywhere.
    • The graph holds frozen plain objects (FrozenInternalNode).
    • createNode() returns DraftNode (renamed from UnfrozenInternalNode): validated, with deep-frozen values, but the object itself is not frozen.
  • private/draft.ts replaces the ReadWriteNode class with a plain Draft record plus functions:
    • createDraft, readDraft, commitDraft, setDraftPartOf, removeDraftReferencesTo, getDraftReferenceIds.
    • commitDraft freezes an owned node in place when possible. Otherwise it rebuilds the node in one O(properties) pass (no delete), keeps key order, and reuses a FrozenNodeSet whose IDs haven't changed.
  • private/hiddenNodeState.ts stores the cached dateCreated time and sorted children as private fields, using the constructor-return trick.
    • They are invisible to Object.keys, spread and JSON.stringify.
    • If the stamp is lost (e.g. userland returns a JSON.parse(JSON.stringify(node)) clone), getDateCreatedTime() re-parses dateCreated.
    • Private fields benchmarked about 5× faster than a symbol property to attach (npm run benchmark:node).
  • Removed: ReadWriteNode, freezeNode, dateCreatedTime.ts and the symbol-based sorted-children getter.

upsert() semantics

  • Reads inside an updater:
    • First read of a node in a transaction (clean read): the frozen node from the graph.
    • Later reads in the same transaction (dirty read): a new plain copy with the transaction's changes.
    • In both cases the node is frozen in finally, so it can only be changed inside its own updater.
  • No upsert() / delete() inside an updater. Nested calls throw before any state changes.
    • The ban also covers code that runs while the store reads the returned object (getters, proxies).
    • Reading committed state (getSnapshot() etc.) is still allowed.
  • Identity fast paths. If the updater returns the same hasPart / isPartOf it received, the store skips validating and diffing them. The nesting ban is what makes this safe: the sets shown to the updater are still current when it returns.
  • Child sets without copying. The live child set is finalized and a new working copy is started on top, at O(changes) instead of the old O(children) copy.
transaction.upsert(id, node => ({ ...node, text: ['Hi'] }));          // keeps the same hasPart: O(1)
transaction.upsert(id, node => {                                        // second read: writable here only
  node.isPartOf = new Set(node.isPartOf).add({ '@id': '_:other' });
  return node;
});

createNode

  • Throws if a node, a property-value item or a node reference has toJSON(), own or inherited. toJSON() is still called inside a JSON literal's @value.
  • hasPart / isPartOf that are already a FrozenNodeSet skip valibot validation and are reused as-is (about 300 µs saved per 1,000 parts).

Benchmarks

New store-level rows in benchmark.ts, plus a new benchmark.node.ts (npm run benchmark:node):

Benchmark (100k nodes) Before After
Update parent (µs/op) 88,279 12
Repeat upsert (µs/op) 104,658 9
Mirror churn (µs/op) 144,482 24

Other rows (Append, Random, Delete, Iterate, identifier rows, memory per node) are unchanged or slightly better. "Update parent add one" is still O(N), because the updater copies hasPart itself with new Set(...).

Trade-offs for review

  • A later read in the same transaction always copies the node, at O(properties).
  • Child sets are finalized mid-transaction. If the transaction then fails, the next commit that touches one of them pays a one-time O(size) copy.
  • A node's references are not cached in the Draft; they are recomputed on every change at O(properties).

OPINIONS.md now documents the toJSON rule, the dirty-read lock and the hidden-state rebuild.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…-field state, dirty-read lock, toJSON rejection

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants