[Feature]: Add `throwIfError` method for map and parallel result

[wangyb-A]

What would you like?

I'd like to have a throwIfError method equivalent for Map and Parallel like other SDKs:

• js: https://github.com/aws/aws-durable-execution-sdk-js/blob/main/packages/aws-durable-execution-sdk-js/src/handlers/concurrent-execution-handler/batch-result.ts#L169
• py: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python/src/aws_durable_execution_sdk_python/concurrency/models.py#L382

Possible Implementation

See #573 (comment)

Is this a breaking change?

No

Does this require an RFC?

No

Additional Context

No response

[zhongkechen]

The name throwIfError isn't clear enough. It doesn't throw all the errors if multiple branches fail.

[hln33]

Implementation note: Java SDK divergence

The plan is to add a getOrThrow() method on the ParallelOperation and MapOperation classes to mirror the throwIfError() method the JS and Python SDKs expose on their Parallel/Map result types:

• JS implementation
• Python implementation

While investigating, I found the Java implementation needs to diverge from the other SDKs in a couple of ways. Documenting them here:

1. The method lives on the ParallelOperation/MapOperation classes, not on ParallelResult/MapResult.
   • This is more idiomatic for Java users: parallel.getOrThrow() vs. parallel.get().throwIfError().
2. A new MapFailedException/ParallelFailedException is thrown carrying the full result object, instead of re-throwing the individual branch error.
   • This lets users inspect more than just the first failure.

The more general reason behind these differences: Java uses separate MapResult/ParallelResult types rather than the single BatchResult type the JS and Python SDKs share, so the result isn't self-sufficient for re-throwing errors the way it is in the other SDKs.

[yaythomas]

Thank you for outlining a solution :-) The aggregate-exception direction makes sense, but some follow-up questions....

1. getOrThrow() must be exposed on the public types callers receive. parallel() returns ParallelDurableFuture, so the method should be declared there and implemented by ParallelOperation. map() returns MapResult, while mapAsync() returns DurableFuture<MapResult<O>>, so a method only on MapOperation would not be callable through the public API. The map equivalent should live on MapResult, or use a separate public handle without changing existing signatures.

2. MapResult contains per-item errors, so MapFailedException can carry useful aggregate details. ParallelResult contains only counts and statuses, so carrying it would show which branches failed but not why. ParallelFailedException should also carry structured per-branch error details.

[zhongkechen]

Revised proposal: configuration-driven failure propagation

Other durable operations already follow a consistent contract: get() returns the operation result when the operation succeeds and throws an exception when it fails. Ideally, map and parallel should follow the same contract. The fact that they preserve partial branch outcomes in an aggregate result does not require get() to silently return that result when failures occurred; an aggregate exception can carry the result for inspection.

To introduce that behavior without breaking the current major version, MapConfig and ParallelConfig could expose a shared failure-handling configuration parameter:

var config = MapConfig.builder()
        .failureHandling(FailureHandling.THROW_AGGREGATE)
        .build();

The two modes would be:

• RETURN_RESULT: preserve the current behavior and return the aggregate result even when one or more items or branches failed.
• THROW_AGGREGATE: construct the complete aggregate result and then throw an aggregate exception when the result represents a failure.

RETURN_RESULT should remain the default for the current major version to preserve compatibility. In the next major version, we would have the opportunity to make THROW_AGGREGATE the default, bringing map and parallel into line with the failure behavior of all other operations. Callers that intentionally consume partial failures as data could continue to select RETURN_RESULT explicitly. This provides a migration path toward consistent get() semantics without removing the existing use case.

Consistent synchronous and asynchronous behavior

The synchronous map() methods already delegate to mapAsync(...).get(). If the failure policy is stored by MapOperation, MapOperation.get() can enforce it, giving synchronous and asynchronous callers exactly the same behavior:

var result = context.map("work", items, String.class, function, config);

var future = context.mapAsync("work", items, String.class, function, config);
var result = future.get();

With THROW_AGGREGATE, both calls throw on aggregate failure. With RETURN_RESULT, both return MapResult for explicit inspection. ParallelOperation.get() can apply the same policy. A strict ParallelConfig would also make ParallelDurableFuture.close() propagate the aggregate failure, which is consistent with its configured get() behavior.

Other operations do not need this configuration parameter because their get() implementations already throw on failure. The parameter is needed only to transition map and parallel from their existing result-returning behavior to the same contract.

This also means a universal DurableFuture.getOrThrow() is probably unnecessary. For ordinary operations it would duplicate get(), while map and parallel can support the aligned behavior through their configuration and eventually use it by default. Avoiding both mechanisms also prevents ambiguous combinations such as configuring result-returning behavior and then calling getOrThrow().

Exception behavior

Strict mode should throw one aggregate exception, not rethrow only the first branch error:

• MapFailedException should carry the complete MapResult, which already contains structured per-item errors.
• ParallelFailedException should carry the ParallelResult plus structured per-branch failure details, such as branch index, name, and error. ParallelOperation can collect these details from its branch operations without changing the currently serialized shape of ParallelResult.

The exception therefore preserves every failure and the completion reason while still giving callers one throwable to handle.

Failure detection should include:

• one or more failed items or branches; or
• an overall failed completion decision, such as FAILURE_TOLERANCE_EXCEEDED or CUSTOM_COMPLETION_FAILED, even when no individual branch error exists.

A SKIPPED item or branch should not by itself cause an exception. For example, skipped work after a successful MIN_SUCCESSFUL_REACHED completion is expected.

API shape

A shared enum such as FailureHandling.RETURN_RESULT / THROW_AGGREGATE makes the choice explicit and gives map and parallel the same policy model.

This approach preserves compatibility in the current major version, gives synchronous and asynchronous APIs identical semantics, and creates a clear path to consistent failure behavior across all operations in the next major version.