CellAsStream extension
Bridges a Cell to a Dart Stream<V?>.
CellAsStream is the binding's Egress Bridge: the counterpart of
Cell.ingress at the widget/Dart-interop boundary. Where a cell is the
reactive graph's internal signal carrier, a Stream is the lingua franca
of most Dart APIs (isolate channels, package SDKs, test utilities). This
extension converts one to the other without exposing the cell's egress
machinery to the caller.
Why it is used
- Dart interop: hand a cell's values to a
Stream-consuming API (StreamTransformer,StreamBuilder, an isolate port, a third-party SDK). - Testing:
await for (final v in cell.asStream<int>())gives a pump-free way to observe pulses in widget tests and unit tests. - Composition:
stream.where,stream.map,stream.firstare all available once the cell is bridged — useful for one-shot adapters outside the cell graph.
How it works
- A single-subscription StreamController is created; the underlying
Cell.observelink is not opened until the firstlisten(onListen). Merely callingasStream()does not subscribe to Cell. - On
onListen, the cell is observed and every pulse is forwarded into the controller — errors go throughaddError, data throughadd. - If the observed cell does not emit synchronously upon subscription,
the bridge falls back to
retainedPulseOffor a one-shot seed — this serves every state-like operator's retained pulse (fromFuture,fromStream,asyncMap,derive) as well as a ValueCell's current value (see Seed semantics below). - On
onCancel, the egress is stopped. The controller is intentionally not closed fromonCancel—close()waits ononCancel, so calling it from there deadlocks thedonefuture.
Design Note: sync vs. async delivery
sync defaults to true. A sync stream delivers each value in the same
microtask that the pulse fires in — useful for tests, where a synchronous
subscription avoids pump()-style waits. Production interop with
Streams that assume asynchronous delivery should pass sync: false.
Lifecycle
- Single-subscription: the controller is not broadcast. Calling
stream.listentwice throwsStateError. For broadcast semantics, wrap the returned stream with.asBroadcastStream()— the wrapper creates and tears down its own single subscription. - Lazy: dropping the stream without listening does not subscribe to the cell.
- Cancellation stops the egress: after
onCancel, no further pulses are forwarded. - The stream never completes. The controller is deliberately never
closed (see How it works), so
await for,drain, andtoListhang forever on it. Uselistenwith a manualcancel,take(...)with a completing terminal, ortimeout— do not await completion. - Synchronous error delivery: with
sync= true(default), a seed that turns out to be an error pulse is delivered synchronously insidelisten; a caller that has not registeredonErrorbefore the first microtask will see an unhandled zone error. RegisteronError, or passsync: false.
Seed semantics (please read)
The lazy seed is sourced from retainedPulseOf, which reads the core
package's retained pulse via Cell.latestPulse and serves ValueCell
as a fallback. A plain async cell
(Cell.fromFuture / Cell.fromStream / Cell.asyncMap /
Cell.derive) that already emitted before the stream was listened
to is replayed as the first event. A cell that has never emitted
produces no seed — the stream waits for the next live pulse. See
test/seed_paths_test.dart for the coverage.
Error pulses
Only Cell.fromFuture emits Pulse<Object>(type: 'error') on its
failure path. Cell.fromStream and Cell.asyncMap do not emit
error pulses in the core package today, so their failures never reach
this bridge. With emitErrors = true (default), a received error
pulse becomes Stream.addError; with emitErrors = false it is
silently dropped. A type-mismatched data payload is always surfaced
as Stream.addError (a StateError), regardless of emitErrors — it
is a caller bug, not a transient source error. The per-source behavior
is asserted in test/error_pulse_sources_test.dart.
Concurrent asyncMap caveat
Sources produced by Cell.asyncMap with concurrency > 0 (or overlapping
latestOnly futures) inherit the framework's caveat:
concurrent effect attribution is tracked separately and is not yet
verified end-to-end. The bridge itself is correct; the caveat concerns the
source's replay fidelity. See the cell core package for status.
Example: seed a ValueCell's current value
final counter = Cell.state<int>(initial: 0);
final sub = counter.cell.asStream<int>().listen((v) => print('seed $v'));
// The seed serves `ValueCell` sources: the listener receives 0 on the
// first microtask after listen, then each later pulse.
counter.update(1); // → 1
await sub.cancel(); // stops the internal egress
A plain cell (fromFuture, fromStream, asyncMap, derive) that
emitted before listen is replayed as the first event — see Seed
semantics.
Parameters:
sync: Delivery Mode.true(default) delivers in the same microtask as the pulse;falsedelivers asynchronously.emitErrors: Error Forwarding. Whentrue(default), error pulses becomeStream.addError. Type-mismatch errors are always forwarded regardless of this flag.
Returns:
A single-subscription Stream<V?> that forwards the cell's payloads.
See Also:
- CellAsValue — to mirror a cell into a ValueCell instead of a stream.
CellAsyncBuilder— the snapshot-style widget form of the same idea.Cell.ingress— the reverse bridge (Stream → Cell is not provided; useCell.fromStream).retainedPulseOf— the lazy-seed probe.test/seed_paths_test.dart— the seed-behavior coverage.- Example: see
test/for pump-free stream-bridge usage in widget tests.
- on