Workflow.step

Workflow.step is the fundamental building block of durable workflows. Each step’s result is automatically cached in Durable Object storage so that on workflow replay, completed steps are skipped and their cached value is returned directly.

Signature

function step<A, E, R>(
  config: StepConfig<A, E, R>
): Effect.Effect<A, StepErrors<E>, StepRequirements<R>>

Parameters

config

StepConfig

required

Configuration object for the step.

Show StepConfig fields

name

string

required

Unique name for this step within the workflow. Used as the cache key in Durable Object storage, and appears in logs and event traces. Two steps with the same name in the same workflow will share their cached result.

execute

Effect<O, E, R>

required

The effectful computation to run. Can call external APIs, access databases, or perform any async work. The return value is serialized and stored — it must be JSON-serializable. Use Effect.asVoid to discard non-serializable results, or Effect.map to extract serializable fields.

retry

RetryConfig

Optional retry configuration. When provided, failed executions are retried according to the specified policy. Retries are durable — they persist across workflow restarts.

Show RetryConfig fields

maxAttempts

number

required

Maximum number of retry attempts, not including the initial attempt. For example, maxAttempts: 3 means up to 4 total executions.

delay

string | number | BackoffStrategy | ((attempt: number) => number)

Delay between retry attempts.

string — Human-readable duration: "5 seconds", "1 minute"
number — Milliseconds
BackoffStrategy — From Backoff.exponential, Backoff.linear, or Backoff.constant
function — Custom delay: (attempt) => 1000 * Math.pow(2, attempt)

Default: exponential backoff starting at 1 second (up to 60 seconds).

maxDuration

string | number

Total time budget for all retry attempts combined. Once elapsed, the step fails with RetryExhaustedError regardless of remaining attempts. Accepts the same formats as delay.

jitter

boolean

default:"true"

Add ±10% randomness to retry delays to prevent the thundering herd problem when many clients retry simultaneously. Set to false for precise, deterministic timing.

isRetryable

(error: E | WorkflowTimeoutError) => boolean

Optional predicate to filter which errors trigger a retry. Return true to retry, false to fail immediately. When omitted, all errors are retried.

timeout

string | number

Per-attempt timeout. If the step execution does not complete within this duration, it fails with WorkflowTimeoutError. The timeout applies to each individual attempt — when combined with retry, each retry gets the full timeout again. Accepts the same formats as RetryConfig.delay.

Return type

Returns Effect<A, StepErrors<E>, StepRequirements<R>> where A is the step’s output type and StepErrors<E> is a union of:

StepErrors

union

Show error types

your error type

The error type from your execute effect, propagated when no retry is configured or when isRetryable returns false.

RetryExhaustedError

class

Thrown when all retry attempts are exhausted or maxDuration is exceeded. Has stepName: string, attempts: number, and lastError: unknown.

WorkflowTimeoutError

class

Thrown when a step attempt exceeds the configured timeout. Has stepName: string, timeoutMs: number, and elapsedMs: number.

StepCancelledError

class

Thrown when the workflow is cancelled before the step executes. Has stepName: string.

StorageError

class

Thrown when Durable Object storage operations fail.

Serialization requirement

Step results are serialized to JSON and stored in Durable Object storage. The value returned by execute must be JSON-serializable (plain objects, arrays, strings, numbers, booleans, null).

// Non-serializable result (ORM object, class instance) — discard it
yield* Workflow.step({
  name: "Update database",
  execute: updateRecord(id).pipe(Effect.asVoid),
});

// Extract serializable fields from a complex result
yield* Workflow.step({
  name: "Create order",
  execute: createOrder(data).pipe(
    Effect.map((order) => ({ id: order.id, status: order.status }))
  ),
});

Examples

Basic step

const user = yield* Workflow.step({
  name: "Fetch user",
  execute: fetchUser(userId),
});

// user is typed based on what fetchUser returns
console.log(user.email);

Step with retry

yield* Workflow.step({
  name: "Call external API",
  execute: callExternalAPI(),
  retry: {
    maxAttempts: 5,
    delay: "5 seconds",
  },
});

Step with exponential backoff and jitter disabled

import { Backoff } from "@durable-effect/workflow";

yield* Workflow.step({
  name: "Payment processor",
  execute: chargeCard(orderId),
  retry: {
    maxAttempts: 5,
    delay: Backoff.exponential({ base: "1 second", max: "30 seconds" }),
    jitter: false,
  },
});

Step with timeout

yield* Workflow.step({
  name: "Slow third-party API",
  execute: callThirdParty(),
  timeout: "30 seconds",
});

Step with timeout and retry

When combined, the timeout applies to each attempt individually:

yield* Workflow.step({
  name: "Resilient API call",
  execute: callAPI(),
  timeout: "30 seconds",  // each attempt gets 30 seconds
  retry: { maxAttempts: 3 },
  // total max time: 3 attempts × 30 seconds = 90 seconds (plus delays)
});

Selective retry with isRetryable

import { Data } from "effect";

class ValidationError extends Data.TaggedError("ValidationError")<{
  readonly message: string;
}> {}

class NetworkError extends Data.TaggedError("NetworkError")<{
  readonly message: string;
}> {}

yield* Workflow.step({
  name: "Process payment",
  execute: processPayment(paymentId),
  retry: {
    maxAttempts: 5,
    delay: Backoff.presets.standard(),
    isRetryable: (error) => error instanceof NetworkError,
    // ValidationError will not be retried
  },
});

Step with total max duration

yield* Workflow.step({
  name: "Time-bounded operation",
  execute: operation(),
  retry: {
    maxAttempts: 100,
    delay: Backoff.exponential({ base: "1 second" }),
    maxDuration: "5 minutes",
  },
});

@durable-effect/workflow

@durable-effect/jobs

@durable-effect/task

Signature

Parameters

Return type

Serialization requirement

Examples

Basic step

Step with retry

Step with exponential backoff and jitter disabled

Step with timeout

Step with timeout and retry

Selective retry with isRetryable

Step with total max duration

Build docs developers (and LLMs) love

@durable-effect/workflow

@durable-effect/jobs

@durable-effect/task

​Signature

​Parameters

​Return type

​Serialization requirement

​Examples

​Basic step

​Step with retry

​Step with exponential backoff and jitter disabled

​Step with timeout

​Step with timeout and retry

​Selective retry with isRetryable

​Step with total max duration

Build docs developers (and LLMs) love

Signature

Parameters

Return type

Serialization requirement

Examples

Basic step

Step with retry

Step with exponential backoff and jitter disabled

Step with timeout

Step with timeout and retry

Selective retry with isRetryable

Step with total max duration