Context​

A flush takes the source mutations that accumulated since the last flush and settles everything that depends on them. Sources are the inputs — a user typed, a request resolved, code called upsert. Anything that happens while the flush runs is downstream of those inputs.

Problem​

The tempting shortcut is to reprocess whatever gets enqueued mid-flush in the same flush. It rests on a category error: that a value written during the batch might be new input. It never is. Walk the cases:

• "When X changes, set Y." Y is a function of X — that is denormalization, and the thing that turns one value into another is a computed. Written as an imperative effect, it's a computed you haven't named. Re-drained in place, it thrashes (recomputes once per source-mutation) and can run on a half-updated graph — a glitch (why computed values wait for the flush).
• An async result. It isn't in this batch at all — the response lands later, as its own event, starting its own flush. The effect in this batch only kicks off the I/O; the write happens in a future round.
• The current time, a random value. These are genuinely new information — so they are inputs. If Y = X × now(), you have two inputs, X and now, and Y is a computed of both. You model the clock as a source, not as an imperative write buried in an effect.

Every route ends in the same place: what arises during the batch is a derivation. New input always arrives as its own event, in its own batch.

Options​

• Re-drain mid-flush enqueues in place. Treats derivations as inputs — thrash, glitches, and writes that feed themselves with no bounded end.
• Recompute derivations eagerly, per mutation. Redundant recomputes and glitches on every shared descendant.
• Settle derivations once, after the sources are fixed, in dependency order. Each derived value recomputes once; new source truth only ever comes from the next batch.

What OIMDB does​

The third. The compute runtime recomputes dirty computeds once each, parents before children, by graph level, at the flush boundary. A chain A → B → C collapses in one ordered pass; a value with three dirty inputs recomputes once.

And the queue defends the boundary. If code does write a source inside an effect — a computed that wasn't named — a double-buffered swap sends that write's notification to the next flush, not this one. The mismodeled write can't cascade in place; the current flush stays bounded. The fix is still to make it a computed, but the queue won't let it melt down in the meantime.

Cost​

One mental model to hold: the batch settles at the flush boundary, not at the instant of each write. A source you write in an effect is in the store immediately but doesn't notify until the next flush, so a subscriber won't have reacted synchronously. And the tell is simple — if you're writing a source inside an effect, you've found a computed you haven't named yet.

Where it lives​

• packages/core/src/modules/compute/core/OIMComputeRuntime.ts, .../computed/core/OIMComputed.ts — level-ordered, recompute-once-per-flush derivation.
• packages/core/src/core/OIMEventQueue.ts — double-buffered drain; a source write during a flush defers to the next.

Context​

An OIMComputed or OIMEffect declares its dependencies explicitly — deps: [...] — fixed at construction and never changing. That single constraint is what the rest of this rests on.

The alternative is autotracking (Jotai, Solid, MobX): a node's dependencies are discovered by running its compute and recording which sources it read. Deps aren't known until the node runs, and they can differ run to run (cond ? get(a) : get(b)).

Problem​

To avoid glitches and redundant recomputes (why computed values wait for the flush), the runtime must recompute dirty nodes parents-first — in topological order. Someone has to produce that order.

With dynamic deps you can't know it ahead of time, and it can change, so you rebuild it on every propagation: collect the dirty dependents, count in-degrees within that subgraph, drain the zero-in-degree ones first (Kahn's algorithm). That is a topological sort per write, scaling with the affected subgraph.

With static deps the edges never move — so the order never moves either.

Options​

The axis is where the ordering work lives.

• Dynamic deps, sort per write. Maximum flexibility — conditional dependencies, edges that appear and vanish. Pays a topological sort on every propagation, and can precompute nothing.
• Static deps, recompute the order each flush. Throwing away the fact that edges are fixed — the same per-flush sort cost for no reason.
• Static deps, precompute levels once. A node's level = one above the max of its dependencies' levels, derived at construction. The runtime never sorts: it buckets scheduled nodes by level and drains 0 → N. Ordering cost at flush time is zero; the price is that deps can't change at runtime.

What OIMDB does​

The third. When a computed is built, the engine derives its level from its dependencies — which were built earlier, so their levels already exist — and stores it. Levels live in the runtime: the engine owns them, nodes don't carry them.

