RFC: Replace `useAsyncComputed$` with a more flexible `useAsync$` primitive

[wmertens]

Champion

@Varixo and @wmertens

What's the motivation for this proposal?

Summary
Replace useAsyncComputed$ with a new useAsync$ that unifies async computation, observable values, polling, and eager cleanup, while aligning closer to useSignal semantics.

Motivation
Current useAsyncComputed$ overlaps with useResource$ but neither are great.
A more powerful, writable async primitive would better support data fetching, streaming, auto-updating values, and background calculations.

Proposal

Rename useAsyncComputed$ to useAsync$:

useAsync$<T>(
  callback: (ctx: { track: TrackFn, cleanup: CleanupFn, poll: PollFn }) => Promise<T> | T,
  options?: {
    initial?: T | (() => T);    // like useSignal; prevents throw on read when uninitialized
    eagerCleanup?: boolean;     // run cleanup next tick when subscribers drop to 0
    awaitPrevious?: boolean;    // wait for previous invocation to complete before running again
    pollMs?: number;            // re-run after N ms if subscribers exist
    timeout?: number;           // abort after timeout
  }
): AsyncSignal<unknown>;

Key changes:

1. Writable result – result.value = … updates subscribers directly; clears loading/error state.
2. Error handling – result.error = … propagates error on read.
3. Initial value – optional initial avoids throw when reading before first resolution.
4. Eager cleanup – cleanup runs immediately (next tick) when no subscribers remain.
5. Polling – via pollMs: number option or poll(ms) callback for periodic re-execution; use .invalidate() as before to do it manually.

Example

const data = useAsync$(({ cleanup }) => {
  const channel = await makeChannel();
  channel.on('data', d => data.value = d);     // push updates
  channel.on('error', e => data.error = e);    // propagate errors
  cleanup(() => channel.close());
  return 'PENDING';
}, { eagerCleanup: true });

Benefits

• Single primitive for async data, observables, polling, and background tasks.
• Consistent with useSignal mental model.
• Reduces need for separate useResource$ or custom observables.
• Enables streaming/server-sent events, WebSocket handling, and auto-refetching patterns out of the box.

Discussion points

• Should poll be an option, callback, both, or neither?

Addition: generators

The callback should also be able to be a generator function, it should be wrapped so that every invocation updates the value.

[maiieul]

👀 This looks like a fundamental new building block 👀 so we better think about it thoroughly.

Motivation

Current useAsyncComputed$ overlaps with useResource$ but neither are great.
Can you summarize the limitations of those? Or provide a link? I'm especially interested in understanding the limitations of current useAsyncComputed$ and the proposed useAsync$

Naming

Could also be called ‘useAsyncSignal$’? In which case it’s a bit weird that it’s a QRL and useSignal is not. So does it have to be a QRL? Still might be less weird than useAsync$. useAsync$ doesn't hint that it's reactive. So people might get confused as to why there are both useAsync$ and routeLoader$.

Integration

How would it integrate with other hooks like useComputed$? Can it be incrementally added and used alongside existing useResource$?

[wmertens]

So as discussed in the meeting, we have useComputed$ which is also eliding the "Signal". It's more than just computing, so useAsync$ is nicely generic but also descriptive.

The idea is that useResource$ is just implemented using useAsync. The <Resource/> component can take an AsyncSignal too.

But, in fact we need one more setting:

• awaitPrevious: (default true) if false, then invalidations will cause a new function run in the next tick, even if the previous invocation is still running.

To implement this: if the AsyncSignal is not invalidated yet, mark it as invalid and remove invalid+calculate in the next tick. This doesn't block or get blocked by anything.

For cleanups: normally we await cleanup before running the function again but maybe we have to run them in parallel.

[wmertens]

during implementation, awaitPrevious turned out to be unnecessary, it's the only action that makes sense.

[wmertens]

fully implemented in beta with fun extras