map vs flatMap in Java Streams — Transform vs Flatten

map and flatMap differ by whether the function returns a single value or a stream.

`map(T → R)`

• One element in, one element out
• Cardinality preserved: 100 in, 100 out
• Use for: changing type, transforming values, formatting

`flatMap(T → Stream)`

• One element in, zero or more out
• Inner streams are flattened into the outer pipeline
• Use for: 1-to-many expansion, flattening nested collections, Optional chaining

The rule of thumb

• Function returns a value? → map
• Function returns a stream / collection / Optional? → flatMap
• Get this wrong and you end up with Stream> — impossible downstream

Canonical use cases

1. Flatten `List>`:

• nested.stream().flatMap(List::stream).toList()

2. Explode 1-to-many:

• users.stream().flatMap(u -> u.getOrders().stream()).toList()

3. Optional chaining:

• findUser(id).flatMap(User::getAddress).flatMap(Address::getEmail)
• If you used map, you'd get Optional>> — awkward

4. Tokenize:

• sentences.stream().flatMap(s -> Arrays.stream(s.split("\\s+")))

5. Read multiple files:

• paths.stream().flatMap(p -> Files.lines(p))

The common mistake

• users.stream().map(u -> u.getOrders().stream())
• Returns Stream>
• Fix: replace map with flatMap
• Equivalent: flatMap(u -> u.getOrders().stream()).map(...) — flatten, then map

Monadic view

• flatMap is the monadic bind operation
• Same concept in Scala, Haskell, Kotlin
• Also exists on Optional (flatMap) and CompletableFuture (thenCompose)
• Common pattern: chain operations where each step returns another container; flatMap keeps you at one level of nesting

Primitive variants

• flatMapToInt, flatMapToLong, flatMapToDouble
• List to flat int[]: arrays.stream().flatMapToInt(Arrays::stream).toArray()

Java 16+ alternative — mapMulti

• Callback-based instead of returning a stream
• Can be faster for small per-element output (avoids Stream allocation)
• Less idiomatic; flatMap usually reads better

Watch out for

• Returning `null` from flatMap — NPE. Use Stream.empty() to skip
• I/O-backed inner streams like Files.lines — can leak. Close explicitly or wrap in try-with-resources
• Parallel streams: outer parallelism doesn't extend to inner streams; each user's orders processed sequentially

Recommendation: Think of flatMap as "map and then flatten" — when your transformation function naturally returns a collection (orders of a user, tokens of a string, lines of a file), flatMap is what you want; when it returns a scalar value (a name, a transformed number), map is right. If you find yourself writing stream.map(...).flatMap(x -> x) to unwrap nested streams, that's a sign to refactor into a single flatMap. Use `Optional.flatMap` for safe chained lookups; it keeps nesting flat. For tight numeric loops with known small output sizes, consider `mapMulti` (Java 16+) for a marginal performance win, but flatMap remains the idiomatic default.