feat(zql): make applyChange immutable for React.memo optimization

[Karavil]

Immutable applyChange with O(N + K) Batching

Makes applyChange return new objects instead of mutating in place. Unchanged rows keep their object reference, changed rows get new references. This lets React.memo and Solid reactivity actually work.

Right now Zero deep clones every snapshot because applyChange mutates in place. Every row gets a new reference on every sync, even if nothing changed.

Current behavior (mutable + deepClone):

  DB: UPDATE row A         Consumer receives snapshot
  ┌──────────────┐         ┌──────────────────────────┐
  │ A = "new"    │         │ A' ← new ref (changed)   │
  │ B = "same"   │  ────►  │ B' ← new ref (unchanged) │  ← React.memo fails
  │ C = "same"   │         │ C' ← new ref (unchanged) │  ← everything re-renders
  └──────────────┘         └──────────────────────────┘

With immutable applyChange, unchanged rows keep their reference:

New behavior (immutable):

  DB: UPDATE row A         Consumer receives snapshot
  ┌──────────────┐         ┌──────────────────────────┐
  │ A = "new"    │         │ A' ← new ref (changed)   │  ← re-render
  │ B = "same"   │  ────►  │ B  ← same ref            │  ← memo skips
  │ C = "same"   │         │ C  ← same ref            │  ← memo skips
  └──────────────┘         └──────────────────────────┘

Performance

Started with a naive immutable implementation. @tantaman pointed out it was O(K × N) for K changes to an N-item array:

Naive immutable (O(K × N)):

  push(change₁) ──► [...array]  ─┐
  push(change₂) ──► [...array]   │  K rebuilds
  push(change₃) ──► [...array]   │  of N items
  ...                            │
  push(changeₖ) ──► [...array]  ─┘

Ran benchmarks, it was ~4x slower at scale. Still under 0.1ms but felt like we could do better.

Tried batching but hit a blocker: tests expected .data to reflect changes immediately after push(). Solution: auto-flush in the .data getter.

Batched immutable (O(N + K)):

  push(change₁) ──► buffer  ─┐
  push(change₂) ──► buffer   │  O(K) to buffer
  push(change₃) ──► buffer   │
  ...                        │
  push(changeₖ) ──► buffer  ─┘
                     │
                     ▼
  flush() ─────► sorted merge ──► one new array
                     │
              O(N + K log K)

The .data getter auto-flushes if there are pending changes, so existing code just works.

Benchmarks (time in ms):

  N=2000, K=200
  ─────────────────────────────────────────────────────────
  Mutable O(K)      │████████████████████████  0.023ms
  Immutable O(K×N)  │████████████████████████████████████████████████████████  0.109ms
  Batched O(N+K)    │███████████████  0.015ms  ◄── faster than mutable!
  ─────────────────────────────────────────────────────────

At larger scales batched beats mutable because we do not have to copy the objects over and
over

Changes

applyChange()
├── returns Entry instead of void
├── uses toSpliced()/with() for immutable array ops
└── uses spread for immutable object ops

ArrayView
├── push() buffers changes
├── flush() applies in one sorted merge pass
└── .data getter auto-flushes for backwards compat

Consumers
├── React: removes deepClone
└── Solid: uses produce with in-place mutation

Manual Testing: React (zbugs)

To verify React.memo actually works with stable references, I modified zbugs' list page:

1. Extracted IssueRow outside the component and wrapped with React.memo
2. Added custom comparator (default shallow compare fails because style is new object each render)
3. Added render count tracking to each row

const areIssueRowPropsEqual = (prev, next) => {
  if (prev.issue !== next.issue) return false;           // reference check
  if (prev.style?.transform !== next.style?.transform)   // value check
    return false;
  // ... other props
  return true;
};

const IssueRow = memo(function IssueRow({ issue, style, ... }) {
  // render count tracking for testing
}, areIssueRowPropsEqual);

Then ran the app and updated rows directly via psql while watching console:

