Merge pull request #41 from nibble-4bits/refactor-6

Refactor 6

Author: nibble-4bits

README.md

@@ -1,6 +1,6 @@
 # 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!
 

examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Here you can find some useful examples demonstrating specific usages of AWS Local Step Functions.
+
+- [abort-execution-without-throwing](./abort-execution-without-throwing.js): Abort a running execution without throwing an error.
+- [abort-execution](./abort-execution.js): Abort a running execution.
+- [check-for-execution-failure](./check-for-execution-failure.js): Check if execution failed and catch error.
+- [disable-state-machine-validation](./disable-state-machine-validation.js): Disable ARN and/or JSONPath validations when instantiating a new `StateMachine` object.
+- [task-state-local-override](./task-state-local-override.js): Override the default action for a `Task` state, so that instead of invoking the Lambda specified in the `Resource` field, it runs a local function. This allows running state machines completely locally.
+- [wait-state-local-override](./wait-state-local-override.js): Override the wait duration of a `Wait` state so that instead of waiting the duration specified in the `Seconds`, `Timestamp`, `SecondsPath`, `TimestampPath` fields, it waits for a specified number of milliseconds.

examples/check-for-execution-failure.js

@@ -0,0 +1,34 @@
+import { StateMachine, ExecutionError } from 'aws-local-stepfunctions';
+
+const machineDefinition = {
+  StartAt: 'MapState',
+  States: {
+    MapState: {
+      Type: 'Map',
+      Iterator: {
+        StartAt: 'Success',
+        States: {
+          Success: {
+            Type: 'Succeed',
+          },
+        },
+      },
+      End: true,
+    },
+  },
+};
+
+const stateMachine = new StateMachine(machineDefinition);
+const myInput = 'this is not an array';
+const execution = stateMachine.run(myInput);
+
+try {
+  // Execution fails because Map state expects an array as input
+  const result = await execution.result;
+  console.log(result);
+} catch (error) {
+  // When execution fails, type of error is `ExecutionError`
+  if (error instanceof ExecutionError) {
+    console.error('The execution has failed:', error);
+  }
+}

src/stateMachine/InputOutputProcessing.ts

@@ -1,5 +1,6 @@
 import type { PayloadTemplate } from '../typings/InputOutputProcessing';
 import type { JSONValue } from '../typings/JSONValue';
+import type { Context } from '../typings/Context';
 import { isPlainObj } from '../util';
 import { jsonPathQuery } from './JsonPath';
 import { StatesResultPathMatchFailureError } from '../error/predefined/StatesResultPathMatchFailureError';
@@ -13,7 +14,7 @@ import set from 'lodash/set.js';
  * * If `InputPath` is `null`, returns an empty object (`{}`).
  * * If `InputPath` is a string, it's considered a JSONPath and the selected portion of the current input is returned.
  */
