skip to content

Explain the difference between Provider.map and Provider.flatMap, and when you must use flatMap.

level: middleimportance: must knowfreq 58%

answer

  1. map: T -> R
  2. flatMap: T -> Provider<R>
  3. flatMap flattens nested provider
  4. task->task output = flatMap
  5. preserves dependency

basics

~10 s

map's function returns a plain value (T -> R, giving Provider<R>). flatMap's function returns another provider (T -> Provider<R>, also giving Provider<R> by flattening). Use flatMap when your transform itself produces a provider.

solid answer

~40 s

Both produce a `Provider<R>`. With `map`, the transformer returns a plain value `R`, so `map: (T) -> R`. With `flatMap`, the transformer returns a `Provider<R>`, and Gradle *flattens* the nested `Provider<Provider<R>>` into a single `Provider<R>`: `flatMap: (T) -> Provider<R>`. You **must** use `flatMap` whenever the value you derive is itself lazy — most commonly when reaching from one task to another task's output property. For example `compileTask.flatMap { it.outputDir }` gives a `Provider<Directory>` that stays lazy and, critically, **preserves the task dependency** on `compileTask`. If you used `map` there you'd end up with a `Provider<Provider<Directory>>`, forcing you to call `.get()` inside the lambda and losing laziness plus dependency tracking. Rule of thumb: transform returns a value → `map`; transform returns a provider → `flatMap`.

code

kotlin · 5 lines
kotlin
abstract class GenerateTask : DefaultTask() {
    @get:OutputFile abstract val outputFile: RegularFileProperty
}
val generate = tasks.register<GenerateTask>("generate")
val out: Provider<RegularFile> = generate.flatMap { it.outputFile } // not map!

go deeper

for a junior

Recall that flatMap's lambda returns a provider while map's returns a value.

for a middle

Explain the flattening, the nested-provider problem, and the task->task output use case with dependency preservation.

for a senior

Discuss how flatMap underpins task-output wiring and configuration avoidance, and the pitfalls of get()-inside-map.

for a principal

Set conventions across plugins: outputs exposed as providers, consumers wire via flatMap, eliminating manual dependsOn graphs.

## The type signatures ``` Provider<T>.map(transform: (T) -> R): Provider<R> Provider<T>.flatMap(transform: (T) -> Provider<R>): Provider<R> ``` This mirrors the `map`/`flatMap` pair you see on collections and `Optional`: `map` wraps the result, `flatMap` flattens an already-wrapped result so you don't end up with a doubly-nested container. ## Why flatMap exists In Gradle, many useful derivations *return providers*. A task's output property is a `Provider`/`Property`, an extension's lazily configured field is a `Property`, and `ProviderFactory` methods return providers. If you reach into one of those from inside a `map`, the lambda's result is a `Provider`, so `map` gives you `Provider<Provider<X>>`. `flatMap` collapses that into `Provider<X>`. ## The dependency-tracking payoff Providers that originate from a task carry an implicit dependency on that task. When you `flatMap` from `taskA` into `taskA`'s output property and wire the result into `taskB`'s input, Gradle automatically schedules `taskA` before `taskB` — no explicit `dependsOn` needed. This is the single biggest reason to prefer `flatMap` over manually `.get()`-ing inside `map`. ```kotlin val generate = tasks.register<GenerateTask>("generate") // flatMap: lambda returns generate.outputFile (a Provider) -> flattened val generatedFile: Provider<RegularFile> = generate.flatMap { it.outputFile } tasks.register<ProcessTask>("process") { inputFile.set(generatedFile) // process now implicitly dependsOn generate } ``` ## Common mistake Writing `generate.map { it.outputFile.get() }` superficially "works" but forces evaluation of the nested provider eagerly inside the lambda *at query time of the outer provider*, and — worse — can drop the task dependency in some wiring scenarios because you've reduced it to a plain value. Reach for `flatMap` and never call `.get()` inside these lambdas.

  • What type do you get if you use map where flatMap is needed?
    Provider<Provider<R>> — a nested provider you then have to unwrap, usually by an eager get() that loses laziness and may drop the task dependency.
  • Why does flatMap from a task output preserve build ordering?
    The task's output property is a provider that carries an implicit dependency on the producing task; flatMap keeps it lazy so wiring it into another input establishes the dependency automatically.
  • Is there a flatMap on TaskProvider too?
    Yes — TaskProvider exposes map and flatMap, so you can derive lazy values from a task without realizing/configuring it eagerly.

Like Optional.map vs Optional.flatMap: if your function already returns an Optional, flatMap stops you drowning in Optional<Optional<X>>.

saying these in an interview costs you the question

  • Saying map and flatMap are interchangeable.
  • Calling .get() inside a map to unwrap a provider instead of using flatMap.
  • Claiming flatMap forces eager evaluation.

context

resolving links…