aws-local-stepfunctions 0.6.0 → 1.0.0

package/build/main.node.cjs

@@ -50,7 +50,7 @@ var main_exports = {};
 __export(main_exports, {
   ExecutionAbortedError: () => ExecutionAbortedError,
   ExecutionError: () => ExecutionError,
-  ExecutionTimeoutError: () => StatesTimeoutError,
+  ExecutionTimeoutError: () => ExecutionTimeoutError,
   StateMachine: () => StateMachine
 });
 module.exports = __toCommonJS(main_exports);
@@ -63,27 +63,11 @@ var ExecutionAbortedError = class extends Error {
   }
 };
 
-// src/error/RuntimeError.ts
-var RuntimeError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "RuntimeError";
-    this.retryable = true;
-    this.catchable = true;
-  }
-  get isRetryable() {
-    return this.retryable;
-  }
-  get isCatchable() {
-    return this.catchable;
-  }
-};
-
-// src/error/predefined/StatesTimeoutError.ts
-var StatesTimeoutError = class extends RuntimeError {
+// src/error/ExecutionTimeoutError.ts
+var ExecutionTimeoutError = class extends Error {
   constructor() {
-    super("States.Timeout");
-    this.name = "States.Timeout";
+    super("Execution timed out");
+    this.name = "ExecutionTimeoutError";
   }
 };
 
@@ -134,20 +118,32 @@ function sfc32(a, b, c, d) {
     return (t >>> 0) / 4294967296;
   };
 }