-function processInputPath(path: string | null | undefined, input: JSONValue, context?: JSONValue): JSONValue {
+function processInputPath(path: string | null | undefined, input: JSONValue, context?: Context): JSONValue {
   if (path === undefined) {
     return input;
   }
@@ -32,11 +33,7 @@ function processInputPath(path: string | null | undefined, input: JSONValue, con
  * @param context The context object to evaluate, if the path expression starts with `$$`.
  * @returns The processed payload template.
  */
-function processPayloadTemplate(
-  payloadTemplate: PayloadTemplate,
-  json: JSONValue,
-  context?: JSONValue
-): PayloadTemplate {
+function processPayloadTemplate(payloadTemplate: PayloadTemplate, json: JSONValue, context?: Context): PayloadTemplate {
   const resolvedProperties = Object.entries(payloadTemplate).map(([key, value]) => {
     let sanitizedKey = key;
     let resolvedValue = value;
@@ -78,7 +75,7 @@ function processResultPath(path: string | null | undefined, rawInput: JSONValue,
   const sanitizedPath = path.replace('$.', '');
 
   if (isPlainObj(rawInput)) {
-    const clonedRawInput = cloneDeep(rawInput) as object;
+    const clonedRawInput = cloneDeep(rawInput);
     return set(clonedRawInput, sanitizedPath, result);
   }
 
@@ -92,7 +89,7 @@ function processResultPath(path: string | null | undefined, rawInput: JSONValue,
  * * If `OutputPath` is `null`, returns an empty object (`{}`).
  * * If `OutputPath` is a string, it's considered a JSONPath and the selected portion of the current result is returned.
  */
-function processOutputPath(path: string | null | undefined, result: JSONValue, context?: JSONValue): JSONValue {
+function processOutputPath(path: string | null | undefined, result: JSONValue, context?: Context): JSONValue {
   if (path === undefined) {
     return result;
   }

src/stateMachine/JsonPath.ts

@@ -1,4 +1,5 @@
 import type { JSONValue } from '../typings/JSONValue';
+import type { Context } from '../typings/Context';
 import { JSONPath as jp } from 'jsonpath-plus';
 
 /**
@@ -8,7 +9,7 @@ import { JSONPath as jp } from 'jsonpath-plus';
  * @param context The context object to evaluate, if the path expression starts with `$$`.
  * @returns The value of the property that was queried for, if found. Otherwise returns `undefined`.
  */
-function jsonPathQuery<T>(pathExpression: string, json: JSONValue, context?: JSONValue): T {
+function jsonPathQuery<T>(pathExpression: string, json: JSONValue, context?: Context): T {
   // If the expression starts with double `$$`, evaluate the path in the context object.
   if (pathExpression.startsWith('$$')) {
     return jp({ path: pathExpression.slice(1), json: context ?? null, wrap: false });

src/stateMachine/StateExecutor.ts

@@ -12,6 +12,7 @@ import type { ChoiceState } from '../typings/ChoiceState';
 import type { FailState } from '../typings/FailState';
 import type { SucceedState } from '../typings/SucceedState';
 import type { RuntimeError } from '../error/RuntimeError';
+import type { Context } from '../typings/Context';
 import {
   processInputPath,
   processOutputPath,
@@ -101,7 +102,7 @@ export class StateExecutor {
   /**
    * Execute the current state.
    */
-  async execute(input: JSONValue, context: Record<string, unknown>, options: ExecuteOptions): Promise<ExecutionResult> {
+  async execute(input: JSONValue, context: Context, options: ExecuteOptions): Promise<ExecutionResult> {
     const rawInput = cloneDeep(input);
 
     try {
@@ -127,7 +128,7 @@ export class StateExecutor {
       // Handle `Retry` logic
       const { shouldRetry, waitTimeBeforeRetry } = this.shouldRetry(error as RuntimeError);
       if (shouldRetry && waitTimeBeforeRetry) {
-        await sleep(waitTimeBeforeRetry);
+        await sleep(waitTimeBeforeRetry, options.abortSignal);
         return this.execute(input, context, options);
       }
 
@@ -144,7 +145,7 @@ export class StateExecutor {
   /**
    * Process the current input according to the `InputPath` and `Parameters` fields.
    */
-  private processInput(input: JSONValue, context: Record<string, unknown>): JSONValue {
+  private processInput(input: JSONValue, context: Context): JSONValue {
     let processedInput = input;
 
     if ('InputPath' in this.stateDefinition) {
@@ -163,7 +164,7 @@ export class StateExecutor {
   /**
    * Process the current result according to the `ResultSelector`, `ResultPath` and `OutputPath` fields.
    */
-  private processResult(result: JSONValue, rawInput: JSONValue, context: Record<string, unknown>): JSONValue {
+  private processResult(result: JSONValue, rawInput: JSONValue, context: Context): JSONValue {
     let processedResult = result;
 
     if ('ResultSelector' in this.stateDefinition) {
@@ -265,7 +266,7 @@ export class StateExecutor {
   private async executeTaskState(
     stateDefinition: TaskState,
     input: JSONValue,
-    context: Record<string, unknown>,
+    context: Context,
     stateName: string,
     options: ExecuteOptions
   ): Promise<ExecutionResult> {
@@ -287,7 +288,7 @@ export class StateExecutor {
   private async executeMapState(
     stateDefinition: MapState,
     input: JSONValue,
-    context: Record<string, unknown>,
+    context: Context,
     stateName: string,
     options: ExecuteOptions
   ): Promise<ExecutionResult> {
@@ -309,7 +310,7 @@ export class StateExecutor {
   private async executePassState(
     stateDefinition: PassState,
     input: JSONValue,
-    context: Record<string, unknown>,
+    context: Context,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     stateName: string,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -330,7 +331,7 @@ export class StateExecutor {
   private async executeWaitState(
     stateDefinition: WaitState,
     input: JSONValue,
-    context: Record<string, unknown>,
+    context: Context,
     stateName: string,
     options: ExecuteOptions
   ): Promise<ExecutionResult> {
@@ -363,7 +364,7 @@ export class StateExecutor {
   private async executeChoiceState(
     stateDefinition: ChoiceState,
     input: JSONValue,
-    context: Record<string, unknown>,
+    context: Context,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     stateName: string,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -383,7 +384,7 @@ export class StateExecutor {
   private async executeSucceedState(
     stateDefinition: SucceedState,
     input: JSONValue,
-    context: Record<string, unknown>,
+    context: Context,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     stateName: string,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -403,7 +404,7 @@ export class StateExecutor {
   private async executeFailState(
     stateDefinition: FailState,
     input: JSONValue,
-    context: Record<string, unknown>,
+    context: Context,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     stateName: string,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars

src/stateMachine/StateMachine.ts

@@ -1,6 +1,7 @@
 import type { StateMachineDefinition } from '../typings/StateMachineDefinition';
 import type { JSONValue } from '../typings/JSONValue';
 import type { ExecuteOptions, RunOptions, ValidationOptions } from '../typings/StateMachineImplementation';
+import type { Context } from '../typings/Context';
 import { ExecutionAbortedError } from '../error/ExecutionAbortedError';
 import { ExecutionError } from '../error/ExecutionError';
 import { StateExecutor } from './StateExecutor';
@@ -87,7 +88,7 @@ export class StateMachine {
     let nextState = '';
     let isEndState = false;
     // eslint-disable-next-line prefer-const
-    let context: Record<string, unknown> = {};
+    let context: Context = {};
 
     try {
       do {

src/stateMachine/stateActions/BaseStateAction.ts

@@ -3,6 +3,7 @@ import type { TerminalState } from '../../typings/TerminalState';
 import type { JSONValue } from '../../typings/JSONValue';
 import type { BaseState } from '../../typings/BaseState';
 import type { ExecutionResult } from '../../typings/StateActions';
+import type { Context } from '../../typings/Context';
 
 abstract class BaseStateAction<T extends BaseState | IntermediateState | TerminalState> {
   protected stateDefinition: T;
@@ -25,11 +26,7 @@ abstract class BaseStateAction<T extends BaseState | IntermediateState | Termina
     return executionResult;
   }
 
-  abstract execute(
-    input: JSONValue,
-    context: Record<string, unknown>,
-    options?: Record<string, unknown>
-  ): Promise<ExecutionResult>;
+  abstract execute(input: JSONValue, context: Context, options?: Record<string, unknown>): Promise<ExecutionResult>;
 }
 
 export { BaseStateAction };

src/stateMachine/stateActions/ChoiceStateAction.ts

@@ -1,6 +1,7 @@
 import type { JSONValue } from '../../typings/JSONValue';
 import type { ChoiceState, ChoiceRuleWithoutNext } from '../../typings/ChoiceState';
 import type { ChoiceStateActionOptions, ExecutionResult } from '../../typings/StateActions';
+import type { Context } from '../../typings/Context';
 import { BaseStateAction } from './BaseStateAction';
 import { jsonPathQuery } from '../JsonPath';
 import { StatesNoChoiceMatchedError } from '../../error/predefined/StatesNoChoiceMatchedError';
@@ -253,7 +254,7 @@ class ChoiceStateAction extends BaseStateAction<ChoiceState> {
   override async execute(
     input: JSONValue,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    context: Record<string, unknown>,
+    context: Context,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     options?: ChoiceStateActionOptions
   ): Promise<ExecutionResult> {

src/stateMachine/stateActions/FailStateAction.ts

@@ -1,6 +1,7 @@
 import type { JSONValue } from '../../typings/JSONValue';
 import type { FailState } from '../../typings/FailState';
 import type { ExecutionResult, FailStateActionOptions } from '../../typings/StateActions';
+import type { Context } from '../../typings/Context';
 import { BaseStateAction } from './BaseStateAction';
 import { FailStateError } from '../../error/FailStateError';
 
@@ -13,7 +14,7 @@ class FailStateAction extends BaseStateAction<FailState> {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     input: JSONValue,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    context: Record<string, unknown>,
+    context: Context,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     options?: FailStateActionOptions
   ): Promise<ExecutionResult> {