nestjs-temporal-core
    Preparing search index...

    Interface WorkflowHandle<T>

    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.
    interface WorkflowHandle<T extends Workflow = Workflow> {
        client: WorkflowClient;
        workflowId: string;
        cancel(): Promise<IRequestCancelWorkflowExecutionResponse>;
        describe(): Promise<WorkflowExecutionDescription>;
        executeUpdate<
            Ret,
            Args extends [any, ...any[]],
            Name extends string = string,
        >(
            def: string | UpdateDefinition<Ret, Args, Name>,
            options: WorkflowUpdateOptions & { args: Args },
        ): Promise<Ret>;
        executeUpdate<Ret, Args extends [], Name extends string = string>(
            def: string | UpdateDefinition<Ret, Args, Name>,
            options?: WorkflowUpdateOptions & { args?: Args },
        ): Promise<Ret>;
        fetchHistory(): Promise<IHistory>;
        getUpdateHandle<Ret>(updateId: string): WorkflowUpdateHandle<Ret>;
        query<Ret, Args extends any[] = []>(
            def: string | QueryDefinition<Ret, Args, string>,
            ...args: Args,
        ): Promise<Ret>;
        result(): Promise<WorkflowResultType<T>>;
        signal<Args extends any[] = [], Name extends string = string>(
            def: string | SignalDefinition<Args, Name>,
            ...args: Args,
        ): Promise<void>;
        startUpdate<
            Ret,
            Args extends [any, ...any[]],
            Name extends string = string,
        >(
            def: string | UpdateDefinition<Ret, Args, Name>,
            options: WorkflowUpdateOptions & { args: Args; waitForStage: "ACCEPTED" },
        ): Promise<WorkflowUpdateHandle<Ret>>;
        startUpdate<Ret, Args extends [], Name extends string = string>(
            def: string | UpdateDefinition<Ret, Args, Name>,
            options: WorkflowUpdateOptions & { args?: Args; waitForStage: "ACCEPTED" },
        ): Promise<WorkflowUpdateHandle<Ret>>;
        terminate(reason?: string): Promise<ITerminateWorkflowExecutionResponse>;
    }

    Type Parameters

    • T extends Workflow = Workflow

    Hierarchy

    • BaseWorkflowHandle<T>
      • WorkflowHandle
    Index

    Properties

    client workflowId

    Methods

    cancel describe executeUpdate fetchHistory getUpdateHandle query result signal startUpdate terminate

    Properties

    client: WorkflowClient

    Readonly accessor to the underlying WorkflowClient

    workflowId: string

    The workflowId of the current Workflow

    Methods

    • 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 the current workflow execution

      Returns Promise<WorkflowExecutionDescription>

    • Start an Update and wait for the result.

      Type Parameters

      • Ret
      • Args extends [any, ...any[]]
      • Name extends string = string

      Parameters

      • def: string | UpdateDefinition<Ret, Args, Name>

        an Update definition as returned from defineUpdate

      • options: WorkflowUpdateOptions & { args: Args }

        Update arguments

      Returns Promise<Ret>

      WorkflowUpdateFailedError if Update validation fails or if ApplicationFailure is thrown in the Update handler.

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

      const updateResult = await handle.executeUpdate(incrementAndGetValueUpdate, { args: [2] });

    • Type Parameters

      • Ret
      • Args extends []
      • Name extends string = string

      Parameters

      • def: string | UpdateDefinition<Ret, Args, Name>
      • Optionaloptions: WorkflowUpdateOptions & { args?: Args }

      Returns Promise<Ret>

    • Return a workflow execution's history

      Returns Promise<IHistory>

    • Get a handle to an Update of this Workflow.

      Type Parameters

      • Ret

      Parameters

      • updateId: string

      Returns WorkflowUpdateHandle<Ret>

    • Query a running or completed Workflow.

      Type Parameters

      • Ret
      • 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>

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

    • Promise that resolves when Workflow execution completes

      Returns Promise<WorkflowResultType<T>>

    • Signal a running Workflow.

      Type Parameters

      • Args extends any[] = []
      • Name extends string = string

      Parameters

      • def: string | SignalDefinition<Args, Name>

        a signal definition as returned from defineSignal

      • ...args: Args

      Returns Promise<void>

      await handle.signal(incrementSignal, 3);

    • 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
      • Args extends [any, ...any[]]
      • Name extends string = string

      Parameters

      • 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

        {
          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>>

      WorkflowUpdateFailedError if Update validation fails.

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

      const updateHandle = await handle.startUpdate(incrementAndGetValueUpdate, {
        args: [2],
        waitForStage: 'ACCEPTED',
      });
      const updateResult = await updateHandle.result();

    • Type Parameters

      • Ret
      • Args extends []
      • Name extends string = string

      Parameters

      • def: string | UpdateDefinition<Ret, Args, Name>
      • options: WorkflowUpdateOptions & { args?: Args; waitForStage: "ACCEPTED" }

      Returns Promise<WorkflowUpdateHandle<Ret>>

    • Terminate a running Workflow

      Parameters

      • Optionalreason: string

      Returns Promise<ITerminateWorkflowExecutionResponse>

    Settings

    Member Visibility

    On This Page

    Properties
    Methods