Workflow.foreach()

The .foreach() method creates a loop that executes a step for each item in an array. It always returns an array containing the output from each iteration, preserving the original order.

Usage example

workflow.foreach(step1, { concurrency: 2 });

Parameters

step:

Step

The step instance to execute in the loop. The previous step must return an array type.

opts?:

object

Optional configuration for the loop. The concurrency option controls how many iterations can run in parallel (default: 1)

number

Returns

workflow:

Workflow

The workflow instance for method chaining. The output type is an array of the step's output type.

Behavior

Execution and waiting

The .foreach() method processes all items before the next step executes. The step following .foreach() only runs after every iteration has completed, regardless of concurrency settings. With concurrency: 1 (default), items process sequentially. With higher concurrency, items process in parallel batches, but the next step still waits for all batches to finish.

If you need to run multiple operations per item, use a nested workflow as the step. This keeps all operations for each item together and is cleaner than chaining multiple .foreach() calls. See Nested workflows inside foreach for examples.

Output structure

.foreach() always outputs an array. Each element in the output array corresponds to the result of processing the element at the same index in the input array.

// Input: [{ value: 1 }, { value: 2 }, { value: 3 }]
// Step adds 10 to each value
// Output: [{ value: 11 }, { value: 12 }, { value: 13 }]

Using .then() after .foreach()

When you chain .then() after .foreach(), the next step receives the entire output array as its input. This allows you to aggregate or process all results together.

workflow
  .foreach(processItemStep)    // Output: array of processed items
  .then(aggregateStep)         // Input: the entire array
  .commit();

Using .map() after .foreach()

Use .map() to transform the array output before passing it to the next step:

workflow
  .foreach(processItemStep)
  .map(async ({ inputData }) => ({
    total: inputData.reduce((sum, item) => sum + item.value, 0),
    count: inputData.length
  }))
  .then(nextStep)
  .commit();

Chaining multiple .foreach() calls

When you chain .foreach() calls, each operates on the array from the previous step:

workflow
  .foreach(stepA)    // If input is [a, b, c], output is [A, B, C]
  .foreach(stepB)    // Operates on [A, B, C], output is [A', B', C']
  .commit();

If a step inside .foreach() returns an array, the output becomes an array of arrays. Use .map() with .flat() to flatten:

workflow
  .foreach(chunkStep)           // Output: [[chunk1, chunk2], [chunk3, chunk4]]
  .map(async ({ inputData }) => inputData.flat())  // Output: [chunk1, chunk2, chunk3, chunk4]
  .foreach(embedStep)
  .commit();

Related

• Looping with foreach