State: transitions without mutable globals

An application moves through statuses: DRAFT → SUBMITTED → UNDER_REVIEW → APPROVED. The imperative version stores the status in a field and mutates it; the State version treats each transition as a value — a function from old state to (result, new state) that composes with the next transition.

The implementation

1
public record State<S, A>(Fn1<S, Tuple2<A, S>> run) {
2

3
    public A eval(S state)  { return run.apply(state).first(); }   // the value
4
    public S exec(S state)  { return run.apply(state).second(); }  // the final state
5

6
    public <B> State<S, B> map(Fn1<? super A, ? extends B> mapper) {
7
        return new State<>(state -> {
8
            Tuple2<A, S> outcome = run.apply(state);
9
            return new Tuple2<>(mapper.apply(outcome.first()), outcome.second());
10
        });
11
    }
12

13
    public <B> State<S, B> flatMap(Fn1<? super A, ? extends State<S, B>> mapper) {
14
        return new State<>(state -> {
15
            Tuple2<A, S> outcome = run.apply(state);
16
            return mapper.apply(outcome.first()).apply(outcome.second());
17
        });
18
    }
19

20
    public static <S, A> State<S, A> of(A value) { ... }
21
    public static <S> State<S, S> get()          { ... }  // value = current state
22
    public static <S> State<S, S> set(S next)    { ... }
23
    public static <S> State<S, S> modify(Fn1<S, S> transition) { ... }
24
}

flatMap is where the threading happens: run the first step, take its new state, feed it to the next step. eval gives you just the produced value, exec just the final state — you choose what you care about at the edge.

Scheme example: the application workflow

1
public static State<ApplicationStatus, ApplicationStatus> submit() {
2
    return State.modify(status -> switch (status) {
3
        case DRAFT -> ApplicationStatus.SUBMITTED;
4
        default -> throw new IllegalStateException("cannot submit from " + status);
5
    });
6
}
7

8
public static State<ApplicationStatus, ApplicationStatus> submitAndReview() {
9
    return submit().flatMap(submitted -> startReview());
10
}

1
assertThat(ApplicationWorkflow.submitAndReview().exec(ApplicationStatus.DRAFT))
2
        .isEqualTo(ApplicationStatus.UNDER_REVIEW);

Two properties fall out for free. The transition table lives in the switch — approve from DRAFT throws, so illegal sequences are unrepresentable in a composed program. And the whole pipeline is a value: you can test submitAndReview from any starting status without standing up a workflow engine, because “the current state” is just the argument to exec.

When State earns its complexity

Be honest about the cost: State is the least ergonomic type in the library. Java has no for-comprehension, so long flatMap chains read as nested lambdas, and a mutable AtomicReference or a plain field does the same job with less ceremony when the workflow is short and single-threaded. Reach for State when the transition sequence is itself the thing under test — multi-step workflows where you want to assert “from status X, this program lands in status Y” without a container, a database, or a thread — or when you need to replay a transition log against a stored snapshot for audit. For a two-step flow in a singleton service, a guarded setter is fine and nobody should feel guilty about it.