At a flush, an invalidated node schedules itself at its level into an array indexed by level (levels are dense small integers — direct index, no hashing, unlike a map), and the runtime drains ascending. The per-level buckets are pooled Sets, cleared between flushes rather than reallocated. The hot path is an array index and a drain — no sort, no per-node lookup, no allocation.

Two things fall out of static levels that a per-write approach doesn't get for free:

• The deep-uneven glitch disappears. A node that depends on both a shallow ancestor A and a deep one D (with D several levels below A) is scheduled the instant A fires — but it lands in its own high bucket and waits until D's level has drained. It reads D fresh, exactly once. Without levels it would run early in A's wave and read a stale D — a glitch that lazy pull-on-read doesn't catch, because D isn't even marked dirty yet.

• Turning the levels on was nearly free at runtime. Flipping the scheduler from "everything at level 0, let lazy pulls sort out the order" to "each node at its real depth" removed the redundant reschedules and out-of-order pulls; the array-by-level removed the map hashing. On the compute benchmarks that was roughly +78% on a diamond graph and +24% on a depth-50 chain — for a change that only moved work to construction time.

Cost​

Dependencies are fixed. No get(cond) ? get(a) : get(b) — a node can't grow or drop a dependency at runtime. If a value genuinely depends on different sources at different times, you declare the union and branch inside compute, or rebuild the node. You trade the flexibility of autotracking for a runtime with no per-update ordering work and a deterministic pass — and levels you compute once instead of re-deriving on every write.

Where it lives​

• packages/core/src/modules/compute/core/OIMComputeRuntime.ts — computeLevel / registerLevel / getLevel, and the array-by-level drain with pooled sets.
• packages/core/src/modules/computed/core/OIMComputed.ts, .../effect/core/OIMEffect.ts — declare deps; level derived from the runtime at construction.
• packages/core/src/dx/on.ts, .../dx/OIMCollectionKit.ts — on.* + kit.computed / kit.effect build the static graph without hand-wiring dependencies.

Context​

OIMCarrierKeyedEmitter is the per-key pub/sub behind collections and indexes. Handlers live on the carrier — the collection's entity slot, or the index's bucket (see handlers on the carrier). On a write the changed carrier is marked dirty; on queue.flush() the batch of dirty carriers is delivered once.

Problem​

Marking a carrier dirty runs on every mutation — the hottest write-path op, and far more frequent than flushes. The batch has to dedup: a carrier written ten times in one tick must be delivered once.

Options​

• Set<carrier> — set.add(carrier) computes the carrier's identity hash, probes the set's table, inserts. Membership and dedup come for free.
• flag + array — if (carrier.dirty) return; carrier.dirty = true; arr.push(carrier). Dedup is a boolean read, membership lives on the carrier itself, append is an array push.

What OIMDB does​

Flag + array:

if (carrier.dirty) return;        // already in the batch
carrier.dirty = true;
this.dirtyCarriers.push(carrier);

The flag is reset as each carrier is delivered, leaving it re-markable next tick.

Microbench — 1000 carriers, marked + iterated over 20,000 flushes (20M mark cycles), reused containers:

~4.3× (all dirty), ~4.8× (sparse). The gap is the identity-hash that Set.add runs on every mark and the array push skips.

This measures the batching primitive in isolation — mark + iterate, nothing else. A real write does more around it (apply the patch, schedule the flush), so the dirty-batch op is a fraction of one write, not 4× of end-to-end write time. The point is that it's a fraction paid on every mutation while flushes are rare, so shaving the per-mark constant compounds.

Cost​

The flag is shared mutable state with an invariant: carrier.dirty === true iff the carrier is in dirtyCarriers. Break it and you either drop updates (flag stuck true → future marks skipped) or double-deliver. A Set needs none of this — removal from the batch is implicit.

Holding the invariant when a handler throws mid-flush takes explicit cleanup: delivery resets the flags of any carriers it never reached.

} finally {
    for (; i < flushing.length; i++) flushing[i].dirty = false;
}

Where it lives​

packages/core/src/core/OIMCarrierKeyedEmitter.ts

Context​

OIMEventQueue batches one-shot tasks: emitters and the store enqueue a flush task, and flush() runs the batch. Every reactive write enqueues, so enqueue is a hot-path op — and tasks must be cancellable, because an emitter torn down before flush has to drop its pending task.

