ComputeStreamTransformer<TInput, TOutput> class

A generic StreamTransformerBase that runs each stream event through Flutter's compute (a one-shot background isolate), keeping CPU-bound per-event work off the UI thread.

Each incoming event is handed to computeFunction on a background isolate via compute(); the result is emitted on the output stream. Events are processed one at a time and IN ORDER — asyncMap awaits each compute() before pulling the next event, so a later event that computes faster can never overtake an earlier one.

computeFunction MUST be a top-level or static function (a compute requirement — closures capturing state cannot be sent to an isolate). The event payload must also be sendable across the isolate boundary (primitives, strings, and lists/maps of those copy cleanly; arbitrary objects with native handles do not).

If onError is supplied, an exception thrown while computing an event is converted into a fallback output value instead of erroring the stream; when onError is null the error is rethrown onto the output stream. onError guards ONLY failures inside compute() — an error emitted by the SOURCE stream passes through untouched, because that is not a compute failure.

Edge cases:

  • Empty source stream → emits nothing and closes.
  • Source error (not a callback throw) → forwarded as-is, even when onError is set.
  • onError itself throwing → that error surfaces on the stream (it is not swallowed); a fallback callback must not throw if the stream is to survive.
  • On web there is no real isolate: compute() runs the callback inline on the main thread, so the transform still produces correct results but loses the off-thread benefit.

Example:

// Top-level function — required by compute().
List<Foo> _decode(List<int> bytes) => FooCodec.decode(bytes);

sourceStream.transform(
  ComputeStreamTransformer<List<int>, List<Foo>>(
    computeFunction: _decode,
  ),
);
Inheritance

Constructors

ComputeStreamTransformer({required ComputeCallback<TInput, TOutput> computeFunction, TOutput onError(Object error, StackTrace stackTrace)?})
Creates a transformer that runs computeFunction on a background isolate for each event, optionally recovering compute failures via onError. Audited: 2026-06-12 11:26 EDT

Properties

computeFunction → ComputeCallback<TInput, TOutput>
The top-level/static function applied to each event on a background isolate. A closure capturing state cannot be sent across the isolate boundary and will fail at compute() time — this is why the type is ComputeCallback, not an arbitrary lambda.
final
hashCode → int
The hash code for this object.
no setterinherited
onError → TOutput Function(Object error, StackTrace stackTrace)?
Optional recovery for a failure thrown while computing a single event.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

bind(Stream<TInput> stream) → Stream<TOutput>
Transforms the provided stream.
override
cast<RS, RT>() → StreamTransformer<RS, RT>
Provides a StreamTransformer<RS, RT> view of this stream transformer.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

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