aws-local-stepfunctions 0.7.0 → 1.0.0

package/README.md

@@ -2,7 +2,25 @@
 
 A TypeScript implementation of the [Amazon States Language specification](https://states-language.net/spec.html).
 
-This package lets you run AWS Step Functions completely locally, both in Node.js and in the browser!
+This package lets you run AWS Step Functions state machines completely locally, both in Node.js and in the browser!
+
+<p align="left">
+  <a href="/LICENSE">
+    <img alt="Project license (MIT)" src="https://img.shields.io/github/license/nibble-4bits/aws-local-stepfunctions">
+  </a>
+  <a href="https://github.com/nibble-4bits/aws-local-stepfunctions/actions/workflows/pr-run-tests.yml">
+    <img alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/nibble-4bits/aws-local-stepfunctions/pr-run-tests.yml">
+  </a>
+  <a href="https://www.npmjs.com/package/aws-local-stepfunctions">
+    <img alt="Latest npm version" src="https://img.shields.io/npm/v/aws-local-stepfunctions">
+  </a>
+  <a href="https://www.npmjs.com/package/aws-local-stepfunctions">
+    <img alt="node-lts" src="https://img.shields.io/node/v-lts/aws-local-stepfunctions">
+  </a>
+  <a href="https://www.npmjs.com/package/aws-local-stepfunctions">
+    <img alt="npm type definitions" src="https://img.shields.io/npm/types/aws-local-stepfunctions">
+  </a>
+</p>
 
 ## Table of contents
 
@@ -22,6 +40,7 @@ This package lets you run AWS Step Functions completely locally, both in Node.js
   - [Overriding Task and Wait states](#overriding-task-and-wait-states)
     - [Task state override](#task-state-override)
     - [Wait state override](#wait-state-override)
+  - [Passing a custom Context Object](#passing-a-custom-context-object)
   - [Disabling ASL validations](#disabling-asl-validations)
   - [Exit codes](#exit-codes)
 - [Examples](#examples)
@@ -119,8 +138,9 @@ const stateMachine = new StateMachine(machineDefinition, {
 
 Runs the state machine with the given `input` parameter and returns an object with the following properties:
 
+- `result`: A `Promise` that resolves with the result of the execution once it terminates.
 - `abort`: A function that takes no parameters and doesn't return any value. If called, [aborts the execution](/docs/feature-support.md#abort-a-running-execution) and throws an `ExecutionAbortedError`, unless the `noThrowOnAbort` option is set.
-- `result`: A `Promise` that resolves with the execution result once it finishes.
+- `eventLogs`: An `AsyncGenerator` that [produces a log of events](/docs/feature-support.md#execution-event-logs) as the execution runs. To learn more about the events, their type, and their format, see the [following document](/docs/execution-event-logs.md).
 
 Each execution is independent of all others, meaning that you can concurrently call this method as many times as needed, without worrying about race conditions.
 
@@ -132,6 +152,7 @@ Each execution is independent of all others, meaning that you can concurrently c
     - `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.
   - `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.
 
 #### Basic example:
 
@@ -212,7 +233,11 @@ Note that each line of the output corresponds to the result of each input, in th
 
 ### Passing input from stdin
 
-`local-sfn` can also read the execution input from the standard input. For example, assume you have the following text file, called `inputs.txt`, and you want to pass the contents of the file as inputs to `local-sfn`:
+`local-sfn` can also read the execution input from the standard input.
+
+If the first line of stdin can be parsed as a single JSON value, then `local-sfn` will consider each line as an input. Otherwise, the entire stdin will be considered as a single JSON input.
+
+For example, assume you have the following text file, called `inputs.txt`, and you want to pass the contents of the file as inputs to `local-sfn`:
 
 ```txt
 { "num1": 1, "num2": 2 }
@@ -220,6 +245,8 @@ Note that each line of the output corresponds to the result of each input, in th
 { "num1": 5, "num2": 6 }
 ```
 
+Because the first line is parsable as JSON, `local-sfn` will process each line as a single input.
+
 You can then run the following command to pass the inputs of the text file to `local-sfn`:
 
 ```sh
@@ -232,7 +259,16 @@ Alternatively, using input redirection:
 local-sfn -f state-machine.json < inputs.txt
 ```
 
-When reading from stdin, `local-sfn` will take each line and use it as an input. Hence, to avoid any parsing errors, make sure the output of the command you're piping into `local-sfn` prints each input in a new line.
+On the other hand, assume you have this additional file, called `input.json`:
+
+```json
+{
+  "num1": 5,
+  "num2": 3
+}
+```
+
+If you pass this file as input, `local-sfn` will automatically detect that it is a single, multiline JSON value and process it as a single value.
 
 ### Overriding Task and Wait states
 
@@ -299,6 +335,46 @@ 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.
 
+### 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:
+
+```json
+{
+  "StartAt": "Get execution context data",
+  "States": {
+    "Get execution context data": {
+      "Type": "Pass",
+      "Parameters": {
+        "execId.$": "$$.Execution.Id",
+        "execName.$": "$$.Execution.Name"
+      },
+      "End": true
+    }
+  }
+}
+```
+
+And given the following `context.json` file:
+
+```json
+{
+  "Execution": {
+    "Id": "arn:aws:states:us-east-1:123456789012:execution:stateMachineName:executionName",
+    "Name": "executionName"
+  }
+}
+```
+
+You could provide the Context Object to the execution in the following manner:
+
+```sh
+local-sfn \
+  -f state-machine.json \
+  --context-file context.json \
+  '{}'
+```
+
 ### Disabling ASL validations
 
 Before attempting to run the state machine with the given inputs, the state machine definition itself is validated to check that:

package/build/CLI.cjs

@@ -38,7 +38,7 @@ var import_readline = __toESM(require("readline"), 1);
 var import_commander = require("commander");
 
 // package.json
-var version = "0.7.0";
+var version = "1.0.0";
 
 // src/cli/ArgumentParsers.ts
 var import_fs = require("fs");
@@ -110,6 +110,33 @@ function parseOverrideWaitOption(value, previous = {}) {
   previous[waitStateName] = Number(duration);
   return previous;
 }
+function parseContextOption(command, context) {
+  const jsonOrError = tryJSONParse(context);
+  if (jsonOrError instanceof Error) {
+    command.error(
+      `error: parsing of context object passed in option '--context <json>' failed: ${jsonOrError.message}`,
+      {
+        exitCode: 1 /* PreExecutionFailure */
+      }
+    );
+  }
+  return jsonOrError;
+}
+function parseContextFileOption(command, contextFile) {
+  let file;
+  try {
+    file = (0, import_fs.readFileSync)(contextFile).toString();
+  } catch (error) {
+    command.error(`error: ${error.message}`, { exitCode: 1 /* PreExecutionFailure */ });
+  }
+  const jsonOrError = tryJSONParse(file);
+  if (jsonOrError instanceof Error) {
+    command.error(`error: parsing of context object in file '${contextFile}' failed: ${jsonOrError.message}`, {
+      exitCode: 1 /* PreExecutionFailure */
+    });
+  }
+  return jsonOrError;
+}
 function parseInputArguments(command, value, previous = []) {
   const jsonOrError = tryJSONParse(value);
   if (jsonOrError instanceof Error) {
@@ -139,7 +166,8 @@ async function commandAction(inputs, options, command) {
       overrides: {
         taskResourceLocalHandlers: options.overrideTask,
         waitTimeOverrides: options.overrideWait
-      }
+      },
+      context: options.context ?? options.contextFile
     });
     return result;
   });
@@ -204,11 +232,21 @@ 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(
+      "--context <json>",
+      "A JSON object that will be passed to each execution as the context object."
+    ).argParser((value) => parseContextOption(command, value))
+  ).addOption(
+    new import_commander.Option(
+      "--context-file <path>",
+      "Path to a file containing a JSON object that will be passed to each execution as the context object."
+    ).argParser((value) => parseContextFileOption(command, value))
   ).addOption(
     new import_commander.Option("--no-jsonpath-validation", "Disable validation of JSONPath strings in the state machine definition.")
   ).addOption(new import_commander.Option("--no-arn-validation", "Disable validation of ARNs in the state machine definition.")).argument(
     "[inputs...]",
-    "Input data for the state machine, can be any valid JSON value. Each input represents a state machine execution. If reading from the standard input, each line will be considered as an input.",
+    "Input data for the state machine, can be any valid JSON value. Each input represents a state machine execution.\n\nWhen reading from the standard input, if the first line can be parsed as a single JSON value, then each line will be considered as an input. Otherwise, the entire standard input will be considered as a single JSON input.",
     (value, previous) => parseInputArguments(command, value, previous)
   ).hook("preAction", preActionHook).action(commandAction);
   return command;
@@ -226,6 +264,11 @@ if (require.main === module) {
       for await (const line of rl) {
         stdin.push(line);
       }
+      const firstLineJSON = tryJSONParse(stdin[0]);
+      if (firstLineJSON instanceof Error) {
+        await program.parseAsync([...process.argv, stdin.join("").trim()]);
+        return;
+      }
       await program.parseAsync([...process.argv, ...stdin.filter((line) => line)]);
     }
   })();