Why are side effects in stream operations (and especially using peek for mutation) discouraged, and what is peek actually for?

## Definitions - **Side effect**: a lambda doing something *observable outside itself* — mutating a field, adding to an external list, incrementing a counter, writing to I/O — rather than just returning a value computed from its input. - **Pure function**: a function whose output depends only on its input and which changes nothing external. Streams are built assuming the functions you pass are (mostly) pure. - **`peek`**: an **intermediate** operation that takes a `Consumer`, runs it on each element as it flows by, and passes the element through **unchanged**. It returns a stream of the same elements. - **Laziness**: intermediate operations don't run when you call them; they run only as the **terminal** operation pulls elements through. - **Short-circuiting**: terminal ops like `findFirst`, `anyMatch`, `limit(n)` stop early, so upstream lambdas run **fewer** times than the source size. ## Why side effects inside the pipeline are a trap ### 1. Laziness means it might not run An intermediate operation with no terminal op never executes: ```java list.stream().peek(x -> log.info("{}", x)); // logs NOTHING — no terminal op ``` ### 2. Short-circuiting means it runs a surprising number of times ```java list.stream() .peek(x -> counter.incrementAndGet()) // how many times? .anyMatch(x -> x > 10); // stops at the first match ``` The counter reflects only elements processed *up to* the first match, not the whole list. Worse, the JIT is allowed to **elide** `peek` when it can prove the elements' identity is all that matters and the side effect is unobservable to the stream — so the count can be even less than you'd guess. ### 3. Parallel streams race ```java List<String> sink = new ArrayList<>(); big.parallelStream().forEach(sink::add); // DATA RACE: ArrayList isn't thread-safe ``` Multiple threads mutate one non-thread-safe structure → corrupted state, lost elements, or `ArrayIndexOutOfBoundsException`. Even an `int` captured and mutated would be a race (and won't compile if you try, because captured locals must be effectively final — which is itself a hint not to do this). ## What `peek` is actually for `peek` is a **debugging/observability** hook: log or inspect elements as they pass, without changing them. Its Javadoc explicitly says that for pipelines where the side effect is the *point*, behavior is unspecified, and the operation may be optimized away. So: ```java result = orders.stream() .filter(Order::isPaid) .peek(o -> log.debug("kept {}", o.id())) // OK: logging only .map(Order::total) .collect(toList()); ``` That is fine. Using `peek` to *mutate* each order, or to populate an external list, is the misuse. ## The correct way to produce results Let the **terminal** operation own the accumulation, via a **collector** (which is built to be safe even in parallel) or a controlled `forEach`: ```java List<Integer> totals = orders.stream() .filter(Order::isPaid) .map(Order::total) .collect(Collectors.toList()); // no external mutation Map<String, List<Order>> byCustomer = orders.stream() .collect(Collectors.groupingBy(Order::customerId)); ``` If you must do a side effect (I/O, say), use `forEach` (sequential) or `forEachOrdered`, and never mutate shared, non-thread-safe state from a parallel stream — use a collector or a concurrent/atomic accumulator instead. ## One-line takeaway Keep intermediate steps pure; use `peek` only to *look*, not to *change*; produce results with a collector at the terminal end.