Workflow Update (#1277)

// An Update is defined similarly to Query and Signal. The second type parameter (input) is optional
const myUpdate = wf.defineUpdate<string, [string]>('myUpdate');

// A handler is a sync or async function; the optional validator is always sync.
wf.setHandler(myUpdate, handler, { validator });

// `await wfHandle.executeUpdate` to start an update and block until it completes or fails.
// The signature resembles `WorkflowClient.start` in that the arguments are supplied
// in the optional options object
// (as opposed to the variadic signatures of wfHandle.query and wfHandle.signal)
// An error is thrown if the RPC times out (we do not poll for this call)
// or if the validator rejects, or the handler throws ApplicationFailure.
const updateResult = await handle.executeUpdate(myUpdate, { args: ['a'] });

// `startUpdate` to block until Accepted and obtain a handle to the Update. Signature the same as `executeUpdate`.
const updateHandle = await handle.startUpdate(myUpdate, { args: ['a'] });
// Blocking call to fetch result, with polling.
// Validation failures or ApplicationFailure in the handler would throw here.
const updateResult = await updateHandle.result();

Author: dandavison

docs/activation-in-debug-mode.mermaid

@@ -12,7 +12,7 @@ sequenceDiagram
     end
     Core->>-MT: Respond with Activation
     MT->>MT: Decode Payloads
-    loop patches, signals, completions, queries as jobs
+    loop patches, signals, updates, completions, queries as jobs
         MT->>VM: Activate(jobs)
         VM->>VM: Run Microtasks
         MT->>VM: Try Unblock Conditions

docs/activation.mermaid

@@ -14,7 +14,7 @@ sequenceDiagram
     Core->>-MT: Respond with Activation
     MT->>MT: Decode Payloads
     MT->>+WT: Run Workflow Activation
-    loop patches, signals, completions, queries as jobs
+    loop patches, signals, updates, completions, queries as jobs
         WT->>VM: Activate(jobs)
         VM->>VM: Run Microtasks
         WT->>VM: Try Unblock Conditions

packages/client/src/errors.ts

@@ -35,6 +35,17 @@ export class WorkflowFailedError extends Error {
   }
 }
 
+/**
+ * Thrown by the client while waiting on Workflow Update result if Update
+ * completes with failure.
+ */
+@SymbolBasedInstanceOfError('WorkflowUpdateFailedError')
+export class WorkflowUpdateFailedError extends Error {
+  public constructor(message: string, public readonly cause: TemporalFailure | undefined) {
+    super(message);
+  }
+}
+
 /**
  * Thrown the by client while waiting on Workflow execution result if Workflow
  * continues as new.

packages/client/src/interceptors.ts

@@ -13,9 +13,9 @@ import {
   TerminateWorkflowExecutionResponse,
   WorkflowExecution,
 } from './types';
-import { CompiledWorkflowOptions } from './workflow-options';
+import { CompiledWorkflowOptions, WorkflowUpdateOptions } from './workflow-options';
 
-export { Next, Headers };
+export { Headers, Next };
 
 /** Input for WorkflowClientInterceptor.start */
 export interface WorkflowStartInput {
@@ -25,6 +25,23 @@ export interface WorkflowStartInput {
   readonly options: CompiledWorkflowOptions;
 }
 
+/** Input for WorkflowClientInterceptor.update */
+export interface WorkflowStartUpdateInput {
+  readonly updateName: string;
+  readonly args: unknown[];
+  readonly workflowExecution: WorkflowExecution;
+  readonly firstExecutionRunId?: string;
+  readonly headers: Headers;
+  readonly options: WorkflowUpdateOptions;
+}
+
+/** Output for WorkflowClientInterceptor.startUpdate */
+export interface WorkflowStartUpdateOutput {
+  readonly updateId: string;
+  readonly workflowRunId: string;
+  readonly outcome?: temporal.api.update.v1.IOutcome;
+}
+
 /** Input for WorkflowClientInterceptor.signal */
 export interface WorkflowSignalInput {
   readonly signalName: string;
@@ -81,6 +98,15 @@ export interface WorkflowClientInterceptor {
    * {@link signalWithStart} most likely needs to be implemented too
    */
   start?: (input: WorkflowStartInput, next: Next<this, 'start'>) => Promise<string /* runId */>;
+  /**
+   * Intercept a service call to updateWorkflowExecution
+   *
+   * @experimental Update is an experimental feature.
+   */
+  startUpdate?: (
+    input: WorkflowStartUpdateInput,
+    next: Next<this, 'startUpdate'>
+  ) => Promise<WorkflowStartUpdateOutput>;
   /**
    * Intercept a service call to signalWorkflowExecution
    *