┌───────────────────────────────────────────────────────────────────────┐
│ Test 1: Update title only (no sort position change)                   │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  psql> UPDATE issue SET title = 'TITLE ONLY UPDATE'                   │
│        WHERE id = '_6cIk1pH24n6nmJ5sI6Ar';                            │
│                                                                       │
│  Console output after Zero sync:                                      │
│  ┌───────────────────────────────────────────────────────────────┐    │
│  │ [render #3] IssueRow: _6cIk1pH - "TITLE ONLY UPDATE"          │    │
│  │                                              (sameRef: false) │    │
│  └───────────────────────────────────────────────────────────────┘    │
│                                                                       │
│  Result: ONLY the updated row re-rendered. Other 99 rows skipped.     │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────┐
│ Test 2: Update title + modified (causes sort position change)         │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  psql> UPDATE issue SET title = 'POSITION CHANGE',                    │
│                         modified = 1769210037000                      │
│        WHERE id = 'dSHOxE86nkbGafajdd1ew';                            │
│                                                                       │
│  Console output after Zero sync:                                      │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │ [render #3] IssueRow: dSHOxE86 - "POSITION CHANGE"             │   │
│  │ [render #3] IssueRow: oGP3NonM - "Some other issue"            │   │
│  └────────────────────────────────────────────────────────────────┘   │
│                                                                       │
│  Result: Updated row + displaced row re-rendered. Expected behavior   │
│  since style.transform changed for rows that moved.                   │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

Key insight: Zero maintains stable object references for unchanged issues. The sameRef: true/false logging confirmed this. When only the title changes, that row gets a new reference, but all other rows keep their original reference.

Manual Testing: Solid (zbugs-lite-solid)

(this is no longer part of the PR)

Created a minimal Solid app that imports Zero schema/queries from zbugs. Added render count badges to each row.

┌────────────────────────────────────────────────────────────────────────┐
│ Test: Update one issue while watching render counts                    │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  psql> UPDATE issue SET title = 'MODIFIED BY PSQL'                     │
│        WHERE id = 'HdpMkgbH...';                                       │
│                                                                        │
│  Before:                          After:                               │
│  ┌──────────────────────────┐    ┌──────────────────────────┐          │
│  │ [1] Leaking listeners... │    │ [1] MODIFIED BY PSQL     │ ← +0     │
│  │ [1] Sort and remove...   │    │ [1] Sort and remove...   │          │
│  │ [1] UnknownError: Int... │    │ [1] UnknownError: Int... │          │
│  │ [1] Fix: race condition  │    │ [1] Fix: race condition  │          │
│  │ [1] Add support for...   │    │ [1] Add support for...   │          │
│  └──────────────────────────┘    └──────────────────────────┘          │
│                                                                        │
│  Items keep their reference so Solid never rerenders.                  │
│  All other rows stayed at 1.                                           │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Solid's fine-grained reactivity handles the in-place updates efficiently via produce. No special memo config needed.

Related

• Follows up on feat(zero-react): add select option to useQuery for selective re-renders #5455
• Revives wip(zero-client): Immutable apply change #3688 (original immutable attempt)
• Fixes zero/3036

[vercel]

Someone is attempting to deploy a commit to the Rocicorp Team on Vercel.

A member of the Team first needs to authorize it.

[aboodman]

Thanks, amazing. Have you actually done the manual test yet?

This is going to require careful review. These files are super sensitive and have been a source of subtle bugs in the past. One of us is going to have to set aside a few hours to work through it. Maybe next week?

Appreciate the contribution.

[Karavil]

Thanks, amazing. Have you actually done the manual test yet?

This is going to require careful review. These files are super sensitive and have been a source of subtle bugs in the past. One of us is going to have to set aside a few hours to work through it. Maybe next week?

Appreciate the contribution.

Nope, was giving this a shot using Ralph loop and Claude hahaha. Not ready for review yet! Will do manual reviews. I'm not super comfortable with Solid so it definitely needs some testing on that front (there are bits in the code that I don't understand too well).

[tantaman]

How does this handle the case where every single row changes? Does it intelligently replace the view or does it path-copy for every single modification? It looks like it does the latter.

On a quick scan (didn't think too hard since the PR is still draft), it looks like the current PR is in this situation --

The parent spreads at each level:

  return {...parentEntry, [relationship]: newView};                                                                         

So for a single change at depth D in a tree with array sizes N₁, N₂, ... Nᴅ:

• Old: O(1) mutation at leaf
• New: O(N₁) + O(N₂) + ... + O(Nᴅ) array copies up the path

For K changes in one transaction, each touching the same level-1 array of size N:

• Old: O(K) mutations + O(total_nodes) deep clone
• New: O(K × N) array copies

[Karavil]

How does this handle the case where every single row changes? Does it intelligently replace the view or does it path-copy for every single modification? It looks like it does the latter.

On a quick scan (didn't think too hard since the PR is still draft), it looks like the current PR is in this situation --

The parent spreads at each level:

  return {...parentEntry, [relationship]: newView};                                                                         

So for a single change at depth D in a tree with array sizes N₁, N₂, ... Nᴅ:

• Old: O(1) mutation at leaf
• New: O(N₁) + O(N₂) + ... + O(Nᴅ) array copies up the path

For K changes in one transaction, each touching the same level-1 array of size N:

• Old: O(K) mutations + O(total_nodes) deep clone
• New: O(K × N) array copies

Ah, good point! I think I can optimize this by batching mutations.

[Karavil]

How does this handle the case where every single row changes? Does it intelligently replace the view or does it path-copy for every single modification? It looks like it does the latter.

For K changes in one transaction, each touching the same level-1 array of size N:

• Old: O(K) mutations + O(total_nodes) deep clone
• New: O(K × N) array copies

I tried to implement batching to get O(N + K) complexity but ran into a blocker.

The issue is that .data seems to be expected to return current state immediately after push(). Found tests doing this:

consume(source.push({type: 'add', ...}));
expect(view.data).toEqual(...);  // no flush() call

True batching would mean .data is stale until flush(), which feels like a breaking change. Maybe there's a way around this I'm not seeing?

That said, I ran some benchmarks and the O(K × N) cost might be fine in practice:

Scenario	Mutable	Immutable	Ratio
N=100, K=10	0.001ms	0.001ms	1.1x
N=500, K=50	0.003ms	0.005ms	1.8x
N=1000, K=100	0.008ms	0.019ms	2.5x
N=2000, K=200	0.024ms	0.097ms	4.1x

Even the worst case (N=2000, K=200) is under 0.1ms, which is way under the 16ms frame budget. On a slow device (10x multiplier), still under 1ms.

The upside is that immutability preserves reference identity for unchanged items, so React.memo / Solid reactivity can skip re-rendering rows that didn't change. Not sure if that fully justifies the complexity tradeoff, but it seems reasonable?

[Karavil]

Hey @tantaman, figured out a way to make batching work!

Added an auto-flush safety net in the .data getter so existing code still works (reads trigger flush if there are pending changes). This means:

• push() buffers changes
• flush() applies them all in one O(N + K) pass
• .data auto-flushes for backwards compatibility

Ran benchmarks comparing all 3 approaches:

N, K	1. Mutable O(K)	2. Imm O(K×N)	3. Batched O(N+K)
100, 10	0.000ms	0.001ms	0.003ms
500, 50	0.003ms	0.006ms	0.003ms
1000, 100	0.007ms	0.020ms	0.007ms
2000, 200	0.023ms	0.109ms	0.015ms

At larger scales the batched approach actually beats mutable because it avoids K splice operations that each shift elements. Wasn't expecting that!

All 2202 zql tests pass with the new implementation.

[arv]

Update:

@Karavil @grgbkr I added the flag to applyChange.

I updated the types and the tests.

I need to go back to the old SolidJS behavior.

[arv]

CleanShot.2026-02-12.at.10.54.15.mp4

This works great. Look at those render counts!!!

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
replicache-docs	Ready	Preview, Comment	Feb 12, 2026 4:26pm
zbugs	Ready	Preview	Feb 12, 2026 4:26pm

[arv]

@devagrawal09 FYI

[devagrawal09]

Thanks for the ping @arv. Happy to see that the produce mutate behavior is intact for optimal performance with Solid.