`either` & the `Raise` scope

Runs a block in a Raise<E> scope: straight-line code that can short-circuit with a typed error. A raised E becomes Left, a normal return becomes Right.

Either<E, A> either<E, A>(A Function(Raise<E> r) block) Future<Either<E, A>> eitherAsync<E, A>(FutureOr<A> Function(Raise<E> r) block) Either<E, A> eitherCatching<E, A>(block, E Function(Object thrown, StackTrace st) onThrow) (+ eitherCatchingAsync) on Raise<E>: bind · bindAll · ensure · ensureNotNull · recover(block, onRaise, {onThrow}) · withError · raise

Lecture

The builder hands your block a scope r — the port of Kotlin Arrow's either { }. Everything hangs off it; type r. and discover the whole vocabulary:

r.bind(either) / r.bindAll(eithers) — unwrap a success or short-circuit with the failure.
r.ensure(cond, () => err) — the typed-error require.
r.ensureNotNull(x, () => err) — returns non-null, with type promotion.
r.recover(block, onRaise) — handle a raised error in a nested scope and keep going.
r.withError(transform, block) — adapt a different error type into this scope.
r.raise(err) — short-circuit directly; returns Never, so flow analysis knows execution stops.

Internally this is not flatMap chaining: a failed bind throws a private, scope-tagged signal that the builder catches at its boundary. That is why early returns, loops and ifs all just work inside the block, and why nested builders never capture each other's errors. eitherAsync is the async twin — same vocabulary, await allowed (raise only within the same awaited chain).

Demo 1 · ensure & ensureNotNull

Demo 2 · bind — the flatMap-pyramid killer

Demo 3 · recover, withError & raise

Demo 4 · eitherCatching — the exception boundary, pre-combined

Real parsing fails two ways at once: your rules raise typed errors, while the platform (int.parse, jsonDecode) throws. eitherCatching is either + catching as one builder — the block may raise or throw, and the second argument maps anything thrown into the same typed error. The raise signal itself is never handed to it. recover accepts the same optional onThrow: clause, completing Arrow 2.x's three-clause recover(block, recover, catch).

import 'package:fxdart/fxdart.dart';

/// One builder for both failure channels: a raise stays typed, a THROWN
/// exception is mapped into the same error type by the second argument.
Either<String, int> parsePort(String raw) => eitherCatching(
      (r) {
        final port = int.parse(raw); // may throw FormatException
        r.ensure(port > 0 && port < 65536, () => 'port out of range: $port');
        return port;
      },
      (thrown, _) => 'not a number: $raw',
    );

void main() {
  print(parsePort('8080')); // Right(8080)
  print(parsePort('99999')); // Left(port out of range: 99999) — raised
  print(parsePort('http')); // Left(not a number: http) — thrown, mapped

// was: either((r) => catching(() => ..., (e, _) => r.raise(...)))

// recover gained the same third clause (Arrow's recover/catch):
  final fallback = either<String, int>((r) => r.recover(
        (inner) => int.parse('x'), // throws
        (raised) => -1,
        onThrow: (thrown, _) => 0,
      ));
  print(fallback); // Right(0)
}

Try it yourself

Exercise: make checkAge fail with a typed error instead of throwing — ensureNotNull for the parse, ensure for the age limit.

Two rules. (1) Never return a lazy pipeline from a raise block — materialize with toList() inside it, or use the eager Either terminals; a deferred raise fails loudly with RaiseLeakedError. (2) Never bare-catch inside a raise block — use catching/catchingAsync, which always let the short-circuit signal through.

Related: Either — the boundary type · nullable — the info-free twin that returns T? · accumulation — collect every failure · typed errors — full guide

either & the Raise scope

Lecture

Demo 1 · ensure & ensureNotNull

Demo 2 · bind — the flatMap-pyramid killer

Demo 3 · recover, withError & raise

Demo 4 · eitherCatching — the exception boundary, pre-combined

Try it yourself

`either` & the `Raise` scope