Skip to content
SST
Blog Docs Examples
23K
Console

Map

The Map state is internally used by the StepFunctions component to add a Map workflow state to a state machine.

You’ll find this component returned by the map method of the StepFunctions component.

Constructor

new Map(args)

Parameters

MapArgs

assign?

Type Record<string, any>

Store variables that can be accessed by any state later in the workflow, instead of passing it through each state.

This takes a set of key/value pairs. Where the key is the name of the variable that can be accessed by any subsequent state.

The value can be any JSON value; object, array, string, number, boolean, null.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true
  }
}

Or, you can pass in a JSONata expression.

{
  assign: {
    product: "{% $states.input.order.product %}",
    currentPrice: "{% $states.result.Payload.current_price %}"
  }
}

Learn more about passing data between states with variables.

itemSelector?

Type Input<Record<string, Input<any>>>

Reformat the values of the input array items before they’re passed on to each state iteration.

For example, you can pass in what you want the fields to be.

{
  "itemSelector": {
    "size": 10,
    "value.$": "$$.Map.Item.Value"
  }
}

When applied to the following list of items.

[
  {
    "resize": "true",
    "format": "jpg"
  },
  {
    "resize": "false",
    "format": "png"
  }
]

A transformed item will look like.

{
  "size": 10,
  "value": {
    "resize": "true",
    "format": "jpg"
  }
}

Learn more about ItemSelector.

items?

Type Input<any[] | “{% ${string} %}”>

The list of items to process.

For example, you can specify an array of items.

{
  items: ["item1", "item2", "item3"]
}

Or, specify a JSONata expression that evaluates to an array of items.

{
  items: "{% $states.input.items %}"
}

maxConcurrency?

Type Input<number | “{% ${string} %}”>

Default 0

An upper bound on the number of Map state iterations that can run in parallel. Takes an integer or a JSONata expression that evaluates to an integer.

Default to 0, which means there’s no limit on the concurrency.

For example, to limit it to 10 concurrent iterations.

{
  maxConcurrency: 10
}

mode?

Type Input<“standard” | “express” | “inline”>

Default “inline”

The processing mode for the Map state.

The inline mode is the default and has limited concurrency. In this mode, each item in the Map state runs as a part of the current workflow.

The standard and express mode have high concurrency. In these mode, each item in the Map state runs as a child workflow. This enables high concurrency of up to 10,000 parallel child workflows. Each child workflow has its own, separate execution history.

  • In standard mode, each child runs as a StepFunctions Standard workflow.
  • In express mode, each child runs as a StepFunctions Express workflow.
{
  type: "express"
}

name

Type string

The name of the state. This needs to be unique within the state machine.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Transform the output of the state. When specified, the value overrides the default output from the state.

This takes any JSON value; object, array, string, number, boolean, null.

{
  output: {
    charged: true
  }
}

Or, you can pass in a JSONata expression.

{
  output: {
    product: "{% $states.input.product %}"
  }
}

Learn more about transforming data with JSONata.

processor

Type State

The state to execute for each item in the array.

For example, to iterate over an array of items and execute a Lambda function for each item.

sst.config.ts
const processor = sst.aws.StepFunctions.lambdaInvoke({
  name: "Processor",
  function: "src/processor.handler"
});


sst.aws.StepFunctions.map({
  processor,
  name: "Map",
  items: "{% $states.input.items %}"
});

Methods

catch

catch(state, args?)

Parameters

  • state State

    The state to transition to on error.

  • args? CatchArgs

    Properties to customize error handling.

Returns Map

Add a catch behavior to the Map state. So if the state fails with any of the specified errors, it’ll continue execution to the given state.

This defaults to.

sst.config.ts
sst.aws.StepFunctions.map({
  // ...
})
.catch({
  errors: ["States.ALL"]
});

next

next(state)

Parameters

  • state State

    The state to transition to.

Returns State

Add a next state to the Map state. If the state completes successfully, continue execution to the given state.

sst.config.ts
sst.aws.StepFunctions.map({
  // ...
})
.next(state);

retry

retry(args?)

Parameters

  • args? RetryArgs

    Properties to define the retry behavior.

Returns Map

Add a retry behavior to the Map state. If the state fails with any of the specified errors, retry the execution.

This defaults to.

sst.config.ts
sst.aws.StepFunctions.map({
  // ...
})
.retry({
  errors: ["States.ALL"],
  interval: "1 second",
  maxAttempts: 3,
  backoffRate: 2
});
OSZAR »