feat(sdk): Add naming support for map and parallel operations (#93)

*Description of changes:*

Add support for custom naming in parallel branches and map iterations to
improve debugging and monitoring capabilities.

## New Features

### Named Parallel Branches
- Add NamedParallelBranch interface with optional name and func
properties
- Support mixed named and unnamed branches in parallel operations

### Map Item Naming
- Add itemNamer function to MapConfig for custom map item names
- itemNamer receives (item, index) parameters for flexible naming

### Enhanced Operation Tracking
- Add optional name field to ConcurrentExecutionItem interface
- Pass item names to runInChildContext for better operation hierarchy
- Include item names in ConcurrencyController logging

## Usage Examples

### Named Parallel Branches:
```typescript
await context.parallel([
  { name: 'fetch-user', func: async (ctx) => fetchUser() },
  { name: 'fetch-posts', func: async (ctx) => fetchPosts() }
]);
```

### Custom Map Item Names:
```typescript
await context.map(users, processUser, {
  itemNamer: (user, index) => `User-${user.id || index}`
});
```

## Testing
- Add unit tests for all naming scenarios
- Test named, unnamed, and mixed branch configurations
- Verify itemNamer parameter passing and fallback behavior
- Ensure backward compatibility with existing code

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

Co-authored-by: Pooya Paridel <parpooya@amazon.com>

Author: ParidelPooya

packages/aws-durable-execution-sdk-js/bundle-size-history.json

@@ -1,9 +1,4 @@
 [
-  {
-    "timestamp": "2025-07-10T01:35:30.375Z",
-    "size": 891887,
-    "gitCommit": "ee000fbc8653964a49a894906b8741272288490f"
-  },
   {
     "timestamp": "2025-07-10T02:01:22.836Z",
     "size": 891900,
@@ -248,5 +243,10 @@
     "timestamp": "2025-10-02T19:56:14.710Z",
     "size": 357050,
     "gitCommit": "7934b1ddf1b32907d5a20f1995a49bfa22845821"
+  },
+  {
+    "timestamp": "2025-10-02T22:13:20.410Z",
+    "size": 357303,
+    "gitCommit": "678d972dbbde52016b0dde14c31dff7ebcafaef2"
   }
-]
+]

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

@@ -12,6 +12,7 @@ import {
   MapConfig,
   ParallelFunc,
   ParallelConfig,
+  NamedParallelBranch,
   ConcurrentExecutionItem,
   ConcurrentExecutor,
   ConcurrencyConfig,
@@ -157,11 +158,11 @@ export const createDurableContext = (
     );
   };
 
