accumulation — `zipOrAccumulate` & friends

Validation wants all the errors, not the first one. These operations run every branch and concatenate the failures into a NonEmptyList — Arrow 2.x's replacement for a separate Validated type.

on Raise<Nel<E>>: R accumulate<R>(R Function(Accumulator<E> acc) block) R zipOrAccumulate2..5(branch1, …, combine) List<B> mapOrAccumulate<A, B>(items, transform) · A bindNel<A>(EitherNel<E, A> e) on Accumulator<E>: accumulating(block) · dependent(block) · hasErrors

Lecture

Inside either<Nel<E>, _>(...) — any scope whose error type is a NonEmptyList — the scope gains the accumulation vocabulary:

r.zipOrAccumulate2..5(branches…, combine) — run N independent branches, report every failure, combine the successes.
r.accumulate((acc) { … }) — the general form: run branches with acc.accumulating(block), then read each result's .value. If anything failed, reading a value (or reaching the end of the block) raises the full error list.
r.mapOrAccumulate(items, transform) — validate a whole collection fail-slow.
r.bindNel(eitherNel) — unwrap an EitherNel, raising all of its errors at once; someEither.toEitherNel() bridges a fail-fast value in.

The contract is Arrow's: every branch runs (errors concatenate in branch order), a branch that throws instead of raising wins over accumulation, and after the first error successful results are no longer retained — iteration continues only to collect the remaining errors.

Demo 1 · zipOrAccumulate2

Demo 2 · accumulate — the general form

import 'package:fxdart/fxdart.dart';

// The general form: open an accumulating scope with r.accumulate, run each
// branch with acc.accumulating, combine the .value results at the end.
EitherNel<String, String> validate(Map<String, String> input) =>
    either((r) => r.accumulate((acc) {
          final name = acc.accumulating((r) {
            final v = r.ensureNotNull(input['name'], () => 'name missing');
            r.ensure(v.isNotEmpty, () => 'name is empty');
            return v;
          });
          final age = acc.accumulating((r) {
            final raw = r.ensureNotNull(input['age'], () => 'age missing');
            return r.ensureNotNull(
                int.tryParse(raw), () => 'age is not a number');
          });
          // Reading .value raises the FULL error list if anything failed:
          return '${name.value} (${age.value})';
        }));

void main() {
  print(validate({'name': 'kim', 'age': '30'})); // Right(kim (30))
  print(validate({'name': '', 'age': 'abc'}));
  // Left([name is empty, age is not a number])
}

Demo 3 · mapOrAccumulate, bindNel & toEitherNel

Demo 4 · dependent — rules that read sibling values

A branch cannot read a sibling's Accumulated.value without detonating — accumulation's one hard rule. But real validation has dependent rules ("an expense needs a positive amount"), which is why forms kept dropping down to a manual if (!acc.hasErrors) guard. acc.dependent(block) names that guard: the block runs only when every branch so far succeeded — so sibling .value reads inside it are safe by construction — and is skipped entirely otherwise. (No Arrow counterpart; Arrow users hand-roll the same guard.)

import 'package:fxdart/fxdart.dart';

/// Two independent branches plus one rule that DEPENDS on both: an expense
/// needs a positive amount. Reading a sibling's .value is only safe once
/// every earlier branch succeeded — dependent runs its block exactly then.
EitherNel<String, String> classify(String type, String rawAmount) =>
    either<Nel<String>, String>((r) => r.accumulate((acc) {
          final t = acc.accumulating((br) => br.ensureNotNull(
              {'expense', 'income'}.contains(type) ? type : null,
              () => 'unknown type: $type'));
          final a = acc.accumulating((br) => br.ensureNotNull(
              double.tryParse(rawAmount), () => 'bad amount: $rawAmount'));

// was: if (!acc.hasErrors) { acc.accumulating((br) => ...); }
          acc.dependent((br) {
            br.ensure(t.value != 'expense' || a.value > 0,
                () => 'an expense needs a positive amount');
            return null;
          });

return '${t.value} of ${a.value}';
        }));

void main() {
  print(classify('expense', '12.5')); // Right(expense of 12.5)
  print(classify('expense', '-3'));
  // Left([an expense needs a positive amount])

// Both independent branches fail — the dependent rule never runs, so
  // the report holds exactly the independent errors:
  print(classify('meal', 'x')); // Left([unknown type: meal, bad amount: x])
}

Try it yourself

Exercise: finish both branches of signup so the second call reports both failures.

Related: NonEmptyList — the error carrier · Either × pipelines — fail-slow validation over fx() chains, with concurrency · either & Raise — the fail-fast scope this extends · typed errors — full guide

accumulation — zipOrAccumulate & friends

Lecture

Demo 1 · zipOrAccumulate2

Demo 2 · accumulate — the general form

Demo 3 · mapOrAccumulate, bindNel & toEitherNel

Demo 4 · dependent — rules that read sibling values

Try it yourself

accumulation — `zipOrAccumulate` & friends