Support Workflow Update as a Nexus Operation by Evanthx · Pull Request #2194 · temporalio/sdk-typescript

Evanthx · 2026-07-10T22:28:28Z

What was changed

Why?

Checklist

Closes
How was this tested:

Any docs updates needed?

Quinn-With-Two-Ns · 2026-07-15T20:40:51Z

+// requires server-side support for delivering Workflow Update completion callbacks to Nexus, which
+// the bundled ephemeral server (Temporal 1.31.2) does not yet provide (workflow-run completion
+// callbacks do work there). Enable once the test server delivers Update completion callbacks.
+test.skip('UpdateWorkflow Nexus operation - pending update completes asynchronously via callback', async (t) => {


Same comment as dotnet, this should be enabled

Quinn-With-Two-Ns · 2026-07-15T20:44:09Z

+      case OperationTokenType.UPDATE_WORKFLOW: {
+        let updateToken;
+        try {
+          updateToken = loadUpdateWorkflowOperationToken(token);


Why are we reparsing the token, we already have opToken?

Quinn-With-Two-Ns · 2026-07-15T21:21:48Z

+  /**
+   * The Run ID extracted from the operation token. May be empty if the run was not pinned.
+   */
+  readonly runId: string;


The run ID should be know here since the server returns the run ID on the update response

VegetarianOrc · 2026-07-16T16:28:55Z

    const dataConverter = this.dataConverter;
    const context = this.workflowSerializationContext(input.workflowExecution.workflowId!);
    const updateId = input.options?.updateId ?? randomUUID();
+    const internalOptions = (input.options as InternalWorkflowUpdateOptions | undefined)?.[


Casting to InternalWorkflowUpdateOptions is sufficient here. internalOptions stays the same type b/c the value at the InternalWorkflowUpdateOptionsSymbol is an optional property.

Suggested change

const internalOptions = (input.options as InternalWorkflowUpdateOptions | undefined)?.[

const internalOptions = (input.options as InternalWorkflowUpdateOptions)[

VegetarianOrc · 2026-07-16T16:29:38Z

    } catch (err) {
      this.rethrowUpdateGrpcError(err, 'Workflow Update failed', input.workflowExecution);
    }
+    const internalOptions = (input.options as InternalWorkflowUpdateOptions | undefined)?.[


Suggested change

const internalOptions = (input.options as InternalWorkflowUpdateOptions | undefined)?.[

const internalOptions = (input.options as InternalWorkflowUpdateOptions)[

VegetarianOrc · 2026-07-16T16:45:25Z

+export interface NexusUpdateWorkflowOptions<Ret, Args extends any[]> {
+  /**
+   * ID of the Workflow to send the Update to.
+   */
+  readonly workflowId: string;
+
+  /**
+   * Run ID of the Workflow to send the Update to. If unset, the Update is sent to the most recent
+   * run of the Workflow.
+   */
+  readonly runId?: string;
+
+  /**
+   * The Update definition (as returned by `defineUpdate`) or the Update name.
+   */
+  readonly update: UpdateDefinition<Ret, Args> | string;


I think we should consider threading the Name type through to the UpdateDefinition like the WorkflowHandle

executeUpdate<Ret, Args extends [], Name extends string = string>( def: UpdateDefinition<Ret, Args, Name> | string, options?: WorkflowUpdateOptions & { args?: Args } ): Promise<Ret>;

VegetarianOrc · 2026-07-16T16:51:04Z

+  /**
+   * The Update lifecycle stage to wait for. Only {@link WorkflowUpdateStage.ACCEPTED} is supported
+   * for Nexus operations; any other value is rejected. Defaults to
+   * {@link WorkflowUpdateStage.ACCEPTED}.
+   */
+  readonly waitForStage?: WorkflowUpdateStage;


Should we expose this at all if there's only one valid value and we default to it?

VegetarianOrc · 2026-07-16T16:54:52Z

+  const url = new URL(
+    `temporal:///namespaces/${encodeURIComponent(wl.namespace)}/workflows/${encodeURIComponent(
+      wl.workflowId
+    )}/${encodeURIComponent(wl.runId ?? '')}/history`


If the wl.runId property is coalesced to '' does the URL still resolve to a valid page on the UI?

VegetarianOrc · 2026-07-16T17:10:23Z

+    ns: namespace,
+    wid: workflowId,
+    // `rid` is optional, so omit it if not present
+    ...(runId ? { rid: runId } : {}),


I think this is sufficient and avoids the spread. Another thing to note is that runId is required in this function so this is only catching an empty string. Is that the intended behavior?

Suggested change

...(runId ? { rid: runId } : {}),

rid: runId ? runId : undefined,

VegetarianOrc · 2026-07-16T17:34:38Z

+ * These mirror the acceptance criteria of the Go SDK's TestNexusUpdateWorkflowOperation suite:
+ * validation failures surface as failed operations, valid updates succeed, updates sharing an
+ * Update ID are idempotent, and updates against a completed workflow fail.


Suggested change

* These mirror the acceptance criteria of the Go SDK's TestNexusUpdateWorkflowOperation suite:

* validation failures surface as failed operations, valid updates succeed, updates sharing an

* Update ID are idempotent, and updates against a completed workflow fail.

VegetarianOrc · 2026-07-16T17:58:07Z

+      if (sleepMs > 0) {
+        await workflow.sleep(sleepMs);
+      }


Is this sleep necessary? I'm wondering if there's a potential flake being hidden by this.

VegetarianOrc · 2026-07-16T18:05:44Z

+
+  /**
+   * Sends an Update to a Workflow as the backing operation for the current Nexus Operation.
+   *
+   * The Update request is augmented with the Nexus Operation's request ID (for deduplication), its
+   * request links, and a completion callback carrying the operation token, so the Update's
+   * completion is delivered back to the Nexus caller.
+   *
+   * Only asynchronous, `ACCEPTED`-stage Updates are supported: this method returns once the Update
+   * is accepted, yielding an asynchronous {@link TemporalOperationResult} whose completion is
+   * delivered via the callback. If the Update has already completed by the time it is accepted (for
+   * example a retried request with the same Update ID, or an Update that completes immediately), a
+   * synchronous result is returned instead; if that completed Update failed (e.g. validation
+   * rejection, which is non-retryable), it surfaces as a failed Nexus Operation.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  updateWorkflow<Ret, Args extends any[] = []>(
+    options: NexusUpdateWorkflowOptions<Ret, Args>
+  ): Promise<TemporalOperationResult<Ret>>;


I think we should put this function onto the Nexus specific workflow handle to match the signal method.

VegetarianOrc · 2026-07-16T18:06:09Z

+        'failed',
+        'Nexus operation Workflow Updates only support the ACCEPTED wait stage for async updates'
+      );
+    }


Similar to the above comment, I think we should consider removing this check and just always using ACCEPTED.

Evanthx requested a review from a team as a code owner July 10, 2026 22:28

Evanthx force-pushed the nexus-update-workflow branch from fc51ac9 to c219b68 Compare July 10, 2026 23:39

Evanthx added 3 commits July 13, 2026 15:54

Support Workflow Update as a Nexus Operation

28801f8

Fixed a duplicate import

6336c32

Lint fix

121ff88

Evanthx force-pushed the nexus-update-workflow branch from 52d2045 to 121ff88 Compare July 13, 2026 23:21

Quinn-With-Two-Ns reviewed Jul 15, 2026

View reviewed changes

VegetarianOrc reviewed Jul 16, 2026

View reviewed changes

No longer skipping any tests

5b7d5cd

	const internalOptions = (input.options as InternalWorkflowUpdateOptions \| undefined)?.[
	const internalOptions = (input.options as InternalWorkflowUpdateOptions)[

	...(runId ? { rid: runId } : {}),
	rid: runId ? runId : undefined,

	* These mirror the acceptance criteria of the Go SDK's TestNexusUpdateWorkflowOperation suite:
	* validation failures surface as failed operations, valid updates succeed, updates sharing an
	* Update ID are idempotent, and updates against a completed workflow fail.

Uh oh!

Conversation

Evanthx commented Jul 10, 2026

What was changed

Why?

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants