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?): CancellationScope

Parameters

Name	Type
options?	CancellationScopeOptions

Returns

CancellationScope

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 CancellationScope.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

Name	Type
fn	() => Promise<T>

Returns

Promise<T>

the result of fn

---

cancellable

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

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

Type parameters

Name
T

Parameters

Name	Type
fn	() => Promise<T>

Returns

Promise<T>

---

current

▸ current(): CancellationScope

Get the current "active" scope

Returns

CancellationScope

---

nonCancellable

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

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

Type parameters

Name
T

Parameters

Name	Type
fn	() => Promise<T>

Returns

Promise<T>

---

withTimeout

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

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

Type parameters

Name
T

Parameters

Name	Type
timeout	number
fn	() => Promise<T>

Returns

Promise<T>