@sst-community/sst 4.21.1 → 5.0.0-alpha.2

package/platform/src/components/aws/step-functions/choice.ts

@@ -0,0 +1,123 @@
+import { isJSONata, JSONata, State, StateArgs } from "./state";
+
+export interface ChoiceArgs extends StateArgs { }
+
+/**
+ * The `Choice` state is internally used by the `StepFunctions` component to add a [Choice
+ * workflow state](https://docs.aws.amazon.com/step-functions/latest/dg/state-choice.html)
+ * to a state machine.
+ *
+ * :::note
+ * This component is not intended to be created directly.
+ * :::
+ *
+ * You'll find this component returned by the `choice` method of the `StepFunctions` component.
+ */
+export class Choice extends State {
+  private choices: {
+    condition: JSONata;
+    next: State;
+  }[] = [];
+  private defaultNext?: State;
+
+  constructor(protected args: ChoiceArgs) {
+    super(args);
+  }
+
+  /**
+   * Add a matching condition to the `Choice` state. If the given condition matches,
+   * it'll continue execution to the given state.
+   *
+   * The condition needs to be a JSONata expression that evaluates to a boolean.
+   *
+   * @example
+   *
+   * ```ts
+   * sst.aws.StepFunctions.choice({
+   *   // ...
+   * })
+   * .when(
+   *   "{% $states.input.status === 'unpaid' %}",
+   *   state
+   * );
+   * ```
+   *
+   * @param condition The JSONata condition to evaluate.
+   * @param next The state to transition to.
+   */
+  public when(condition: JSONata, next: State) {
+    if (!isJSONata(condition))
+      throw new Error("Condition must start with '{%' and end with '%}'.");
+
+    this.choices.push({ condition, next });
+    return this;
+  }
+
+  /**
+   * Add a default next state to the `Choice` state. If no other condition matches,
+   * continue execution with the given state.
+   */
+  public otherwise(next: State) {
+    this.defaultNext = next;
+    return this;
+  }
+
+  /**
+   * @internal
+   */
+  public assertStateNameUnique(states: Map<string, State> = new Map()) {
+    super.assertStateNameUnique(states);
+    this.choices.forEach((c) => c.next.assertStateNameUnique(states));
+    this.defaultNext?.assertStateNameUnique(states);
+  }
+
+  /**
+   * @internal
+   */
+  public assertStateNotReused(
+    states: Map<State, string> = new Map(),
+    graphId: string = "main",
+  ) {
+    super.assertStateNotReused(states, graphId);
+    this.choices.forEach((c) => c.next.assertStateNotReused(states, graphId));
+    this.defaultNext?.assertStateNotReused(states, graphId);
+  }
+
+  /**
+   * @internal
+   */
+  public getPermissions() {
+    return [
+      ...this.choices.flatMap((c) => c.next.getPermissions()),
+      ...(this.defaultNext?.getPermissions() || []),
+      ...super.getPermissions(),
+    ];
+  }
+
+  /**
+   * @internal
+   */
+  public serialize() {
+    return {
+      ...super.serialize(),
+      ...this.defaultNext?.serialize(),
+      ...this.choices.reduce(
+        (acc, c) => ({ ...acc, ...c.next.serialize() }),
+        {},
+      ),
+    };
+  }
+
+  protected toJSON() {
+    return {
+      Type: "Choice",
+      Choices: this.choices.map((c) => ({
+        Condition: c.condition,
+        Next: c.next.name,
+      })),
+      Default: this.defaultNext?.name,
+      ...super.toJSON(),
+      End: undefined,
+    };
+  }
+}

package/platform/src/components/aws/step-functions/fail.ts

