@temporalio/workflow 1.12.2 → 1.13.0

package/src/internals.ts

@@ -41,7 +41,14 @@ import { alea, RNG } from './alea';
 import { RootCancellationScope } from './cancellation-scope';
 import { UpdateScope } from './update-scope';
 import { DeterminismViolationError, LocalActivityDoBackoff, isCancellation } from './errors';
-import { QueryInput, SignalInput, UpdateInput, WorkflowExecuteInput, WorkflowInterceptors } from './interceptors';
+import {
+  QueryInput,
+  SignalInput,
+  StartNexusOperationOutput,
+  UpdateInput,
+  WorkflowExecuteInput,
+  WorkflowInterceptors,
+} from './interceptors';
 import {
   ContinueAsNew,
   DefaultSignalHandler,
@@ -95,10 +102,9 @@ export interface PromiseStackStore {
   promiseToStack: Map<Promise<unknown>, Stack>;
 }
 
-export interface Completion {
-  resolve(val: unknown): unknown;
-
-  reject(reason: unknown): unknown;
+export interface Completion<Success> {
+  resolve(val: Success): void;
+  reject(reason: Error): void;
 }
 
 export interface Condition {
@@ -127,6 +133,8 @@ interface MessageHandlerExecution {
   id?: string;
 }
 
+type InferMapValue<T> = T extends Map<number, infer V> ? V : never;
+
 /**
  * Keeps all of the Workflow runtime state like pending completions for activities and timers.
  *
@@ -150,16 +158,19 @@ export class Activator implements ActivationHandler {
    * Cache for modules - referenced in reusable-vm.ts
    */
   readonly moduleCache = new Map<string, unknown>();
+
   /**
    * Map of task sequence to a Completion
    */
   readonly completions = {
-    timer: new Map<number, Completion>(),
-    activity: new Map<number, Completion>(),
-    childWorkflowStart: new Map<number, Completion>(),
-    childWorkflowComplete: new Map<number, Completion>(),
-    signalWorkflow: new Map<number, Completion>(),
-    cancelWorkflow: new Map<number, Completion>(),
+    timer: new Map<number, Completion<void>>(),
+    activity: new Map<number, Completion<unknown>>(),
+    nexusOperationStart: new Map<number, Completion<StartNexusOperationOutput>>(),
+    nexusOperationComplete: new Map<number, Completion<unknown>>(),
+    childWorkflowStart: new Map<number, Completion<string>>(),
+    childWorkflowComplete: new Map<number, Completion<unknown>>(),
+    signalWorkflow: new Map<number, Completion<void>>(),
+    cancelWorkflow: new Map<number, Completion<void>>(),
   };
 
   /**
@@ -381,6 +392,7 @@ export class Activator implements ActivationHandler {
     signalWorkflow: 1,
     cancelWorkflow: 1,
     condition: 1,
+    nexusOperation: 1,
     // Used internally to keep track of active stack traces
     stack: 1,
   };
@@ -519,7 +531,7 @@ export class Activator implements ActivationHandler {
 
   public async startWorkflowNextHandler({ args }: WorkflowExecuteInput): Promise<any> {
     const { workflow } = this;
-    if (workflow === undefined) {
+    if (workflow == null) {
       throw new IllegalStateError('Workflow uninitialized');
     }
     return await workflow(...args);
@@ -583,12 +595,16 @@ export class Activator implements ActivationHandler {
       resolve(result);
     } else if (activation.result.failed) {
       const { failure } = activation.result.failed;
-      const err = failure ? this.failureToError(failure) : undefined;
-      reject(err);
+      if (failure == null) {
+        throw new TypeError('Got failed result with no failure attribute');
+      }
+      reject(this.failureToError(failure));
     } else if (activation.result.cancelled) {
       const { failure } = activation.result.cancelled;
-      const err = failure ? this.failureToError(failure) : undefined;
-      reject(err);
+      if (failure == null) {
+        throw new TypeError('Got cancelled result with no failure attribute');
+      }
+      reject(this.failureToError(failure));
     } else if (activation.result.backoff) {
       reject(new LocalActivityDoBackoff(activation.result.backoff));
     }
@@ -599,6 +615,9 @@ export class Activator implements ActivationHandler {
   ): void {
     const { resolve, reject } = this.consumeCompletion('childWorkflowStart', getSeq(activation));
     if (activation.succeeded) {
+      if (!activation.succeeded.runId) {
+        throw new TypeError('Got ResolveChildWorkflowExecutionStart with no runId');
+      }
       resolve(activation.succeeded.runId);
     } else if (activation.failed) {
       if (decodeStartChildWorkflowExecutionFailedCause(activation.failed.cause) !== 'WORKFLOW_ALREADY_EXISTS') {
@@ -635,25 +654,68 @@ export class Activator implements ActivationHandler {
       resolve(result);
     } else if (activation.result.failed) {
       const { failure } = activation.result.failed;
-      if (failure === undefined || failure === null) {
+      if (failure == null) {
         throw new TypeError('Got failed result with no failure attribute');
       }
       reject(this.failureToError(failure));
     } else if (activation.result.cancelled) {
       const { failure } = activation.result.cancelled;
-      if (failure === undefined || failure === null) {
+      if (failure == null) {
         throw new TypeError('Got cancelled result with no failure attribute');
       }
       reject(this.failureToError(failure));
     }
   }
 
-  public resolveNexusOperationStart(_: coresdk.workflow_activation.IResolveNexusOperationStart): void {
-    throw new Error('TODO');
+  public resolveNexusOperationStart(activation: coresdk.workflow_activation.IResolveNexusOperationStart): void {
+    const seq = getSeq(activation);
+    const { resolve, reject } = this.consumeCompletion('nexusOperationStart', seq);
+
+    if (!activation.failed) {
+      const completePromise = new Promise((resolve, reject) => {
+        this.completions.nexusOperationComplete.set(seq, {
+          resolve,
+          reject,
+        });
+      });
+      untrackPromise(completePromise);
+      untrackPromise(completePromise.catch(() => undefined));
+
+      resolve({ token: activation.operationToken!, result: completePromise });
+    } else {
+      reject(this.failureToError(activation.failed));
+    }
   }
 
-  public resolveNexusOperation(_: coresdk.workflow_activation.IResolveNexusOperation): void {
-    throw new Error('TODO');
+  public resolveNexusOperation(activation: coresdk.workflow_activation.IResolveNexusOperation): void {
+    const seq = getSeq(activation);
+
+    if (activation.result?.completed) {
+      const result = this.payloadConverter.fromPayload(activation.result.completed);
+
+      // It is possible for ResolveNexusOperation to be received without a prior ResolveNexusOperationStart,
+      // e.g. because the handler completed the Operation synchronously.
+      const startCompletion = this.maybeConsumeCompletion('nexusOperationStart', seq);
+      if (startCompletion) {
+        startCompletion.resolve({ result: Promise.resolve(result) });
+      } else {
+        this.consumeCompletion('nexusOperationComplete', seq).resolve(result);
+      }
+    } else {
+      let err: Error;
+      if (activation.result?.failed) {
+        err = this.failureToError(activation.result.failed);
+      } else if (activation.result?.cancelled) {
+        err = this.failureToError(activation.result.cancelled);
+      } else if (activation.result?.timedOut) {
+        err = this.failureToError(activation.result.timedOut);
+      }
+
+      const completion =
+        this.maybeConsumeCompletion('nexusOperationStart', seq) ??
+        this.consumeCompletion('nexusOperationComplete', seq);
+      completion.reject(err!);
+    }
   }
 
   // Intentionally non-async function so this handler doesn't show up in the stack trace
@@ -749,7 +811,7 @@ export class Activator implements ActivationHandler {
         : null);
 
     // If we don't have an entry from either source, buffer and return
-    if (entry === null) {
+    if (entry == null) {
       this.bufferedUpdates.push(activation);
       return;
     }
@@ -1152,16 +1214,22 @@ export class Activator implements ActivationHandler {
   }
 
   /** Consume a completion if it exists in Workflow state */
-  private maybeConsumeCompletion(type: keyof Activator['completions'], taskSeq: number): Completion | undefined {
+  private maybeConsumeCompletion<K extends keyof Activator['completions']>(
+    type: K,
+    taskSeq: number
+  ): InferMapValue<Activator['completions'][K]> | undefined {
     const completion = this.completions[type].get(taskSeq);
     if (completion !== undefined) {
       this.completions[type].delete(taskSeq);
     }
-    return completion;
+    return completion as InferMapValue<Activator['completions'][K]> | undefined;
   }
 
   /** Consume a completion if it exists in Workflow state, throws if it doesn't */
-  private consumeCompletion(type: keyof Activator['completions'], taskSeq: number): Completion {
+  private consumeCompletion<K extends keyof Activator['completions']>(
+    type: K,
+    taskSeq: number
+  ): InferMapValue<Activator['completions'][K]> {
     const completion = this.maybeConsumeCompletion(type, taskSeq);
     if (completion === undefined) {
       throw new IllegalStateError(`No completion for taskSeq ${taskSeq}`);
@@ -1191,7 +1259,7 @@ export class Activator implements ActivationHandler {
 
 function getSeq<T extends { seq?: number | null }>(activation: T): number {
   const seq = activation.seq;
-  if (seq === undefined || seq === null) {
+  if (seq == null) {
     throw new TypeError(`Got activation with no seq attribute`);
   }
   return seq;

package/src/nexus.ts

@@ -0,0 +1,228 @@
+import * as nexus from 'nexus-rpc';
+import { msOptionalToTs } from '@temporalio/common/lib/time';
+import { userMetadataToPayload } from '@temporalio/common/lib/user-metadata';
+import { composeInterceptors } from '@temporalio/common/lib/interceptors';
+import { CancellationScope } from './cancellation-scope';
+import { getActivator } from './global-attributes';
+import { untrackPromise } from './stack-helpers';
+import { StartNexusOperationInput, StartNexusOperationOutput, StartNexusOperationOptions } from './interceptors';
+
+/**
+ * A Nexus client for invoking Nexus Operations for a specific service from a Workflow.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface NexusClient<T extends nexus.ServiceDefinition> {
+  /**
+   * Start a Nexus Operation and wait for its completion taking a {@link nexus.operation}.
+   * Returns the operation's result.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  executeOperation<O extends T['operations'][keyof T['operations']]>(
+    op: O,
+    input: nexus.OperationInput<O>,
+    options?: Partial<StartNexusOperationOptions>
+  ): Promise<nexus.OperationOutput<O>>;
+
+  // TODO(nexus/post-initial-release): Revisit the "Operation Property Name" terminology,
+  //                                   and reflect in the Nexus RPC SDK.
+
+  /**
+   * Start a Nexus Operation and wait for its completion, taking an Operation's _property name_.
+   * Returns the operation's result.
+   *
+   * An Operation's _property name_ is the name of the property used to define that Operation in
+   * the {@link nexus.ServiceDefinition} object; it may differ from the value of the `name` property
+   * if one was explicitly specified on the {@link nexus.OperationDefinition} object.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  executeOperation<K extends nexus.OperationKey<T['operations']>>(
+    op: K,
+    input: nexus.OperationInput<T['operations'][K]>,
+    options?: Partial<StartNexusOperationOptions>
+  ): Promise<nexus.OperationOutput<T['operations'][K]>>;
+
+  /**
+   * Start a Nexus Operation taking a {@link nexus.operation}.
+   *
+   * Returns a handle that can be used to wait for the Operation's result.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  startOperation<O extends T['operations'][keyof T['operations']]>(
+    op: O,
+    input: nexus.OperationInput<O>,
+    options?: Partial<StartNexusOperationOptions>
+  ): Promise<NexusOperationHandle<nexus.OperationOutput<O>>>;
+
+  /**
+   * Start a Nexus Operation, taking an Operation's _property name_.
+   * Returns a handle that can be used to wait for the Operation's result.
+   *
+   * An Operation's _property name_ is the name of the property used to define that Operation in
+   * the {@link nexus.ServiceDefinition} object; it may differ from the value of the `name` property
+   * if one was explicitly specified on the {@link nexus.OperationDefinition} object.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  startOperation<K extends nexus.OperationKey<T['operations']>>(
+    op: K,
+    input: nexus.OperationInput<T['operations'][K]>,
+    options?: Partial<StartNexusOperationOptions>
+  ): Promise<NexusOperationHandle<nexus.OperationOutput<T['operations'][K]>>>;
+}
+
+/**
+ * A handle to a Nexus Operation.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface NexusOperationHandle<T> {
+  /**
+   * The Operation's service name.
+   */
+  readonly service: string;
+
+  /**
+   * The name of the Operation.
+   */
+  readonly operation: string;
+
+  /**
+   * Operation token as set by the Operation's handler. May be empty if the Operation completed synchronously.
+   */
+  readonly token?: string;
+
+  /**
+   * Wait for Operation completion and get its result.
+   */
+  result(): Promise<T>;
+}
+
+/**
+ * Options for {@link createNexusClient}.
+ */
+export interface NexusClientOptions<T> {
+  endpoint: string;
+  service: T;
+}
+
+/**
+ * Create a Nexus client for invoking Nexus Operations from a Workflow.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export function createNexusClient<T extends nexus.ServiceDefinition>(options: NexusClientOptions<T>): NexusClient<T> {
+  class NexusClientImpl<T extends nexus.ServiceDefinition> implements NexusClient<T> {
+    async executeOperation<O extends T['operations'][keyof T['operations']]>(
+      operation: string | T['operations'][nexus.OperationKey<T['operations']>],
+      input: nexus.OperationInput<T['operations'][nexus.OperationKey<T['operations']>]>,
+      operationOptions?: Partial<StartNexusOperationOptions>
+    ): Promise<nexus.OperationOutput<O>> {
+      const handle = await this.startOperation(operation, input, operationOptions);
+      return await handle.result();
+    }
+
+    async startOperation<O extends T['operations'][keyof T['operations']]>(
+      operation: string | T['operations'][nexus.OperationKey<T['operations']>],
+      input: nexus.OperationInput<T['operations'][nexus.OperationKey<T['operations']>]>,
+      operationOptions?: StartNexusOperationOptions
+    ) {
+      const opName = typeof operation === 'string' ? options.service.operations[operation]?.name : operation.name;
+
+      const activator = getActivator();
+      const seq = activator.nextSeqs.nexusOperation++;
+
+      const execute = composeInterceptors(
+        activator.interceptors.outbound,
+        'startNexusOperation',
+        startNexusOperationNextHandler
+      );
+
+      // TODO: Do we want to make the interceptor async like we do for child workflow? That seems redundant.
+      // REVIEW: I ended up changing this so that the interceptor returns a Promise<StartNexusOperationOutput>,
+      //         and the result promise is contained in that Output object. As a consequence of this,
+      //         the result promise/completion does not exist until the StartNexusOperation event is received.
+      //         That's totally different from what we did in ChildWorkflow, but I think that's cleaner from
+      //         interceptors point of view, and will make it easier to extend the API in the future.
+      const { token, result: resultPromise } = await execute({
+        endpoint: options.endpoint,
+        service: options.service.name,
+        operation: opName,
+        options: operationOptions ?? {},
+        headers: {},
+        seq,
+        input,
+      });
+
+      return {
+        service: options.service.name,
+        operation: opName,
+        token,
+        async result(): Promise<nexus.OperationOutput<O>> {
+          return resultPromise as nexus.OperationOutput<O>;
+        },
+      };
+    }
+  }
+
+  return new NexusClientImpl<T>();
+}
+
+function startNexusOperationNextHandler({
+  input,
+  endpoint,
+  service,
+  options,
+  operation,
+  seq,
+  headers,
+}: StartNexusOperationInput): Promise<StartNexusOperationOutput> {
+  const activator = getActivator();
+
+  return new Promise<StartNexusOperationOutput>((resolve, reject) => {
+    const scope = CancellationScope.current();
+    if (scope.consideredCancelled) {
+      untrackPromise(scope.cancelRequested.catch(reject));
+      return;
+    }
+    if (scope.cancellable) {
+      untrackPromise(
+        scope.cancelRequested.catch(() => {
+          const completed =
+            !activator.completions.nexusOperationStart.has(seq) &&
+            !activator.completions.nexusOperationComplete.has(seq);
+
+          if (!completed) {
+            activator.pushCommand({
+              requestCancelNexusOperation: { seq },
+            });
+          }
+
+          // Nothing to cancel otherwise
+        })
+      );
+    }
+
+    activator.pushCommand({
+      scheduleNexusOperation: {
+        seq,
+        endpoint,
+        service,
+        operation,
+        nexusHeader: headers,
+        input: activator.payloadConverter.toPayload(input),
+        scheduleToCloseTimeout: msOptionalToTs(options?.scheduleToCloseTimeout),
+        // FIXME(nexus-post-initial-release): cancellationType is not supported yet
+      },
+      userMetadata: userMetadataToPayload(activator.payloadConverter, options?.summary, undefined),
+    });
+
+    activator.completions.nexusOperationStart.set(seq, {
+      resolve,
+      reject,
+    });
+  });
+}

package/src/workflow.ts

@@ -523,8 +523,7 @@ export type ActivityFunctionWithOptions<T extends ActivityFunction> = T & {
    * @param args: list of arguments
    * @returns return value of the activity
    *
-   * @experimental executeWithOptions is a new method to provide call-site options
-   * and is subject to change
+   * @experimental executeWithOptions is a new method to provide call-site options and is subject to change
    */
   executeWithOptions(options: ActivityOptions, args: Parameters<T>): Promise<Awaited<ReturnType<T>>>;
 };
@@ -545,8 +544,7 @@ export type LocalActivityFunctionWithOptions<T extends ActivityFunction> = T & {
    * @param args: list of arguments
    * @returns return value of the activity
    *
-   * @experimental executeWithOptions is a new method to provide call-site options
-   * and is subject to change
+   * @experimental executeWithOptions is a new method to provide call-site options and is subject to change
    */
   executeWithOptions(options: LocalActivityOptions, args: Parameters<T>): Promise<Awaited<ReturnType<T>>>;
 };