Problem​

A cancellable enqueue has to give the caller some way to cancel. The usual shapes allocate. Returning a disposer closure is one function object per call; wrapping the task so the queue can flip a "cancelled" flag on it is another — plus the GC of discarding them when the task runs. Most callers never cancel, so on a hot path that allocation is mostly waste.

Options​

• Return a disposer closure (enqueue(fn): () => void) — ergonomic, callers hold one handle. Allocates a closure per call whether or not anyone cancels.
• Wrap the task to carry cancel state — store { fn, cancelled } instead of fn; cancel flips cancelled and the drain skips it, so cancel never has to locate and delete an entry. But the wrapper is an allocation per enqueue (the very tax this is trying to avoid), and the stored object is no longer the caller's fn, so identity-based dedup is lost.
• Store the function reference, cancel by reference — enqueue(fn) adds fn to a Set; cancel(fn) deletes it. No wrapper, no returned closure; dedup falls out of Set identity. The caller must keep the reference to cancel.

What OIMDB does​

Store the reference, cancel by reference:

public enqueue(fn: () => void): void {
    this.tasks.add(fn);
    this.ensureScheduled();
}

public cancel(fn: () => void): void {
    this.tasks.delete(fn);
    this.flushing?.delete(fn);
}

Zero allocation per enqueue, and idempotent — the same fn enqueued twice runs once, because the Set keys on identity. Each emitter holds one stable onFlush method and enqueues that, so its scheduling dedup is just the Set.

The disposer-closure shape against the by-reference one (3M iterations, no-op task — so this isolates queue overhead, not task work):

The gap (~0.05–0.07 µs) is the closure the call no longer allocates. By-reference reads the same for cancel and flush because the task is a no-op: at this resolution the closure alloc is the only thing that moves, so removing it flattens both columns to the bare Set op.

Cost​

Cancellation needs the caller to hold the original reference and pass the same one back — there is no opaque handle to lean on. Callers that enqueue a stable bound method already have it; it is only a sharper edge for code that wanted a disposer to stash.

Where it lives​

packages/core/src/core/OIMEventQueue.ts

Context​

OIMComputed nodes and effects form a dependency graph driven by OIMComputeRuntime. A write to a source marks its dependents dirty; the runtime is what decides when and in what order they recompute.

Problem​

The classic diamond. A synchronous, push-on-write graph propagates a change to A's dependents in stored order: A → B → D, then A → C → D. The first path recomputes D while C still holds its old value. D runs twice, and its first run produces a value computed from a half-updated graph — one that never should have existed. Eager subscribers see that ghost. The deeper the graph, the more shared descendants multiply both the redundant work and the inconsistent snapshots flowing downstream.

Options​

Judge each on the diamond's two failure modes — glitches (a node runs on a stale parent) and redundant recompute — plus how subscribers get told to run.

• Synchronous push — recompute a node the instant any input changes. Hits both failures: D recomputes once per path (twice) and emits the half-updated value in between. Subscribers fire eagerly, so they see the glitch too. Cheapest to build, wrong on every shared descendant.
• Mark-dirty + pull on read — invalidate eagerly, recompute lazily when something reads. Removes the redundant recompute and the glitch for code that pulls. But effects and subscribers don't pull — they must be told when to run; pure pull leaves that undefined (who reads, and when?).
• Batched, level-ordered recompute — mark dirty on write, then at a flush boundary recompute the dirty nodes once, parents before children. No glitch (a child never runs on a stale parent), no redundant recompute (each node once), and it still pushes, so effects keep a defined firing point. Costs a flush boundary and a topological scheduler.

What OIMDB does​

The third. Writes mark dependents dirty and schedule them on OIMComputeRuntime, bucketed by level (graph depth). On the queue's AFTER_FLUSH boundary the runtime drains levels in ascending order — every parent settles before any child runs — and each node recomputes once per flush. In the diamond, D runs a single time, after both B and C are current.

All three on the same workload. The metric here is recompute count — how many times nodes re-run for one source update, on stacked diamonds (each layer adds a diamond over the previous tip). Count, not time, because that's what separates the options: it's both the wasted work and the number of glitch windows a subscriber could observe.

