`rights`, `lefts` & `separated`

Either-aware operators on an event chain of Either values — unwrap one side, or split both at once.

FxEvents<R> FxEvents<Either<L, R>>.rights() FxEvents<L> FxEvents<Either<L, R>>.lefts() (FxEvents<L> failures, FxEvents<R> successes) FxEvents<Either<L, R>>.separated()

Lecture

Once a chain is FxEvents<Either<L, R>> — from attempt or mapEither — these three operators are the push-side counterparts of FxEitherOps. rights() keeps only the successes, unwrapped; lefts() keeps only the failures, unwrapped; separated() splits into (failures, successes) — the Either shape of partition.

No terminals live here. pull() hands the chain to FxAsync, where sequence() and flattenOrAccumulate() already exist. These operators stay in the events layer so a UI can listen to successes and failures as two feeds.

separated() inherits partition's lifetime rules: the record is returned eagerly, listening to either side starts the source, cancelling both cancels it, and a value belonging to a side nobody listens to is dropped rather than buffered.

It inherits partition's error fan-out too: an error event is not an Either, so it goes to every side currently listening — one upstream failure surfaces on both halves. Call attempt upstream when a failure should be counted once, as a Left on the failures half.

Demo 1 · rights and lefts

Demo 2 · separated splits both halves

Try it yourself

Exercise: an error event fans out to both halves; attempt upstream counts it once.

import 'dart:async';

import 'package:fxdart/fxdart.dart';

Future<List<String>> drain(FxEvents<Object?> src) {
  final out = <String>[];
  final done = Completer<void>();
  src.listen(
    (v) => out.add('data $v'),
    onError: (Object e) => out.add('error $e'),
    onDone: done.complete,
  );
  return done.future.then((_) => out);
}

Future<void> main() async {
  // Exercise: an error *event* is not an Either, so separated fans it
  // out to every side currently listening. attempt upstream counts the
  // failure once, as a Left on the failures half.

final raw = StreamController<Either<String, int>>();
  final (rawFail, rawOk) = fxEvents(raw.stream).separated();
  final rawFailD = drain(rawFail);
  final rawOkD = drain(rawOk);
  raw
    ..add(const Right(1))
    ..addError('boom')
    ..add(const Right(2));
  await raw.close();
  print('without attempt');
  print(await rawFailD); // [error boom]
  print(await rawOkD); // [data 1, error boom, data 2]

final src = StreamController<int>();
  final (failures, successes) = fxEvents(
    src.stream,
  ).attempt<String>((e, _) => 'E:$e').separated();
  final failD = drain(failures);
  final okD = drain(successes);
  src
    ..add(1)
    ..addError('boom')
    ..add(2);
  await src.close();
  print('with attempt');
  print(await failD); // [data E:boom]
  print(await okD); // [data 1, data 2]
}

Related: Either × pipelines — the pull-side twins, plus sequence and flattenOrAccumulate · partition — separated()'s predicate cousin · attempt — convert an error event so it counts once, on the failures half

rights, lefts & separated

Lecture

Demo 1 · rights and lefts

Demo 2 · separated splits both halves

Try it yourself

`rights`, `lefts` & `separated`