Retry Handler Support when call activity or suborchestration

packages/durabletask-js/src/index.ts

@@ -62,18 +62,36 @@ export {
 // Proto types (for advanced usage)
 export { OrchestrationStatus as ProtoOrchestrationStatus } from "./proto/orchestrator_service_pb";
 
+// Failure details
+export { FailureDetails, TaskFailureDetails } from "./task/failure-details";
+
 // Task utilities
 export { getName, whenAll, whenAny } from "./task";
 export { Task } from "./task/task";
 
 // Retry policies and task options
-export { RetryPolicy, RetryPolicyOptions } from "./task/retry";
+export {
+  RetryPolicy,
+  RetryPolicyOptions,
+  FailureHandlerPredicate,
+  RetryContext,
+  createRetryContext,
+  RetryHandler,
+  AsyncRetryHandler,
+  toAsyncRetryHandler,
+} from "./task/retry";
 export {
   TaskOptions,
   SubOrchestrationOptions,
   StartOrchestrationOptions,
+  TaskRetryOptions,
   taskOptionsFromRetryPolicy,
+  taskOptionsFromRetryHandler,
+  taskOptionsFromSyncRetryHandler,
   subOrchestrationOptionsFromRetryPolicy,
+  subOrchestrationOptionsFromRetryHandler,
+  isRetryPolicy,
+  isRetryHandler,
 } from "./task/options";
 
 // Types

packages/durabletask-js/src/task/exception/task-failed-error.ts

@@ -9,6 +9,7 @@ export class TaskFailedError extends Error {
 
   constructor(message: string, details: pb.TaskFailureDetails) {
     super(message);
+    this.name = "TaskFailedError";
 
     this._details = new FailureDetails(
       details.getErrormessage(),

packages/durabletask-js/src/task/failure-details.ts

@@ -1,7 +1,20 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-export class FailureDetails {
+/**
+ * Interface representing task failure details.
+ * This is used for retry handlers to inspect failure information.
+ */
+export interface TaskFailureDetails {
+  /** The type/class name of the error */
+  readonly errorType: string;
+  /** The error message */
+  readonly message: string;
+  /** The stack trace, if available */
+  readonly stackTrace?: string;
+}
+
+export class FailureDetails implements TaskFailureDetails {
   private _message: string;
   private _errorType: string;
   private _stackTrace: string | undefined;

packages/durabletask-js/src/task/options/index.ts

@@ -5,6 +5,12 @@ export {
   TaskOptions,
   SubOrchestrationOptions,
   StartOrchestrationOptions,
+  TaskRetryOptions,
   taskOptionsFromRetryPolicy,
+  taskOptionsFromRetryHandler,
+  taskOptionsFromSyncRetryHandler,
   subOrchestrationOptionsFromRetryPolicy,
+  subOrchestrationOptionsFromRetryHandler,
+  isRetryPolicy,
+  isRetryHandler,
 } from "./task-options";

packages/durabletask-js/src/task/options/task-options.ts

@@ -2,16 +2,31 @@
 // Licensed under the MIT License.
 
 import { RetryPolicy } from "../retry/retry-policy";
+import { AsyncRetryHandler, RetryHandler, toAsyncRetryHandler } from "../retry/retry-handler";
+
+/**
+ * Union type representing the available retry strategies for a task.
+ *
+ * - {@link RetryPolicy} for declarative retry control (with backoff, max attempts, etc.)
+ * - {@link AsyncRetryHandler} for asynchronous imperative retry control
+ * - {@link RetryHandler} for synchronous imperative retry control
+ *
+ * When a synchronous {@link RetryHandler} is provided, it is automatically
+ * wrapped into an {@link AsyncRetryHandler} internally.
+ */
+export type TaskRetryOptions = RetryPolicy | AsyncRetryHandler | RetryHandler;
 
 /**
  * Options that can be used to control the behavior of orchestrator task execution.
  */
 export interface TaskOptions {
   /**
-   * The retry policy for the task.
-   * Controls how many times a task is retried and the delay between retries.
+   * The retry options for the task.
+   * Can be a RetryPolicy for declarative retry control,
+   * an AsyncRetryHandler for async imperative retry control,
+   * or a RetryHandler for sync imperative retry control.
    */
-  retry?: RetryPolicy;
+  retry?: TaskRetryOptions;
   /**
    * The tags to associate with the task.
    */
@@ -81,6 +96,48 @@ export function taskOptionsFromRetryPolicy(policy: RetryPolicy): TaskOptions {
   return { retry: policy };
 }
 
+/**
+ * Creates a TaskOptions instance from an AsyncRetryHandler.
+ *
+ * @param handler - The async retry handler to use
+ * @returns A TaskOptions instance configured with the retry handler
+ *
+ * @example
+ * ```typescript
+ * const handler: AsyncRetryHandler = async (context) => {
+ *   if (context.lastAttemptNumber >= 5) return false;
+ *   if (context.lastFailure.errorType === "ValidationError") return false;
+ *   return true;
+ * };
+ *
+ * const options = taskOptionsFromRetryHandler(handler);
+ * await ctx.callActivity("myActivity", input, options);
+ * ```
+ */
+export function taskOptionsFromRetryHandler(handler: AsyncRetryHandler): TaskOptions {
+  return { retry: handler };
+}
+
+/**
+ * Creates a TaskOptions instance from a synchronous RetryHandler.
+ *
+ * @param handler - The sync retry handler to use (will be wrapped in a Promise)
+ * @returns A TaskOptions instance configured with the retry handler
+ *
+ * @example
+ * ```typescript
+ * const handler: RetryHandler = (context) => {
+ *   return context.lastAttemptNumber < 3;
+ * };
+ *
+ * const options = taskOptionsFromSyncRetryHandler(handler);
+ * await ctx.callActivity("myActivity", input, options);
+ * ```
+ */
+export function taskOptionsFromSyncRetryHandler(handler: RetryHandler): TaskOptions {
+  return { retry: toAsyncRetryHandler(handler) };
+}
+
 /**
  * Creates a SubOrchestrationOptions instance from a RetryPolicy and optional instance ID.
  *
@@ -104,3 +161,47 @@ export function subOrchestrationOptionsFromRetryPolicy(
 ): SubOrchestrationOptions {
   return { retry: policy, instanceId };
 }
+
+/**
+ * Creates a SubOrchestrationOptions instance from an AsyncRetryHandler and optional instance ID.
+ *
+ * @param handler - The async retry handler to use
+ * @param instanceId - Optional instance ID for the sub-orchestration
+ * @returns A SubOrchestrationOptions instance configured with the retry handler
+ *
+ * @example
+ * ```typescript
+ * const handler: AsyncRetryHandler = async (context) => {
+ *   return context.lastAttemptNumber < 3;
+ * };
+ *
+ * const options = subOrchestrationOptionsFromRetryHandler(handler, "my-sub-orch-123");
+ * ```
+ */
+export function subOrchestrationOptionsFromRetryHandler(
+  handler: AsyncRetryHandler,
+  instanceId?: string,
+): SubOrchestrationOptions {
+  return { retry: handler, instanceId };
+}
+
+/**
+ * Type guard to check if the retry option is a RetryPolicy.
+ *
+ * @param retry - The retry option to check
+ * @returns true if the retry option is a RetryPolicy, false otherwise
+ */
+export function isRetryPolicy(retry: TaskRetryOptions | undefined): retry is RetryPolicy {
+  return retry instanceof RetryPolicy;
+}
+
+/**
+ * Type guard to check if the retry option is a retry handler function
+ * (either {@link AsyncRetryHandler} or {@link RetryHandler}).
+ *
+ * @param retry - The retry option to check
+ * @returns true if the retry option is a handler function, false otherwise
+ */
+export function isRetryHandler(retry: TaskRetryOptions | undefined): retry is AsyncRetryHandler | RetryHandler {
+  return typeof retry === "function";
+}