Map And Reduce

View Source

Overview

Map and Reduce operate on ordered lists. Map preserves source order. Reduce is a serial left fold.

Run the cells from top to bottom.

Install The Package

Mix.install([{:jido_action, "~> 3.0.0-beta.11"}])

Define Item Actions

defmodule FlowCollections.Double do
  use Jido.Action, name: "flow_collections_double"

  @impl true
  def run(%{value: value, index: index}, _context) do
    {:ok, %{value: value * 2, index: index}}
  end
end

defmodule FlowCollections.Sum do
  use Jido.Action, name: "flow_collections_sum"

  @impl true
  def run(%{total: total, value: value}, _context) do
    {:ok, %{total: total + value}}
  end
end

Map Then Reduce

defmodule FlowCollections.Example do
  use Jido.Flow, name: "flow_collections_example"

  flow do
    map "doubled",
      collection: input(:values),
      action: FlowCollections.Double,
      params: %{
        value: item(),
        index: item_index()
      }

    reduce "total" do
      collection(result("doubled"))
      initial(%{total: 0})
      action(FlowCollections.Sum)
      params(%{
        total: accumulator(:total),
        value: item(:value)
      })
    end

    output(%{items: result("doubled"), total: result("total")})
  end
end
{:ok, %{items: items, total: %{total: 12}} = result} =
  Jido.Exec.run(FlowCollections.Example, %{values: [1, 2, 3]})

[%{value: 2, index: 0}, %{value: 4, index: 1}, %{value: 6, index: 2}] = items

result

Map returns one ordered list of Action outputs when a scalar expression reads its result. Map supports item(), item_index(), and item_id(). Reduce adds accumulator(). The item ID is a runtime identifier for one collection work unit. IDs are deterministic for the Flow, component name, and source index. Reduce uses its own component name for item IDs, including when it reads a Map result. Do not treat item IDs as execution IDs.

An empty Map returns an empty list. An empty Reduce returns its initial value.

A Reduce reads the complete ordered Map result without consuming it. Other components can read the same Map result, and the Flow can return both results, as shown above.

The Map Action runs once per input item, regardless of the number of readers. Each Reduce runs its own serial fold over that list.

Map Error Modes

The default on_error: :fail_fast stops the component on an item failure.

on_error: :collect_errors returns one tagged record for every item, in source order:

%{status: :ok, value: action_result}
%{status: :error, error: error_map}

The error map uses Jido.Flow.Error.to_map/1: type, message, details, and retryable?. Action failures retain their error type and existing details, including the Map node, target, phase, item index, and item ID. Detail values can contain runtime terms. A parameter reference failure retains its reference path and reason; it does not add target or item identity. Runtime stacktraces are not included in this map.

Choose the mode as part of author intent. A fallback or retry is not inferred.

Concurrency

Map items can run concurrently when max_concurrency is greater than 1. The option limits the native Runic item runnables in each ready wave.

Jido.Exec.run(
  FlowCollections.Example,
  %{values: [1, 2, 3]},
  %{},
  max_concurrency: 2
)

Result order stays equal to input order. Reduce work always stays serial. Collection targets must be Actions, not Flow modules.

Use Named Collection Actions

Map and Reduce use Action modules. Put item, item_index, item_id, and accumulator references in params. This keeps collection declarations as graph data and gives the Action an independent contract.