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.
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 } | 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
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
<WorkflowUpdateHandle
<Ret
>>
terminate
▸ terminate(reason?
): Promise
<ITerminateWorkflowExecutionResponse
>
Terminate a running Workflow
Parameters
Name | Type |
---|---|
reason? | string |
Returns
Promise
<ITerminateWorkflowExecutionResponse
>