Skip to content
Effect Days 2026 Get your ticket

Activity

Defines named effects whose results can be stored by a workflow engine.

An Activity is an Effect with a stable name and schemas for its success and error values. make wraps an effect so the WorkflowEngine can execute it, store its result, or replay that result during a workflow run. This module also includes helpers for retry attempts, idempotency keys, and durable races.

8 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates a workflow activity from an effect, using the provided schemas to encode successes and failures for durable execution.

Gotchas

Only completed activity results are memoized. If the activity suspends while awaiting child workflows or a durable clock, its body runs again when the parent workflow replays. Side effects before the suspension can repeat; make those side effects idempotent.

Signature

declare function make<R, Success extends Constraint = Void, Error extends Constraint = Never>(options: {
  readonly annotations?: Context<never>;
  readonly error?: Error;
  readonly execute: Effect<Success["Type"], Error["Type"], R>;
  readonly interruptRetryPolicy?: Schedule<any, Cause<unknown>, never, never>;
  readonly name: string;
  readonly success?: Success;
}): Activity<Success, Error, Exclude<R, Scope | WorkflowEngine | WorkflowInstance>>

Error Handling

retry

Added in v4.0.0 Source

Retries an effect with Effect.retry while updating CurrentAttempt for each attempt.

Signature

declare const retry: {
  <E, O extends NoExcessProperties<Omit<Options<E>, "schedule">, O>>(options: O): <A, R>(self: Effect<A, E, R>) => Effect<A, O extends {
    schedule: Schedule<infer _O, infer _I, infer _E1, infer _R>;
  } ? E : O extends {
    times: number;
  } ? E : O extends {
    until: Predicate.Refinement<E, infer E2>;
  } ? E2 : O extends {
    while: Predicate.Refinement<E, infer E2>;
  } ? Exclude<E, E2> : E | O extends {
    schedule: Schedule<infer _O, infer _I, infer E, infer _R>;
  } ? E : never | O extends {
    while: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
  } ? E : never | O extends {
    until: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
  } ? E : never, R | O extends {
    schedule: Schedule<infer _O, infer _I, infer _E1, infer R>;
  } ? R : never | O extends {
    while: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
  } ? R : never | O extends {
    until: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
  } ? R : never>;
  <A, E, R, O extends NoExcessProperties<Omit<Options<E>, "schedule">, O>>(self: Effect<A, E, R>, options: O): Effect<A, O extends {
    schedule: Schedule<infer _O, infer _I, infer _E1, infer _R>;
  } ? E : O extends {
    times: number;
  } ? E : O extends {
    until: Predicate.Refinement<E, infer E2>;
  } ? E2 : O extends {
    while: Predicate.Refinement<E, infer E2>;
  } ? Exclude<E, E2> : E | O extends {
    schedule: Schedule<infer _O, infer _I, infer E, infer _R>;
  } ? E : never | O extends {
    while: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
  } ? E : never | O extends {
    until: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
  } ? E : never, R | O extends {
    schedule: Schedule<infer _O, infer _I, infer _E1, infer R>;
  } ? R : never | O extends {
    while: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
  } ? R : never | O extends {
    until: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
  } ? R : never>;
}

Idempotency

idempotencyKey

Added in v4.0.0 Source

Computes a deterministic activity idempotency key from the current workflow execution ID, the supplied name, and optionally the current attempt.

Signature

declare const idempotencyKey: (name: string, options?: {
  readonly includeAttempt?: boolean;
}) => Effect.Effect<string, never, WorkflowInstance>

Models

Activity interface

Added in v4.0.0 Source

Durable workflow activity that behaves as an Effect and records its name, result schemas, annotations, and encoded execution form for the workflow engine.

Signature

interface Activity<Success extends Schema.Constraint = Schema.Void, Error extends Schema.Constraint = Schema.Never, R = never> extends Effect<Success["Type"], Error["Type"], Success["DecodingServices"] | Error["DecodingServices"] | R | WorkflowEngine | WorkflowInstance> {
  readonly "~effect/workflow/Activity": "~effect/workflow/Activity";
  readonly annotations: Context<never>;
  readonly errorSchema: Error;
  readonly execute: Effect<Success["Type"], Error["Type"], Scope | WorkflowEngine | WorkflowInstance | R | Success["DecodingServices"] | Error["DecodingServices"] | Success["EncodingServices"] | Error["EncodingServices"]>;
  readonly executeEncoded: Effect<unknown, unknown, Scope | WorkflowEngine | WorkflowInstance | R | Success["DecodingServices"] | Error["DecodingServices"] | Success["EncodingServices"] | Error["EncodingServices"]>;
  readonly exitSchema: Exit<Success, Error, Defect>;
  readonly exitSchemaPartial: Exit<Success, Error, Unknown>;
  readonly name: string;
  readonly successSchema: Success;
  annotate<I, S>(key: Key<I, S>, value: S): Activity<Success, Error, R>;
  annotateMerge<I>(annotations: Context<I>): Activity<Success, Error, R>;
}

Any interface

Added in v4.0.0 Source

Type-erased activity shape for APIs that only need the activity identity, name, annotations, and encoded execution.

Signature

interface Any {
  readonly "~effect/workflow/Activity": "~effect/workflow/Activity";
  readonly annotations: Context<never>;
  readonly executeEncoded: Effect<any, any, any>;
  readonly name: string;
}

AnyWithProps interface

Added in v4.0.0 Source

Type-erased activity shape that also exposes success and error schemas for derived workflow APIs.

Signature

interface AnyWithProps {
  readonly "~effect/workflow/Activity": "~effect/workflow/Activity";
  readonly errorSchema: Top;
  readonly executeEncoded: Effect<any, any, any>;
  readonly name: string;
  readonly successSchema: Top;
}

Racing

raceAll

Added in v4.0.0 Source

Runs a non-empty collection of activities as a durable race and returns the first completed success or failure using unioned success and error schemas.

Signature

declare function raceAll<Activities extends readonly [Any, Any]>(name: string, activities: Activities): Effect<Activities[number] extends Activity<_A, _E, _R> ? _A["Type"] : never, Activities[number] extends Activity<_A, _E, _R> ? _E["Type"] : never, WorkflowEngine | WorkflowInstance | Activities[number] extends Activity<Success, Error, R> ? R | Success["DecodingServices"] | Error["DecodingServices"] : never>

Services

CurrentAttempt

Added in v4.0.0 Source

Context reference containing the current activity retry attempt, defaulting to 1.

Signature

declare const CurrentAttempt: Reference<number>