Skip to main content

Class: CancellationScope

workflow.CancellationScope

In the SDK, Workflows are represented internally by a tree of scopes where the execute function runs in the root scope. Cancellation propagates from outer scopes to inner ones and is handled by catching CancelledFailures thrown by cancellable operations (see below).

Scopes are created using the CancellationScope constructor or the static helper methods cancellable, nonCancellable and withTimeout.

When a CancellationScope is cancelled, it will propagate cancellation any child scopes and any cancellable operations created within it, such as:

  • Activities
  • Child Workflows
  • Timers (created with the sleep function)
  • Triggers

Example

await CancellationScope.cancellable(async () => {
const promise = someActivity();
CancellationScope.current().cancel(); // Cancels the activity
await promise; // Throws `ActivityFailure` with `cause` set to `CancelledFailure`
});

Example

const scope = new CancellationScope();
const promise = scope.run(someActivity);
scope.cancel(); // Cancels the activity
await promise; // Throws `ActivityFailure` with `cause` set to `CancelledFailure`

Constructors

constructor

new CancellationScope(options?)

Parameters

NameType
options?CancellationScopeOptions

Properties

cancelRequested

Readonly cancelRequested: Promise<never>

Rejected when scope cancellation is requested


cancellable

Readonly cancellable: boolean

If false, prevent outer cancellation from propagating to inner scopes, Activities, timers, and Triggers, defaults to true. (Scope still propagates CancelledFailure thrown from within)


parent

Optional Readonly parent: CancellationScope

An optional CancellationScope (useful for running background tasks), defaults to current()

Accessors

consideredCancelled

get consideredCancelled(): boolean

Returns

boolean

Methods

cancel

cancel(): void

Request to cancel the scope and linked children

Returns

void


run

run<T>(fn): Promise<T>

Activate the scope as current and run fn

Any timers, Activities, Triggers and CancellationScopes created in the body of fn automatically link their cancellation to this scope.

Type parameters

Name
T

Parameters

NameType
fn() => Promise<T>

Returns

Promise<T>

the result of fn


cancellable

Static cancellable<T>(fn): Promise<T>

Alias to new CancellationScope({ cancellable: true }).run(fn)

Type parameters

Name
T

Parameters

NameType
fn() => Promise<T>

Returns

Promise<T>


current

Static current(): CancellationScope

Get the current "active" scope

Returns

CancellationScope


nonCancellable

Static nonCancellable<T>(fn): Promise<T>

Alias to new CancellationScope({ cancellable: false }).run(fn)

Type parameters

Name
T

Parameters

NameType
fn() => Promise<T>

Returns

Promise<T>


withTimeout

Static withTimeout<T>(timeout, fn): Promise<T>

Alias to new CancellationScope({ cancellable: true, timeout }).run(fn)

Type parameters

Name
T

Parameters

NameType
timeoutnumber
fn() => Promise<T>

Returns

Promise<T>