Skip to main content

Interface: WorkflowHandle<T>

client.WorkflowHandle

A client side handle to a single Workflow instance. It can be used to start, signal, query, wait for completion, terminate and cancel a Workflow execution.

Given the following Workflow definition:

export const incrementSignal = defineSignal<[number]>('increment');
export const getValueQuery = defineQuery<number>('getValue');
export const incrementAndGetValueUpdate = defineUpdate<number, [number]>('incrementAndGetValue');
export async function counterWorkflow(initialValue: number): Promise<void>;

Create a handle for running and interacting with a single Workflow:

const client = new WorkflowClient();
// Start the Workflow with initialValue of 2.
const handle = await client.start({
workflowType: counterWorkflow,
args: [2],
taskQueue: 'tutorial',
});
await handle.signal(incrementSignal, 2);
const queryResult = await handle.query(getValueQuery); // 4
const firstUpdateResult = await handle.executeUpdate(incrementAndGetValueUpdate, { args: [2] }); // 6
const secondUpdateHandle = await handle.startUpdate(incrementAndGetValueUpdate, { args: [2] });
const secondUpdateResult = await secondUpdateHandle.result(); // 8
await handle.cancel();
await handle.result(); // throws a WorkflowFailedError with `cause` set to a CancelledFailure.

Type parameters

NameType
Textends Workflow = Workflow

Hierarchy

Properties

client

Readonly client: WorkflowClient

Readonly accessor to the underlying WorkflowClient


workflowId

Readonly workflowId: string

The workflowId of the current Workflow

Inherited from

BaseWorkflowHandle.workflowId

Methods

cancel

cancel(): Promise<IRequestCancelWorkflowExecutionResponse>

Cancel a running Workflow.

When a Workflow is cancelled, the root scope throws CancelledFailure with message: 'Workflow canceled'. That means that all cancellable scopes will throw CancelledFailure.

Cancellation may be propagated to Activities depending on ActivityOptions#cancellationType, after which Activity calls may throw an ActivityFailure, and isCancellation(error) will be true (see isCancellation).

Cancellation may be propagated to Child Workflows depending on ChildWorkflowOptions#cancellationType, after which calls to executeChild and ChildWorkflowHandle#result will throw, and isCancellation(error) will be true (see isCancellation).

Returns

Promise<IRequestCancelWorkflowExecutionResponse>


describe

describe(): Promise<WorkflowExecutionDescription>

Describe the current workflow execution

Returns

Promise<WorkflowExecutionDescription>


executeUpdate

executeUpdate<Ret, Args, Name>(def, options): Promise<Ret>

Start an Update and wait for the result.

Update is an experimental feature.

Type parameters

NameType
RetRet
Argsextends [any, ...any[]]
Nameextends string = string

Parameters

NameTypeDescription
defstring | UpdateDefinition<Ret, Args, Name>an Update definition as returned from defineUpdate
optionsWorkflowUpdateOptions & { args: Args }Update arguments

Returns

Promise<Ret>

Throws

WorkflowUpdateFailedError if Update validation fails or if ApplicationFailure is thrown in the Update handler.

Example

const updateResult = await handle.executeUpdate(incrementAndGetValueUpdate, { args: [2] });

executeUpdate<Ret, Args, Name>(def, options?): Promise<Ret>

Type parameters

NameType
RetRet
Argsextends []
Nameextends string = string

Parameters

NameType
defstring | UpdateDefinition<Ret, Args, Name>
options?WorkflowUpdateOptions & { args?: Args }

Returns

Promise<Ret>


fetchHistory

fetchHistory(): Promise<IHistory>

Return a workflow execution's history

Returns

Promise<IHistory>


getUpdateHandle

getUpdateHandle<Ret>(updateId): WorkflowUpdateHandle<Ret>

Get a handle to an Update of this Workflow.

Type parameters

Name
Ret

Parameters

NameType
updateIdstring

Returns

WorkflowUpdateHandle<Ret>


query

query<Ret, Args>(def, ...args): Promise<Ret>

Query a running or completed Workflow.

Type parameters

NameType
RetRet
Argsextends any[] = []

Parameters

NameTypeDescription
defstring | QueryDefinition<Ret, Args, string>a query definition as returned from defineQuery or query name (string)
...argsArgs-

Returns

Promise<Ret>

Example

await handle.query(getValueQuery);
await handle.query<number, []>('getValue');

result

result(): Promise<WorkflowResultType<T>>

Promise that resolves when Workflow execution completes

Returns

Promise<WorkflowResultType<T>>

Inherited from

BaseWorkflowHandle.result


signal

signal<Args, Name>(def, ...args): Promise<void>

Signal a running Workflow.

Type parameters

NameType
Argsextends any[] = []
Nameextends string = string

Parameters

NameTypeDescription
defstring | SignalDefinition<Args, Name>a signal definition as returned from defineSignal
...argsArgs-

Returns

Promise<void>

Example

await handle.signal(incrementSignal, 3);

Inherited from

BaseWorkflowHandle.signal


startUpdate

startUpdate<Ret, Args, Name>(def, options): Promise<WorkflowUpdateHandle<Ret>>

Start an Update and receive a handle to the Update. The Update validator (if present) is run before the handle is returned.

Update is an experimental feature.

Type parameters

NameType
RetRet
Argsextends [any, ...any[]]
Nameextends string = string

Parameters

NameTypeDescription
defstring | UpdateDefinition<Ret, Args, Name>an Update definition as returned from defineUpdate
optionsWorkflowUpdateOptions & { args: Args }Update arguments

Returns

Promise<WorkflowUpdateHandle<Ret>>

Throws

WorkflowUpdateFailedError if Update validation fails.

Example

const updateHandle = await handle.startUpdate(incrementAndGetValueUpdate, { args: [2] });
const updateResult = await updateHandle.result();

startUpdate<Ret, Args, Name>(def, options?): Promise<WorkflowUpdateHandle<Ret>>

Type parameters

NameType
RetRet
Argsextends []
Nameextends string = string

Parameters

NameType
defstring | UpdateDefinition<Ret, Args, Name>
options?WorkflowUpdateOptions & { args?: Args }

Returns

Promise<WorkflowUpdateHandle<Ret>>


terminate

terminate(reason?): Promise<ITerminateWorkflowExecutionResponse>

Terminate a running Workflow

Parameters

NameType
reason?string

Returns

Promise<ITerminateWorkflowExecutionResponse>