aws-local-stepfunctions 1.2.0 → 1.3.1

package/README.md

@@ -41,6 +41,7 @@ This package lets you run AWS Step Functions state machines completely locally,
   - [Overriding Task and Wait states](#overriding-task-and-wait-states)
     - [Task state override](#task-state-override)
     - [Wait state override](#wait-state-override)
+    - [Retry field pause override](#retry-field-pause-override)
   - [Passing a custom Context Object](#passing-a-custom-context-object)
   - [Disabling ASL validations](#disabling-asl-validations)
   - [Exit codes](#exit-codes)
@@ -160,8 +161,18 @@ Each execution is independent of all others, meaning that you can concurrently c
   - `overrides?`: An object to override the behavior of certain states:
     - `taskResourceLocalHandlers?`: An [object that overrides](/docs/feature-support.md#task-state-resource-override) the resource of the specified `Task` states to run a local function.
     - `waitTimeOverrides?`: An [object that overrides](/docs/feature-support.md#wait-state-duration-override) the wait duration of the specified `Wait` states. The specified override duration should be in milliseconds.
+    - `retryIntervalOverrides?`: An [object that overrides](/docs/feature-support.md#retry-field-interval-override) the pause duration of the specified state's `Retry` field. The specified override duration should be a number in milliseconds; or an array of numbers, where each number represents milliseconds.
   - `noThrowOnAbort?`: If this option is set to `true`, aborting the execution will simply return `null` as result instead of throwing.
-  - `context?`: An object that will be used as the [Context Object](https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html) for the execution. If not passed, the Context Object will default to an empty object. This option is useful to mock the Context Object in case your definition references it in a JSONPath.
+  - `context?`: An object that will be used as the [Context Object](https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html) for the execution. If not passed, the Context Object will default to the following object:
+    ```js
+    {
+      "Execution": {
+        "Input": /* input passed to the execution */,
+        "StartTime": /* ISO 8601 timestamp of when the execution started */
+      }
+    }
+    ```
+    This option is useful to mock the fields of the Context Object in case your definition references it in a JSONPath.
 
 #### Return value
 
@@ -352,6 +363,54 @@ local-sfn \
 
 This command would execute the state machine, and override `Wait` states `WaitResponse` and `PauseUntilSignal` to pause the execution for 1500 and 250 milliseconds, respectively. The `Delay` state wouldn't be paused at all, since the override value is set to 0.
 
+#### Retry field pause override
+
+To override the duration of the pause in the `Retry` field of a state, pass the `-r, --override-retry` option. This option takes as value the name of the state whose `Retry` field you want to override, and a number that represents the amount in milliseconds that you want to pause the execution for before retrying the state. The state name and the milliseconds amount must be separated by a colon `:`.
+
+For example, suppose the state machine definition contains a state called `TaskToRetry` that is defined as follows:
+
+```json
+{
+  "Type": "Task",
+  "Resource": "arn:aws:lambda:us-east-1:123456789012:function:HelloWorld",
+  "Retry": [
+    { "ErrorEquals": ["States.Timeout", "SyntaxError"] },
+    { "ErrorEquals": ["RangeError"] },
+    { "ErrorEquals": ["States.ALL"] }
+  ],
+  "End": true
+}
+```
+
+Then, the following command is run:
+
+```sh
+local-sfn -f state-machine.json -r TaskToRetry:100 '{ "num1": 1, "num2": 2 }'
+```
+
+This command would execute the state machine, and if the `TaskToRetry` state fails, the execution would be paused for 100 milliseconds before retrying the state again, disregarding the `IntervalSeconds`, `BackoffRate`, `MaxDelaySeconds`, and `JitterStrategy` fields that could've been specified in any of the `Retry` field retriers.
+
+Alternatively, you can also pass a list of comma-separated numbers as value, to override the duration of specific retriers, for instance:
+
+```sh
+local-sfn -f state-machine.json -r TaskToRetry:100,-1,20 '{ "num1": 1, "num2": 2 }'
+```
+
+The above command would pause the execution for 100 milliseconds if the state error is matched by the first retrier and it would pause for 20 milliseconds if the error matches the third retrier. Note that a -1 was passed for the second retrier. This means that the pause duration of the second retrier will not be overridden, instead, it will be calculated as usually with the `IntervalSeconds` and the other retrier fields, or use the default values if said fields are not specified.
+
+Furthermore, you can pass this option multiple times, to override the `Retry` fields in multiple states. For example:
+
+```sh
+local-sfn \
+  -f state-machine.json \
+  -r SendRequest:1500 \
+  -r ProcessData:250 \
+  -r MapResponses:0 \
+  '{ "num1": 1, "num2": 2 }'
+```
+
+This command would execute the state machine, and override the duration of the retry pause in states `SendRequest` and `ProcessData` to pause the execution for 1500 and 250 milliseconds, respectively. The retry in the `MapResponses` state wouldn't be paused at all, since the override value is set to 0.
+
 ### Passing a custom Context Object
 
 If the JSONPaths in your definition reference the Context Object, you can provide a mock Context Object by passing either the `--context` or the `--context-file` option. For example, given the following definition:

package/bin/CLI.cjs

@@ -38,7 +38,7 @@ var import_readline = __toESM(require("readline"), 1);
 var import_commander = require("commander");
 
 // package.json
-var version = "1.2.0";
+var version = "1.3.1";
 
 // src/cli/ArgumentParsers.ts
 var import_fs = require("fs");
@@ -111,6 +111,15 @@ function parseOverrideWaitOption(value, previous = {}) {
   previous[waitStateName] = Number(duration);
   return previous;
 }
+function parseOverrideRetryOption(value, previous = {}) {
+  const [stateName, duration] = value.split(":");
+  if (!isNaN(duration)) {
+    previous[stateName] = Number(duration);
+  } else {
+    previous[stateName] = duration.split(",").map(Number);
+  }
+  return previous;
+}
 function parseContextOption(command, context) {
   const jsonOrError = tryJSONParse(context);
   if (jsonOrError instanceof Error) {
@@ -167,7 +176,8 @@ async function commandAction(inputs, options, command) {
     const { result } = stateMachine.run(input, {
       overrides: {
         taskResourceLocalHandlers: options.overrideTask,
-        waitTimeOverrides: options.overrideWait
+        waitTimeOverrides: options.overrideWait,
+        retryIntervalOverrides: options.overrideRetry
       },
       context: options.context ?? options.contextFile
     });
@@ -207,7 +217,7 @@ function makeProgram() {
   const command = new import_commander.Command();
   command.name("local-sfn").description(
     `Execute an Amazon States Language state machine with the given inputs.
-The result of each execution will be output in a new line and in the same order as its corresponding input.`
+The result of each execution will be printed in a new line and in the same order as its corresponding input.`
   ).helpOption("-h, --help", "Print help for command and exit.").configureHelp({ helpWidth: 80 }).addHelpText(
     "after",
     `
@@ -234,6 +244,11 @@ Example calls:
       "-w, --override-wait <mapping>",
       "Override a Wait state to pause for the specified amount of milliseconds, instead of pausing for the duration specified in the state definition. The mapping value has to be provided in the format [WaitStateToOverride]:[number]."
     ).argParser(parseOverrideWaitOption)
+  ).addOption(
+    new import_commander.Option(
+      "-r, --override-retry <mapping>",
+      "Override a 'Retry' field to pause for the specified amount of milliseconds, instead of pausing for the duration specified by the retry policy. The mapping value has to be provided in the format [NameOfStateWithRetryField]:[number]."
+    ).argParser(parseOverrideRetryOption)
   ).addOption(
     new import_commander.Option(
       "--context <json>",