Sync push ≈2ᵈᵉᵖᵗʰ — every shared descendant re-fires once per path, and each extra recompute is a glitch. Pull-on-read and batched are both linear (~3 per diamond); they do the same work. So the choice between them is not count — it's delivery: batched pushes to subscribers, giving effects a defined firing point, while pull leaves "when does the effect run" to whoever happens to read.

Separately, the wall cost of a single recompute (the time dimension, not the count) is ~1.6 µs — so batched at depth 10, ~31 recomputes, is ≈ 50 µs total against sync push's 4,092 ≈ 6.5 ms.

.get() is the escape hatch: a direct read calls recomputeAndEmitIfChanged() on the spot, so an imperative read is always live. Only delivery to subscribers waits for the flush.

Cost​

Subscribers observe values at flush boundaries, not at the instant of the write — a mental model to internalize ("the graph settles on flush"). Code that writes and synchronously expects a subscriber to have fired will be surprised, and imperative .get() (live) and push delivery (deferred) are two timing contracts on the same value.

Where it lives​

• packages/core/src/modules/compute/core/OIMComputeRuntime.ts — level-ordered scheduler, AFTER_FLUSH drain.
• packages/core/src/modules/computed/core/OIMComputed.ts — dirty-tracking, compare-gated emit, live .get().
• packages/core/src/modules/effect/core/OIMEffect.ts — schedule-once-per-invalidation.

Context​

OIMCarrierKeyedEmitter delivers per key: subscribe to pk 42, get notified when 42 changes. It backs every reactive collection and index. The textbook layout is Map<key, Set<handler>>.

Problem​

The hot path is marking a changed key dirty — it runs on every mutation. With a map that means hash the key, look up the bucket, check it exists. But the writer that mutated the entity already holds the entity object: it just paid to find the entity, and now pays again to find that entity's subscribers by key.

Options​

• Map<key, Set<handler>> in the emitter — self-contained; carriers know nothing about subscriptions. Every mark and every delivery is a key hash + map lookup, even though the caller already holds the changed object.
• Subscribers on the carrier — the entity slot (collection) or bucket (index) carries its own subscribers set. The writer holds the carrier, so markUpdatedCarrier(carrier) reads carrier.subscribers directly — no hash, no lookup.

What OIMDB does​

Subscribers live on the carrier (IOIMSubscribable), and the fast mark path never touches a map:

public markUpdatedCarrier(carrier: TCarrier): void {
    this.assertNotInFlush();
    const subscribers = carrier.subscribers;
    if (!subscribers || subscribers.size === 0) return;
    if (carrier.dirty) return;
    carrier.dirty = true;
    this.dirtyCarriers.push(carrier);
    this.scheduleFlush();
}

When only a key is available, markUpdatedKey resolves the carrier through an IOIMCarrierResolver.

Two numbers, because the micro-win and the end-to-end win are different sizes. In isolation — just the dispatch, nothing around it — the carrier emitter is 55–68% faster per key than the Map<key, handlers> emitter (option A); the range is across key-set sizes (the bigger the map, the more the saved hash+lookup is worth). But dispatch is a small slice of a real operation, so the number that matters end-to-end is the second: inside a full index write, delivery is ~14% of total time with the map emitter and ~0–3% with the carrier one. Membership bookkeeping, not delivery, dominates the rest — so once delivery is near-free, little is left to shave, and the 55–68% does not translate into a 55–68% faster operation.

Cost​

The emitter is no longer self-contained: it depends on carrier objects and a resolver. The index case, where the carrier is a standalone per-key object, reintroduces a Map<key, carrier> plus an onCarrierEmptied hook to prune carriers whose last subscriber left — without it a churning key space leaks carriers. A uniform data structure is traded for a faster one whose correctness depends on prune callbacks firing.

Where it lives​

packages/core/src/core/OIMCarrierKeyedEmitter.ts, packages/core/src/types/IOIMSubscribable.ts, packages/core/src/core/OIMKeyedCarrierResolver.ts

Context​

An index maps a key (say teamId) to the entities under it. Each bucket stores slots — { pk, item } wrappers shared with the collection — so a read returns either the pks (getPksByKey) or the entities (getEntitiesByKey).

Problem​

An index bucket holds slots { pk, item }; item is undefined when the pk is reserved but its entity hasn't arrived yet (or was removed) — e.g. message ids indexed before the bodies load.

