Consider async observer triggering

[fynyky]

Have it be a property of the reactor? Any reactor given an async tag will trigger observers asynchronously? Allow it to be awaitable?
In a recursively fashion make async signals and nested reactors too?
Should this be default? Since await is normal now?

@claude help me think through if I should implement this and if I do, how I would do it

[claude]

Claude finished @fynyky's task in 3m 44s —— View job

---

Thinking through async observer triggering

• Read codebase to understand current architecture
• Analyze tradeoffs of sync vs async observer triggering
• Explore implementation approaches (per-reactor flag, recursive propagation, defaulting)
• Provide recommendation

---

Where you are today

The current model (from reactor.js + elemental.js):

• Observer triggering is synchronous — rx.foo = 'bar' immediately re-runs dependents inside the same call stack.
• You already ship batch(() => { … }), which collects mutations and flushes a deduplicated trigger set at the end of the block (README L648-664). That's the existing answer to "I changed five things and got five renders."
• The only async surface in elemental today is the MutationObserver-driven observer lifecycle in src/elemental.js:24-49,62-68 — observers auto-start/stop on DOM attach/detach. That's why some tests need setTimeout(10) after appendChild before asserting (e.g. test/test.js:471-481).

So you're not starting from zero. The architectural question is whether async triggering buys enough over batch() to justify the cost.

---

What async actually buys you

1. Implicit coalescing. Today, three mutations outside batch() = three observer runs. Microtask scheduling makes them one without the user having to think. This is the real upside, and the reason every modern signal library (Solid, Vue, Svelte 5, MobX) defaults to microtask-scheduled effects.
2. Awaitable settling. A tick() / flush() helper lets tests and async flows say "wait until the DOM is consistent." Replaces today's await new Promise(r => setTimeout(r, 10)) pattern in your own test suite — those waits exist because of the MutationObserver lifecycle, but a unified scheduler would absorb that too.
3. Recursion safety. Diamond dependencies and cycles that today stack-overflow on sync would queue flat.
4. Glitch-free reads. Observers can never see a half-applied intermediate state (assuming all dependents schedule on the same flush).

---

What it costs

1. Breaks the simple mental model. The line in your README that sells the library — "no complex framework internals" — gets harder to live up to once readers have to know about a flush queue and "when did my DOM actually update?" Most of the README's code blocks rely on sync triggering to be true (e.g. L459, L477, L494, L508, L529, L539).
2. Breaking change for users. Every existing snippet like rx.foo = 'baz'; expect(node.textContent).toBe('baz') would need an await tick().
3. Subtle ordering inside elemental. el()'s observer path at src/elemental.js:160-204 wires up a metaObserver that fires during Observer setup to insert initial content. The hide(() => child.call(self, self)) + metaObserver.start() sequence is sync-ordered today. Async triggering doesn't break it, but you'd want to audit ordering against the MutationObserver-driven start/stop cycle — there's now two async lanes (Mutation + flush queue) that can interleave.
4. bind() semantics. The two-way binding at src/elemental.js:251-256 uses a sync observer to mirror reactor[key] back into $.value. Going async means a one-microtask window where the input shows the user's typed value and the reactor still reflects the prior state. Probably fine, but worth knowing.

---

Design options, ranked by how much I'd actually do

A. Do nothing. Lean on batch(). Document it more prominently as the recommended pattern. Cheapest, preserves the "no magic" pitch. The honest question: are you or your users actually hitting render-thrash in practice, or is this aesthetic? If aesthetic, don't.

B. Add tick() / flush() + opt-in async batch. Keep sync as default. Extend batch to take a mode, or add batch.async(() => { … }) that returns a Promise and defers the trigger set to a microtask. Add a global tick() helper for tests. This gives you awaitability with zero behavior change for existing code. Low-medium effort, low risk. This is my recommendation.

C. Async observers as opt-in property of the Observer. new Observer(fn, { async: true }) defers its own triggers to a microtask, coalescing within that tick. Doesn't help cross-observer batching but is conceptually local. Medium effort.

D. Async opt-in on the Reactor. Any mutation to a tagged Reactor schedules its triggers via a queue. "Recursive" in the sense you mention falls out naturally if downstream Reactors/Observers inherit through the trigger queue rather than the data itself. More coherent than (C) but proliferates configurations.

E. Async by default + global flush queue. Match Solid/Vue. Largest upside, but it's a v1.0-shaped breaking change. Don't do this unless you're rev'ing the major version of both reactor.js and elemental and willing to rewrite the README's examples.

I would skip per-Reactor and per-Observer flags (C and D). They look flexible but each one doubles the matrix of behavior people have to reason about, and in 2 years you'll have users who can't tell whether their bug is because of the flag or in spite of it.

---

On "should this be default since await is normal now?"

The fact that await is universal is an argument for making async possible and awaitable — not for making sync go away. await only helps when you're already in async code; a fully-sync UI mutation in an event handler still wants to "just work" without a tick(). The reason Solid/Vue made it default isn't that await exists, it's that they amortize the cost across rendering large component trees where the win is huge. Your library is more "sprinkle reactivity on plain DOM" — sync is closer to what users expect there.

---

What I'd build (option B, concretely)

In reactor.js:

• Keep current sync batch() exactly as is.
• Add batch.async(fn) (or defer(fn)): runs fn sync, collects triggers, schedules the flush as a microtask, returns a Promise<void> that resolves after flush.
• Add module-level tick(): resolves once the next scheduled flush completes; resolves immediately if no flush pending. Useful for tests.
• Internally, a single queue de-duplicates observers across overlapping async batches in the same microtask.

In elemental.js:

• No changes needed for the core behavior, but consider exposing tick() and updating the test suite's setTimeout(10) waits to await tick() once the MutationObserver lifecycle is also threaded through the same queue (later, optional).

This gives you awaitability + opt-in coalescing without breaking a single existing test or README example.

---

TL;DR recommendation

Don't make it default. Don't add per-Reactor/per-Observer async flags. Do add batch.async() + tick() so async users get awaitable, coalesced semantics on demand, and the sync-as-default story stays clean. If users start consistently asking for the default to flip, that's the signal to consider option E in a v1 major bump.

Happy to prototype any of (B)/(C)/(D) — say which and I'll open a PR. Note that the trigger logic itself lives in reactor.js, so the bulk of any implementation goes there, not in this repo.
• Branch: claude/issue-35-20260525-0629