Skip to main content

Interface: WorkflowHandle<T>

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:41

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.

Extends​

  • BaseWorkflowHandle<T>

Type Parameters​

T​

T extends Workflow = Workflow

Properties​

client​

readonly client: WorkflowClient

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:151

Readonly accessor to the underlying WorkflowClient

workflowId​

readonly workflowId: string

Defined in: node_modules/@temporalio/common/lib/workflow-handle.d.ts:57

The workflowId of the current Workflow

Inherited from​

BaseWorkflowHandle.workflowId

Methods​

cancel()​

cancel(): Promise<IRequestCancelWorkflowExecutionResponse>

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:139

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>

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:143

Describe the current workflow execution

Returns​

Promise<WorkflowExecutionDescription>

executeUpdate()​

Call Signature​

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

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:56

Start an Update and wait for the result.

Type Parameters​
Ret​

Ret

Args​

Args extends [any, ...any[]]

Name​

Name extends string = string

Parameters​
def​

string | UpdateDefinition<Ret, Args, Name>

an Update definition as returned from defineUpdate

options​

WorkflowUpdateOptions & object

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

Call Signature​

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

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:59

Type Parameters​
Ret​

Ret

Args​

Args extends []

Name​

Name extends string = string

Parameters​
def​

string | UpdateDefinition<Ret, Args, Name>

options?​

WorkflowUpdateOptions & object

Returns​

Promise<Ret>

fetchHistory()​

fetchHistory(): Promise<IHistory>

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:147

Return a workflow execution's history

Returns​

Promise<IHistory>

getUpdateHandle()​

getUpdateHandle<Ret>(updateId, options?): WorkflowUpdateHandle<Ret>

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:103

Get a handle to an Update of this Workflow.

Type Parameters​

Ret​

Ret

Parameters​

updateId​

string

options?​

GetWorkflowUpdateHandleOptions

Returns​

WorkflowUpdateHandle<Ret>

query()​

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

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:115

Query a running or completed Workflow.

Type Parameters​

Ret​

Ret

Args​

Args extends any[] = []

Parameters​

def​

string | QueryDefinition<Ret, Args, string>

a query definition as returned from defineQuery or query name (string)

args​

...Args

Returns​

Promise<Ret>

Example​

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

queryWithOptions()​

queryWithOptions<Ret, Args>(queryName, options): Promise<Ret>

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:121

Experimental

Query a running or completed Workflow by Query name with additional options, including call-site TypeInfo.

Type Parameters​

Ret​

Ret

Args​

Args extends any[] = []

Parameters​

queryName​

string

options​

WorkflowQueryOptions<Args>

Returns​

Promise<Ret>

result()​

result(): Promise<WorkflowResultType<T>>

Defined in: node_modules/@temporalio/common/lib/workflow-handle.d.ts:34

Promise that resolves when Workflow execution completes

Returns​

Promise<WorkflowResultType<T>>

Inherited from​

BaseWorkflowHandle.result

signal()​

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

Defined in: node_modules/@temporalio/common/lib/workflow-handle.d.ts:47

Signal a running Workflow.

To provide call-site TypeInfo when signaling by name, use signalWithOptions.

Type Parameters​

Args​

Args extends any[] = []

Name​

Name extends string = string

Parameters​

def​

string | SignalDefinition<Args, Name>

a signal definition as returned from defineSignal, or a signal name

args​

...Args

Returns​

Promise<void>

Example​

await handle.signal(incrementSignal, 3);

Inherited from​

BaseWorkflowHandle.signal

signalWithOptions()​

signalWithOptions<Args>(signalName, options): Promise<void>

Defined in: node_modules/@temporalio/common/lib/workflow-handle.d.ts:53

Experimental

Signal a running Workflow by Signal name with additional options, including call-site TypeInfo.

Type Parameters​

Args​

Args extends any[] = []

Parameters​

signalName​

string

options​

WorkflowSignalOptions<Args>

Returns​

Promise<void>

Inherited from​

BaseWorkflowHandle.signalWithOptions

startUpdate()​

Call Signature​

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

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:92

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

Type Parameters​
Ret​

Ret

Args​

Args extends [any, ...any[]]

Name​

Name extends string = string

Parameters​
def​

string | UpdateDefinition<Ret, Args, Name>

an Update definition as returned from defineUpdate

options​

WorkflowUpdateOptions & object

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

{
  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: 'ACCEPTED',
});
const updateResult = await updateHandle.result();

Call Signature​

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

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:96

Type Parameters​
Ret​

Ret

Args​

Args extends []

Name​

Name extends string = string

Parameters​
def​

string | UpdateDefinition<Ret, Args, Name>

options​

WorkflowUpdateOptions & object

Returns​

Promise<WorkflowUpdateHandle<Ret>>

terminate()​

terminate(reason?): Promise<ITerminateWorkflowExecutionResponse>

Defined in: node_modules/@temporalio/client/lib/workflow-client.d.ts:125

Terminate a running Workflow

Parameters​

reason?​

string

Returns​

Promise<ITerminateWorkflowExecutionResponse>