On read, dropping the empty slots makes the entity array shorter than the pk array, so position N no longer matches. That breaks any index→row mapping (virtual lists).

Options​

• Compaction — drop empty slots. Breaks positional alignment, hides "loading".
• Throw / filter at the boundary — pushes an existence check onto every caller, still loses position.
• Holes — one entry per slot, undefined where absent. Stays 1:1 with the pks (LEFT JOIN → NULLs).

What OIMDB does​

OIMIndex.slotsToEntities pushes slot.item for every slot, including the undefined ones. So getPksByKey(key)[i] and getEntitiesByKey(key)[i] are the same row: a virtual list renders pks.length rows and shows a skeleton where the entity is undefined.

The non-obvious payoff is that the hole is the loading signal. The instinct — and what a normalizer returning "the entities for this key" usually does — is to surface only the entities that exist. That quietly throws away two things: the row's position, and the fact that the row exists but hasn't loaded yet. With holes the index doubles as a presence map: a known pk with no entity is exactly a hole, so the consumer needs no parallel "which of these are still loading" structure kept in sync with the list. Position carries the identity (pks[i]), the hole carries the state.

Cost​

Callers must handle undefined — TypeScript forces narrowing, mildly annoying when everything is loaded. The alternative, TEntity[] sometimes shorter than its own key list, loses the alignment and gives no signal about which rows are missing — pushing the caller back to a side structure to track partial loads.

Where it lives​

• packages/core/src/abstract/OIMIndex.ts (slotsToEntities, getEntitiesByKey)
• packages/core/src/types/TOIMEntitySlot.ts (the item: TEntity | undefined slot)

Context​

An entity updater decides how a partial patch is applied to the stored entity on upsertOne. OIMCollection calls it on every write. The decision it encodes is whether the stored object keeps its reference or gets a new one.

Problem​

That single reference decision splits readers, and one strategy can't serve both:

• Reference-comparison readers — React's Object.is / useSyncExternalStore, React.memo, prev/next diffing, time-travel — need a new reference to notice a change.
• Subscription readers — signal hooks that re-read on a keyed notification — want a stable reference and don't compare.

Options​

• Merge — { ...prev, ...draft } — new reference per update, so reference-comparison readers see the change; the previous object is left intact. Costs one allocation + shallow copy per update.
• In-place — Object.assign(prev, draft) — zero allocation, stable reference; reference-comparison readers go blind, and a collection read by both a signal hook and a memoized React tree updates one and not the other.

What OIMDB does​

