flatMap()

Transform the result to another task and flatten the result.

Syntax

task.flatMap<U>(fn: (value: T) => FuturableTask<U>): FuturableTask<U>

Parameters

fn

A function that takes the task's result and returns a new FuturableTask.

Return Value

A new FuturableTask<U> with the flattened result.

Description

The flatMap() method (also known as chain()) is used when your transformation function returns a FuturableTask instead of a plain value. It automatically flattens the nested task structure.

Examples

Basic Usage

const task = FuturableTask
  .of(() => 5)
  .flatMap(x => FuturableTask.of(() => x * 2));

await task.run(); // 10

Sequential API Calls

const getUserPosts = FuturableTask
  .fetch('/api/current-user')
  .map(res => res.json())
  .flatMap(user =>
    FuturableTask.fetch(`/api/users/${user.id}/posts`)
      .map(res => res.json())
  );

Dependent Operations

const workflow = FuturableTask
  .of(() => validateInput(data))
  .flatMap(validated =>
    FuturableTask.of(() => processData(validated))
  )
  .flatMap(processed =>
    FuturableTask.of(() => saveToDatabase(processed))
  );

Conditional Task Execution

const task = FuturableTask
  .of(() => checkCache(key))
  .flatMap(cached =>
    cached
      ? FuturableTask.resolve(cached)
      : FuturableTask.fetch(`/api/data/${key}`)
          .map(res => res.json())
  );

Error Handling Chain

const resilient = FuturableTask
  .fetch('/api/primary')
  .map(res => res.json())
  .flatMap(data => {
    if (data.needsEnrichment) {
      return FuturableTask.fetch('/api/enrich')
        .map(res => res.json())
        .map(enrichment => ({ ...data, ...enrichment }));
    }
    return FuturableTask.resolve(data);
  });

When to Use

Use flatMap() when:

• The transformation returns a FuturableTask
• You need sequential dependent operations
• Conditional task execution based on previous results

Use map() when:

• The transformation returns a plain value
• Simple data transformations

Comparison

// ❌ Wrong - creates nested task
const wrong = FuturableTask
  .of(() => 5)
  .map(x => FuturableTask.of(() => x * 2));
// Type: FuturableTask<FuturableTask<number>>

// ✅ Correct - flattens automatically
const correct = FuturableTask
  .of(() => 5)
  .flatMap(x => FuturableTask.of(() => x * 2));
// Type: FuturableTask<number>

See Also

• map() - Transform values
• Composition Guide