PulseRecorder<T extends Cell> class

A recorder that captures every pulse emitted by a Cell, in order.

PulseRecorder is the binding's Pulse Journal. It owns exactly one Cell.observe link on a source cell and appends every received pulse to an in-order list, so tests can assert on the sequence, payloads, and error types of a cell's emissions without subscribing to the cell themselves.

Why it is used

  • Sequence assertions: the recorded list preserves order, so a test can assert expect(recorder.payloads, [1, 2, 3]) on a burst of updates that a value-only view would collapse into the final value.
  • Error visibility: pulses exposes the raw pulse list, allowing tests to distinguish data from type == 'error' emissions — see the extension docs for which core operators currently emit errors.
  • Harness-integrated: CellTestHarness wraps one of these internally and manages its lifecycle, so most tests use the harness rather than the recorder directly.

How it works

  1. Construction: the private constructor (invoked via CellRecordPulses.recordPulses) opens one Cell.observe link on the source cell; the effect appends every pulse to an internal list.
  2. Reading: pulses returns a snapshot copy of the list; payloads derives a payload-only view on demand.
  3. Reset: clear empties the recorded list without releasing the egress — useful for setUp-style isolation within a single test.
  4. Release: stop releases the egress. Idempotent.

Cleanup (read this)

Always release the recorder. It holds a strong reference to the source cell until stop is called, so a recorder left running pins its source for the lifetime of the isolate. Two correct patterns:

  • addTearDown(recorder.stop) for standalone use.
  • Let CellTestHarness manage it — the harness calls stop on dispose.

Pulse semantics

  • Data pulses are recorded with their payload.
  • Error pulses are recorded with type == 'error' and the error object as payload. Only Cell.fromFuture currently emits these in the core package — see the extension docs for the full picture.
  • Ordering: pulses are appended in emission order; the list is neither filtered nor coalesced.

Technical Details

  • Snapshot-copy reads: pulses returns List.unmodifiable(_pulses), which is a copy of the internal list, not a live view — subsequent recordings do not appear in a previously obtained list, and each access is O(n). Hold the result when iterating over a long recording.
  • Reusable: clear resets the recording without dropping the egress, so one recorder can span multiple assertion phases.
  • Idempotent stop: repeated calls are no-ops; after the first stop, pulses continues to return the last recorded list.
  • Strong reference: the source cell is pinned for the recorder's lifetime (see Cleanup).

See Also:

Properties

cell → T
The source cell.
final
hashCode → int
The hash code for this object.
no setterinherited
payloads → List<Object?>
The payloads of all recorded pulses, in order.
no setter
pulses → List<Pulse<Object?>>
All pulses recorded so far, in order.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

clear() → void
Clears the recorded list without stopping the recorder.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
stop() → void
Stops recording and releases the egress.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited