durable-execution-sdk-js.durableexecutionhandler.md

Home > @aws/durable-execution-sdk-js > DurableExecutionHandler

DurableExecutionHandler type

A handler function type for a durable execution that provides automatic state persistence, retry logic, and workflow orchestration capabilities.

This handler type is the core interface for building stateful, long-running AWS Durable Executions using the Durable Execution SDK. The handler receives a durable context that enables: - Step-based execution with automatic checkpointing and replay - Built-in retry strategies with exponential backoff and jitter - Workflow orchestration with parallel execution and child contexts - External system integration via callbacks and conditional waiting - Batch operations with concurrency control

This handler function must be wrapped by withDurableExecution() to enable durable execution capabilities. During replay scenarios, the handler function is re-executed, however the durable context operations that already completed(steps, waits, callbacks, etc.) are not re-executed.

Signature:

export type DurableExecutionHandler<
  TEvent = any,
  TResult = any,
  TLogger extends DurableLogger = DurableLogger,
> = (event: TEvent, context: DurableContext<TLogger>) => Promise<TResult>;

References: DurableLogger, DurableContext

Example

const durableHandler: DurableExecutionHandler<
  { userId: string },
  { status: string }
> = async (event, context) => {
  // Execute durable step with automatic retry and checkpointing
  const user = await context.step("fetch-user", async () =>
    fetchUserFromDB(event.userId),
  );

  // Wait for external callback (e.g., manual approval)
  const approval = await context.waitForCallback(
    "approval",
    async (callbackId) => {
      await sendApprovalRequest(callbackId, user);
    },
  );

  // Process in parallel with concurrency control
  const results = await context.parallel("parallel-tasks", [
    async (ctx) => ctx.step("task1", () => processTask1(user)),
    async (ctx) => ctx.step("task2", () => processTask2(user)),
  ]);

  return { status: "completed" };
};

export const handler = withDurableExecution(durableHandler);