@aws/durable-execution-sdk-js 1.0.1 → 1.0.2

package/README.md

@@ -285,17 +285,37 @@ Control execution guarantees:
 ```typescript
 import { StepSemantics } from "@aws/durable-execution-sdk-js";
 
-// At-most-once per retry (default)
+// At-least-once per retry (default)
+await context.step("retriable-operation", async () => sendNotification(), {
+  semantics: StepSemantics.AtLeastOncePerRetry,
+});
+
+// At-most-once per retry
 await context.step("idempotent-operation", async () => updateDatabase(), {
   semantics: StepSemantics.AtMostOncePerRetry,
 });
+```
 
-// At-least-once per retry
-await context.step("retriable-operation", async () => sendNotification(), {
-  semantics: StepSemantics.AtLeastOncePerRetry,
-});
+**Important**: These semantics apply _per retry_, not per overall execution:
+
+- **AtLeastOncePerRetry**: The step will execute at least once on each retry attempt. If the step succeeds but the checkpoint fails (e.g., sandbox crash), the step will re-execute on replay.
+- **AtMostOncePerRetry**: The step will execute at most once per retry attempt. A checkpoint is created before execution, so if a failure occurs after the checkpoint but before step completion, the previous step retry attempt is skipped on replay.
+
+**To achieve at-most-once semantics on a step-level**, use a custom retry strategy:
+
+```typescript
+await context.step(
+  "truly-once-only",
+  async () => callThatCannotTolerateDuplicates(),
+  {
+    semantics: StepSemantics.AtMostOncePerRetry,
+    retryStrategy: () => ({ shouldRetry: false }), // No retries
+  },
+);
 ```
 
+Without this, a step using `AtMostOncePerRetry` with retries enabled could still execute multiple times across different retry attempts.
+
 ### Jitter Strategies
 
 Prevent thundering herd:

package/dist/index.mjs

