thenCompose vs thenCombine — Sequential Chain vs Parallel Combine

thenCompose and thenCombine handle the two fundamental async topologies.

`thenCompose` — sequential dependent

• Second async op needs first result to start
• Signature: Function>
• Flattens a CompletableFuture> into CompletableFuture
• Exactly the monadic flatMap / JavaScript await-chain equivalent
• Use when: chained DB → service → cache lookups where each uses the previous
• Latency: sum of all stages (inherent to dependence)

`thenCombine` — parallel independent

• Two futures run simultaneously; combine results when both done
• Signature: (other, BiFunction)
• Use when: fetch orders and preferences for a user in parallel, then build a response
• Latency: max of the two stages (parallel)

The rule of thumb

• Return type of your function tells you which to use
• Function returns U → thenApply
• Function returns CompletableFuture → thenCompose
• You already have two futures → thenCombine

The two classic bugs

Bug 1 — thenApply instead of thenCompose:

• userF.thenApply(user -> findOrdersAsync(user))
• Result: CompletableFuture>> — double-wrapped
• Every downstream must .join().join() or unwrap explicitly
• Fix: use thenCompose

Bug 2 — thenCompose when thenCombine would work:

• Fetching orders and prefs for the same user
• Neither depends on the other, only on user
• Chaining thenCompose serializes them: time = orders + prefs
• Should be thenCombine: time = max(orders, prefs)
• Easy 30–40% latency win for typical dashboards

Mental model

• thenCompose ≈ flatMap / monadic bind / await-chain
• thenCombine ≈ zip / diamond merge
• thenApply ≈ map

Async variants on both

• thenComposeAsync(fn, executor) — fn on supplied executor
• thenCombineAsync(other, fn, executor) — combiner on supplied executor
• Use when combiner does non-trivial work; otherwise the non-async form skips a thread hop

For N > 2 parallel operations

• Don't chain thenCombine N times
• Use CompletableFuture.allOf(f1, f2, f3, ...) then read each result
• Cleaner and doesn't build a left-leaning tree

Recommendation: When reviewing async Java, read the function return types — they tell you whether thenApply, thenCompose, or thenCombine is right. Any `thenCompose` chain where the intermediate result isn't used later is a red flag: those stages can probably run in parallel via thenCombine or allOf. Extract long chains into named helper methods; a page-long chain of lambdas is nearly impossible to debug. And on Java 21, ask whether virtual threads with blocking code would be clearer than the CompletableFuture dance — often it will be.