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.

Throws

WorkflowUpdateRPCTimeoutOrCancelledError if this Update call timed out or was cancelled. This doesn't mean the update itself was timed out or cancelled.

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 ; waitForStage: ACCEPTED }update arguments, and update lifecycle stage to wait for Currently, startUpdate always waits until a worker is accepting tasks for the workflow and the update is accepted or rejected, and the options object must be at least ts { waitForStage: WorkflowUpdateStage.ACCEPTED } If the update takes arguments, then the options object must additionally contain an args property with an array of argument values.

Returns

Promise<WorkflowUpdateHandle<Ret>>

Throws

WorkflowUpdateFailedError if Update validation fails.

Throws

WorkflowUpdateRPCTimeoutOrCancelledError if this Update call timed out or was cancelled. This doesn't mean the update itself was timed out or cancelled.

Example

const updateHandle = await handle.startUpdate(incrementAndGetValueUpdate, {
args: [2],
waitForStage: WorkflowUpdateStage.ACCEPTED,
});
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>
optionsWorkflowUpdateOptions & { args?: Args ; waitForStage: ACCEPTED }

Returns

Promise<WorkflowUpdateHandle<Ret>>


terminate

terminate(reason?): Promise<ITerminateWorkflowExecutionResponse>

Terminate a running Workflow

Parameters

NameType
reason?string

Returns

Promise<ITerminateWorkflowExecutionResponse>