Implement Throttled Update Notifications for Query Reactivity

[KyleAMathews]

Problem

Currently, every mutation or sync triggers immediate reactivity and query invalidation.
In high-update scenarios (e.g., rapid optimistic updates, bulk sync events), this causes excessive re-rendering, layout thrashing, degraded scroll performance, and input lag.

Debouncing is not suitable because it would delay the first user-driven update, breaking perceived responsiveness.

Optimistic updates must render immediately. Only subsequent updates need rate limiting.

Proposed Solution

Introduce throttling of query invalidation and reactivity notifications.

Behavior

• First mutation immediately triggers query reactivity.
• Subsequent mutations within the throttle window are grouped.
• Only one re-render is allowed per throttle window.
• After the throttle window expires, if additional mutations occurred, flush once and reopen the window.

Default Settings

• Target: 120fps smoothness.
• Frame budget: 8.3333ms per frame.
• Default throttle interval: 8.3333ms.

API Design

Global configuration:

configureDb({
  updateThrottling: {
    intervalMs: 8.3333
  }
});

Optional per-query override:

const { results } = useDb()
  .from('posts')
  .withUpdateThrottling({ intervalMs: 16 }) // e.g., throttle to 60fps if desired
  .get();

Design Principles

• Store mutations always apply immediately.
• Only reactivity and re-rendering are throttled.
• Optimistic updates behave identically to server sync updates with respect to throttling.
• No observable data inconsistency.

Constraints

• No batching or throttling in strict testing mode to preserve determinism.
• Throttle window must be precisely timed.
• Throttling must be fully internal; developers should not manage timers manually.

Future Work

• Adaptive throttling based on device performance or application state.
• Metrics collection for mutation vs render rates to optimize default settings.

[samwillis]

I don't think this should be on by default. It inherently results in the query results becoming asynchronous which in React can cause issues if you are binding an input (such as a text input) to a collection value. I would caution against making a collection, or db/global config for that reason, it would have side effects if not on initially, and then turned on later.

[KyleAMathews]

It'd be throttling so the initial result is always sync still and follow on results are also sync unless it's been less than the intervalMs setting.

But agree it should probably be off by default. Also no need to implement this for a while until it's obviously needed