aws-local-stepfunctions 0.3.2 → 0.5.0

package/README.md

@@ -1,8 +1,8 @@
 # AWS Local Step Functions
 
-A Node.js implementation of the [Amazon States Language specification](https://states-language.net/spec.html).
+A TypeScript implementation of the [Amazon States Language specification](https://states-language.net/spec.html).
 
-This package lets you run AWS Step Functions locally on your machine!
+This package lets you run AWS Step Functions 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.
 
@@ -14,9 +14,11 @@ This package lets you run AWS Step Functions locally on your machine!
   - [Node.js](#nodejs)
     - [CommonJS](#commonjs)
     - [ES Module](#es-module)
+  - [Browser](#browser)
 - [API](#api)
-  - [Constructor](#constructor-new-statemachinedefinition-validationoptions)
+  - [Constructor](#constructor-new-statemachinedefinition-statemachineoptions)
   - [StateMachine.run](#statemachineruninput-options)
+- [Examples](#examples)
 - [License](#license)
 
 ## Features
@@ -31,8 +33,6 @@ npm install aws-local-stepfunctions
 
 ## Importing
 
-Currently, the only supported environment to import the package is Node.js. Browser support is not available yet.
-
 ### Node.js
 
 #### CommonJS
@@ -47,20 +47,44 @@ const { StateMachine } = require('aws-local-stepfunctions');
 import { StateMachine } from 'aws-local-stepfunctions';
 ```
 
+### Browser
+
+You can import the bundled package directly into a browser script as an ES module, from one of the following CDNs:
+
+> NOTE: The following examples will import the latest package version. Refer to the CDNs websites to know about other ways in which you can specify the package URL (for example, to import a specific version).
+
+#### [unpkg](https://unpkg.com/)
+
+```js
+import { StateMachine } from 'https://unpkg.com/aws-local-stepfunctions';
+```
+
+#### [jsDelivr](https://www.jsdelivr.com/)
+
+```js
+import { StateMachine } from 'https://cdn.jsdelivr.net/npm/aws-local-stepfunctions/build/main.browser.esm.js';
+```
+
 ## API
 
-### Constructor: `new StateMachine(definition[, validationOptions])`
+### Constructor: `new StateMachine(definition[, stateMachineOptions])`
 
 #### Parameters
 
 The constructor takes the following parameters:
 
 - `definition`: The Amazon States Language definition of the state machine.
-- `validationOptions` (optional): 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.
-
-The constructor will attempt to validate the definition by default, unless the `validationOptions` param is specified. If the definition is not valid, an error will be thrown.
+- `stateMachineOptions?`:
+  - `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.
+    - `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.
+
+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.
 
 #### Example
 
@@ -80,7 +104,9 @@ const machineDefinition = {
 };
 
 // Instantiate a new state machine with the given definition and don't validate JSONPaths.
-const stateMachine = new StateMachine(machineDefinition, { checkPaths: false });
+const stateMachine = new StateMachine(machineDefinition, {
+  validationOptions: { checkPaths: false },
+});
 ```
 
 ### `StateMachine.run(input[, options])`
@@ -95,15 +121,13 @@ Each execution is independent of all others, meaning that you can concurrently c
 #### Parameters
 
 - `input`: The initial input to pass to the state machine. This can be any valid JSON value.
-- `options` (optional):
-  - `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.
-  - `noThrowOnAbort`: If this option is set to `true`, aborting the execution will simply return `null` as result instead of throwing.
+- `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.
+  - `noThrowOnAbort?`: If this option is set to `true`, aborting the execution will simply return `null` as result instead of throwing.
 
-#### Examples
-
-##### Example without `options`:
+#### Basic example:
 
 ```js
 import { StateMachine } from 'aws-local-stepfunctions';
@@ -127,89 +151,23 @@ const result = await execution.result; // wait until the execution finishes to g
 console.log(result); // log the result of the execution
 ```
 
-##### Example with `options`:
+## Examples
 
-```js
-import { StateMachine } from 'aws-local-stepfunctions';
+You can check more examples and options usage in the [examples](/examples) directory.
 
-const machineDefinition = {
-  StartAt: 'Hello World',
-  States: {
-    'Hello World': {
-      Type: 'Task',
-      Resource: 'arn:aws:lambda:us-east-1:123456789012:function:HelloWorld',
-      Next: 'AddNumbers',
-    },
-    AddNumbers: {
-      Type: 'Task',
-      Resource: 'arn:aws:lambda:us-east-1:123456789012:function:AddNumbers',
-      Next: 'Wait10Seconds',
-    },
-    Wait10Seconds: {
-      Type: 'Wait',
-      Seconds: 10,
-      End: true,
-    },
-  },
-};
-
-function addNumbersLocal(input) {
-  return input.num1 + input.num2;
-}
-
-const stateMachine = new StateMachine(machineDefinition);
-const myInput = { value1: 'hello', value2: 123, value3: true };
-const execution = stateMachine.run(myInput, {
-  overrides: {
-    taskResourceLocalHandlers: {
-      AddNumbers: addNumbersLocal, // call the `addNumbersLocal` function instead of invoking the Lambda function specified for the `AddNumbers` state
-    },
-    waitTimeOverrides: {
-      Wait10Seconds: 500, // wait for 500 milliseconds instead of the 10 seconds specified in the `Wait10Seconds` state
-    },
-  },
-});
+To run the examples, clone the repo, install the dependencies and build the project:
 
-const result = await execution.result;
-console.log(result);
+```sh
+git clone https://github.com/nibble-4bits/aws-local-stepfunctions.git --depth 1
+cd aws-local-stepfunctions
+npm install
+npm run build
 ```
 
-##### Aborting an execution
+Then run whichever example you want:
 
-```js
-import { StateMachine, ExecutionAbortedError } from 'aws-local-stepfunctions';
-
-const machineDefinition = {
-  StartAt: 'Hello World',
-  States: {
-    'Hello World': {
-      Type: 'Task',
-      Resource: 'arn:aws:lambda:us-east-1:123456789012:function:HelloWorld',
-      End: true,
-    },
-  },
-};
-
-const stateMachine = new StateMachine(machineDefinition);
-const myInput = { value1: 'hello', value2: 123, value3: true };
-const execution = stateMachine.run(myInput);
-
-// abort the execution after 3 seconds
-setTimeout(() => {
-  execution.abort();
-}, 3000);
-
-try {
-  const result = await execution.result;
-  console.log(result);
-} catch (e) {
-  if (e instanceof ExecutionAbortedError) {
-    // since execution was aborted, type of error is `ExecutionAbortedError`
-    console.log('Execution was aborted');
-  } else {
-    console.error('Some other error', e);
-  }
-}
+```sh
+node examples/abort-execution.js
 ```
 
 ## License