@@ -0,0 +1,69 @@
+import { Input } from "../../input";
+import { State, StateArgs } from "./state";
+
+export interface FailArgs extends StateArgs {
+  /**
+   * A custom string that describes the cause of the error.
+   *
+   * ```ts
+   * {
+   *   cause: "User not found"
+   * }
+   * ```
+   *
+   * Alternatively, you can specify a JSONata expression that evaluates to a string.
+   *
+   * ```ts
+   * {
+   *   cause: "{% $states.input.user %}"
+   * }
+   * ```
+   */
+  cause?: Input<string>;
+  /**
+   * An error name that you can provide to perform error handling using `retry` or
+   * `catch`.
+   * ```ts
+   * {
+   *   error: "UserNotFound"
+   * }
+   * ```
+   * Alternatively, you can specify a JSONata expression that evaluates to a string.
+   * ```ts
+   * {
+   *   error: "{% $states.input.error %}"
+   * }
+   * ```
+   */
+  error?: Input<string>;
+}
+
+/**
+ * The `Fail` state is internally used by the `StepFunctions` component to add a
+ * [Fail workflow state](https://docs.aws.amazon.com/step-functions/latest/dg/state-fail.html)
+ * to a state machine.
+ *
+ * :::note
+ * This component is not intended to be created directly.
+ * :::
+ *
+ * You'll find this component returned by the `fail` method of the `StepFunctions` component.
+ */
+export class Fail extends State {
+  constructor(protected args: FailArgs) {
+    super(args);
+  }
+
+  /**
+   * Serialize the state into JSON state definition.
+   */
+  protected toJSON() {
+    return {
+      Type: "Fail",
+      Error: this.args.error,
+      Cause: this.args.cause,
+      ...super.toJSON(),
+      End: undefined,
+    };
+  }
+}

package/platform/src/components/aws/step-functions/map.ts

