FuturableTask.traverse()

Map an array of values to tasks and execute them sequentially.

Syntax

FuturableTask.traverse<T, U>(
  values: T[],
  fn: (value: T, index: number) => FuturableTask<U>,
  signal?: AbortSignal
): FuturableTask<U[]>

Parameters

values

Array of values to map over.

fn

Function that maps each value to a FuturableTask. Receives the value and its index.

signal (optional)

AbortSignal for cancellation.

Return Value

A FuturableTask<U[]> that resolves with an array of all results.

Description

Combines mapping and sequential execution. Takes an array of values, applies a function to each to create a task, then executes all tasks sequentially.

Examples

Fetch Users by ID

const userIds = [1, 2, 3, 4, 5];

const users = await FuturableTask
  .traverse(
    userIds,
    id => FuturableTask.fetch(`/api/users/${id}`)
      .map(res => res.json())
  )
  .run();

Process Files

const filePaths = ['file1.txt', 'file2.txt', 'file3.txt'];

const contents = await FuturableTask
  .traverse(
    filePaths,
    path => FuturableTask.of(() => readFile(path))
  )
  .run();

With Index

const items = ['a', 'b', 'c'];

const results = await FuturableTask
  .traverse(
    items,
    (item, index) => FuturableTask.of(() => `${index}: ${item}`)
  )
  .run();
// ['0: a', '1: b', '2: c']

Transform and Save

const data = [
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' }
];

await FuturableTask
  .traverse(
    data,
    item => FuturableTask.of(async () => {
      const transformed = transformItem(item);
      await saveToDatabase(transformed);
      return transformed;
    })
  )
  .run();

With Rate Limiting

const limiter = FuturableTask.createLimiter(3);

const results = await FuturableTask
  .traverse(
    urls,
    url => limiter(
      FuturableTask.fetch(url).map(r => r.json())
    )
  )
  .run();

Comparison with sequence()

// traverse - create tasks from values
const result1 = await FuturableTask.traverse(
  [1, 2, 3],
  n => FuturableTask.of(() => n * 2)
).run();

// sequence - execute existing tasks
const tasks = [1, 2, 3].map(n =>
  FuturableTask.of(() => n * 2)
);
const result2 = await FuturableTask.sequence(tasks).run();

// Both produce [2, 4, 6]

See Also

• sequence() - Execute tasks sequentially
• parallel() - Execute tasks in parallel
• map() - Transform task values