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('increment');export const getValueQuery = defineQuery<number>('getValue');export async function counterWorkflow(initialValue: number): Promise<void>;

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

const client = new WorkflowClient();const handle = connection.createWorkflowHandle(counterWorkflow, { taskQueue: 'tutorial' });// Start the Workflow with initialValue of 2.await handle.start(2);await handle.signal(incrementSignal, 2);await handle.query(getValueQuery); // 4await handle.cancel();await handle.result(); // throws WorkflowExecutionCancelledError

Type parameters#

NameType
Textends 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

Returns#

Promise<IRequestCancelWorkflowExecutionResponse>


describe#

describe(): Promise<IDescribeWorkflowExecutionResponse>

Describe the current workflow execution

Returns#

Promise<IDescribeWorkflowExecutionResponse>


execute#

execute(...args): Promise<WorkflowResultType<T>>

Start the Workflow with arguments, returns a Promise that resolves when the Workflow execution completes

Parameters#

NameType
...argsParameters<T>

Returns#

Promise<WorkflowResultType<T>>

Inherited from#

BaseWorkflowHandle.execute


query#

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

Query a running or completed Workflow.

example

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

Type parameters#

NameType
RetRet
Argsextends any[][]

Parameters#

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

Returns#

Promise<Ret>


result#

result(): Promise<WorkflowResultType<T>>

Promise that resolves when Workflow execution completes

Returns#

Promise<WorkflowResultType<T>>

Inherited from#

BaseWorkflowHandle.result


signal#

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

Signal a running Workflow.

example

await handle.signal(incrementSignal, 3);

Type parameters#

NameType
Argsextends any[][]

Parameters#

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

Returns#

Promise<void>

Inherited from#

BaseWorkflowHandle.signal


signalWithStart#

signalWithStart<Args>(def, signalArgs, workflowArgs): Promise<string>

Sends a signal to a running Workflow or starts a new one if not already running and immediately signals it. Useful when you're unsure of the Workflows' run state.

Type parameters#

NameType
Argsextends any[][]

Parameters#

NameType
defstring | SignalDefinition<Args>
signalArgsArgs
workflowArgsParameters<T>

Returns#

Promise<string>

the runId of the Workflow


start#

start(...args): Promise<string>

Start the Workflow with arguments, returns a Promise that resolves with the execution runId

Parameters#

NameType
...argsParameters<T>

Returns#

Promise<string>

Inherited from#

BaseWorkflowHandle.start


terminate#

terminate(reason?): Promise<ITerminateWorkflowExecutionResponse>

Terminate a running Workflow

Parameters#

NameType
reason?string

Returns#

Promise<ITerminateWorkflowExecutionResponse>