-  const map: DurableContext["map"] = <T>(
-    nameOrItems: string | undefined | any[],
-    itemsOrMapFunc: any[] | MapFunc<T>,
-    mapFuncOrConfig?: MapFunc<T> | MapConfig,
-    maybeConfig?: MapConfig,
+  const map: DurableContext["map"] = <TInput, TOutput>(
+    nameOrItems: string | undefined | TInput[],
+    itemsOrMapFunc: TInput[] | MapFunc<TInput, TOutput>,
+    mapFuncOrConfig?: MapFunc<TInput, TOutput> | MapConfig<TInput>,
+    maybeConfig?: MapConfig<TInput>,
   ) => {
     const mapHandler = createMapHandler(executionContext, executeConcurrently);
     return mapHandler(
@@ -173,8 +174,13 @@ export const createDurableContext = (
   };
 
   const parallel: DurableContext["parallel"] = <T>(
-    nameOrBranches: string | undefined | ParallelFunc<T>[],
-    branchesOrConfig?: ParallelFunc<T>[] | ParallelConfig,
+    nameOrBranches:
+      | string
+      | undefined
+      | (ParallelFunc<T> | NamedParallelBranch<T>)[],
+    branchesOrConfig?:
+      | (ParallelFunc<T> | NamedParallelBranch<T>)[]
+      | ParallelConfig,
     maybeConfig?: ParallelConfig,
   ) => {
     const parallelHandler = createParallelHandler(

packages/aws-durable-execution-sdk-js/src/handlers/concurrent-execution-handler/concurrent-execution-handler.ts

@@ -9,6 +9,7 @@ export interface ConcurrentExecutionItem<T> {
   id: string;
   data: T;
   index: number;
+  name?: string;
 }
 
 /**
@@ -141,11 +142,12 @@ export class ConcurrencyController {
           log(this.isVerbose, "▶️", `Starting ${this.operationName} item:`, {
             index,
             itemId: item.id,
+            itemName: item.name,
           });
 
           parentContext
             .runInChildContext(
-              item.id,
+              item.name || item.id,
               (childContext) => executor(item, childContext),
               { subType: config.iterationSubType },
             )
@@ -164,6 +166,7 @@ export class ConcurrencyController {
                   {
                     index,
                     itemId: item.id,
+                    itemName: item.name,
                   },
                 );
                 onComplete();
@@ -184,6 +187,7 @@ export class ConcurrencyController {
                   {
                     index,
                     itemId: item.id,
+                    itemName: item.name,
                     error: err.message,
                   },
                 );

packages/aws-durable-execution-sdk-js/src/handlers/map-handler/map-handler.test.ts

@@ -30,7 +30,9 @@ describe("Map Handler", () => {
   describe("parameter parsing", () => {
     it("should parse parameters with name", async () => {
       const items = ["item1", "item2"];
-      const mapFunc: MapFunc<string> = jest.fn().mockResolvedValue("result");
+      const mapFunc: MapFunc<string, string> = jest
+        .fn()
+        .mockResolvedValue("result");
 
       const mockResult = new MockBatchResult([
         { index: 0, result: "result1", status: BatchItemStatus.SUCCEEDED },
@@ -43,8 +45,8 @@ describe("Map Handler", () => {
       expect(mockExecuteConcurrently).toHaveBeenCalledWith(
         "test-map",
         [
-          { id: "map-item-0", data: "item1", index: 0 },
-          { id: "map-item-1", data: "item2", index: 1 },
+          { id: "map-item-0", data: "item1", index: 0, name: undefined },
+          { id: "map-item-1", data: "item2", index: 1, name: undefined },
         ],
         expect.any(Function),
         {
@@ -61,7 +63,9 @@ describe("Map Handler", () => {
 
     it("should parse parameters without name", async () => {
       const items = ["item1", "item2"];
-      const mapFunc: MapFunc<string> = jest.fn().mockResolvedValue("result");
+      const mapFunc: MapFunc<string, string> = jest
+        .fn()
+        .mockResolvedValue("result");
 
       const mockResult = new MockBatchResult([
         { index: 0, result: "result1", status: BatchItemStatus.SUCCEEDED },
@@ -74,8 +78,8 @@ describe("Map Handler", () => {
       expect(mockExecuteConcurrently).toHaveBeenCalledWith(
         undefined,
         [
-          { id: "map-item-0", data: "item1", index: 0 },
-          { id: "map-item-1", data: "item2", index: 1 },
+          { id: "map-item-0", data: "item1", index: 0, name: undefined },
+          { id: "map-item-1", data: "item2", index: 1, name: undefined },
         ],
         expect.any(Function),
         {
@@ -88,7 +92,7 @@ describe("Map Handler", () => {
 
     it("should accept undefined as name parameter", async () => {
       const items = ["item"];
-      const mapFunc: MapFunc<string> = jest.fn();
+      const mapFunc: MapFunc<string, string> = jest.fn();
 
       const mockResult = new MockBatchResult([
         { index: 0, result: "result", status: BatchItemStatus.SUCCEEDED },
@@ -99,7 +103,7 @@ describe("Map Handler", () => {
 
       expect(mockExecuteConcurrently).toHaveBeenCalledWith(
         undefined,
-        [{ id: "map-item-0", data: "item", index: 0 }],
+        [{ id: "map-item-0", data: "item", index: 0, name: undefined }],
         expect.any(Function),
         {
           ...TEST_CONSTANTS.DEFAULT_MAP_CONFIG,
@@ -111,7 +115,9 @@ describe("Map Handler", () => {
 
     it("should parse parameters with config", async () => {
       const items = ["item1", "item2"];
-      const mapFunc: MapFunc<string> = jest.fn().mockResolvedValue("result");
+      const mapFunc: MapFunc<string, string> = jest
+        .fn()
+        .mockResolvedValue("result");
       const config = {
         ...{
           ...TEST_CONSTANTS.DEFAULT_MAP_CONFIG,
@@ -132,8 +138,8 @@ describe("Map Handler", () => {
       expect(mockExecuteConcurrently).toHaveBeenCalledWith(
         undefined,
         [
-          { id: "map-item-0", data: "item1", index: 0 },
-          { id: "map-item-1", data: "item2", index: 1 },
+          { id: "map-item-0", data: "item1", index: 0, name: undefined },
+          { id: "map-item-1", data: "item2", index: 1, name: undefined },
         ],
         expect.any(Function),
         {
@@ -150,7 +156,7 @@ describe("Map Handler", () => {
 
   describe("validation", () => {
     it("should throw error for non-array items", async () => {
-      const mapFunc: MapFunc<string> = jest.fn();
+      const mapFunc: MapFunc<string, string> = jest.fn();
 
       await expect(mapHandler("not-an-array" as any, mapFunc)).rejects.toThrow(
         "Map operation requires an array of items",
@@ -169,7 +175,7 @@ describe("Map Handler", () => {
   describe("execution", () => {
     it("should handle empty array", async () => {
       const items: string[] = [];
-      const mapFunc: MapFunc<string> = jest.fn();
+      const mapFunc: MapFunc<string, string> = jest.fn();
 
       const mockResult = new MockBatchResult([]);
       mockExecuteConcurrently.mockResolvedValue(mockResult as any);
@@ -191,7 +197,9 @@ describe("Map Handler", () => {
 
     it("should create correct execution items", async () => {
       const items = ["item1", "item2", "item3"];
-      const mapFunc: MapFunc<string> = jest.fn().mockResolvedValue("result");
+      const mapFunc: MapFunc<string, string> = jest
+        .fn()
+        .mockResolvedValue("result");
 
       const mockResult = new MockBatchResult([
         { index: 0, result: "result1", status: BatchItemStatus.SUCCEEDED },
@@ -205,9 +213,9 @@ describe("Map Handler", () => {
       expect(mockExecuteConcurrently).toHaveBeenCalledWith(
         undefined,
         [
-          { id: "map-item-0", data: "item1", index: 0 },
-          { id: "map-item-1", data: "item2", index: 1 },
-          { id: "map-item-2", data: "item3", index: 2 },
+          { id: "map-item-0", data: "item1", index: 0, name: undefined },
+          { id: "map-item-1", data: "item2", index: 1, name: undefined },
+          { id: "map-item-2", data: "item3", index: 2, name: undefined },
         ],
         expect.any(Function),
         {
@@ -220,7 +228,7 @@ describe("Map Handler", () => {
 
     it("should return BatchResult with correct structure", async () => {
       const items = ["item1", "item2"];
-      const mapFunc: MapFunc<string> = jest
+      const mapFunc: MapFunc<string, string> = jest
         .fn()
         .mockResolvedValueOnce("result1")
         .mockResolvedValueOnce("result2");
@@ -241,7 +249,7 @@ describe("Map Handler", () => {
 
     it("should create executor that calls mapFunc correctly", async () => {
       const items = ["item1", "item2"];
-      const mapFunc: MapFunc<string> = jest
+      const mapFunc: MapFunc<string, string> = jest
         .fn()
         .mockResolvedValueOnce("result1")
         .mockResolvedValueOnce("result2");
@@ -284,7 +292,9 @@ describe("Map Handler", () => {
 
     it("should pass through maxConcurrency config", async () => {
       const items = ["item1", "item2"];
-      const mapFunc: MapFunc<string> = jest.fn().mockResolvedValue("result");
+      const mapFunc: MapFunc<string, string> = jest
+        .fn()
+        .mockResolvedValue("result");
       const config = {
         ...{
           ...TEST_CONSTANTS.DEFAULT_MAP_CONFIG,
@@ -309,5 +319,107 @@ describe("Map Handler", () => {
         config,
       );
     });
+
+    describe("itemNamer functionality", () => {
+      it("should use custom itemNamer when provided", async () => {
+        const items = [
+          { id: "user1", name: "Alice" },
+          { id: "user2", name: "Bob" },
+        ];
+        const mapFunc: MapFunc<{ id: string; name: string }, string> = jest
+          .fn()
+          .mockResolvedValue("processed");
+        const itemNamer = (item: any, index: number) => `User-${item.id}`;
+
+        const mockResult = new MockBatchResult([
+          { index: 0, result: "processed", status: BatchItemStatus.SUCCEEDED },
+          { index: 1, result: "processed", status: BatchItemStatus.SUCCEEDED },
+        ]);
+        mockExecuteConcurrently.mockResolvedValue(mockResult as any);
+
+        await mapHandler(items, mapFunc, { itemNamer });
+
+        expect(mockExecuteConcurrently).toHaveBeenCalledWith(
+          undefined,
+          [
+            { id: "map-item-0", data: items[0], index: 0, name: "User-user1" },
+            { id: "map-item-1", data: items[1], index: 1, name: "User-user2" },
+          ],
+          expect.any(Function),
+          {
+            ...TEST_CONSTANTS.DEFAULT_MAP_CONFIG,
+            summaryGenerator: expect.any(Function),
+            completionConfig: undefined,
+          },
+        );
+      });
+
+      it("should use undefined names when itemNamer is not provided", async () => {
+        const items = ["item1", "item2"];
+        const mapFunc: MapFunc<string, string> = jest
+          .fn()
+          .mockResolvedValue("processed");
+
+        const mockResult = new MockBatchResult([
+          { index: 0, result: "processed", status: BatchItemStatus.SUCCEEDED },
+          { index: 1, result: "processed", status: BatchItemStatus.SUCCEEDED },
+        ]);
+        mockExecuteConcurrently.mockResolvedValue(mockResult as any);
+
+        await mapHandler(items, mapFunc);
+
+        expect(mockExecuteConcurrently).toHaveBeenCalledWith(
+          undefined,
+          [
+            { id: "map-item-0", data: "item1", index: 0, name: undefined },
+            { id: "map-item-1", data: "item2", index: 1, name: undefined },
+          ],
+          expect.any(Function),
+          {
+            ...TEST_CONSTANTS.DEFAULT_MAP_CONFIG,
+            summaryGenerator: expect.any(Function),
+            completionConfig: undefined,
+          },
+        );
+      });
+
+      it("should pass item and index to itemNamer", async () => {
+        const items = ["a", "b", "c"];
+        const mapFunc: MapFunc<string, string> = jest
+          .fn()
+          .mockResolvedValue("processed");
+        const itemNamer = jest.fn(
+          (item: string, index: number) => `${item}-${index}`,
+        );
+
+        const mockResult = new MockBatchResult([
+          { index: 0, result: "processed", status: BatchItemStatus.SUCCEEDED },
+          { index: 1, result: "processed", status: BatchItemStatus.SUCCEEDED },
+          { index: 2, result: "processed", status: BatchItemStatus.SUCCEEDED },
+        ]);
+        mockExecuteConcurrently.mockResolvedValue(mockResult as any);
+
+        await mapHandler(items, mapFunc, { itemNamer });
+
+        expect(itemNamer).toHaveBeenCalledWith("a", 0);
+        expect(itemNamer).toHaveBeenCalledWith("b", 1);
+        expect(itemNamer).toHaveBeenCalledWith("c", 2);
+
+        expect(mockExecuteConcurrently).toHaveBeenCalledWith(
+          undefined,
+          [
+            { id: "map-item-0", data: "a", index: 0, name: "a-0" },
+            { id: "map-item-1", data: "b", index: 1, name: "b-1" },
+            { id: "map-item-2", data: "c", index: 2, name: "c-2" },
+          ],
+          expect.any(Function),
+          {
+            ...TEST_CONSTANTS.DEFAULT_MAP_CONFIG,
+            summaryGenerator: expect.any(Function),
+            completionConfig: undefined,
+          },
+        );
+      });
+    });
   });
 });