Merge pull request #51 from nibble-4bits/refactor-9

Refactor 9

Author: nibble-4bits

README.md

@@ -2,11 +2,9 @@
 
 A TypeScript implementation of the [Amazon States Language specification](https://states-language.net/spec.html).
 
-This package lets you run AWS Step Functions locally, both in Node.js and in the browser!
+This package lets you run AWS Step Functions completely locally, both in Node.js and in the browser!
 
-> NOTE: This is a work in progress. Some features defined in the specification might not be supported at all yet or might have limited support.
-
-## Table of Contents
+## Table of contents
 
 - [Features](#features)
 - [Installation](#installation)
@@ -23,7 +21,7 @@ This package lets you run AWS Step Functions locally, both in Node.js and in the
 
 ## Features
 
-To see a list of features that have full support, partial support, or no support, refer to [this document](/docs/feature-support.md).
+To see the list of features defined in the specification that have full support, partial support, or no support, refer to [this document](/docs/feature-support.md).
 
 ## Installation
 
@@ -78,11 +76,11 @@ The constructor takes the following parameters:
   - `validationOptions?`: An object that specifies how the definition should be validated.
     - `checkPaths`: If set to `false`, won't validate JSONPaths.
     - `checkArn`: If set to `false`, won't validate ARN syntax in `Task` states.
-  - `awsConfig?`: An object that specifies the AWS region and credentials to use when invoking a Lambda function in a `Task` state. If not set, the AWS config will be resolved based on the [credentials provider chain](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html) of the AWS SDK for JavaScript V3. You don't need to use this option if you have a [shared config/credentials file](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) (for example, if you have the [AWS CLI](https://aws.amazon.com/cli/) installed) or if you use a local override for all of your `Task` states.
+  - `awsConfig?`: An object that specifies the [AWS region and credentials](/docs/feature-support.md#providing-aws-credentials-and-region-to-execute-lambda-functions-specified-in-task-states) to use when invoking a Lambda function in a `Task` state. If not set, the AWS config will be resolved based on the [credentials provider chain](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html) of the AWS SDK for JavaScript V3. You don't need to use this option if you have a [shared config/credentials file](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) (for example, if you have the [AWS CLI](https://aws.amazon.com/cli/) installed) or if you use a local override for all of your `Task` states.
     - `region`: The AWS region where the Lambda functions are created.
     - `credentials`: An object that specifies which type of credentials to use.
-      - `cognitoIdentityPool`: An object that specifies the Cognito Identity Pool to use for requesting credentials.
-      - `accessKeys`: An object that specifies the [Access Key ID and Secret Access Key](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html#sec-access-keys-and-secret-access-keys) to use as credentials.
+      - `cognitoIdentityPool`: An object that specifies the Cognito Identity Pool ID to use for requesting credentials.
+      - `accessKeys`: An object that specifies the Access Key ID and Secret Access Key to use as credentials.
 
 The constructor will attempt to validate the definition by default, unless the `validationOptions` property is specified. If the definition is not valid, an error will be thrown.
 
@@ -113,7 +111,7 @@ const stateMachine = new StateMachine(machineDefinition, {
 
 Runs the state machine with the given `input` parameter and returns an object with the following properties:
 
-- `abort`: A function that takes no parameters and doesn't return any value. If called, aborts the execution and throws an `ExecutionAbortedError`, unless the `noThrowOnAbort` option is set.
+- `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.
 
 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.
@@ -123,8 +121,8 @@ Each execution is independent of all others, meaning that you can concurrently c
 - `input`: The initial input to pass to the state machine. This can be any valid JSON value.
 - `options?`:
   - `overrides?`: An object to override the behavior of certain states:
-    - `taskResourceLocalHandlers?`: Overrides the resource of the specified `Task` states to run a local function.
-    - `waitTimeOverrides?`: Overrides the wait duration of the specified `Wait` states. The specifed override duration should be in milliseconds.
+    - `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 specifed 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.
 
 #### Basic example:

docs/feature-support.md

@@ -1,5 +1,16 @@
 # Feature support
 
+## Table of contents
+
+- [Spec features](#spec-features)
+  - [Fully supported](#fully-supported)
+  - [Not supported](#not-supported)
+- [Non-spec features](#non-spec-features)
+  - [Task resource override](#task-state-resource-override)
+  - [Wait duration override](#wait-state-duration-override)
+  - [Abort a running execution](#abort-a-running-execution)
+  - [AWS config for Lambda functions](#providing-aws-credentials-and-region-to-execute-lambda-functions-specified-in-task-states)
+
 ## Spec features
 
 The following features all come from the [Amazon States Language specification](https://states-language.net/).
@@ -22,6 +33,8 @@ The following features all come from the [Amazon States Language specification](
     - [x] `SecondsPath`
     - [x] `Timestamp`
     - [x] `TimestampPath`
+  - [x] Task
+    - [x] `Resource` (only Lambda functions supported)
   - [x] Parallel
     - [x] `Branches`
   - [x] Map
@@ -86,22 +99,71 @@ The following features all come from the [Amazon States Language specification](
     - [x] Predefined error codes
   - [x] Retry/Catch
 
-### Limited support
+### Not supported
 
 - States
   - Task
-    - [x] `Resource` (only Lambda functions supported)
     - [ ] `TimeoutSeconds`
     - [ ] `HeartbeatSeconds`
     - [ ] `TimeoutSecondsPath`
     - [ ] `HeartbeatSecondsPath`
-
-### No support
+    - [ ] `Credentials`
+  - Map
+    - [ ] Distributed mode
+    - [ ] `ItemProcessor`
+    - [ ] `ItemReader`
+    - [ ] `ItemSelector`
+    - [ ] `ItemBatcher`
+    - [ ] `ResultWriter`
+    - [ ] `MaxConcurrencyPath`
+    - [ ] `ToleratedFailurePercentage`
+    - [ ] `ToleratedFailureCount`
 
 ## Non-spec features
 
 The following features are not defined in the specification, but they have been added for convenience.
 
-- [x] Override Task state resource with a local function handler ([example](/examples/task-state-local-override.js))
-- [x] Override Wait state duration ([example](/examples/wait-state-local-override.js))
-- [x] Abort a running execution ([example](/examples/abort-execution.js))
+### `Task` state resource override
+
+`aws-local-stepfunctions` has the ability to invoke Lambda functions specified in the `Resource` field of `Task` states, provided that you have the necessary AWS credentials. No other service integrations are currently available.
+
+However, if you want to be able to run a state machine completely locally (no matter the type of `Resource` specified) you can specify a local function to be called in place of the resource. This is accomplished through the `overrides.taskResourceLocalHandlers` option of the [`StateMachine.run`](/README.md#statemachineruninput-options) method. This option expects an object that maps state names to an overriding local function.
+
+The overriding function will receive the processed input of its `Task` state as the first argument. The return value of said function will be the result of the state (but not its output, which as defined in the spec, depends on further processing done by the `ResultSelector`, `ResultPath` and `OutputPath` fields).
+
+Effectively, task resource overrides allow `aws-local-stepfunctions` to execute state machines without calls to any AWS service, if you override all of the `Task` states in the state machine definition.
+
+An example usage of this feature can be found [here](/examples/task-state-local-override.js).
+
+### `Wait` state duration override
+
+As defined by the spec, `Wait` states in `aws-local-stepfunction` will pause the state machine execution until the specified `Seconds` have elapsed or the specified `Timestamp` has been reached.
+
+Nonetheless, if you want to override the duration of the wait period of a `Wait` state, you can do so by specifying the `overrides.waitTimeOverrides` option of the [`StateMachine.run`](/README.md#statemachineruninput-options) method. This option expects an object that maps state names to numbers, where the number represents the amount of milliseconds that the overridden `Wait` state will pause the execution for. Note that you may pass `0` for the number value, which effectively means that the overridden `Wait` state will not pause the execution at all.
+
+An example usage of this feature can be found [here](/examples/wait-state-local-override.js).
+
+### Abort a running execution
+
+If for some reason you need to abort an execution in progress, you can do so by calling the `abort` method that is part of the value returned by the `StateMachine.run` method.
+
+By default, aborting an execution will throw an error of type `ExecutionAbortedError`, which you can catch and compare against using `instanceof`. A demonstration of this behavior can be found in this [example](/examples/abort-execution.js).
+
+If instead you prefer to abort an execution without throwing an error, you can pass the `noThrowOnAbort` option to the `StateMachine.run` method. When this option is `true`, aborting an execution will simply return `null` as result. Likewise, an example demonstrating this behavior can be found [here](/examples/abort-execution-without-throwing.js).
+
+### Providing AWS credentials and region to execute Lambda functions specified in `Task` states
+
+_NOTE: If you have [overridden](#task-state-resource-override) all `Task` states in your state machine with local functions, you don't need to specify any AWS credentials or region._
+
+When using `aws-local-stepfunctions` on Node, you don't need to specify AWS credentials explicitly, as those will be automatically loaded from the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` [environment variables](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html) or from the [shared credentials file](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html), as described in the [AWS JavaScript SDK docs](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html).
+
+Similarly, you don't need to specify the AWS region, as it will also be automatically loaded, in this case from the `AWS_REGION` environment variable or from the shared config file, as described in the [SDK docs](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html).
+
+However, when using `aws-local-stepfunctions` in the browser you must provide AWS credentials, otherwise the `aws-local-stepfunctions` will not be able to invoke the Lambda functions and the execution will fail.
+
+To provide credentials and region, specify the `stateMachineOptions.awsConfig` option in the `StateMachine` [constructor](/README.md#constructor-new-statemachinedefinition-statemachineoptions). You can set two types of credentials:
+
+1. [Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html): Access Key ID and Secret Access Key ([example](/examples/aws-credentials-access-keys.js)).
+2. [Cognito Identity Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html): The ID of a Cognito Identity Pool ([example](/examples/aws-credentials-cognito.js)).
+
+Make sure that the IAM user/role associated with the access keys or Cognito Identity Pool have the necessary policies to be able to invoke the Lambda functions referenced in your state machine definition.

examples/aws-credentials-access-keys.js

@@ -27,6 +27,11 @@ const stateMachine = new StateMachine(machineDefinition, {
         accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
         secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
       },
+      // WARNING: You shouldn't commit the `accessKeys` option, as that will expose your keys to other people in the repository.
+      // Ideally, on Node your access keys should be loaded from one of the following two settings:
+      //  - the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html
+      //  - the shared `credentials` file: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html
+      // The `accessKeys` option is meant for browser use, where the two settings above are not available as they have no web platform equivalent.
     },
   },
 });

examples/check-for-execution-timeout.js

@@ -1,4 +1,4 @@
-import { StateMachine, StatesTimeoutError } from 'aws-local-stepfunctions';
+import { StateMachine, ExecutionTimeoutError } from 'aws-local-stepfunctions';
 
 const machineDefinition = {
   StartAt: 'WaitState',
@@ -21,8 +21,8 @@ try {
   const result = await execution.result;
   console.log(result);
 } catch (error) {
-  // When execution times out, type of error is `StatesTimeoutError`
-  if (error instanceof StatesTimeoutError) {
+  // When execution times out, type of error is `ExecutionTimeoutError`
+  if (error instanceof ExecutionTimeoutError) {
     console.error('The execution has timed out');
   }
 }

examples/task-state-local-override.js

@@ -25,6 +25,7 @@ const execution = stateMachine.run(myInput, {
     // by specifying the Task state name as the key and the local function as value, as in the example below:
     taskResourceLocalHandlers: {
       // Call the `addNumbersLocal` function instead of invoking the Lambda function specified for the `AddNumbers` state.
+      // Note that the key is the name of the `Task` state that we want to override.
       AddNumbers: addNumbersLocal,
     },
   },

examples/wait-state-local-override.js

@@ -18,6 +18,7 @@ const execution = stateMachine.run(myInput, {
     // Property `waitTimeOverrides` lets you override any number of Wait states,
     // by specifying the Wait state name as the key and the duration override as value (represented in milliseconds):
     waitTimeOverrides: {
+      // Note that the key is the name of the `Wait` state that we want to override.
       Wait10Seconds: 500, // wait for 500 milliseconds instead of the 10 seconds specified in the `Wait10Seconds` state
     },
   },