`Either` × pipelines

Typed errors fused with FxDart's lazy, concurrency-aware pipelines — the part neither Arrow nor any Dart FP library has.

on Fx<Either<L, R>>: rights() · lefts() · separated() · sequence() · flattenOrAccumulate() on FxAsync<Either<L, R>>: rights() · lefts() · separated() · sequence() · flattenOrAccumulate() on Fx<T> / FxAsync<T>: Either<Nel<E>, List<R>> mapOrAccumulate(transform, {concurrency})

Lecture

A chain of Either values gets Either-aware terminals: rights() and lefts() keep one side, separated() splits both at once (same record shape as partition), and sequence() is all-or-nothing — every success collected into one list, failing fast on the first Left. Because the pipeline is lazy, fail-fast is literal: sequence() stops pulling at the first failure, so later elements are never computed.

The fail-slow twin is mapOrAccumulate(transform) on any fx()/async chain: validate every element, keep every failure. On async chains it takes concurrency: n and rides the same concurrent(n) back-channel as the rest of FxDart — n elements in flight, results in order, and each element runs in its own scope, so a failure in one can never leak into a sibling.

All of these are eager by design, which also makes them the sanctioned escape from the laziness × raise hazard: never return a lazy pipeline from a raise block — return one of these results instead.

Demo 1 · rights, lefts & separated

Demo 2 · sequence — fail-fast, literally

Demo 3 · concurrent fail-slow validation

Demo 4 · flattenOrAccumulate & the async extracts

When you already have the Eithers, the fail-slow terminal used to be spelled mapOrAccumulate((r, v) => r.bind(v)) — an identity bind. flattenOrAccumulate() (Arrow's name) is that terminal directly: every success, or every failure as a Nel. It completes the trio — separated() keeps both sides, sequence() fails fast, flattenOrAccumulate() fails slow. And the async chain now carries the whole extract family (rights / lefts / separated / sequence / flattenOrAccumulate), so an async validation feeds a counts badge in one terminal.

import 'package:fxdart/fxdart.dart';

Either<String, int> parse(String s) =>
    either((r) => r.ensureNotNull(int.tryParse(s), () => 'bad: $s'));

void main() async {
  final verdicts = fx(['1', 'x', '3', 'y']).map(parse).toList();

// sequence stops at the FIRST Left; flattenOrAccumulate keeps walking
  // and reports EVERY failure (Arrow's name, Arrow's semantics):
  print(fx(verdicts).sequence()); // Left(bad: x)
  print(fx(verdicts).flattenOrAccumulate()); // Left([bad: x, bad: y])

// was: fx(verdicts).mapOrAccumulate((r, v) => r.bind(v))

// All-good input collects every value:
  print(fx(['1', '2']).map(parse).flattenOrAccumulate()); // Right([1, 2])

// The async chain has the full extract family now — the "47 ok ·
  // 3 problems" badge over an async validation is one terminal:
  final (bad, good) =
      await fx(['1', 'x', '3']).toAsync().map(parse).separated();
  print('${good.length} ok · ${bad.length} problems'); // 2 ok · 1 problems

// Only one side needed? Skip allocating the pair:
  print(await fx(['1', 'x', '3']).toAsync().map(parse).rights()); // [1, 3]
}

Try it yourself

Exercise: sum what parsed, report what didn't.

Related: accumulation — the scope-level fail-slow vocabulary · concurrent — the back-channel the async variant rides · partition — separated()'s predicate cousin · rights / separated — the same extracts on an event chain · typed errors — full guide

Either × pipelines

Lecture

Demo 1 · rights, lefts & separated

Demo 2 · sequence — fail-fast, literally

Demo 3 · concurrent fail-slow validation

Demo 4 · flattenOrAccumulate & the async extracts

Try it yourself

`Either` × pipelines