feat(sdk): add nesting option to Map/Parallel (#456)

*Issue #, if available:*
#451 

*Description of changes:*
- Add nesting?: NestingType in ParallelConfig
- Add nesting?: NestingType in MapConfig
- Add NestingType enum with NESTED and FLAT values for better API
clarity
- NESTED: Creates CONTEXT operations with full observability but higher
cost
- FLAT: Uses virtual contexts for ~30% cost reduction and higher scale
- Update map and parallel handlers to use new nesting configuration
- Update virtual context examples to use NestingType.FLAT
- Add TSDoc explaining trade-offs between observability, cost, and scale
- Maintain backward compatibility through optional nesting parameter

Author: ParidelPooya

package-lock.json

@@ -0,0 +1,33 @@
+import { LocalDurableTestRunner } from "@aws/durable-execution-sdk-js-testing";
+import { handler } from "./map-virtual-context";
+
+describe("Map Virtual Context", () => {
+  let runner: LocalDurableTestRunner;
+
+  beforeAll(async () => {
+    await LocalDurableTestRunner.setupTestEnvironment({ skipTime: true });
+  });
+
+  afterAll(async () => {
+    await LocalDurableTestRunner.teardownTestEnvironment();
+  });
+
+  beforeEach(() => {
+    runner = new LocalDurableTestRunner({ handlerFunction: handler });
+  });
+
+  it("should process items with virtual context", async () => {
+    const result = await runner.run({});
+
+    expect(result.getStatus()).toBe("SUCCEEDED");
+
+    const output = result.getResult();
+    expect(output.processedItems).toEqual([2, 4, 6, 8, 10]);
+    expect(output.totalCount).toBe(5);
+    expect(output.successCount).toBe(5);
+
+    // Verify map operation exists
+    const mapOp = runner.getOperation("process-items-virtual");
+    expect(mapOp.getStatus()).toBe("SUCCEEDED");
+  });
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/map/virtual-context/map-virtual-context.test.ts

@@ -0,0 +1,32 @@
+import {
+  withDurableExecution,
+  NestingType,
+} from "@aws/durable-execution-sdk-js";
+
+export const config = {
+  name: "Map Virtual Context",
+  description:
+    "Demonstrates map operation with flat nesting for cost optimization",
+};
+
+export const handler = withDurableExecution(async (event, context) => {
+  const items = [1, 2, 3, 4, 5];
+
+  // Map with flat nesting (cost optimized)
+  const result = await context.map(
+    "process-items-virtual",
+    items,
+    async (ctx, item) => {
+      return await ctx.step(`process-${item}`, async () => {
+        return item * 2;
+      });
+    },
+    { nesting: NestingType.FLAT }, // Use flat nesting to skip checkpointing
+  );
+
+  return {
+    processedItems: result.getResults(),
+    totalCount: result.totalCount,
+    successCount: result.successCount,
+  };
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/map/virtual-context/map-virtual-context.ts

@@ -0,0 +1,37 @@
+import { LocalDurableTestRunner } from "@aws/durable-execution-sdk-js-testing";
+import { handler } from "./parallel-virtual-context";
+
+describe("Parallel Virtual Context", () => {
+  let runner: LocalDurableTestRunner;
+
+  beforeAll(async () => {
+    await LocalDurableTestRunner.setupTestEnvironment({ skipTime: true });
+  });
+
+  afterAll(async () => {
+    await LocalDurableTestRunner.teardownTestEnvironment();
+  });
+
+  beforeEach(() => {
+    runner = new LocalDurableTestRunner({ handlerFunction: handler });
+  });
+
+  it("should execute parallel tasks with virtual context", async () => {
+    const result = await runner.run({});
+
+    expect(result.getStatus()).toBe("SUCCEEDED");
+
+    const output = result.getResult();
+    expect(output.results).toEqual([
+      { data: "fetched" },
+      { processed: true },
+      { valid: true },
+    ]);
+    expect(output.totalCount).toBe(3);
+    expect(output.successCount).toBe(3);
+
+    // Verify parallel operation exists
+    const parallelOp = runner.getOperation("parallel-tasks-virtual");
+    expect(parallelOp.getStatus()).toBe("SUCCEEDED");
+  });
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/parallel/virtual-context/parallel-virtual-context.test.ts

@@ -0,0 +1,50 @@
+import {
+  withDurableExecution,
+  NestingType,
+} from "@aws/durable-execution-sdk-js";
+
+export const config = {
+  name: "Parallel Virtual Context",
+  description:
+    "Demonstrates parallel execution with flat nesting for cost optimization",
+};
+
+export const handler = withDurableExecution(async (event, context) => {
+  // Parallel execution with flat nesting (cost optimized)
+  const result = await context.parallel(
+    "parallel-tasks-virtual",
+    [
+      {
+        name: "fetch-data",
+        func: async (ctx) => {
+          return await ctx.step("fetch", async () => {
+            return { data: "fetched" };
+          });
+        },
+      },
+      {
+        name: "process-data",
+        func: async (ctx) => {
+          return await ctx.step("process", async () => {
+            return { processed: true };
+          });
+        },
+      },
+      {
+        name: "validate-data",
+        func: async (ctx) => {
+          return await ctx.step("validate", async () => {
+            return { valid: true };
+          });
+        },
+      },
+    ],
+    { nesting: NestingType.FLAT }, // Use flat nesting to skip checkpointing
+  );
+
+  return {
+    results: result.getResults(),
+    totalCount: result.totalCount,
+    successCount: result.successCount,
+  };
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/parallel/virtual-context/parallel-virtual-context.ts

@@ -0,0 +1,56 @@
+[
+  {
+    "EventType": "ExecutionStarted",
+    "EventId": 1,
+    "Id": "caf3a43a-540c-49e0-9722-85ca8c0faa33",
+    "EventTimestamp": "2026-01-22T23:10:25.041Z",
+    "ExecutionStartedDetails": {
+      "Input": {
+        "Payload": "{}"
+      }
+    }
+  },
+  {
+    "EventType": "StepStarted",
+    "SubType": "Step",
+    "EventId": 2,
+    "Id": "ea66c06c1e1c05fa",
+    "EventTimestamp": "2026-01-22T23:10:25.044Z",
+    "StepStartedDetails": {}
+  },
+  {
+    "EventType": "StepSucceeded",
+    "SubType": "Step",
+    "EventId": 3,
+    "Id": "ea66c06c1e1c05fa",
+    "EventTimestamp": "2026-01-22T23:10:25.044Z",
+    "StepSucceededDetails": {
+      "Result": {
+        "Payload": "\"virtual child step completed\""
+      },
+      "RetryDetails": {}
+    }
+  },
+  {
+    "EventType": "InvocationCompleted",
+    "EventId": 4,
+    "EventTimestamp": "2026-01-22T23:10:25.044Z",
+    "InvocationCompletedDetails": {
+      "StartTimestamp": "2026-01-22T23:10:25.041Z",
+      "EndTimestamp": "2026-01-22T23:10:25.044Z",
+      "Error": {},
+      "RequestId": "d70e5350-ff1c-40f6-8d56-d224ff3d01ca"
+    }
+  },
+  {
+    "EventType": "ExecutionSucceeded",
+    "EventId": 5,
+    "Id": "caf3a43a-540c-49e0-9722-85ca8c0faa33",
+    "EventTimestamp": "2026-01-22T23:10:25.045Z",
+    "ExecutionSucceededDetails": {
+      "Result": {
+        "Payload": "\"virtual child step completed\""
+      }
+    }
+  }
+]

packages/aws-durable-execution-sdk-js-examples/src/examples/run-in-child-context/virtual/virtual-run-in-child-context.history.json

@@ -0,0 +1,26 @@
+import {
+  DurableContext,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+
+export const config: ExampleConfig = {
+  name: "Run in Virtual Child Context",
+  description:
+    "Usage of context.runInChildContext() with virtualContext option for cost optimization",
+};
+
+export const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    const result = await context.runInChildContext(
+      async (childContext: DurableContext) => {
+        const stepResult = await childContext.step(async () => {
+          return "virtual child step completed";
+        });
+        return stepResult;
+      },
+      { virtualContext: true }, // Skip checkpointing to save operation costs
+    );
+    return result;
+  },
+);