Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

DurableDeferred unstable

Defines named wait points for durable workflow executions.

A DurableDeferred has a stable name and schemas for the value that will be recorded later. Workflows can await it, suspend when no result exists yet, and resume after its result is recorded. Tokens identify the workflow name, execution id, and deferred name so external code can complete the correct wait point later.

19 exports Since v4.0.0 Source

Combinators

done

unstable
Since v4.0.0

Completes the durable deferred identified by a token with the supplied exit, encoding the result through the deferred schemas.

Signature

declare const done: {
  <Success extends Constraint, Error extends Constraint>(options: {
    readonly exit: Exit.Exit<Success["Type"], Error["Type"]>;
    readonly token: Token;
  }): (self: DurableDeferred<Success, Error>) => Effect<void, never, WorkflowEngine | Success["EncodingServices"] | Error["EncodingServices"]>;
  <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>, options: {
    readonly exit: Exit.Exit<Success["Type"], Error["Type"]>;
    readonly token: Token;
  }): Effect<void, never, WorkflowEngine | Success["EncodingServices"] | Error["EncodingServices"]>;
}

fail

unstable
Since v4.0.0

Completes the durable deferred identified by a token with a typed failure.

Signature

declare const fail: {
  <Success extends Constraint, Error extends Constraint>(options: {
    readonly error: Error["Type"];
    readonly token: Token;
  }): (self: DurableDeferred<Success, Error>) => Effect<void, never, WorkflowEngine | Error["EncodingServices"]>;
  <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>, options: {
    readonly error: Error["Type"];
    readonly token: Token;
  }): Effect<void, never, WorkflowEngine | Error["EncodingServices"]>;
}

failCause

unstable
Since v4.0.0

Completes the durable deferred identified by a token with a failure cause.

Signature

declare const failCause: {
  <Success extends Constraint, Error extends Constraint>(options: {
    readonly cause: Cause.Cause<Error["Type"]>;
    readonly token: Token;
  }): (self: DurableDeferred<Success, Error>) => Effect<void, never, WorkflowEngine | Error["EncodingServices"]>;
  <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>, options: {
    readonly cause: Cause.Cause<Error["Type"]>;
    readonly token: Token;
  }): Effect<void, never, WorkflowEngine | Error["EncodingServices"]>;
}

into

unstable
Since v4.0.0

Runs an effect and records its exit into the durable deferred, resuming workflows that are waiting on that deferred.

Details

The effect and the write of its exit count as one in-flight activity of the workflow, so concurrent branches parked on durable waits do not suspend the run until the exit is recorded. This applies even when the effect itself is not an activity. If the effect parks on a durable wait, the run suspends once the other in-flight activities finish, and nothing is recorded.

Gotchas

A long-running effect keeps the run active instead of letting a parked sibling suspend it. Completing a deferred the run is waiting on still interrupts and replays the run.

Signature

declare const into: {
  <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>): <R>(effect: Effect<Success["Type"], Error["Type"], R>) => Effect<Success["Type"], Error["Type"], WorkflowEngine | WorkflowInstance | R | Success["DecodingServices"] | Error["DecodingServices"] | Success["EncodingServices"] | Error["EncodingServices"]>;
  <Success extends Constraint, Error extends Constraint, R>(effect: Effect<Success["Type"], Error["Type"], R>, self: DurableDeferred<Success, Error>): Effect<Success["Type"], Error["Type"], WorkflowEngine | WorkflowInstance | R | Success["DecodingServices"] | Error["DecodingServices"] | Success["EncodingServices"] | Error["EncodingServices"]>;
}

succeed

unstable
Since v4.0.0

Completes the durable deferred identified by a token with a successful value.

Signature

declare const succeed: {
  <Success extends Constraint, Error extends Constraint>(options: {
    readonly token: Token;
    readonly value: Success["Type"];
  }): (self: DurableDeferred<Success, Error>) => Effect<void, never, WorkflowEngine | Success["EncodingServices"]>;
  <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>, options: {
    readonly token: Token;
    readonly value: Success["Type"];
  }): Effect<void, never, WorkflowEngine | Success["EncodingServices"]>;
}

Constructors

make

unstable
Since v4.0.0

Creates a named durable deferred with optional success and error schemas for persisted completion.

Signature

declare function make<Success extends Constraint = Void, Error extends Constraint = Never>(name: string, options?: {
  readonly error?: Error;
  readonly success?: Success;
}): DurableDeferred<Success, Error>

token

unstable
Since v4.0.0

Creates a token for a durable deferred using the current workflow instance's workflow name and execution ID.

Signature

declare const token: <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>) => Effect.Effect<Token, never, WorkflowInstance>

tokenFromExecutionId

unstable
Since v4.0.0

Creates a durable deferred token from an explicit workflow, execution ID, and deferred name.

Signature

