Optimistic atomic increment on the useQuery hook (0.6.0)

[HomemadeToast57]

Why

Counters lag. A live todo (create/update/remove through the hook) is optimistic and instant, but a counter goes through updateMany({ id }, { $inc }), which is atomic but not optimistic and not on the hook. So the number can't move until the server echo returns, and generated code papered over it with a local bump + refetch() (flickers) and a working guard (drops fast taps).

What

bool.entities.<table>.useQuery().increment(id, field, by?) (by defaults to 1):

• bumps the field in the same frame as the tap (optimistic overlay);
• writes atomically as SQL $inc, so simultaneous taps can't lose each other's clicks;
• reads the committed row back before retiring the overlay, so the digit never dips to a stale value;
• rolls back and surfaces the error on failure; never throws.

The overlay is ABSOLUTE, not a delta (this is the load-bearing detail)

The first cut used a +by delta overlay. That double-counts against the private doorbell's echo of your own write: the row-bearing ding lands on server with the committed value while the delta is still up, so it adds on top — 0 → 1 → 2 → 1, worse the faster you tap. Caught in live testing, not by the initial unit tests. The fix stores the absolute optimistic value (current + by) and SETs the field in emit, exactly like update's overlay, so it stays idempotent with both the echo and the read-back. current is read from the live snapshot, so rapid unsettled taps still stack.

On the read-back

Each increment does the $inc then a keyed filter read-back before dropping the overlay. The doorbell echo also settles server, so the read-back is close to redundant — it exists to avoid a brief dip in the ~100ms before the echo lands. Deliberate tradeoff (one extra GET vs a visible dip); flagging it for review.

Tests

bun test: 201 pass. New in live.test.ts: optimistic bump with no double-count, rapid taps summing atomically, rollback on failure, and a regression that fires a mid-flight doorbell echo and asserts no double-count. Typecheck + build clean.

Verified live

Confirmed end to end on a preview: a fresh counter on the fixed prerelease climbs cleanly on fast clicks with no bounce (the delta version bounced through 2). Additive; the realtime engine (doorbell, LiveEntityStore merge, create/update/remove) is untouched.

Rollout

The bool-side follow-up (seed ^0.6.0, teach increment, gate it on isIncrementCapableSdkSpec) is codehs/bool#1063, which is blocked on this shipping to latest. Order: merge this → cut v0.6.0 release (publishes latest) → un-draft and merge bool#1063.

🤖 Generated with Claude Code