IO: effects at the boundary

Everything so far has been pure — values in, values out. But a scheme engine eventually has to do things: append an audit record, publish an event, call a registry. IO<T> is the educational device for keeping those honest: it is a description of an effectful computation that has not run yet. Building an IO does nothing; only unsafeRun() at the outermost edge performs the effects.

The implementation

1
public final class IO<T> {
2

3
    private final Supplier<T> thunk;
4

5
    private IO(Supplier<T> thunk) {
6
        this.thunk = thunk;
7
    }
8

9
    public static <T> IO<T> of(T value) {
10
        return new IO<>(() -> value);
11
    }
12

13
    public static <T> IO<T> delay(Supplier<T> thunk) {
14
        return new IO<>(Objects.requireNonNull(thunk, "thunk must not be null"));
15
    }
16

17
    public <R> IO<R> map(Fn1<? super T, ? extends R> mapper) {
18
        return new IO<>(() -> mapper.apply(unsafeRun()));
19
    }
20

21
    public <R> IO<R> flatMap(Fn1<? super T, ? extends IO<R>> mapper) {
22
        return new IO<>(() -> mapper.apply(unsafeRun()).unsafeRun());
23
    }
24

25
    public T unsafeRun() {
26
        return thunk.get();
27
    }
28
}

IO.delay captures a side effect without running it; map and flatMap build larger descriptions. The name unsafeRun is deliberate — it is the moment the pure description meets the impure world, and it should appear exactly once per request, in the outermost layer.

Why bother — the test

1
@Test
2
void ioDoesNotRunUntilUnsafeRun() {
3
    AtomicInteger calls = new AtomicInteger();
4
    IO<Integer> io = IO.delay(calls::incrementAndGet).map(x -> x + 1);
5

6
    assertThat(calls).hasValue(0);          // described, not executed
7
    assertThat(io.unsafeRun()).isEqualTo(2);
8
    assertThat(calls).hasValue(1);
9
}

The payoff is that the composition of effects — what runs, in what order, on which inputs — is a value you can pass to a test and inspect without executing anything.

Scheme example: the decision pipeline’s boundary

1
public IO<DecisionReport> auditedEvaluation(String citizenId, AuditStore audit, Clock clock) {
2
    return evaluation(citizenId)
3
            .map(result -> result.fold(
4
                    error -> new DecisionReport(
5
                            new ManualReview(scheme.value(), citizenId, "registry error"),
6
                            RULE_VERSION, clock.instant(), citizenId),
7
                    outcome -> new DecisionReport(outcome, RULE_VERSION, clock.instant(), citizenId)))
8
            .map(report -> {
9
                audit.append(report);
10
                return report;
11
            });
12
}

The policy evaluation is pure; the audit append is wrapped in the IO description. A test can call auditedEvaluation and assert on the returned IO — or run it against an in-memory AuditStore and assert the trail — without a database, because the effect is data until unsafeRun.

Honest limitations: this IO has no error channel, no cancellation, no async execution, and no retry — it is Supplier with composition and a guilty name. Production JVM effect systems (cats-effect, ZIO) add fiber scheduling, structured concurrency, and resource safety; Part 18 shows the pragmatic middle ground of CompletableFuture and virtual threads. Treat IO here as the teaching device that makes “pure core, effectful edges” a compilable rule rather than a convention.

JavaFunctional Programming