feat(stepfunctions): add support for Map state

packages/@aws-cdk/aws-stepfunctions/lib/index.ts

@@ -18,6 +18,7 @@ export * from './states/state';
 export * from './states/succeed';
 export * from './states/task';
 export * from './states/wait';
+export * from './states/map';
 
 // AWS::StepFunctions CloudFormation Resources:
 export * from './stepfunctions.generated';

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

@@ -0,0 +1,164 @@
+import cdk = require('@aws-cdk/core');
+import { Chain } from '../chain';
+import { StateGraph } from '../state-graph';
+import { CatchProps, IChainable, INextable, RetryProps } from '../types';
+import { StateType } from './private/state-type';
+import { renderJsonPath, State } from './state';
+
+/**
+ * Properties for defining a Map state
+ */
+export interface MapProps {
+    /**
+     * An optional description for this state
+     *
+     * @default No comment
+     */
+    readonly comment?: string;
+
+    /**
+     * JSONPath expression to select part of the state to be the input to this state.
+     *
+     * May also be the special value DISCARD, which will cause the effective
+     * input to be the empty object {}.
+     *
+     * @default $
+     */
+    readonly inputPath?: string;
+
+    /**
+     * JSONPath expression to select part of the state to be the output to this state.
+     *
+     * May also be the special value DISCARD, which will cause the effective
+     * output to be the empty object {}.
+     *
+     * @default $
+     */
+    readonly outputPath?: string;
+
+    /**
+     * JSONPath expression to indicate where to inject the state's output
+     *
+     * May also be the special value DISCARD, which will cause the state's
+     * input to become its output.
+     *
+     * @default $
+     */
+    readonly resultPath?: string;
+
+    /**
+     * JSONPath expression to select the array to iterate over
+     *
+     * @default $
+     */
+    readonly itemsPath?: string;
+
+    /**
+     * The JSON that you want to override your default iteration input
+     *
+     * @default $
+     */
+    readonly parameters?: { [key: string]: any };
+
+    /**
+     * MaxConcurrency
+     *
+     * An upper bound on the number of iterations you want running at once.
+     *
+     * @default - full concurrency
+     */
+    readonly maxConcurrency?: number;
+}
+
+/**
+ * Define a Map state in the state machine
+ *
+ * A Map state can be used to dynamically process elements of an array through sub state machines
+ *
+ * The Result of a Map state is the transformed array after processing through the iterator state machines.
+ */
+export class Map extends State implements INextable {
+    public readonly endStates: INextable[];
+
+    private readonly maxConcurrency?: number;
+    private readonly itemsPath?: string;
+
+    constructor(scope: cdk.Construct, id: string, props: MapProps = {}) {
+        super(scope, id, props);
+        this.endStates = [this];
+        this.maxConcurrency = props.maxConcurrency;
+        this.itemsPath = props.itemsPath;
+    }
+
+    /**
+     * Add retry configuration for this state
+     *
+     * This controls if and how the execution will be retried if a particular
+     * error occurs.
+     */
+    public addRetry(props: RetryProps = {}): Map {
+        super._addRetry(props);
+        return this;
+    }
+
+    /**
+     * Add a recovery handler for this state
+     *
+     * When a particular error occurs, execution will continue at the error
+     * handler instead of failing the state machine execution.
+     */
+    public addCatch(handler: IChainable, props: CatchProps = {}): Map {
+        super._addCatch(handler.startState, props);
+        return this;
+    }
+
+    /**
+     * Continue normal execution with the given state
+     */
+    public next(next: IChainable): Chain {
+        super.makeNext(next.startState);
+        return Chain.sequence(this, next);
+    }
+
+    /**
+     * Define iterator state machine in Map
+     */
+    public iterator(iterator: IChainable): Map {
+        const name = `Map ${this.stateId} Iterator`;
+        super.addIterator(new StateGraph(iterator.startState, name));
+        return this;
+    }
+
+    /**
+     * Return the Amazon States Language object for this state
+     */
+    public toStateJson(): object {
+        return {
+            Type: StateType.MAP,
+            Comment: this.comment,
+            ResultPath: renderJsonPath(this.resultPath),
+            ...this.renderNextEnd(),
+            ...this.renderInputOutput(),
+            ...this.renderRetryCatch(),
+            ...this.renderIterator(),
+            ...this.renderItemsPath(),
+            MaxConcurrency: this.maxConcurrency
+        };
+    }
+
+    /**
+     * Validate this state
+     */
+    protected validate(): string[] {
+        if (!!this.iterator) {
+            return ['Map state must have a non-empty iterator'];
+        }
+        return [];
+    }
+
+    private renderItemsPath(): any {
+        return {
+            ItemsPath: renderJsonPath(this.itemsPath)
+        };
+    }
+}

packages/@aws-cdk/aws-stepfunctions/lib/states/private/state-type.ts

