aws-local-stepfunctions 1.1.0 → 1.3.0

package/build/main.d.ts

@@ -15,15 +15,15 @@ type JSONObject = {
 };
 type JSONValue = JSONPrimitiveValue | JSONObject | JSONArray;
 
-type PayloadTemplate = JSONObject;
+type PayloadTemplate = JSONObject | JSONArray;
 interface CanHaveInputPath {
     InputPath?: string | null;
 }
 interface CanHaveParameters {
-    Parameters?: PayloadTemplate;
+    Parameters?: JSONValue;
 }
 interface CanHaveResultSelector {
-    ResultSelector?: PayloadTemplate;
+    ResultSelector?: JSONValue;
 }
 interface CanHaveResultPath {
     ResultPath?: string | null;
@@ -101,7 +101,9 @@ type TerminalState = EndableState | SucceedOrFailState;
 interface BaseFailState extends BaseState {
     Type: 'Fail';
     Cause?: string;
+    CausePath?: string;
     Error?: string;
+    ErrorPath?: string;
 }
 type FailState = TerminalState & BaseFailState;
 
@@ -110,6 +112,8 @@ type Retrier = {
     IntervalSeconds?: number;
     MaxAttempts?: number;
     BackoffRate?: number;
+    MaxDelaySeconds?: number;
+    JitterStrategy?: 'NONE' | 'FULL';
 };
 interface RetryableState {
     Retry?: Retrier[];
@@ -129,11 +133,15 @@ interface NextableState extends BaseState {
 }
 type IntermediateState = NextableState;
 
-interface BaseMapState extends BaseState, CanHaveInputPath, CanHaveParameters, CanHaveResultSelector, CanHaveResultPath, CanHaveOutputPath, RetryableState, CatchableState {
+interface BaseMapState extends BaseState, CanHaveInputPath, CanHaveResultSelector, CanHaveResultPath, CanHaveOutputPath, RetryableState, CatchableState {
     Type: 'Map';
-    Iterator: Omit<StateMachineDefinition, 'Version' | 'TimeoutSeconds'>;
+    Iterator?: Omit<StateMachineDefinition, 'Version' | 'TimeoutSeconds'>;
+    ItemProcessor?: Omit<StateMachineDefinition, 'Version' | 'TimeoutSeconds'>;
+    Parameters?: PayloadTemplate;
+    ItemSelector?: PayloadTemplate;
     ItemsPath?: string;
     MaxConcurrency?: number;
+    MaxConcurrencyPath?: string;
 }
 type MapState = (IntermediateState | TerminalState) & BaseMapState;
 
@@ -157,6 +165,8 @@ type SucceedState = TerminalState & BaseSucceedState;
 interface BaseTaskState extends BaseState, CanHaveInputPath, CanHaveParameters, CanHaveResultSelector, CanHaveResultPath, CanHaveOutputPath, RetryableState, CatchableState {
     Type: 'Task';
     Resource: string;
+    TimeoutSeconds?: number;
+    TimeoutSecondsPath?: string;
 }
 type TaskState = (IntermediateState | TerminalState) & BaseTaskState;
 
@@ -179,7 +189,15 @@ interface StateMachineDefinition {
     TimeoutSeconds?: number;
 }
 
-type Context = Record<string, unknown>;
+type ContextExecution = {
+    Input?: JSONValue;
+    StartTime?: string;
+    [other: string]: unknown;
+};
+type Context = {
+    Execution?: ContextExecution;
+    [other: string]: unknown;
+};
 
 declare class ErrorWithCause extends Error {
     #private;
@@ -322,6 +340,9 @@ type TaskStateResourceLocalHandler = {
 type WaitStateTimeOverride = {
     [waitStateName: string]: number;
 };
+type RetryIntervalOverrides = {
+    [retryableStateName: string]: number | number[];
+};
 interface Overrides {
     /**
      * Pass an object to this option to override a `Task` state to run a local function,
@@ -333,6 +354,11 @@ interface Overrides {
      * instead of pausing for the duration specified by the `Seconds`, `Timestamp`, `SecondsPath`, or `TimestampPath` fields.
      */
     waitTimeOverrides?: WaitStateTimeOverride;
+    /**
+     * Pass an object to this option to override the duration in milliseconds a retrier in a `Retry` field waits before retrying the state,
+     * instead of pausing for the duration calculated by the `IntervalSeconds`, `BackoffRate`, `MaxDelaySeconds`, and `JitterStrategy` fields.
+     */
+    retryIntervalOverrides?: RetryIntervalOverrides;
 }
 interface ValidationOptions {
     /**

package/build/main.node.cjs

@@ -135,6 +135,8 @@ function isPlainObj(value) {
   return !!value && Object.getPrototypeOf(value) === Object.prototype;
 }
 function sleep(ms, abortSignal) {
+  if (ms === 0)
+    return;
   return new Promise((resolve) => {
     if (abortSignal?.aborted) {
       return resolve();
@@ -160,6 +162,13 @@ function isRFC3339Timestamp(date) {
 function stringifyJSONValue(value) {
   return JSON.stringify(value);
 }
+function clamp(value, min, max) {
+  if (min && value < min)
+    return min;
+  if (max && value > max)
+    return max;
+  return value;
+}
 
 // src/stateMachine/jsonPath/JsonPath.ts
 var import_jsonpath_plus = require("jsonpath-plus");
@@ -906,9 +915,18 @@ function processInputPath(path, input, context) {
   return jsonPathQuery(path, input, context);
 }
 function processPayloadTemplate(payloadTemplate, json, context) {
+  if (typeof payloadTemplate !== "object" || payloadTemplate === null) {
+    return payloadTemplate;
+  }
+  if (Array.isArray(payloadTemplate)) {
+    return payloadTemplate.map((value) => processPayloadTemplate(value, json, context));
+  }
   const resolvedProperties = Object.entries(payloadTemplate).map(([key, value]) => {
     let sanitizedKey = key;
     let resolvedValue = value;
+    if (Array.isArray(value)) {
+      resolvedValue = value.map((innerValue) => processPayloadTemplate(innerValue, json, context));
+    }
     if (isPlainObj(value)) {
       resolvedValue = processPayloadTemplate(value, json, context);
     }
@@ -1293,7 +1311,20 @@ var FailStateAction = class extends BaseStateAction {
     super(stateDefinition, stateName);
   }
   async execute(input, context, options) {
-    throw new FailStateError(this.stateDefinition.Error, this.stateDefinition.Cause);
+    const state = this.stateDefinition;
+    let error = state.Error;
+    let cause = state.Cause;
+    if (state.ErrorPath) {
+      error = jsonPathQuery(state.ErrorPath, input, context, {
+        constraints: [StringConstraint]
+      });
+    }
+    if (state.CausePath) {
+      cause = jsonPathQuery(state.CausePath, input, context, {
+        constraints: [StringConstraint]
+      });
+    }
+    throw new FailStateError(error, cause);
   }
 };
 
@@ -1308,6 +1339,31 @@ var ArrayConstraint = class extends BaseJSONPathConstraint {
   }
 };
 
+// src/stateMachine/jsonPath/constraints/IntegerConstraint.ts
+var IntegerConstraint = class extends BaseJSONPathConstraint {
+  test(value) {
+    if (!Number.isInteger(value)) {
+      throw new StatesRuntimeError(
+        `Path expression '${this.pathExpression}' evaluated to ${stringifyJSONValue(value)}, but expected an integer`
+      );
+    }
+  }
+  static greaterThanOrEqual(n) {
+    return class extends this {
+      test(value) {
+        super.test(value);
+        if (value < n) {
+          throw new StatesRuntimeError(
+            `Path expression '${this.pathExpression}' evaluated to ${stringifyJSONValue(
+              value
+            )}, but expected an integer >= ${n}`
+          );
+        }
+      }
+    };
+  }
+};
+
 // src/stateMachine/stateActions/MapStateAction.ts
 var import_p_limit = __toESM(require("p-limit"), 1);
 var DEFAULT_MAX_CONCURRENCY = 40;
@@ -1332,8 +1388,9 @@ var MapStateAction = class extends BaseStateAction {
         Value: item
       }
     };
-    if (state.Parameters) {
-      paramValue = processPayloadTemplate(state.Parameters, input, context);
+    if (state.Parameters || state.ItemSelector) {
+      const parameters = state.ItemSelector ?? state.Parameters;
+      paramValue = processPayloadTemplate(parameters, input, context);
     }
     const execution = stateMachine.run(paramValue ?? item, options.runOptions);
     this.executionAbortFuncs.push(execution.abort);
@@ -1351,11 +1408,19 @@ 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, {
+    const iteratorDefinition = state.ItemProcessor ?? state.Iterator;
+    const iteratorStateMachine = new StateMachine(iteratorDefinition, {
       ...options.stateMachineOptions,
       validationOptions: { noValidate: true }
     });
-    const limit = (0, import_p_limit.default)(state.MaxConcurrency || DEFAULT_MAX_CONCURRENCY);
+    let maxConcurrency = state.MaxConcurrency;
+    if (state.MaxConcurrencyPath) {
+      maxConcurrency = jsonPathQuery(state.MaxConcurrencyPath, input, context, {
+        constraints: [IntegerConstraint.greaterThanOrEqual(0)],
+        ignoreDefinedValueConstraint: true
+      });
+    }
+    const limit = (0, import_p_limit.default)(maxConcurrency || DEFAULT_MAX_CONCURRENCY);
     const processedItemsPromise = items.map(
       (item, i) => limit(() => this.processItem(iteratorStateMachine, item, input, context, i, options))
     );
@@ -1441,6 +1506,14 @@ var SucceedStateAction = class extends BaseStateAction {
   }
 };
 
+// src/error/predefined/StatesTimeoutError.ts
+var StatesTimeoutError = class extends RuntimeError {
+  constructor() {
+    super("States.Timeout");
+    this.name = "States.Timeout";
+  }
+};
+
 // src/aws/LambdaClient.ts
 var import_client_lambda = require("@aws-sdk/client-lambda");
 var import_credential_providers = require("@aws-sdk/credential-providers");
@@ -1524,41 +1597,47 @@ var LambdaClient = class {
 var TaskStateAction = class extends BaseStateAction {
   constructor(stateDefinition, stateName) {
     super(stateDefinition, stateName);
+    this.timeoutAbortController = new AbortController();
+  }
+  createTimeoutPromise(input, context) {
+    const state = this.stateDefinition;
+    if (!state.TimeoutSeconds && !state.TimeoutSecondsPath)
+      return;
+    let timeout;
+    if (state.TimeoutSeconds) {
+      timeout = state.TimeoutSeconds;
+    } else if (state.TimeoutSecondsPath) {
+      timeout = jsonPathQuery(state.TimeoutSecondsPath, input, context, {
+        constraints: [IntegerConstraint.greaterThanOrEqual(1)]
+      });
+    }
+    return new Promise((_, reject) => {
+      const handleTimeoutAbort = () => clearTimeout(timeoutId);
+      const timeoutId = setTimeout(() => {
+        this.timeoutAbortController.signal.removeEventListener("abort", handleTimeoutAbort);
+        reject(new StatesTimeoutError());
+      }, timeout * 1e3);
+      this.timeoutAbortController.signal.addEventListener("abort", handleTimeoutAbort, { once: true });
+    });
   }
   async execute(input, context, options) {
     const state = this.stateDefinition;
+    const racingPromises = [];
+    const timeoutPromise = this.createTimeoutPromise(input, context);
     if (options.overrideFn) {
-      const result2 = await options.overrideFn(input);
-      return this.buildExecutionResult(result2);
+      const resultPromise = options.overrideFn(input);
+      racingPromises.push(resultPromise);
+    } else {
+      const lambdaClient = new LambdaClient(options.awsConfig);
+      const resultPromise = lambdaClient.invokeFunction(state.Resource, input);
+      racingPromises.push(resultPromise);
     }
-    const lambdaClient = new LambdaClient(options.awsConfig);
-    const result = await lambdaClient.invokeFunction(state.Resource, input);
-    return this.buildExecutionResult(result);
-  }
-};
-
-// src/stateMachine/jsonPath/constraints/IntegerConstraint.ts
-var IntegerConstraint = class extends BaseJSONPathConstraint {
-  test(value) {
-    if (!Number.isInteger(value)) {
-      throw new StatesRuntimeError(
-        `Path expression '${this.pathExpression}' evaluated to ${stringifyJSONValue(value)}, but expected an integer`
-      );
+    if (timeoutPromise) {
+      racingPromises.push(timeoutPromise);
     }
-  }
-  static greaterThanOrEqual(n) {
-    return class extends this {
-      test(value) {
-        super.test(value);
-        if (value < n) {
-          throw new StatesRuntimeError(
-            `Path expression '${this.pathExpression}' evaluated to ${stringifyJSONValue(
-              value
-            )}, but expected an integer >= ${n}`
-          );
-        }
-      }
-    };
+    const result = await Promise.race(racingPromises);
+    this.timeoutAbortController.abort();
+    return this.buildExecutionResult(result);
   }
 };
 
@@ -1598,19 +1677,12 @@ var WaitStateAction = class extends BaseStateAction {
   }
 };
 
-// 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;
 var DEFAULT_INTERVAL_SECONDS = 1;
 var DEFAULT_BACKOFF_RATE = 2;
+var DEFAULT_JITTER_STRATEGY = "NONE";
 var WILDCARD_ERROR = "States.ALL";
 var TASK_STATE_WILDCARD_ERROR = "States.TaskFailed";
 var StateExecutor = class {
@@ -1658,7 +1730,10 @@ var StateExecutor = class {
         input,
         error
       );
-      const { shouldRetry, waitTimeBeforeRetry, retrierIndex } = this.shouldRetry(error);
+      const { shouldRetry, waitTimeBeforeRetry, retrierIndex } = this.shouldRetry(
+        error,
+        options.runOptions?.overrides?.retryIntervalOverrides
+      );
       if (shouldRetry) {
         const stateDefinition = this.stateDefinition;
         await sleep(waitTimeBeforeRetry, options.abortSignal);
@@ -1717,17 +1792,31 @@ var StateExecutor = class {
   /**
    * Decide whether this state should be retried, according to the `Retry` field.
    */
-  shouldRetry(error) {
+  shouldRetry(error, retryIntervalOverrides) {
     if (!("Retry" in this.stateDefinition)) {
       return { shouldRetry: false };
     }
     for (let i = 0; i < this.stateDefinition.Retry.length; i++) {
       const retrier = this.stateDefinition.Retry[i];
+      let intervalOverride = null;
+      if (retryIntervalOverrides?.[this.stateName] !== void 0) {
+        const override = retryIntervalOverrides[this.stateName];
+        if (typeof override === "number") {
+          intervalOverride = override / 1e3;
+        } else if (override[i] !== void 0 && override[i] >= 0) {
+          intervalOverride = override[i] / 1e3;
+        }
+      }
+      const jitterStrategy = retrier.JitterStrategy ?? DEFAULT_JITTER_STRATEGY;
       const maxAttempts = retrier.MaxAttempts ?? DEFAULT_MAX_ATTEMPTS;
       const intervalSeconds = retrier.IntervalSeconds ?? DEFAULT_INTERVAL_SECONDS;
       const backoffRate = retrier.BackoffRate ?? DEFAULT_BACKOFF_RATE;
-      const waitTimeBeforeRetry = intervalSeconds * Math.pow(backoffRate, this.retrierAttempts[i]) * 1e3;
+      const waitInterval = intervalOverride ?? intervalSeconds * Math.pow(backoffRate, this.retrierAttempts[i]);
       const retryable = error.isRetryable ?? true;
+      let waitTimeBeforeRetry = clamp(waitInterval, 0, retrier.MaxDelaySeconds) * 1e3;
+      if (jitterStrategy === "FULL" && intervalOverride === null) {
+        waitTimeBeforeRetry = getRandomNumber(0, waitTimeBeforeRetry);
+      }
       for (const retrierError of retrier.ErrorEquals) {
         const isErrorMatch = retrierError === error.name;
         const isErrorWildcard = retrierError === WILDCARD_ERROR;
@@ -2198,7 +2287,14 @@ var StateMachine = class {
    */
   async execute(input, options, cleanupFn) {
     options.eventLogger.dispatchExecutionStartedEvent(input);
-    const context = options.runOptions?.context ?? {};
+    const context = {
+      ...options.runOptions?.context,
+      Execution: {
+        ...options.runOptions?.context?.Execution,
+        Input: input,
+        StartTime: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
     let currState = this.definition.States[this.definition.StartAt];
     let currStateName = this.definition.StartAt;
     let currInput = (0, import_cloneDeep3.default)(input);