declare const tokenFromExecutionId: {
  (options: {
    readonly executionId: string;
    readonly workflow: Workflow.Any;
  }): <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>) => Token;
  <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>, options: {
    readonly executionId: string;
    readonly workflow: Workflow.Any;
  }): Token;
}

tokenFromPayload

unstable
Since v4.0.0

Creates a durable deferred token by deriving the workflow execution ID from the supplied workflow payload.

Signature

declare const tokenFromPayload: {
  <W extends Any>(options: {
    readonly payload: Workflow.PayloadSchema<W>["~type.make.in"];
    readonly workflow: W;
  }): <Success extends Constraint, Error extends Constraint>(self: DurableDeferred<Success, Error>) => Effect<Token>;
  <Success extends Constraint, Error extends Constraint, W extends Any>(self: DurableDeferred<Success, Error>, options: {
    readonly payload: Workflow.PayloadSchema<W>["~type.make.in"];
    readonly workflow: W;
  }): Effect<Token>;
}

Models

Any

interface unstable
Since v4.0.0

Type-erased durable deferred shape for APIs that only need the deferred identity and name.

Signature

interface Any {
  readonly "~effect/workflow/DurableDeferred": "~effect/workflow/DurableDeferred";
  readonly name: string;
}

AnyWithProps

interface unstable
Since v4.0.0

Type-erased durable deferred shape that also exposes success, error, and exit schemas.

Signature

interface AnyWithProps {
  readonly "~effect/workflow/DurableDeferred": "~effect/workflow/DurableDeferred";
  readonly errorSchema: Top;
  readonly exitSchema: Exit<any, any, any>;
  readonly name: string;
  readonly successSchema: Top;
}

DurableDeferred

interface unstable
Since v4.0.0

Named durable deferred value whose completion is persisted by the workflow engine and encoded with success and error schemas.

Signature

interface DurableDeferred<Success extends Schema.Constraint, Error extends Schema.Constraint = Schema.Never> {
  readonly "~effect/workflow/DurableDeferred": "~effect/workflow/DurableDeferred";
  readonly errorSchema: Error;
  readonly exitSchema: Exit<Top, Top, Top>;
  readonly name: string;
  readonly successSchema: Success;
  readonly withActivityAttempt: Effect<DurableDeferred<Success, Error>>;
}

Token

type unstable
Since v4.0.0

Branded string token identifying a durable deferred for a workflow execution.

Signature

type Token = Brand.Branded<string, TokenTypeId>

Other

await

unstable

Signature

declare const await: <Success extends Schema.Constraint, Error extends Schema.Constraint>(self: DurableDeferred<Success, Error>) => Effect.Effect<Success["Type"], Error["Type"], WorkflowEngine | WorkflowInstance | Success["DecodingServices"] | Error["DecodingServices"]>

Racing

raceAll

unstable
Since v4.0.0

Runs effects as a durable race, returning a previously persisted result when present or completing a named deferred with the first result.

Signature

declare function raceAll<Effects extends readonly [Effect<any, any, any>, Effect<any, any, any>], Success extends Schema<Success<Effects[number]>>, Error extends Schema<Error<Effects[number]>>>(options: {
  effects: Effects;
  error: Error;
  name: string;
  success: Success;
}): Effect<Success<Effects[number]>, Error<Effects[number]>, WorkflowEngine | WorkflowInstance | Services<Effects[number]> | Success["DecodingServices"] | Success["EncodingServices"] | Error["DecodingServices"] | Error["EncodingServices"]>

Schemas

Token

unstable
Since v4.0.0

Schema for branded durable deferred tokens.

Signature

declare const Token: brand<String, "~effect/workflow/DurableDeferred/Token">

TokenParsed

unstable
Since v4.0.0

Schema for a decoded durable deferred token containing the workflow name, execution ID, and deferred name.

Signature

declare class TokenParsed extends {
  readonly deferredName: string;
  readonly executionId: string;
  readonly workflowName: string;
} {
  constructor(...args: [props: {
    readonly deferredName: string;
    readonly executionId: string;
    readonly workflowName: string;
  }, options?: MakeOptions]);
  static readonly encode: (input: TokenParsed, options?: ParseOptions) => string;
  static readonly fromString: (input: string, options?: ParseOptions) => TokenParsed;
  static readonly FromString: decodeTo<typeof TokenParsed, decodeTo<fromJsonString<Tuple<readonly [String, String, String]>>, String, never, never>, never, never>;
  asToken: Token;
}

Type IDs

TokenTypeId

unstable
Since v4.0.0

Runtime brand identifier for durable deferred tokens.

Signature

declare const TokenTypeId: "~effect/workflow/DurableDeferred/Token"

TokenTypeId

type unstable
Since v4.0.0

Type-level brand identifier for Token values.

Signature

type TokenTypeId = typeof TokenTypeId