The default is merge (createMergeEntityUpdater): the common reader is React, where correctness beats a micro-benchmark. In-place is opt-in via createInPlaceEntityUpdater() passed as opts.updateEntity, for collections where every reader is subscription-driven (@oimdb/react's *Signal hooks).

Data-layer cost per update, no React:

The ~0.09 µs gap is the allocation + shallow copy that merge does and in-place skips. Real on update-heavy data layers; invisible under a React commit (~33 µs).

The mean understates in-place's actual point. Merge's per-update allocation is garbage — under sustained high-frequency writes (a streaming feed, a fast tick loop) that's continuous churn the collector has to reclaim, and the cost surfaces as GC pause tail-latency, not in a 0.09 µs average. In-place allocates nothing, so it produces no such garbage. The flat per-op number is the smaller half of the argument.

Cost​

Two updaters with different reference semantics. In-place is faster but fragile — drop it into a tree that relies on Object.is and updates vanish with no error. The footgun is structural: the price of the zero-allocation path.

Where it lives​

• packages/core/src/core/createInPlaceEntityUpdater.ts
• packages/core/src/core/createMergeEntityUpdater.ts
• packages/core/src/core/OIMCollection.ts

Context​

OIMOrderedListCommandStream wraps an ordered index (a slot list per key) and exposes it as a replayable command stream — for imperative or virtual-list renderers that apply edits straight to the DOM.

Problem​

Ordered lists change incrementally: one row inserted, one moved, a span removed. A consumer that wants minimal DOM mutations needs to know what changed, not just that something did. The default reactive shape — "here's the new list, figure out the delta" — forces every consumer to run a list diff (LCS / keyed reconciliation) on every update, which is exactly the work the producer already did when it mutated the list. If the index knows it inserted one slot at position 4, discarding that and making the consumer rediscover it by diffing is wasted information.

Options​

• Emit the whole new list, diff downstream — universal, but every consumer pays diff cost on every change and the producer's edit intent is discarded.
• Emit pk-level diffs (added/removed sets) — cheaper than full diffing, but loses position and order: useless for a move, ambiguous about where an insert lands.
• Emit position-addressed commands — the producer states intent directly: "insert at 4", "move 2→5", "remove 3 from 1". No downstream diffing.

What OIMDB does​

OIMOrderedListCommandStream mutates the underlying ordered index and, per edit, appends the matching TOIMOrderedListCommand, addressed by index. The protocol:

• insert — one element appears at index.
• remove — count elements (default 1, may be > 1) disappear from index.
• move — count elements (default 1) move from from to to.
• set — the element at index is replaced in place (one element, not the list).
• reset — the whole list for the key is replaced by items.

Each writer method (pushSlot, insertSlotAt, removeAt, removeRange, move, moveRange, setSlotAt, setSlots) performs the index mutation and emits the matching command, using the clamped index the mutation actually landed at. Commands buffer per key and deliver once on AFTER_FLUSH.

The axis that decides whether this pays is edit-count vs list-length. Emit-and-diff costs O(list length) per change no matter how small the edit — a reconciler walks the whole list to discover that one row moved. Command replay costs O(edits): one moved row is one move. So the win scales with how big the list is relative to how much of it changes per tick — large list, small incremental edits is where it matters (a 10k-row virtual list nudged by one insert), and it's a wash or worse when most of the list changes at once.

Cost​

Consumers implement a small state machine — replay the protocol against their own list — instead of assigning a new array. That's strictly more consumer code than list = newList, and only some renderers can use it: an imperative/DOM/canvas target that applies edits in place benefits, a React tree that re-renders from a new array gains nothing and still pays the state machine. Whole-list edits also coalesce: a reset supersedes everything buffered before it, and once a batch starts with a reset, later structural edits fold into a fresh reset. So an update that touches the whole list yields a reset, not fine-grained commands — the incremental path isn't automatically cheaper than replacing the array.

Where it lives​

• packages/core/src/modules/wrapper/index/TOIMOrderedListCommand.ts
• packages/core/src/modules/wrapper/index/OIMOrderedListCommandStream.ts

Context​

OIMEventQueue.flush() runs every pending task. A task may enqueue more tasks — a handler writes, which marks another carrier dirty, which enqueues its flush. Those new tasks must land in the next flush, not this one, and the current drain must not observe them.

Problem​

Iterating this.tasks directly is unsafe here: as above, a task can enqueue more tasks mid-flush, and a Set mutated while it is being iterated would run that next-flush work now. The usual fix is to snapshot — copy this.tasks into an array, clear the set, then walk the array; new enqueues land in the empty set and the walk is over a frozen list. It works, but the snapshot is a fresh array sized to the queue, allocated on every flush — and flush runs once per microtask under load.

Options​

• Array.from(this.tasks) snapshot per flush — simple and correct; one array allocation proportional to queue size, every flush.
• Iterate the live Set, clear at the end — no snapshot, but new enqueues during the drain land in the same set being iterated; a Set's for..of visits entries added mid-iteration, so next-flush work runs this flush.
• Two sets, swapped (double buffer) — keep a spare empty Set; swap it into this.tasks and drain the old one; clear the drained set and keep it as the next spare. No per-flush allocation.

What OIMDB does​

Double buffer — two Sets allocated once for the queue's lifetime, swapped each flush:

const flushing = this.tasks;
this.tasks = this.tasksSpare;
this.flushing = flushing;

for (const task of flushing) task();

flushing.clear();
this.tasksSpare = flushing;
this.flushing = undefined;

Enqueues during the drain hit the fresh this.tasks and run next flush — the snapshot's semantics, with no per-flush allocation. The flushing reference is exposed so cancel(fn) can delete a task mid-drain; a Set's for..of skips entries removed before they're reached, so cancelling a not-yet-run task stops it.

Measured on an empty flush, where the array allocation is the entire cost: 0.057 µs with Array.from, 0.037 µs with the double buffer (−35%). That −35% is the headline only because nothing else runs — under real load the tasks themselves dominate flush time, so the snapshot's share (and the relative win) shrinks. What the double buffer removes is a fixed per-flush overhead: Array.from allocates proportional to the queue, the swap is O(1), so the absolute saving grows with queue size while the relative saving is largest exactly when flushes are cheap and frequent — which, under microtask batching, they are.

Cost​

The queue permanently holds two Sets instead of one — a fixed idle-memory cost traded for zero churn. And this.flushing must be set during the drain and cleared after, or cancel() would dereference a stale set: bookkeeping a plain snapshot wouldn't need.

Where it lives​

packages/core/src/core/OIMEventQueue.ts

Context​

OIMUpdateEventEmitter is the Map-based keyed emitter used where the carrier isn't an object the writer already holds — reactive objects, computed nodes, the ordered-list command stream. At flush it delivers to every changed key that has subscribers.

Problem​

There are two collections in play: updatedKeys (what changed this tick) and keyHandlers (everything subscribed). To deliver, walk one and probe the other. Which one gets walked matters: walking the smaller and probing the larger is fewer operations than the reverse.

One detail constrains the whole problem: markUpdatedKeys only records a key that already has handlers (it skips keys with no subscribers). So updatedKeys is always a subset of keyHandlers — M ≤ K, where M = changed keys and K = subscribed keys. The two sets can be equal (via markAllUpdated), never inverted.

Options​

• Sparse — iterate updatedKeys, probe keyHandlers. Few keys changed → updatedKeys.size map lookups. When nearly everything changed it still pays a map get per key, pricier than the map's own in-place iteration.
• Dense — iterate keyHandlers, probe updatedKeys. Most keys changed → one linear map walk, cheap Set.has per entry. When two of ten thousand changed, all ten thousand get walked to find two.
• Heuristic — pick sparse or dense per flush by size (e.g. flushingKeys.size * 2 < keyHandlers.size). Cheap to compute, but the crossover constant is a guess until measured, and it means carrying both walks plus a branch.

What OIMDB does​

Count the lookups. Sparse does M map-gets; dense does K iterations + K Set.hases. Since M ≤ K, sparse does fewer for any M < K. The exception is M = K — every subscribed key dirty — where iterating the map in place avoids K repeated get() re-hashes. Both walks, benchmarked across M/K (min-of-7, K = 10 000, ms total — lower is better):

M/K    sparse   dense    winner
  1%        6      534    sparse
 10%       78      631    sparse
 25%      176      570    sparse
 50%      330      623    sparse
 75%      597      779    sparse
100%      672      606    dense (~10%)

Dense wins exactly one ratio: M = K, by ~7–10% (holds at K = 1k and 50k too). Below that sparse wins — by orders of magnitude when few keys changed. So a size heuristic is doubly wrong with the wrong constant: * 2 flips to dense at M ≥ K/2, across a 50–99% band where sparse still wins, and K/2 has nothing to do with the one ratio (M = K) where dense actually pays.

Be clear about the stake: M = K only happens via markAllUpdated() / clear(), not on ordinary partial writes, and the win there is ~10% of an already-cheap dispatch. This is a small optimization on an infrequent path. The transferable part isn't the speedup — it's the method: the first cut used a * 2 size heuristic on a guessed crossover; a clean min-of-7 sweep showed there is no crossover region at all, just a single exact ratio, so the right code is an equality check, not a tuned threshold.

runSinglePass switches on that exact condition — M = K, which is what markAllUpdated() / clear() produce — and uses sparse otherwise:

if (flushingKeys.size === this.keyHandlers.size) {
    // every subscribed key dirty: iterate the map, skip K get()s
    this.keyHandlers.forEach((handlers, key) => {
        if (!flushingKeys.has(key)) return;
        if (!handlers || handlers.size === 0) return;
        this.notifyHandlers(handlers);
    });
} else {
    flushingKeys.forEach(key => {
        const handlers = this.keyHandlers.get(key);
        if (!handlers || handlers.size === 0) return;
        this.notifyHandlers(handlers);
    });
}

Cost​

Two walks and a branch, versus one. But the branch is an exact equality, not a tuned threshold, so there is no crossover region to mis-place — it triggers only on all-keys-dirty. Both walks probe membership, so either stays correct if a subscription changed between mark and flush.

Where it lives​

packages/core/src/core/OIMUpdateEventEmitter.ts (runSinglePass)