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
Name | Type |
---|---|
T | extends Workflow = Workflow |
Hierarchy
-
↳
WorkflowHandle
Properties
client
• Readonly
client: WorkflowClient
Readonly accessor to the underlying WorkflowClient
workflowId
• Readonly
workflowId: string
The workflowId of the current Workflow
Inherited from
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
Name | Type |
---|---|
Ret | Ret |
Args | extends [any , ...any[]] |
Name | extends string = string |
Parameters
Name | Type | Description |
---|---|---|
def | string | UpdateDefinition <Ret , Args , Name > | an Update definition as returned from defineUpdate |
options | WorkflowUpdateOptions & { 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
Name | Type |
---|---|
Ret | Ret |
Args | extends [] |
Name | extends string = string |
Parameters
Name | Type |
---|---|
def | string | 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
Name | Type |
---|---|
updateId | string |
Returns
WorkflowUpdateHandle
<Ret
>
query
▸ query<Ret
, Args
>(def
, ...args
): Promise
<Ret
>
Query a running or completed Workflow.
Type parameters
Name | Type |
---|---|
Ret | Ret |
Args | extends any [] = [] |
Parameters
Name | Type | Description |
---|---|---|
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');
result
▸ result(): Promise
<WorkflowResultType
<T
>>
Promise that resolves when Workflow execution completes
Returns
Promise
<WorkflowResultType
<T
>>
Inherited from
signal
▸ signal<Args
, Name
>(def
, ...args
): Promise
<void
>
Signal a running Workflow.
Type parameters
Name | Type |
---|---|
Args | extends any [] = [] |
Name | extends string = string |
Parameters
Name | Type | Description |
---|---|---|
def | string | SignalDefinition <Args , Name > | a signal definition as returned from defineSignal |
...args | Args | - |
Returns
Promise
<void
>
Example
await handle.signal(incrementSignal, 3);
Inherited from
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
Name | Type |
---|---|
Ret | Ret |
Args | extends [any , ...any[]] |
Name | extends string = string |
Parameters
Name | Type | Description |
---|---|---|
def | string | UpdateDefinition <Ret , Args , Name > | an Update definition as returned from defineUpdate |
options | WorkflowUpdateOptions & { 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
Name | Type |
---|---|
Ret | Ret |
Args | extends [] |
Name | extends string = string |
Parameters
Name | Type |
---|---|
def | string | UpdateDefinition <Ret , Args , Name > |
options | WorkflowUpdateOptions & { args? : Args ; waitForStage : ACCEPTED } |
Returns
Promise
<WorkflowUpdateHandle
<Ret
>>
terminate
▸ terminate(reason?
): Promise
<ITerminateWorkflowExecutionResponse
>
Terminate a running Workflow
Parameters
Name | Type |
---|---|
reason? | string |
Returns
Promise
<ITerminateWorkflowExecutionResponse
>