feat(stepfunctions): support Map ItemSelector

packages/aws-cdk-lib/aws-stepfunctions/README.md

@@ -498,7 +498,7 @@ execute the same steps for multiple entries of an array in the state input.
 const map = new sfn.Map(this, 'Map State', {
   maxConcurrency: 1,
   itemsPath: sfn.JsonPath.stringAt('$.inputForMap'),
-  parameters: {
+  itemSelector: {
     item: sfn.JsonPath.stringAt('$$.Map.Item.Value'),
   },
   resultPath: '$.mapOutput',
@@ -528,7 +528,7 @@ An `executionType` must be specified for the distributed `Map` workflow.
 const map = new sfn.Map(this, 'Map State', {
   maxConcurrency: 1,
   itemsPath: sfn.JsonPath.stringAt('$.inputForMap'),
-  parameters: {
+  itemSelector: {
     item: sfn.JsonPath.stringAt('$$.Map.Item.Value'),
   },
   resultPath: '$.mapOutput',

packages/aws-cdk-lib/aws-stepfunctions/lib/states/map.ts

@@ -65,10 +65,29 @@ export interface MapProps {
   /**
    * The JSON that you want to override your default iteration input
    *
+   * @deprecated Step Functions has deprecated the `parameters` field in favor of
+   * the new `itemSelector` field
+   *
+   * @see
+   * https://docs.aws.amazon.com/step-functions/latest/dg/input-output-itemselector.html
+   *
    * @default $
    */
   readonly parameters?: { [key: string]: any };
 
+  /**
+   * The JSON that you want to override your default iteration input
+   *
+   * Step Functions has deprecated the `parameters` field in favor of
+   * the new `itemSelector` field.
+   *
+   * @see
+   * https://docs.aws.amazon.com/step-functions/latest/dg/input-output-itemselector.html
+   *
+   * @default $
+   */
+  readonly itemSelector?: { [key: string]: any };
+
   /**
    * The JSON that will replace the state's raw result and become the effective
    * result before ResultPath is applied.
@@ -122,12 +141,14 @@ export class Map extends State implements INextable {
 
   private readonly maxConcurrency: number | undefined;
   private readonly itemsPath?: string;
+  private readonly itemSelector?: { [key: string]: any };
 
   constructor(scope: Construct, id: string, props: MapProps = {}) {
     super(scope, id, props);
     this.endStates = [this];
     this.maxConcurrency = props.maxConcurrency;
     this.itemsPath = props.itemsPath;
+    this.itemSelector = props.itemSelector;
   }
 
   /**
@@ -200,6 +221,7 @@ export class Map extends State implements INextable {
       ...this.renderRetryCatch(),
       ...this.renderIterator(),
       ...this.renderItemsPath(),
+      ...this.renderItemSelector(),
       ...this.renderItemProcessor(),
       MaxConcurrency: this.maxConcurrency,
     };
@@ -219,6 +241,10 @@ export class Map extends State implements INextable {
       errors.push('Map state cannot have both an iterator and an item processor');
     }
 
+    if (this.parameters && this.itemSelector) {
+      errors.push('Map state cannot have both parameters and an item selector');
+    }
+
     if (this.processorConfig?.mode === ProcessorMode.DISTRIBUTED && !this.processorConfig?.executionType) {
       errors.push('You must specify an execution type for the distributed Map workflow');
     }
@@ -240,8 +266,19 @@ export class Map extends State implements INextable {
    * Render Parameters in ASL JSON format
    */
   private renderParameters(): any {
+    if (!this.parameters) return undefined;
     return FieldUtils.renderObject({
       Parameters: this.parameters,
     });
   }
+
+  /**
+   * Render ItemSelector in ASL JSON format
+   */
+  private renderItemSelector(): any {
+    if (!this.itemSelector) return undefined;
+    return FieldUtils.renderObject({
+      ItemSelector: this.itemSelector,
+    });
+  }
 }

packages/aws-cdk-lib/aws-stepfunctions/test/map.test.ts

@@ -133,6 +133,52 @@ describe('Map State', () => {
     });
   }),
 
+  test('State Machine With Map State and Item Selector', () => {
+    // GIVEN
+    const stack = new cdk.Stack();
+
+    // WHEN
+    const map = new stepfunctions.Map(stack, 'Map State', {
+      stateName: 'My-Map-State',
+      maxConcurrency: 1,
+      itemsPath: stepfunctions.JsonPath.stringAt('$.inputForMap'),
+      itemSelector: {
+        foo: 'foo',
+        bar: stepfunctions.JsonPath.stringAt('$.bar'),
+      },
+    });
+    map.itemProcessor(new stepfunctions.Pass(stack, 'Pass State'));
+
+    // THEN
+    expect(render(map)).toStrictEqual({
+      StartAt: 'My-Map-State',
+      States: {
+        'My-Map-State': {
+          Type: 'Map',
+          End: true,
+          ItemSelector: {
+            'foo': 'foo',
+            'bar.$': '$.bar',
+          },
+          ItemProcessor: {
+            ProcessorConfig: {
+              Mode: 'INLINE',
+            },
+            StartAt: 'Pass State',
+            States: {
+              'Pass State': {
+                Type: 'Pass',
+                End: true,
+              },
+            },
+          },
+          ItemsPath: '$.inputForMap',
+          MaxConcurrency: 1,
+        },
+      },
+    });
+  }),
+
   test('State Machine With Map State and Item Processor in distributed mode', () => {
     // GIVEN
     const stack = new cdk.Stack();
@@ -209,6 +255,23 @@ describe('Map State', () => {
     app.synth();
   }),
 
+  test('synth is successful with item selector', () => {
+    const app = createAppWithMap((stack) => {
+      const map = new stepfunctions.Map(stack, 'Map State', {
+        maxConcurrency: 1,
+        itemsPath: stepfunctions.JsonPath.stringAt('$.inputForMap'),
+        itemSelector: {
+          foo: 'foo',
+          bar: stepfunctions.JsonPath.stringAt('$.bar'),
+        },
+      });
+      map.itemProcessor(new stepfunctions.Pass(stack, 'Pass State'));
+      return map;
+    });
+
+    app.synth();
+  }),
+
   test('synth is successful with item processor and distributed mode', () => {
     const app = createAppWithMap((stack) => {
       const map = new stepfunctions.Map(stack, 'Map State', {
@@ -253,6 +316,27 @@ describe('Map State', () => {
     expect(() => app.synth()).toThrow(/Map state cannot have both an iterator and an item processor/);
   }),
 
+  test('fails in synthesis if parameters and item selector are defined', () => {
+    const app = createAppWithMap((stack) => {
+      const map = new stepfunctions.Map(stack, 'Map State', {
+        maxConcurrency: 1,
+        itemsPath: stepfunctions.JsonPath.stringAt('$.inputForMap'),
+        parameters: {
+          foo: 'foo',
+          bar: stepfunctions.JsonPath.stringAt('$.bar'),
+        },
+        itemSelector: {
+          foo: 'foo',
+          bar: stepfunctions.JsonPath.stringAt('$.bar'),
+        },
+      });
+
+      return map;
+    });
+
+    expect(() => app.synth()).toThrow(/Map state cannot have both parameters and an item selector/);
+  }),
+
   test('fails in synthesis if distributed mode and execution type is not defined', () => {
     const app = createAppWithMap((stack) => {
       const map = new stepfunctions.Map(stack, 'Map State', {