@@ -0,0 +1,264 @@
+import { Output, output } from "@pulumi/pulumi";
+import { Input } from "../../input";
+import {
+  CatchArgs,
+  Failable,
+  JSONata,
+  Nextable,
+  RetryArgs,
+  State,
+  StateArgs,
+} from "./state";
+
+export interface MapArgs extends StateArgs {
+  /**
+   * 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.
+   *
+   * :::note
+   * `Map` state with `standard` or `express` mode is not supported in `express` type StepFunctions.
+   * :::
+   *
+   * @default `"inline"`
+   * @example
+   * ```js
+   * {
+   *   type: "express"
+   * }
+   * ```
+   */
+  mode?: Input<"inline" | "standard" | "express">;
+  /**
+   * The list of items to process.
+   *
+   * @example
+   * For example, you can specify an array of items.
+   *
+   * ```ts
+   * {
+   *   items: ["item1", "item2", "item3"]
+   * }
+   * ```
+   *
+   * Or, specify a JSONata expression that evaluates to an array of items.
+   *
+   * ```ts
+   * {
+   *   items: "{% $states.input.items %}"
+   * }
+   * ```
+   */
+  items?: Input<JSONata | 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.
+   *
+   * ```ts
+   * {
+   *   "itemSelector": {
+   *     "size": 10,
+   *     "value.$": "$$.Map.Item.Value"
+   *   }
+   * }
+   * ```
+   *
+   * When applied to the following list of items.
+   *
+   * ```ts
+   * [
+   *   {
+   *     "resize": "true",
+   *     "format": "jpg"
+   *   },
+   *   {
+   *     "resize": "false",
+   *     "format": "png"
+   *   }
+   * ]
+   * ```
+   *
+   * A transformed item will look like.
+   *
+   * ```ts
+   * {
+   *   "size": 10,
+   *   "value": {
+   *     "resize": "true",
+   *     "format": "jpg"
+   *   }
+   * }
+   * ```
+   *
+   * Learn more about [`ItemSelector`](https://docs.aws.amazon.com/step-functions/latest/dg/input-output-itemselector.html).
+   */
+  itemSelector?: Input<Record<string, Input<any>>>;
+  /**
+   * 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.
+   *
+   * @default `0`
+   * @example
+   * For example, to limit it to 10 concurrent iterations.
+   * ```ts
+   * {
+   *   maxConcurrency: 10
+   * }
+   * ```
+   */
+  maxConcurrency?: Input<JSONata | number>;
+  /**
+   * The state to execute for each item in the array.
+   *
+   * @example
+   *
+   * For example, to iterate over an array of items and execute a Lambda function
+   * for each item.
+   *
+   * ```ts title="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 %}"
+   * });
+   * ```
+   */
+  processor: State;
+}
+
+/**
+ * The `Map` state is internally used by the `StepFunctions` component to add a [Map
+ * workflow state](https://docs.aws.amazon.com/step-functions/latest/dg/state-map.html)
+ * to a state machine.
+ *
+ * :::note
+ * This component is not intended to be created directly.
+ * :::
+ *
+ * You'll find this component returned by the `map` method of the `StepFunctions` component.
+ */
+export class Map extends State implements Nextable, Failable {
+  private processor: State;
+  private mode: Output<"inline" | "standard" | "express">;
+
+  constructor(protected args: MapArgs) {
+    super(args);
+    this.processor = args.processor.getHead();
+    this.addChildGraph(this.processor);
+    this.mode = output(args.mode ?? "inline");
+  }
+
+  /**
+   * Add a next state to the `Map` state. If the state completes successfully,
+   * continue execution to the given `state`.
+   *
+   * @param state The state to transition to.
+   *
+   * @example
+   *
+   * ```ts title="sst.config.ts"
+   * sst.aws.StepFunctions.map({
+   *   // ...
+   * })
+   * .next(state);
+   * ```
+   */
+  public next<T extends State>(state: T): T {
+    return this.addNext(state);
+  }
+
+  /**
+   * Add a retry behavior to the `Map` state. If the state fails with any of the
+   * specified errors, retry the execution.
+   *
+   * @param args Properties to define the retry behavior.
+   *
+   * @example
+   *
+   * This defaults to.
+   *
+   * ```ts title="sst.config.ts" {5-8}
+   * sst.aws.StepFunctions.map({
+   *   // ...
+   * })
+   * .retry({
+   *   errors: ["States.ALL"],
+   *   interval: "1 second",
+   *   maxAttempts: 3,
+   *   backoffRate: 2
+   * });
+   * ```
+   */
+  public retry(args?: RetryArgs) {
+    return this.addRetry(args);
+  }
+
+  /**
+   * 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`.
+   *
+   * @param state The state to transition to on error.
+   * @param args Properties to customize error handling.
+   *
+   * @example
+   *
+   * This defaults to.
+   *
+   * ```ts title="sst.config.ts" {5}
+   * sst.aws.StepFunctions.map({
+   *   // ...
+   * })
+   * .catch({
+   *   errors: ["States.ALL"]
+   * });
+   * ```
+   */
+  public catch(state: State, args: CatchArgs = {}) {
+    return this.addCatch(state, args);
+  }
+
+  /**
+   * @internal
+   */
+  public getPermissions() {
+    return [...this.processor.getPermissions(), ...super.getPermissions()];
+  }
+
+  /**
+   * Serialize the state into JSON state definition.
+   */
+  protected toJSON() {
+    return {
+      Type: "Map",
+      Items: this.args.items,
+      ItemSelector: this.args.itemSelector,
+      ItemProcessor: {
+        ProcessorConfig: this.mode.apply((mode) =>
+          mode === "inline"
+            ? { Mode: "INLINE" }
+            : { Mode: "DISTRIBUTED", ExecutionType: mode.toUpperCase() },
+        ),
+        StartAt: this.processor.name,
+        States: this.processor.serialize(),
+      },
+      MaxConcurrency: this.args.maxConcurrency,
+      ...super.toJSON(),
+    };
+  }
+}

package/platform/src/components/aws/step-functions/parallel.ts

@@ -0,0 +1,170 @@
+import { Input } from "../../input";
+import {
+  CatchArgs,
+  Failable,
+  Nextable,
+  RetryArgs,
+  State,
+  StateArgs,
+} from "./state";
+
+export interface ParallelArgs extends StateArgs {
+  /**
+   * The arguments to be passed to the APIs of the connected resources. Values can
+   * include outputs from other resources and JSONata expressions.
+   *
+   * @example
+   *
+   * ```ts
+   * {
+   *   arguments: {
+   *     product: "{% $states.input.order.product %}",
+   *     url: api.url,
+   *     count: 32
+   *   }
+   * }
+   * ```
+   */
+  arguments?: Input<Record<string, Input<any>>>;
+}
+
+/**
+ * The `Parallel` state is internally used by the `StepFunctions` component to add a [Parallel
+ * workflow state](https://docs.aws.amazon.com/step-functions/latest/dg/state-parallel.html)
+ * to a state machine.
+ *
+ * :::note
+ * This component is not intended to be created directly.
+ * :::
+ *
+ * You'll find this component returned by the `parallel` method of the `StepFunctions` component.
+ */
+export class Parallel extends State implements Nextable, Failable {
+  private branches: State[] = [];
+
+  constructor(protected args: ParallelArgs) {
+    super(args);
+  }
+
+  /**
+   * Add a branch state to the `Parallel` state. Each branch runs concurrently.
+   *
+   * @param branch The state to add as a branch.
+   *
+   * @example
+   *
+   * ```ts title="sst.config.ts"
+   * const parallel = sst.aws.StepFunctions.parallel({ name: "Parallel" });
+   * 
+   * parallel.branch(processorA);
+   * parallel.branch(processorB);
+   * ```
+   */
+  public branch(branch: State) {
+    const head = branch.getHead();
+    this.branches.push(head);
+    this.addChildGraph(head);
+    return this;
+  }
+
+  /**
+   * Add a next state to the `Parallel` state. If all branches complete successfully,
+   * this'll continue execution to the given `state`.
+   *
+   * @param state The state to transition to.
+   *
+   * @example
+   *
+   * ```ts title="sst.config.ts"
+   * sst.aws.StepFunctions.parallel({
+   *   // ...
+   * })
+   * .next(state);
+   * ```
+   */
+  public next<T extends State>(state: T): T {
+    return this.addNext(state);
+  }
+
+  /**
+   * Add a retry behavior to the `Parallel` state. If the state fails with any of the
+   * specified errors, retry execution using the specified parameters.
+   *
+   * @param args Properties to define the retry behavior.
+   *
+   * @example
+   *
+   * This defaults to.
+   *
+   * ```ts title="sst.config.ts" {5-8}
+   * sst.aws.StepFunctions.parallel({
+   *   // ...
+   * })
+   * .retry({
+   *   errors: ["States.ALL"],
+   *   interval: "1 second",
+   *   maxAttempts: 3,
+   *   backoffRate: 2
+   * });
+   * ```
+   */
+  public retry(args?: RetryArgs) {
+    return this.addRetry(args);
+  }
+
+  /**
+   * Add a catch behavior to the `Parallel` state. So if the state fails with any
+   * of the specified errors, it'll continue execution to the given `state`.
+   *
+   * @param state The state to transition to on error.
+   * @param args Properties to customize error handling.
+   *
+   * @example
+   *
+   * This defaults to.
+   *
+   * ```ts title="sst.config.ts" {5}
+   * sst.aws.StepFunctions.parallel({
+   *   // ...
+   * })
+   * .catch({
+   *   errors: ["States.ALL"]
+   * });
+   * ```
+   */
+  public catch(state: State, args: CatchArgs = {}) {
+    return this.addCatch(state, args);
+  }
+
+  /**
+   * @internal
+   */
+  public getPermissions() {
+    return [
+      ...this.branches.flatMap((b) => b.getPermissions()),
+      ...super.getPermissions(),
+    ];
+  }
+
+  /**
+   * Serialize the state into JSON state definition.
+   */
+  protected toJSON() {
+    if (this.branches.length === 0) {
+      throw new Error(
+        `The "${this.name}" Parallel state must have at least one branch.`,
+      );
+    }
+
+    return {
+      Type: "Parallel",
+      Branches: this.branches.map((b) => {
+        return {
+          StartAt: b.name,
+          States: b.serialize(),
+        };
+      }),
+      ...super.toJSON(),
+    };
+  }
+}

package/platform/src/components/aws/step-functions/pass.ts

@@ -0,0 +1,48 @@
+import { Input } from "../../input";
+import { Nextable, State, StateArgs } from "./state";
+
+export interface PassArgs extends StateArgs { }
+
+/**
+ * The `Pass` state is internally used by the `StepFunctions` component to add a [Pass
+ * workflow state](https://docs.aws.amazon.com/step-functions/latest/dg/state-pass.html)
+ * to a state machine.
+ *
+ * :::note
+ * This component is not intended to be created directly.
+ * :::
+ *
+ * You'll find this component returned by the `pass` method of the `StepFunctions` component.
+ */
+export class Pass extends State implements Nextable {
+  constructor(protected args: PassArgs) {
+    super(args);
+  }
+
+  /**
+   * Add a next state to the `Pass` state. After this state completes, it'll
+   * transition to the given `state`.
+   *
+   * @example
+   *
+   * ```ts title="sst.config.ts"
+   * sst.aws.StepFunctions.pass({
+   *   // ...
+   * })
+   * .next(state);
+   * ```
+   */
+  public next<T extends State>(state: T): T {
+    return this.addNext(state);
+  }
+
+  /**
+   * Serialize the state into JSON state definition.
+   */
+  protected toJSON() {
+    return {
+      Type: "Pass",
+      ...super.toJSON(),
+    };
+  }
+}