@@ -8,5 +8,6 @@ export enum StateType {
   WAIT = 'Wait',
   SUCCEED = 'Succeed',
   FAIL = 'Fail',
-  PARALLEL = 'Parallel'
+  PARALLEL = 'Parallel',
+  MAP = 'Map'
 }

packages/@aws-cdk/aws-stepfunctions/lib/states/state.ts

@@ -126,6 +126,7 @@ export abstract class State extends cdk.Construct implements IChainable {
     protected readonly outputPath?: string;
     protected readonly resultPath?: string;
     protected readonly branches: StateGraph[] = [];
+    protected iteration?: StateGraph;
     protected defaultChoice?: State;
 
     /**
@@ -210,6 +211,9 @@ export abstract class State extends cdk.Construct implements IChainable {
         for (const branch of this.branches) {
             branch.registerSuperGraph(this.containingGraph);
         }
+        if (!!this.iteration) {
+            this.iteration.registerSuperGraph(this.containingGraph);
+        }
     }
 
     /**
@@ -282,6 +286,16 @@ export abstract class State extends cdk.Construct implements IChainable {
         }
     }
 
+    /**
+     * Add a map iterator to this state
+     */
+    protected addIterator(iteration: StateGraph) {
+        this.iteration = iteration;
+        if (this.containingGraph) {
+            iteration.registerSuperGraph(this.containingGraph);
+        }
+    }
+
     /**
      * Make the indicated state the default choice transition of this state
      */
@@ -334,6 +348,18 @@ export abstract class State extends cdk.Construct implements IChainable {
         };
     }
 
+    /**
+     * Render map iterator in ASL JSON format
+     */
+    protected renderIterator(): any {
+        if (!this.iteration) {
+            throw new Error(`Iterator must not be undefined !`);
+        }
+        return {
+            Iterator: this.iteration.toGraphJson()
+        };
+    }
+
     /**
      * Render error recovery options in ASL JSON format
      */

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

@@ -0,0 +1,50 @@
+import cdk = require('@aws-cdk/core');
+import { Test } from 'nodeunit';
+import stepfunctions = require('../lib');
+
+export = {
+    'State Machine With Map State'(test: Test) {
+        // GIVEN
+        const stack = new cdk.Stack();
+
+        // WHEN
+        const map = new stepfunctions.Map(stack, 'Map State', {
+            maxConcurrency: 1,
+            itemsPath: stepfunctions.Data.stringAt('$.inputForMap'),
+            parameters: {
+                foo: 'foo',
+                bar: stepfunctions.Data.stringAt('$.bar')
+            }
+        });
+        map.iterator(new stepfunctions.Pass(stack, 'Pass State'));
+
+        // THEN
+        test.deepEqual(render(map), {
+            StartAt: 'Map State',
+            States: {
+                'Map State': {
+                    Type: 'Map',
+                    End: true,
+                    Parameters: { foo: 'foo', bar: '$.bar' },
+                    Iterator: {
+                        StartAt: 'Pass State',
+                        States: {
+                            'Pass State': {
+                                Type: 'Pass',
+                                End: true
+                            }
+                        }
+                    },
+                    ItemsPath: '$.inputForMap',
+                    MaxConcurrency: 1
+                }
+            }
+        });
+
+        test.done();
+    }
+};
+
+function render(sm: stepfunctions.IChainable) {
+    return new cdk.Stack().resolve(new stepfunctions.StateGraph(sm.startState, 'Test Graph').toGraphJson());
+}

packages/@aws-cdk/aws-stepfunctions/test/test.parallel.ts

@@ -0,0 +1,36 @@
+import cdk = require('@aws-cdk/core');
+import { Test } from 'nodeunit';
+import stepfunctions = require('../lib');
+
+export = {
+    'State Machine With Parallel State'(test: Test) {
+        // GIVEN
+        const stack = new cdk.Stack();
+
+        // WHEN
+        const parallel = new stepfunctions.Parallel(stack, 'Parallel State');
+        parallel.branch(new stepfunctions.Pass(stack, 'Branch 1'));
+        parallel.branch(new stepfunctions.Pass(stack, 'Branch 2'));
+
+        // THEN
+        test.deepEqual(render(parallel), {
+            StartAt: 'Parallel State',
+            States: {
+                'Parallel State': {
+                    Type: 'Parallel',
+                    End: true,
+                    Branches: [
+                        { StartAt: 'Branch 1', States: { 'Branch 1': { Type: 'Pass', End: true } } },
+                        { StartAt: 'Branch 2', States: { 'Branch 2': { Type: 'Pass', End: true } } }
+                    ]
+                }
+            }
+        });
+
+        test.done();
+    }
+};
+
+function render(sm: stepfunctions.IChainable) {
+    return new cdk.Stack().resolve(new stepfunctions.StateGraph(sm.startState, 'Test Graph').toGraphJson());
+}