Skip to content

DurableDeferred

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 Added in v4.0.0 Source

Combinators

done

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

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 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"]
  >;
};

succeed

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

type Token = Brand.Branded<string, TokenTypeId>;

Other

await

Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Schema for branded durable deferred tokens.

Signature

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

TokenParsed

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Runtime brand identifier for durable deferred tokens.

Signature

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

TokenTypeId type

Added in v4.0.0 Source

Type-level brand identifier for Token values.

Signature

type TokenTypeId = typeof TokenTypeId;