-function getRandomNumber(min, max, rngGenerator = Math.random) {
-  return Math.floor(rngGenerator() * (max - min + 1)) + min;
+function getRandomNumber(min, max, rng = Math.random) {
+  return Math.floor(rng() * (max - min + 1)) + min;
 }
 
 // src/util/index.ts
 function isPlainObj(value) {
   return !!value && Object.getPrototypeOf(value) === Object.prototype;
 }
-function sleep(ms, abortSignal) {
+function sleep(ms, abortSignal, rootAbortSignal) {
   return new Promise((resolve) => {
-    const timeout = setTimeout(resolve, ms);
-    abortSignal?.addEventListener("abort", () => {
+    if (abortSignal?.aborted || rootAbortSignal?.aborted) {
+      return resolve();
+    }
+    const onAbort = () => {
+      abortSignal?.removeEventListener("abort", onAbort);
+      rootAbortSignal?.removeEventListener("abort", onAbort);
       clearTimeout(timeout);
-    });
+      resolve();
+    };
+    const timeout = setTimeout(() => {
+      abortSignal?.removeEventListener("abort", onAbort);
+      rootAbortSignal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    abortSignal?.addEventListener("abort", onAbort);
+    rootAbortSignal?.addEventListener("abort", onAbort);
   });
 }
 function byteToHex(byte) {
@@ -163,6 +159,22 @@ function jsonPathQuery(pathExpression, json, context) {
   return (0, import_jsonpath_plus.JSONPath)({ path: pathExpression, json, wrap: false });
 }
 
+// src/error/RuntimeError.ts
+var RuntimeError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RuntimeError";
+    this.retryable = true;
+    this.catchable = true;
+  }
+  get isRetryable() {
+    return this.retryable;
+  }
+  get isCatchable() {
+    return this.catchable;
+  }
+};
+
 // src/error/predefined/StatesResultPathMatchFailureError.ts
 var StatesResultPathMatchFailureError = class extends RuntimeError {
   constructor() {
@@ -207,7 +219,7 @@ function validateArgumentType(allowedTypes, argPosition, funcArg, funcName) {
     if (matchesAllowedType)
       break;
   }
-  const expectedType = allowedTypes.map((type) => `"${type}"`).join(" | ");
+  const expectedType = allowedTypes.map((type) => `'${type}'`).join(" | ");
   if (!matchesAllowedType) {
     throw new StatesRuntimeError(
       `Intrinsic function ${funcName} expected argument ${argPosition} to be of type ${expectedType}, but received ${typeof funcArg}`
@@ -235,7 +247,7 @@ function validateArgumentConstraints(argConstraints, argPosition, funcArg, funcN
       if (matchesAllConstraints)
         break;
     }
-    const expectedConstraints = argConstraints.map((constraint) => `"${constraint}"`).join(" | ");
+    const expectedConstraints = argConstraints.map((constraint) => `'${constraint}'`).join(" | ");
     if (!matchesAllConstraints) {
       throw new StatesRuntimeError(
         `Intrinsic function ${funcName} expected argument ${argPosition} to satisfy the following constraints: ${expectedConstraints}`
@@ -857,7 +869,7 @@ function processPayloadTemplate(payloadTemplate, json, context) {
     let sanitizedKey = key;
     let resolvedValue = value;
     if (isPlainObj(value)) {
-      resolvedValue = processPayloadTemplate(value, json);
+      resolvedValue = processPayloadTemplate(value, json, context);
     }
     if (key.endsWith(".$") && typeof value === "string") {
       sanitizedKey = key.replace(".$", "");
@@ -897,8 +909,9 @@ function processOutputPath(path, result, context) {
 
 // src/stateMachine/stateActions/BaseStateAction.ts
 var BaseStateAction = class {
-  constructor(stateDefinition) {
+  constructor(stateDefinition, stateName) {
     this.stateDefinition = stateDefinition;
+    this.stateName = stateName;
   }
   buildExecutionResult(stateResult) {
     const executionResult = { stateResult, nextState: "", isEndState: false };
@@ -923,8 +936,8 @@ var StatesNoChoiceMatchedError = class extends RuntimeError {
 // src/stateMachine/stateActions/ChoiceStateAction.ts
 var import_wildcard_match = __toESM(require("wildcard-match"), 1);
 var ChoiceStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
   }
   testChoiceRule(choiceRule, input) {
     if ("And" in choiceRule) {
@@ -1147,8 +1160,8 @@ var FailStateError = class extends RuntimeError {
 
 // src/stateMachine/stateActions/FailStateAction.ts
 var FailStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
   }
   async execute(input, context, options) {
     throw new FailStateError(this.stateDefinition.Error, this.stateDefinition.Cause);
@@ -1159,10 +1172,17 @@ var FailStateAction = class extends BaseStateAction {
 var import_p_limit = __toESM(require("p-limit"), 1);
 var DEFAULT_MAX_CONCURRENCY = 40;
 var MapStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
     this.executionAbortFuncs = [];
   }
+  async forwardEventsToRootEventLogger(eventLogger, executionEventLogs, index, parentStateRawInput) {
+    if (!eventLogger)
+      return;
+    for await (const event of executionEventLogs) {
+      eventLogger.forwardNestedMapEvent(event, index, this.stateName, parentStateRawInput);
+    }
+  }
   processItem(stateMachine, item, input, context, index, options) {
     const state = this.stateDefinition;
     let paramValue;
@@ -1177,6 +1197,7 @@ var MapStateAction = class extends BaseStateAction {
     }
     const execution = stateMachine.run(paramValue ?? item, options?.runOptions);
     this.executionAbortFuncs.push(execution.abort);
+    this.forwardEventsToRootEventLogger(options?.eventLogger, execution.eventLogs, index, options?.rawInput);
     return execution.result;
   }
   async execute(input, context, options) {
@@ -1188,7 +1209,10 @@ var MapStateAction = class extends BaseStateAction {
     if (!Array.isArray(items)) {
       throw new StatesRuntimeError("Input of Map state must be an array or ItemsPath property must point to an array");
     }
-    const iteratorStateMachine = new StateMachine(state.Iterator, options?.stateMachineOptions);
+    const iteratorStateMachine = new StateMachine(state.Iterator, {
+      ...options?.stateMachineOptions,
+      validationOptions: { _noValidate: true }
+    });
     const limit = (0, import_p_limit.default)(state.MaxConcurrency || DEFAULT_MAX_CONCURRENCY);
     const processedItemsPromise = items.map(
       (item, i) => limit(() => this.processItem(iteratorStateMachine, item, input, context, i, options))
@@ -1212,14 +1236,25 @@ var MapStateAction = class extends BaseStateAction {
 var import_p_limit2 = __toESM(require("p-limit"), 1);
 var DEFAULT_CONCURRENCY = 40;
 var ParallelStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
     this.executionAbortFuncs = [];
   }
+  async forwardEventsToRootEventLogger(eventLogger, executionEventLogs, parentStateRawInput) {
+    if (!eventLogger)
+      return;
+    for await (const event of executionEventLogs) {
+      eventLogger.forwardNestedParallelEvent(event, this.stateName, parentStateRawInput);
+    }
+  }
   processBranch(branch, input, context, options) {
-    const stateMachine = new StateMachine(branch, options?.stateMachineOptions);
+    const stateMachine = new StateMachine(branch, {
+      ...options?.stateMachineOptions,
+      validationOptions: { _noValidate: true }
+    });
     const execution = stateMachine.run(input, options?.runOptions);
     this.executionAbortFuncs.push(execution.abort);
+    this.forwardEventsToRootEventLogger(options?.eventLogger, execution.eventLogs, options?.rawInput);
     return execution.result;
   }
   async execute(input, context, options) {
@@ -1243,8 +1278,8 @@ var ParallelStateAction = class extends BaseStateAction {
 
 // src/stateMachine/stateActions/PassStateAction.ts
 var PassStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
   }
   async execute(input, context, options) {
     if (this.stateDefinition.Result) {
@@ -1256,8 +1291,8 @@ var PassStateAction = class extends BaseStateAction {
 
 // src/stateMachine/stateActions/SucceedStateAction.ts
 var SucceedStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
   }
   async execute(input, context, options) {
     return { stateResult: input, nextState: "", isEndState: true };
@@ -1273,12 +1308,12 @@ var LambdaClient = class {
     if (config) {
       if (!config.region) {
         throw new StatesRuntimeError(
-          "`awsConfig` option was specified for state machine, but `region` property is not set"
+          "'awsConfig' option was specified for state machine, but 'region' property is not set"
         );
       }
       if (config.credentials) {
         const credentialsTypes = Object.keys(config.credentials);
-        const credentialsNames = credentialsTypes.map((name) => `\`${name}\``).join(", ");
+        const credentialsNames = credentialsTypes.map((name) => `'${name}'`).join(", ");
         if (credentialsTypes.length > 1) {
           throw new StatesRuntimeError(
             `More than one type of AWS credentials were specified: ${credentialsNames}. Only one type may be specified`
@@ -1312,7 +1347,7 @@ var LambdaClient = class {
     }
     if (invocationResult.FunctionError) {
       const errorResult = resultValue;
-      throw new FailStateError(errorResult.errorType, `Execution of Lambda function "${funcNameOrArn}" failed`);
+      throw new FailStateError(errorResult.errorType, `Execution of Lambda function '${funcNameOrArn}' failed`);
     }
     return resultValue;
   }
@@ -1320,8 +1355,8 @@ var LambdaClient = class {
 
 // src/stateMachine/stateActions/TaskStateAction.ts
 var TaskStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
   }
   async execute(input, context, options) {
     const state = this.stateDefinition;
@@ -1337,36 +1372,44 @@ var TaskStateAction = class extends BaseStateAction {
 
 // src/stateMachine/stateActions/WaitStateAction.ts
 var WaitStateAction = class extends BaseStateAction {
-  constructor(stateDefinition) {
-    super(stateDefinition);
+  constructor(stateDefinition, stateName) {
+    super(stateDefinition, stateName);
   }
   async execute(input, context, options) {
     const state = this.stateDefinition;
     if (options?.waitTimeOverrideOption !== void 0) {
-      await sleep(options.waitTimeOverrideOption, options.abortSignal);
+      await sleep(options.waitTimeOverrideOption, options.abortSignal, options.rootAbortSignal);
       return this.buildExecutionResult(input);
     }
     if (state.Seconds) {
-      await sleep(state.Seconds * 1e3, options?.abortSignal);
+      await sleep(state.Seconds * 1e3, options?.abortSignal, options?.rootAbortSignal);
     } else if (state.Timestamp) {
       const dateTimestamp = new Date(state.Timestamp);
       const currentTime = Date.now();
       const timeDiff = dateTimestamp.getTime() - currentTime;
-      await sleep(timeDiff, options?.abortSignal);
+      await sleep(timeDiff, options?.abortSignal, options?.rootAbortSignal);
     } else if (state.SecondsPath) {
       const seconds = jsonPathQuery(state.SecondsPath, input, context);
-      await sleep(seconds * 1e3, options?.abortSignal);
+      await sleep(seconds * 1e3, options?.abortSignal, options?.rootAbortSignal);
     } else if (state.TimestampPath) {
       const timestamp = jsonPathQuery(state.TimestampPath, input, context);
       const dateTimestamp = new Date(timestamp);
       const currentTime = Date.now();
       const timeDiff = dateTimestamp.getTime() - currentTime;
-      await sleep(timeDiff, options?.abortSignal);
+      await sleep(timeDiff, options?.abortSignal, options?.rootAbortSignal);
     }
     return this.buildExecutionResult(input);
   }
 };
 
+// src/error/predefined/StatesTimeoutError.ts
+var StatesTimeoutError = class extends RuntimeError {
+  constructor() {
+    super("States.Timeout");
+    this.name = "States.Timeout";
+  }
+};
+
 // src/stateMachine/StateExecutor.ts
 var import_cloneDeep2 = __toESM(require("lodash/cloneDeep.js"), 1);
 var DEFAULT_MAX_ATTEMPTS = 3;
@@ -1404,6 +1447,7 @@ var StateExecutor = class {
       } = await this.stateHandlers[this.stateDefinition.Type](
         // @ts-expect-error Indexing `this.stateActions` by non-literal value produces a `never` type for the `this.stateDefinition` parameter of the handler being called
         this.stateDefinition,
+        rawInput,
         processedInput,
         context,
         this.stateName,
@@ -1414,7 +1458,7 @@ var StateExecutor = class {
     } catch (error) {
       const { shouldRetry, waitTimeBeforeRetry } = this.shouldRetry(error);
       if (shouldRetry && waitTimeBeforeRetry) {
-        await sleep(waitTimeBeforeRetry, options.abortSignal);
+        await sleep(waitTimeBeforeRetry, options.abortSignal, options.runOptions?._rootAbortSignal);
         return this.execute(input, context, options);
       }
       const { nextState, errorOutput, resultPath } = this.catchError(error);
@@ -1516,10 +1560,10 @@ var StateExecutor = class {
    * Invokes the Lambda function specified in the `Resource` field
    * and sets the current result of the state machine to the value returned by the Lambda.
    */
-  async executeTaskState(stateDefinition, input, context, stateName, options) {
+  async executeTaskState(stateDefinition, rawInput, input, context, stateName, options) {
     const overrideFn = options.runOptions?.overrides?.taskResourceLocalHandlers?.[stateName];
     const awsConfig = options.stateMachineOptions?.awsConfig;
-    const taskStateAction = new TaskStateAction(stateDefinition);
+    const taskStateAction = new TaskStateAction(stateDefinition, stateName);
     const executionResult = await taskStateAction.execute(input, context, { overrideFn, awsConfig });
     return executionResult;
   }
@@ -1529,11 +1573,13 @@ var StateExecutor = class {
    * Creates a new state machine for each of the branches specified in the `Branches` field,
    * and then executes each branch state machine by passing them the Parallel state input.
    */
-  async executeParallelState(stateDefinition, input, context, stateName, options) {
-    const parallelStateAction = new ParallelStateAction(stateDefinition);
+  async executeParallelState(stateDefinition, rawInput, input, context, stateName, options) {
+    const parallelStateAction = new ParallelStateAction(stateDefinition, stateName);
     const executionResult = await parallelStateAction.execute(input, context, {
       stateMachineOptions: options.stateMachineOptions,
-      runOptions: options.runOptions
+      runOptions: options.runOptions,
+      eventLogger: options.eventLogger,
+      rawInput
     });
     return executionResult;
   }
@@ -1544,11 +1590,13 @@ var StateExecutor = class {
    * by the `ItemsPath` field, and then processes each item by passing it
    * as the input to the state machine specified in the `Iterator` field.
    */
-  async executeMapState(stateDefinition, input, context, stateName, options) {
-    const mapStateAction = new MapStateAction(stateDefinition);
+  async executeMapState(stateDefinition, rawInput, input, context, stateName, options) {
+    const mapStateAction = new MapStateAction(stateDefinition, stateName);
     const executionResult = await mapStateAction.execute(input, context, {
       stateMachineOptions: options.stateMachineOptions,
-      runOptions: options.runOptions
+      runOptions: options.runOptions,
+      eventLogger: options.eventLogger,
+      rawInput
     });
     return executionResult;
   }
@@ -1558,8 +1606,8 @@ var StateExecutor = class {
    * If the `Result` field is specified, copies `Result` into the current result.
    * Else, copies the current input into the current result.
    */
-  async executePassState(stateDefinition, input, context, stateName, options) {
-    const passStateAction = new PassStateAction(stateDefinition);
+  async executePassState(stateDefinition, rawInput, input, context, stateName, options) {
+    const passStateAction = new PassStateAction(stateDefinition, stateName);
     const executionResult = await passStateAction.execute(input, context);
     return executionResult;
   }
@@ -1569,13 +1617,13 @@ var StateExecutor = class {
    * Pauses the state machine execution for a certain amount of time
    * based on one of the `Seconds`, `Timestamp`, `SecondsPath` or `TimestampPath` fields.
    */
-  async executeWaitState(stateDefinition, input, context, stateName, options) {
+  async executeWaitState(stateDefinition, rawInput, input, context, stateName, options) {
     const waitTimeOverrideOption = options.runOptions?.overrides?.waitTimeOverrides?.[stateName];
-    const abortSignal = options.abortSignal;
-    const waitStateAction = new WaitStateAction(stateDefinition);
+    const waitStateAction = new WaitStateAction(stateDefinition, stateName);
     const executionResult = await waitStateAction.execute(input, context, {
       waitTimeOverrideOption,
-      abortSignal
+      abortSignal: options.abortSignal,
+      rootAbortSignal: options.runOptions?._rootAbortSignal
     });
     return executionResult;
   }
@@ -1593,8 +1641,8 @@ var StateExecutor = class {
    * If no rule matches and the `Default` field is not specified, throws a
    * States.NoChoiceMatched error.
    */
-  async executeChoiceState(stateDefinition, input, context, stateName, options) {
-    const choiceStateAction = new ChoiceStateAction(stateDefinition);
+  async executeChoiceState(stateDefinition, rawInput, input, context, stateName, options) {
+    const choiceStateAction = new ChoiceStateAction(stateDefinition, stateName);
     const executionResult = await choiceStateAction.execute(input, context);
     return executionResult;
   }
@@ -1603,8 +1651,8 @@ var StateExecutor = class {
    *
    * Ends the state machine execution successfully.
    */
-  async executeSucceedState(stateDefinition, input, context, stateName, options) {
-    const succeedStateAction = new SucceedStateAction(stateDefinition);
+  async executeSucceedState(stateDefinition, rawInput, input, context, stateName, options) {
+    const succeedStateAction = new SucceedStateAction(stateDefinition, stateName);
     const executionResult = await succeedStateAction.execute(input, context);
     return executionResult;
   }
@@ -1613,13 +1661,186 @@ var StateExecutor = class {
    *
    * Ends the state machine execution and marks it as a failure.
    */
-  async executeFailState(stateDefinition, input, context, stateName, options) {
-    const failStateAction = new FailStateAction(stateDefinition);
+  async executeFailState(stateDefinition, rawInput, input, context, stateName, options) {
+    const failStateAction = new FailStateAction(stateDefinition, stateName);
     const executionResult = await failStateAction.execute(input, context);
     return executionResult;
   }
 };
 
+// src/stateMachine/EventLogger.ts
+var EventLogger = class {
+  constructor() {
+    this.eventTarget = new EventTarget();
+    this.eventQueue = [];
+    this.isLoggerClosed = false;
+  }
+  async *getEvents() {
+    while (true) {
+      if (this.eventQueue.length === 0) {
+        await this.waitForNewEvent();
+      }
+      let event = null;
+      while (event = this.eventQueue.shift()) {
+        yield event;
+      }
+      if (this.isLoggerClosed)
+        return;
+    }
+  }
+  /**
+   * Forward nested events created by `Map` states, to the root state machine event logger.
+   * @param event An event dispatched by the nested state machine spawned by a `Map` state.
+   * @param index Index of the current iteration being processed.
+   * @param mapStateName Name of the `Map` state being executed.
+   * @param mapStateRawInput Raw input passed to the `Map` state being executed.
+   */
+  forwardNestedMapEvent(event, index, mapStateName, mapStateRawInput) {
+    switch (event.type) {
+      case "ExecutionStarted":
+        this.dispatchMapIterationStartedEvent(event, index, mapStateName, mapStateRawInput);
+        break;
+      case "ExecutionSucceeded":
+        this.dispatchMapIterationSucceededEvent(event, index, mapStateName, mapStateRawInput);
+        break;
+      case "ExecutionFailed":
+        this.dispatchMapIterationFailedEvent(event, index, mapStateName, mapStateRawInput);
+        break;
+      case "StateEntered":
+      case "StateExited":
+        event.index = index;
+        this.dispatch(event);
+        break;
+      case "ExecutionAborted":
+      case "ExecutionTimeout":
+        return;
+      default:
+        this.dispatch(event);
+        break;
+    }
+  }
+  /**
+   * Forward nested events created by `Parallel` states, to the root state machine event logger.
+   * @param event An event dispatched by the nested state machines spawned by a `Parallel` state.
+   * @param parallelStateName Name of the `Parallel` state being executed.
+   * @param parallelStateRawInput Raw input passed to the `Parallel` state being executed.
+   */
+  forwardNestedParallelEvent(event, parallelStateName, parallelStateRawInput) {
+    switch (event.type) {
+      case "ExecutionStarted":
+        this.dispatchParallelBranchStartedEvent(event, parallelStateName, parallelStateRawInput);
+        break;
+      case "ExecutionSucceeded":
+        this.dispatchParallelBranchSucceededEvent(event, parallelStateName, parallelStateRawInput);
+        break;
+      case "ExecutionFailed":
+        this.dispatchParallelBranchFailedEvent(event, parallelStateName, parallelStateRawInput);
+        break;
+      case "ExecutionAborted":
+      case "ExecutionTimeout":
+        return;
+      default:
+        this.dispatch(event);
+        break;
+    }
+  }
+  dispatchExecutionStartedEvent(input) {
+    this.dispatch({ type: "ExecutionStarted", timestamp: Date.now(), input });
+  }
+  dispatchExecutionSucceededEvent(output) {
+    this.dispatch({ type: "ExecutionSucceeded", timestamp: Date.now(), output });
+    this.close();
+  }
+  dispatchExecutionFailedEvent(error) {
+    this.dispatch({ type: "ExecutionFailed", timestamp: Date.now(), Error: error.name, Cause: error.message });
+    this.close();
+  }
+  dispatchExecutionAbortedEvent() {
+    this.dispatch({ type: "ExecutionAborted", timestamp: Date.now() });
+    this.close();
+  }
+  dispatchExecutionTimeoutEvent() {
+    this.dispatch({ type: "ExecutionTimeout", timestamp: Date.now() });
+    this.close();
+  }
+  dispatchStateEnteredEvent(stateName, stateType, input) {
+    this.dispatch({
+      type: "StateEntered",
+      timestamp: Date.now(),
+      state: { name: stateName, type: stateType, input }
+    });
+  }
+  dispatchStateExitedEvent(stateName, stateType, input, output) {
+    this.dispatch({
+      type: "StateExited",
+      timestamp: Date.now(),
+      state: { name: stateName, type: stateType, input, output }
+    });
+  }
+  dispatchMapIterationStartedEvent(event, index, mapStateName, mapStateRawInput) {
+    this.dispatch({
+      ...event,
+      type: "MapIterationStarted",
+      index,
+      parentState: { type: "Map", name: mapStateName, input: mapStateRawInput }
+    });
+  }
+  dispatchMapIterationSucceededEvent(event, index, mapStateName, mapStateRawInput) {
+    this.dispatch({
+      ...event,
+      type: "MapIterationSucceeded",
+      index,
+      parentState: { type: "Map", name: mapStateName, input: mapStateRawInput }
+    });
+  }
+  dispatchMapIterationFailedEvent(event, index, mapStateName, mapStateRawInput) {
+    this.dispatch({
+      ...event,
+      type: "MapIterationFailed",
+      index,
+      parentState: { type: "Map", name: mapStateName, input: mapStateRawInput }
+    });
+  }
+  dispatchParallelBranchStartedEvent(event, parallelStateName, parallelStateRawInput) {
+    this.dispatch({
+      ...event,
+      type: "ParallelBranchStarted",
+      parentState: { type: "Parallel", name: parallelStateName, input: parallelStateRawInput }
+    });
+  }
+  dispatchParallelBranchSucceededEvent(event, parallelStateName, parallelStateRawInput) {
+    this.dispatch({
+      ...event,
+      type: "ParallelBranchSucceeded",
+      parentState: { type: "Parallel", name: parallelStateName, input: parallelStateRawInput }
+    });
+  }
+  dispatchParallelBranchFailedEvent(event, parallelStateName, parallelStateRawInput) {
+    this.dispatch({
+      ...event,
+      type: "ParallelBranchFailed",
+      parentState: { type: "Parallel", name: parallelStateName, input: parallelStateRawInput }
+    });
+  }
+  close() {
+    this.isLoggerClosed = true;
+    this.eventTarget.dispatchEvent(new Event("newEvent"));
+  }
+  dispatch(event) {
+    if (this.isLoggerClosed)
+      return;
+    this.eventQueue.push(event);
+    this.eventTarget.dispatchEvent(new Event("newEvent"));
+  }
+  waitForNewEvent() {
+    if (this.isLoggerClosed)
+      return;
+    return new Promise((resolve) => {
+      this.eventTarget.addEventListener("newEvent", resolve, { once: true });
+    });
+  }
+};
+
 // src/stateMachine/StateMachine.ts
 var import_asl_validator = __toESM(require("asl-validator"), 1);
 var import_cloneDeep3 = __toESM(require("lodash/cloneDeep.js"), 1);
@@ -1631,14 +1852,16 @@ var StateMachine = class {
    * These options also apply to state machines defined in the `Iterator` field of `Map` states and in the `Branches` field of `Parallel` states.
    */
   constructor(definition, stateMachineOptions) {
-    const { isValid, errorsText } = (0, import_asl_validator.default)(definition, {
-      checkArn: true,
-      checkPaths: true,
-      ...stateMachineOptions?.validationOptions
-    });
-    if (!isValid) {
-      throw new Error(`State machine definition is invalid, see error(s) below:
+    if (!stateMachineOptions?.validationOptions?._noValidate) {
+      const { isValid, errorsText } = (0, import_asl_validator.default)(definition, {
+        checkArn: true,
+        checkPaths: true,
+        ...stateMachineOptions?.validationOptions
+      });
+      if (!isValid) {
+        throw new Error(`State machine definition is invalid, see error(s) below:
  ${errorsText("\n")}`);
+      }
     }
     this.definition = definition;
     this.stateMachineOptions = stateMachineOptions;
@@ -1648,6 +1871,9 @@ var StateMachine = class {
    * If the execution fails, the result will throw an `ExecutionError` explaining why the
    * execution failed.
    *
+   * If the execution times out because the number of seconds specified in
+   * the `TimeoutSeconds` top-level field has elapsed, the result will throw an `ExecutionTimeoutError`.
+   *
    * By default, if the execution is aborted, the result will throw an `ExecutionAbortedError`. This behavior can be changed by setting
    * the `noThrowOnAbort` option to `true`, in which case the result will be `null`.
    *
@@ -1656,30 +1882,47 @@ var StateMachine = class {
    */
   run(input, options) {
     const abortController = new AbortController();
+    const eventLogger = new EventLogger();
     let onAbortHandler;
     const settleOnAbort = new Promise((resolve, reject) => {
       if (options?.noThrowOnAbort) {
-        onAbortHandler = () => resolve(null);
+        onAbortHandler = () => {
+          eventLogger.dispatchExecutionAbortedEvent();
+          resolve(null);
+        };
       } else {
-        onAbortHandler = () => reject(new ExecutionAbortedError());
+        onAbortHandler = () => {
+          eventLogger.dispatchExecutionAbortedEvent();
+          reject(new ExecutionAbortedError());
+        };
       }
       abortController.signal.addEventListener("abort", onAbortHandler);
     });
-    let rejectOnTimeout = null;
-    if (this.definition.TimeoutSeconds) {
+    let rejectOnTimeout;
+    let timeoutId;
+    if (this.definition.TimeoutSeconds !== void 0) {
       rejectOnTimeout = new Promise((_, reject) => {
-        setTimeout(() => {
+        timeoutId = setTimeout(() => {
           abortController.signal.removeEventListener("abort", onAbortHandler);
           abortController.abort();
-          reject(new StatesTimeoutError());
+          eventLogger.dispatchExecutionTimeoutEvent();
+          reject(new ExecutionTimeoutError());
         }, this.definition.TimeoutSeconds * 1e3);
       });
     }
-    const executionResult = this.execute(input, {
-      stateMachineOptions: this.stateMachineOptions,
-      runOptions: options,
-      abortSignal: abortController.signal
-    });
+    const executionResult = this.execute(
+      input,
+      {
+        stateMachineOptions: this.stateMachineOptions,
+        runOptions: { ...options, _rootAbortSignal: options?._rootAbortSignal ?? abortController.signal },
+        abortSignal: abortController.signal,
+        eventLogger
+      },
+      () => {
+        abortController.signal.removeEventListener("abort", onAbortHandler);
+        clearTimeout(timeoutId);
+      }
+    );
     const racingPromises = [executionResult, settleOnAbort];
     if (rejectOnTimeout) {
       racingPromises.push(rejectOnTimeout);
@@ -1687,31 +1930,39 @@ var StateMachine = class {
     const result = Promise.race(racingPromises);
     return {
       abort: () => abortController.abort(),
+      eventLogs: eventLogger.getEvents(),
       result
     };
   }
   /**
    * Helper method that handles the execution of the machine states and the transitions between them.
    */
-  async execute(input, options) {
+  async execute(input, options, cleanupFn) {
+    options.eventLogger.dispatchExecutionStartedEvent(input);
+    const context = options.runOptions?.context ?? {};
     let currState = this.definition.States[this.definition.StartAt];
     let currStateName = this.definition.StartAt;
     let currInput = (0, import_cloneDeep3.default)(input);
     let currResult = null;
     let nextState = "";
     let isEndState = false;
-    let context = {};
     try {
       do {
+        options.eventLogger.dispatchStateEnteredEvent(currStateName, currState.Type, currInput);
         const stateExecutor = new StateExecutor(currStateName, currState);
         ({ stateResult: currResult, nextState, isEndState } = await stateExecutor.execute(currInput, context, options));
+        options.eventLogger.dispatchStateExitedEvent(currStateName, currState.Type, currInput, currResult);
         currInput = currResult;
         currState = this.definition.States[nextState];
         currStateName = nextState;
       } while (!isEndState && !options.abortSignal.aborted);
     } catch (error) {
+      options.eventLogger.dispatchExecutionFailedEvent(error);
       throw new ExecutionError(error);
+    } finally {
+      cleanupFn();
     }
+    options.eventLogger.dispatchExecutionSucceededEvent(currResult);
     return currResult;
   }
 };