@@ -165,11 +165,56 @@ var DurableLogLevel;
 })(DurableLogLevel || (DurableLogLevel = {}));
 
 /**
+ * Execution semantics for step operations.
+ *
+ * @remarks
+ * These semantics control how step execution is checkpointed and replayed. **Important**: The guarantees apply *per
+ * retry attempt*, not per overall workflow execution.
+ *
+ * With retries enabled (the default), a step could execute multiple times across different retry attempts even when
+ * using `AtMostOncePerRetry`. To achieve step-level at-most-once execution, combine `AtMostOncePerRetry` with a retry
+ * strategy that disables retries (`shouldRetry: false`).
+ *
+ * @example
+ * ```typescript
+ * // At-least-once per retry (default) - safe for idempotent operations
+ * await context.step("send-notification", async () => sendEmail(), {
+ *   semantics: StepSemantics.AtLeastOncePerRetry,
+ * });
+ *
+ * // At-most-once per retry - for non-idempotent operations
+ * await context.step("charge-payment", async () => processPayment(), {
+ *   semantics: StepSemantics.AtMostOncePerRetry,
+ *   retryStrategy: () => ({ shouldRetry: false }),
+ * });
+ * ```
+ *
  * @public
  */
 var StepSemantics;
 (function (StepSemantics) {
+    /**
+     * At-most-once execution per retry attempt.
+     *
+     * @remarks
+     * A checkpoint is created before step execution. If a failure occurs after the checkpoint
+     * but before step completion, the previous step retry attempt is skipped on replay.
+     *
+     * **Note**: This is "at-most-once *per retry*". With multiple retry attempts, the step
+     * could still execute multiple times across different retries. To guarantee the step
+     * executes at most once, disable retries by returning
+     * `{ shouldRetry: false }` from your retry strategy.
+     */
     StepSemantics["AtMostOncePerRetry"] = "AT_MOST_ONCE_PER_RETRY";
+    /**
+     * At-least-once execution per retry attempt (default).
+     *
+     * @remarks
+     * The step will execute at least once on each retry attempt. If the step succeeds
+     * but the checkpoint fails (e.g., due to a sandbox crash), the step will re-execute
+     * on replay. This is the safer default for operations that are idempotent or can
+     * tolerate duplicate execution.
+     */
     StepSemantics["AtLeastOncePerRetry"] = "AT_LEAST_ONCE_PER_RETRY";
 })(StepSemantics || (StepSemantics = {}));
 /**
@@ -2794,7 +2839,13 @@ class ConcurrencyController {
                     tryStartNext();
                 }
             };
-            tryStartNext();
+            if (items.length === 0) {
+                log("🎉", `${this.operationName} completed with no items`);
+                resolve(new BatchResultImpl([], getCompletionReason(0)));
+            }
+            else {
+                tryStartNext();
+            }
         });
     }
 }
@@ -3232,6 +3283,13 @@ class CheckpointUnrecoverableExecutionError extends UnrecoverableExecutionError
 }
 
 const STEP_DATA_UPDATED_EVENT = "stepDataUpdated";
+const TERMINAL_STATUSES = [
+    OperationStatus.SUCCEEDED,
+    OperationStatus.CANCELLED,
+    OperationStatus.FAILED,
+    OperationStatus.STOPPED,
+    OperationStatus.TIMED_OUT,
+];
 class CheckpointManager {
     durableExecutionArn;
     stepData;
@@ -3246,6 +3304,7 @@ class CheckpointManager {
     forceCheckpointPromises = [];
     queueCompletionResolver = null;
     MAX_PAYLOAD_SIZE = 750 * 1024; // 750KB in bytes
+    MAX_ITEMS_IN_BATCH = 250;
     isTerminating = false;
     static textEncoder = new TextEncoder();
     // Operation lifecycle tracking
@@ -3407,7 +3466,9 @@ class CheckpointManager {
         while (this.queue.length > 0) {
             const nextItem = this.queue[0];
             const itemSize = CheckpointManager.textEncoder.encode(JSON.stringify(nextItem)).length;
-            if (currentSize + itemSize > this.MAX_PAYLOAD_SIZE && batch.length > 0) {
+            if ((currentSize + itemSize > this.MAX_PAYLOAD_SIZE ||
+                batch.length >= this.MAX_ITEMS_IN_BATCH) &&
+                batch.length > 0) {
                 break;
             }
             this.queue.shift();
@@ -3589,6 +3650,11 @@ class CheckpointManager {
         if (op.state !== OperationLifecycleState.RETRY_WAITING) {
             throw new Error(`Operation ${stepId} must be in RETRY_WAITING state, got ${op.state}`);
         }
+        // Resolve immediately if the step was completed already
+        const stepData = this.stepData[hashId(stepId)];
+        if (stepData?.Status && TERMINAL_STATUSES.includes(stepData.Status)) {
+            return Promise.resolve();
+        }
         // Start timer with polling
         this.startTimerWithPolling(stepId, op.endTimestamp);
         // Return promise that resolves when status changes
@@ -3604,6 +3670,11 @@ class CheckpointManager {
         if (op.state !== OperationLifecycleState.IDLE_AWAITED) {
             throw new Error(`Operation ${stepId} must be in IDLE_AWAITED state, got ${op.state}`);
         }
+        // Resolve immediately if the step was completed already
+        const stepData = this.stepData[hashId(stepId)];
+        if (stepData?.Status && TERMINAL_STATUSES.includes(stepData.Status)) {
+            return Promise.resolve();
+        }
         // Start timer with polling
         this.startTimerWithPolling(stepId, op.endTimestamp);
         // Return promise that resolves when status changes
@@ -3653,28 +3724,28 @@ class CheckpointManager {
             op.resolver = undefined;
         }
     }
-    checkAndTerminate() {
+    /**
+     * Determines if the function should terminate.
+     * @returns TerminationReason if the function should terminate, or undefined if the function should not terminate
+     */
+    shouldTerminate() {
         // Rule 1: Can't terminate if checkpoint queue is not empty
         if (this.queue.length > 0) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         // Rule 2: Can't terminate if checkpoint is currently processing
         if (this.isProcessing) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         // Rule 3: Can't terminate if there are pending force checkpoint promises
         if (this.forceCheckpointPromises.length > 0) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         const allOps = Array.from(this.operations.values());
         // Rule 4: Can't terminate if any operation is EXECUTING
         const hasExecuting = allOps.some((op) => op.state === OperationLifecycleState.EXECUTING);
         if (hasExecuting) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         // Rule 5: Clean up operations whose ancestors are complete or pending completion
         for (const op of allOps) {
@@ -3697,12 +3768,17 @@ class CheckpointManager {
             op.state === OperationLifecycleState.IDLE_NOT_AWAITED ||
             op.state === OperationLifecycleState.IDLE_AWAITED);
         if (hasWaiting) {
-            const reason = this.determineTerminationReason(remainingOps);
-            this.scheduleTermination(reason);
+            return this.determineTerminationReason(remainingOps);
         }
-        else {
-            this.abortTermination();
+        return undefined;
+    }
+    checkAndTerminate() {
+        const terminationReason = this.shouldTerminate();
+        if (terminationReason) {
+            this.scheduleTermination(terminationReason);
+            return;
         }
+        this.abortTermination();
     }
     abortTermination() {
         if (this.terminationTimer) {
@@ -3726,6 +3802,11 @@ class CheckpointManager {
             cooldownMs: this.TERMINATION_COOLDOWN_MS,
         });
         this.terminationTimer = setTimeout(() => {
+            if (!this.shouldTerminate()) {
+                log("🔄", "Termination conditions no longer valid after cooldown, aborting termination");
+                this.abortTermination();
+                return;
+            }
             this.executeTermination(reason);
         }, this.TERMINATION_COOLDOWN_MS);
     }
@@ -4477,16 +4558,10 @@ async function runHandler(event, context, executionContext, durableExecutionMode
  * Validates that the event is a proper durable execution input
  */
 function validateDurableExecutionEvent(event) {
-    try {
-        const eventObj = event;
-        if (!eventObj?.DurableExecutionArn || !eventObj?.CheckpointToken) {
-            throw new Error("Missing required durable execution fields");
-        }
-    }
-    catch {
-        const msg = `Unexpected payload provided to start the durable execution. 
-Check your resource configurations to confirm the durability is set.`;
-        throw new Error(msg);
+    const eventObj = event;
+    if (!eventObj?.DurableExecutionArn || !eventObj?.CheckpointToken) {
+        throw new Error("Unexpected payload provided to start the durable execution.\n" +
+            "Check your resource configurations to confirm the durability is set.");
     }
 }
 /**
@@ -4564,14 +4639,7 @@ const withDurableExecution = (handler, config) => {
     return async (event, context) => {
         validateDurableExecutionEvent(event);
         const { executionContext, durableExecutionMode, checkpointToken } = await initializeExecutionContext(event, context, config?.client);
-        let response = null;
-        try {
-            response = await runHandler(event, context, executionContext, durableExecutionMode, checkpointToken, handler);
-            return response;
-        }
-        catch (err) {
-            throw err;
-        }
+        return runHandler(event, context, executionContext, durableExecutionMode, checkpointToken, handler);
     };
 };