feat(examples): add completion config examples for map and parallel operations

Add comprehensive examples and tests demonstrating CompletionConfig usage:

Map examples:
- minSuccessful: early completion when target successes reached
- toleratedFailureCount: absolute failure count tolerance
- toleratedFailurePercentage: percentage-based failure tolerance

Parallel examples:
- minSuccessful: early completion with parallel branches
- toleratedFailureCount: failure count tolerance in parallel execution
- toleratedFailurePercentage: failure percentage tolerance in parallel execution

Each example includes realistic scenarios with controlled success/failure patterns,
comprehensive logging, and corresponding unit tests validating expected behavior.
Tests verify completion reasons, success/failure counts, and result collection.

Author: ParidelPooya

packages/aws-durable-execution-sdk-js-examples/src/examples/map/min-successful/map-min-successful.test.ts

@@ -0,0 +1,19 @@
+import { handler } from "./map-min-successful";
+import { createTests } from "../../../utils/test-helper";
+
+createTests({
+  name: "Map minSuccessful",
+  functionName: "map-min-successful",
+  handler,
+  tests: (runner) => {
+    it("should complete early when minSuccessful is reached", async () => {
+      const execution = await runner.run();
+      const result = execution.getResult() as any;
+
+      expect(result.successCount).toBe(2);
+      expect(result.completionReason).toBe("MIN_SUCCESSFUL_REACHED");
+      expect(result.results).toHaveLength(2);
+      expect(result.totalCount).toBe(5);
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/map/min-successful/map-min-successful.ts

@@ -0,0 +1,46 @@
+import {
+  DurableContext,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import { log } from "../../../utils/logger";
+
+export const config: ExampleConfig = {
+  name: "Map minSuccessful",
+  description: "Map operation with minSuccessful completion config",
+};
+
+export const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    const items = [1, 2, 3, 4, 5];
+
+    log(`Processing ${items.length} items with minSuccessful: 2`);
+
+    const results = await context.map(
+      "min-successful-items",
+      items,
+      async (ctx, item, index) => {
+        return await ctx.step(`process-${index}`, async () => {
+          // Simulate processing time
+          await new Promise((resolve) => setTimeout(resolve, 100 * item));
+          return `Item ${item} processed`;
+        });
+      },
+      {
+        completionConfig: {
+          minSuccessful: 2,
+        },
+      },
+    );
+
+    log(`Completed with ${results.successCount} successes`);
+    log(`Completion reason: ${results.completionReason}`);
+
+    return {
+      successCount: results.successCount,
+      totalCount: results.totalCount,
+      completionReason: results.completionReason,
+      results: results.getResults(),
+    };
+  },
+);

packages/aws-durable-execution-sdk-js-examples/src/examples/map/tolerated-failure-count/map-tolerated-failure-count.test.ts

@@ -0,0 +1,20 @@
+import { handler } from "./map-tolerated-failure-count";
+import { createTests } from "../../../utils/test-helper";
+
+createTests({
+  name: "Map toleratedFailureCount",
+  functionName: "map-tolerated-failure-count",
+  handler,
+  tests: (runner) => {
+    it("should complete when failure tolerance is reached", async () => {
+      const execution = await runner.run();
+      const result = execution.getResult() as any;
+
+      expect(result.failureCount).toBe(2);
+      expect(result.successCount).toBe(3);
+      expect(result.completionReason).toBe("ALL_COMPLETED");
+      expect(result.hasFailure).toBe(true);
+      expect(result.totalCount).toBe(5);
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/map/tolerated-failure-count/map-tolerated-failure-count.ts

@@ -0,0 +1,49 @@
+import {
+  DurableContext,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import { log } from "../../../utils/logger";
+
+export const config: ExampleConfig = {
+  name: "Map toleratedFailureCount",
+  description: "Map operation with toleratedFailureCount completion config",
+};
+
+export const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    const items = [1, 2, 3, 4, 5];
+
+    log(`Processing ${items.length} items with toleratedFailureCount: 2`);
+
+    const results = await context.map(
+      "failure-count-items",
+      items,
+      async (ctx, item, index) => {
+        return await ctx.step(`process-${index}`, async () => {
+          // Items 2 and 4 will fail
+          if (item === 2 || item === 4) {
+            throw new Error(`Processing failed for item ${item}`);
+          }
+          return `Item ${item} processed`;
+        });
+      },
+      {
+        completionConfig: {
+          toleratedFailureCount: 2,
+        },
+      },
+    );
+
+    log(`Completed with ${results.failureCount} failures`);
+    log(`Completion reason: ${results.completionReason}`);
+
+    return {
+      successCount: results.successCount,
+      failureCount: results.failureCount,
+      totalCount: results.totalCount,
+      completionReason: results.completionReason,
+      hasFailure: results.hasFailure,
+    };
+  },
+);

packages/aws-durable-execution-sdk-js-examples/src/examples/map/tolerated-failure-percentage/map-tolerated-failure-percentage.test.ts

@@ -0,0 +1,20 @@
+import { handler } from "./map-tolerated-failure-percentage";
+import { createTests } from "../../../utils/test-helper";
+
+createTests({
+  name: "Map toleratedFailurePercentage",
+  functionName: "map-tolerated-failure-percentage",
+  handler,
+  tests: (runner) => {
+    it("should complete with acceptable failure percentage", async () => {
+      const execution = await runner.run();
+      const result = execution.getResult() as any;
+
+      expect(result.failureCount).toBe(3);
+      expect(result.successCount).toBe(7);
+      expect(result.failurePercentage).toBe(30);
+      expect(result.completionReason).toBe("ALL_COMPLETED");
+      expect(result.totalCount).toBe(10);
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/map/tolerated-failure-percentage/map-tolerated-failure-percentage.ts

@@ -0,0 +1,54 @@
+import {
+  DurableContext,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import { log } from "../../../utils/logger";
+
+export const config: ExampleConfig = {
+  name: "Map toleratedFailurePercentage",
+  description:
+    "Map operation with toleratedFailurePercentage completion config",
+};
+
+export const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+    log(`Processing ${items.length} items with toleratedFailurePercentage: 30`);
+
+    const results = await context.map(
+      "failure-percentage-items",
+      items,
+      async (ctx, item, index) => {
+        return await ctx.step(`process-${index}`, async () => {
+          // Items 3, 6, 9 will fail (30% failure rate)
+          if (item % 3 === 0) {
+            throw new Error(`Processing failed for item ${item}`);
+          }
+          return `Item ${item} processed`;
+        });
+      },
+      {
+        completionConfig: {
+          toleratedFailurePercentage: 30,
+        },
+      },
+    );
+
+    log(
+      `Completed with ${results.failureCount} failures (${((results.failureCount / results.totalCount) * 100).toFixed(1)}%)`,
+    );
+    log(`Completion reason: ${results.completionReason}`);
+
+    return {
+      successCount: results.successCount,
+      failureCount: results.failureCount,
+      totalCount: results.totalCount,
+      failurePercentage: Math.round(
+        (results.failureCount / results.totalCount) * 100,
+      ),
+      completionReason: results.completionReason,
+    };
+  },
+);

packages/aws-durable-execution-sdk-js-examples/src/examples/parallel/min-successful/parallel-min-successful.test.ts

@@ -0,0 +1,19 @@
+import { handler } from "./parallel-min-successful";
+import { createTests } from "../../../utils/test-helper";
+
+createTests({
+  name: "Parallel minSuccessful",
+  functionName: "parallel-min-successful",
+  handler,
+  tests: (runner) => {
+    it("should complete early when minSuccessful is reached", async () => {
+      const execution = await runner.run();
+      const result = execution.getResult() as any;
+
+      expect(result.successCount).toBe(2);
+      expect(result.completionReason).toBe("MIN_SUCCESSFUL_REACHED");
+      expect(result.results).toHaveLength(2);
+      expect(result.totalCount).toBe(4);
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/parallel/min-successful/parallel-min-successful.ts

@@ -0,0 +1,62 @@
+import {
+  DurableContext,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import { log } from "../../../utils/logger";
+
+export const config: ExampleConfig = {
+  name: "Parallel minSuccessful",
+  description: "Parallel execution with minSuccessful completion config",
+};
+
+export const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    log("Starting parallel execution with minSuccessful: 2");
+
+    const results = await context.parallel(
+      "min-successful-branches",
+      [
+        async (ctx) => {
+          return await ctx.step("branch-1", async () => {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            return "Branch 1 result";
+          });
+        },
+        async (ctx) => {
+          return await ctx.step("branch-2", async () => {
+            await new Promise((resolve) => setTimeout(resolve, 200));
+            return "Branch 2 result";
+          });
+        },
+        async (ctx) => {
+          return await ctx.step("branch-3", async () => {
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            return "Branch 3 result";
+          });
+        },
+        async (ctx) => {
+          return await ctx.step("branch-4", async () => {
+            await new Promise((resolve) => setTimeout(resolve, 400));
+            return "Branch 4 result";
+          });
+        },
+      ],
+      {
+        completionConfig: {
+          minSuccessful: 2,
+        },
+      },
+    );
+
+    log(`Completed with ${results.successCount} successes`);
+    log(`Completion reason: ${results.completionReason}`);
+
+    return {
+      successCount: results.successCount,
+      totalCount: results.totalCount,
+      completionReason: results.completionReason,
+      results: results.getResults(),
+    };
+  },
+);

packages/aws-durable-execution-sdk-js-examples/src/examples/parallel/tolerated-failure-count/parallel-tolerated-failure-count.test.ts

@@ -0,0 +1,20 @@
+import { handler } from "./parallel-tolerated-failure-count";
+import { createTests } from "../../../utils/test-helper";
+
+createTests({
+  name: "Parallel toleratedFailureCount",
+  functionName: "parallel-tolerated-failure-count",
+  handler,
+  tests: (runner) => {
+    it("should complete when failure tolerance is reached", async () => {
+      const execution = await runner.run();
+      const result = execution.getResult() as any;
+
+      expect(result.failureCount).toBe(2);
+      expect(result.successCount).toBe(3);
+      expect(result.completionReason).toBe("ALL_COMPLETED");
+      expect(result.hasFailure).toBe(true);
+      expect(result.totalCount).toBe(5);
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/parallel/tolerated-failure-count/parallel-tolerated-failure-count.ts

@@ -0,0 +1,65 @@
+import {
+  DurableContext,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import { log } from "../../../utils/logger";
+
+export const config: ExampleConfig = {
+  name: "Parallel toleratedFailureCount",
+  description:
+    "Parallel execution with toleratedFailureCount completion config",
+};
+
+export const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    log("Starting parallel execution with toleratedFailureCount: 2");
+
+    const results = await context.parallel(
+      "failure-count-branches",
+      [
+        async (ctx) => {
+          return await ctx.step("branch-1", async () => {
+            return "Branch 1 success";
+          });
+        },
+        async (ctx) => {
+          return await ctx.step("branch-2", async () => {
+            throw new Error("Branch 2 failed");
+          });
+        },
+        async (ctx) => {
+          return await ctx.step("branch-3", async () => {
+            return "Branch 3 success";
+          });
+        },
+        async (ctx) => {
+          return await ctx.step("branch-4", async () => {
+            throw new Error("Branch 4 failed");
+          });
+        },
+        async (ctx) => {
+          return await ctx.step("branch-5", async () => {
+            return "Branch 5 success";
+          });
+        },
+      ],
+      {
+        completionConfig: {
+          toleratedFailureCount: 2,
+        },
+      },
+    );
+
+    log(`Completed with ${results.failureCount} failures`);
+    log(`Completion reason: ${results.completionReason}`);
+
+    return {
+      successCount: results.successCount,
+      failureCount: results.failureCount,
+      totalCount: results.totalCount,
+      completionReason: results.completionReason,
+      hasFailure: results.hasFailure,
+    };
+  },
+);