feat(sdk): add PromiseCombinatorError for promise combinators (#436)

Promise combinators (all, allSettled, any, race) now throw
PromiseCombinatorError instead of the generic ChildContextError when
failures occur. This provides more specific error types for better error
handling and debugging.

Changes:
- Add PromiseCombinatorError class extending DurableOperationError
- Add errorClass parameter to ChildConfig interface
- Update runInChildContext to use configurable error class
- Pass PromiseCombinatorError to all promise combinator operations
- Update unit and integration tests to expect new error type

*Issue #, if available:*
#433

Author: ParidelPooya

packages/aws-durable-execution-sdk-js-examples/src/examples/promise/any/promise-any.test.ts

@@ -29,7 +29,7 @@ createTests<string>({
 
       expect(execution.getError()).toEqual({
         errorMessage: "All promises were rejected",
-        errorType: "ChildContextError",
+        errorType: "PromiseCombinatorError",
         errorData: undefined,
         stackTrace: undefined,
       });

packages/aws-durable-execution-sdk-js/src/errors/durable-error/durable-error.ts

@@ -135,6 +135,18 @@ export class ChildContextError extends DurableOperationError {
   }
 }
 
+/**
+ * Error thrown when a promise combinator operation fails
+ * @public
+ */
+export class PromiseCombinatorError extends DurableOperationError {
+  readonly errorType = "PromiseCombinatorError";
+
+  constructor(message?: string, cause?: Error, errorData?: string) {
+    super(message || "Promise combinator failed", cause, errorData);
+  }
+}
+
 /**
  * Error thrown when a wait for condition operation fails
  * @public

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

@@ -209,6 +209,7 @@ describe("Promise Handler", () => {
       expect(mockRunInChildContext).toHaveBeenCalledWith(
         undefined,
         expect.any(Function),
+        expect.objectContaining({ errorClass: expect.any(Function) }),
       );
       expect(result).toEqual([1, 2]);
     });
@@ -225,6 +226,7 @@ describe("Promise Handler", () => {
       expect(mockRunInChildContext).toHaveBeenCalledWith(
         "test-all",
         expect.any(Function),
+        expect.objectContaining({ errorClass: expect.any(Function) }),
       );
       expect(result).toEqual([1, 2]);
     });
@@ -259,6 +261,7 @@ describe("Promise Handler", () => {
         expect.any(Function),
         expect.objectContaining({
           serdes: expect.any(Object),
+          errorClass: expect.any(Function),
         }),
       );
     });
@@ -278,7 +281,10 @@ describe("Promise Handler", () => {
       expect(mockRunInChildContext).toHaveBeenCalledWith(
         "test-allSettled",
         expect.any(Function),
-        expect.any(Object),
+        expect.objectContaining({
+          serdes: expect.any(Object),
+          errorClass: expect.any(Function),
+        }),
       );
       expect(result).toHaveLength(2);
       expect(result[0]).toEqual({ status: "fulfilled", value: 1 });
@@ -316,6 +322,7 @@ describe("Promise Handler", () => {
       expect(mockRunInChildContext).toHaveBeenCalledWith(
         undefined,
         expect.any(Function),
+        expect.objectContaining({ errorClass: expect.any(Function) }),
       );
       expect(result).toBe(1); // Promise.any returns the first resolved value
     });
@@ -332,6 +339,7 @@ describe("Promise Handler", () => {
       expect(mockRunInChildContext).toHaveBeenCalledWith(
         "test-any",
         expect.any(Function),
+        expect.objectContaining({ errorClass: expect.any(Function) }),
       );
       expect(result).toBe(1); // Promise.any returns the first resolved value
     });
@@ -373,6 +381,7 @@ describe("Promise Handler", () => {
       expect(mockRunInChildContext).toHaveBeenCalledWith(
         undefined,
         expect.any(Function),
+        expect.objectContaining({ errorClass: expect.any(Function) }),
       );
       expect(result).toBe(1); // Promise.race returns the first resolved value
     });
@@ -389,6 +398,7 @@ describe("Promise Handler", () => {
       expect(mockRunInChildContext).toHaveBeenCalledWith(
         "test-race",
         expect.any(Function),
+        expect.objectContaining({ errorClass: expect.any(Function) }),
       );
       expect(result).toBe(1); // Promise.race returns the first resolved value
     });

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

@@ -1,5 +1,6 @@
 import { DurableContext, DurablePromise, DurableLogger } from "../../types";
 import { Serdes, SerdesContext } from "../../utils/serdes/serdes";
+import { PromiseCombinatorError } from "../../errors/durable-error/durable-error";
 
 // Minimal error decoration for Promise.allSettled results
 function decorateErrors<T>(
@@ -100,7 +101,9 @@ export const createPromiseHandler = <Logger extends DurableLogger>(
       const { name, promises } = parseParams(nameOrPromises, maybePromises);
 
       // Wrap Promise.all execution in a child context for persistence
-      return await runInChildContext(name, () => Promise.all(promises));
+      return await runInChildContext(name, () => Promise.all(promises), {
+        errorClass: PromiseCombinatorError,
+      });
     });
   };
 
@@ -114,6 +117,7 @@ export const createPromiseHandler = <Logger extends DurableLogger>(
       // Wrap Promise.allSettled execution in a child context for persistence
       return await runInChildContext(name, () => Promise.allSettled(promises), {
         serdes: createErrorAwareSerdes<T>(),
+        errorClass: PromiseCombinatorError,
       });
     });
   };
@@ -126,7 +130,9 @@ export const createPromiseHandler = <Logger extends DurableLogger>(
       const { name, promises } = parseParams(nameOrPromises, maybePromises);
 
       // Wrap Promise.any execution in a child context for persistence
-      return await runInChildContext(name, () => Promise.any(promises));
+      return await runInChildContext(name, () => Promise.any(promises), {
+        errorClass: PromiseCombinatorError,
+      });
     });
   };
 
@@ -138,7 +144,9 @@ export const createPromiseHandler = <Logger extends DurableLogger>(
       const { name, promises } = parseParams(nameOrPromises, maybePromises);
 
       // Wrap Promise.race execution in a child context for persistence
-      return await runInChildContext(name, () => Promise.race(promises));
+      return await runInChildContext(name, () => Promise.race(promises), {
+        errorClass: PromiseCombinatorError,
+      });
     });
   };
 

packages/aws-durable-execution-sdk-js/src/handlers/run-in-child-context-handler/run-in-child-context-handler.ts

@@ -199,6 +199,7 @@ export const handleCompletedChildContext = async <
   ) => DurableContext<Logger>,
 ): Promise<T> => {
   const serdes = options?.serdes || defaultSerdes;
+  const ErrorClass = options?.errorClass || ChildContextError;
   const stepData = context.getStepData(entityId);
   const result = stepData?.ContextDetails?.Result;
 
@@ -208,9 +209,9 @@ export const handleCompletedChildContext = async <
       const originalError = DurableOperationError.fromErrorObject(
         stepData.ContextDetails.Error,
       );
-      throw new ChildContextError(originalError.message, originalError);
+      throw new ErrorClass(originalError.message, originalError);
     } else {
-      throw new ChildContextError("Child context failed");
+      throw new ErrorClass("Child context failed");
     }
   }
 
@@ -273,6 +274,7 @@ export const executeChildContext = async <T, Logger extends DurableLogger>(
   parentId?: string,
 ): Promise<T> => {
   const serdes = options?.serdes || defaultSerdes;
+  const ErrorClass = options?.errorClass || ChildContextError;
 
   // Checkpoint at start if not already started (fire-and-forget for performance)
   if (context.getStepData(entityId) === undefined) {
@@ -391,6 +393,6 @@ export const executeChildContext = async <T, Logger extends DurableLogger>(
     const errorObject = createErrorObjectFromError(error);
     const reconstructedError =
       DurableOperationError.fromErrorObject(errorObject);
-    throw new ChildContextError(reconstructedError.message, reconstructedError);
+    throw new ErrorClass(reconstructedError.message, reconstructedError);
   }
 };

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

@@ -1,6 +1,7 @@
 import { Serdes } from "../utils/serdes/serdes";
 import { DurableLogger } from "./durable-logger";
 import { DurableContext } from "./durable-context";
+import { DurableOperationError } from "../errors/durable-error/durable-error";
 
 /**
  * Configuration options for child context operations
@@ -13,6 +14,12 @@ export interface ChildConfig<T> {
   subType?: string;
   /** Function to generate summaries for large results (used internally by map/parallel) */
   summaryGenerator?: (result: T) => string;
+  /** Custom error class to throw when child context fails */
+  errorClass?: new (
+    message?: string,
+    cause?: Error,
+    errorData?: string,
+  ) => DurableOperationError;
 }
 
 /**