@temporalio/workflow 1.14.2-canary-release-testing.0 → 1.16.0

package/src/interfaces.ts

@@ -14,6 +14,8 @@ import {
   Priority,
   WorkerDeploymentVersion,
   VersioningBehavior,
+  InitialVersioningBehavior,
+  SuggestContinueAsNewReason,
 } from '@temporalio/common';
 import { SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
 import { makeProtoEnumConverters } from '@temporalio/common/lib/internal-workflow/enums-helpers';
@@ -45,7 +47,7 @@ export interface WorkflowInfo {
    * This value may change during the lifetime of an Execution.
    * @deprecated Use {@link typedSearchAttributes} instead.
    */
-  readonly searchAttributes: SearchAttributes; // eslint-disable-line deprecation/deprecation
+  readonly searchAttributes: SearchAttributes; // eslint-disable-line @typescript-eslint/no-deprecated
 
   /**
    * Indexed information attached to the Workflow Execution, exposed through an interface.
@@ -122,6 +124,24 @@ export interface WorkflowInfo {
    */
   readonly continueAsNewSuggested: boolean;
 
+  /**
+   * Whether the workflow's Target Worker Deployment Version has changed from its Pinned Version.
+   * When true, the workflow should consider continuing-as-new with
+   * `initialVersioningBehavior: 'AUTO_UPGRADE'` to move to the new version.
+   *
+   * This value changes during the lifetime of an Execution.
+   *
+   * @experimental Upgrade-on-Continue-as-New is experimental and may change.
+   */
+  readonly targetWorkerDeploymentVersionChanged: boolean;
+
+  /**
+   * Reason(s) why continue as new is suggested. Can potentially be multiple reasons.
+   *
+   * @experimental May be removed or changed in the future.
+   */
+  readonly suggestedContinueAsNewReasons?: SuggestContinueAsNewReason[];
+
   /**
    * Task queue this Workflow is executing on
    */
@@ -208,8 +228,6 @@ export interface WorkflowInfo {
    * executing this task for the first time and has a Deployment Version set, then its ID will be
    * used. This value may change over the lifetime of the workflow run, but is deterministic and
    * safe to use for branching.
-   *
-   * @experimental Deployment based versioning is experimental and may change in the future.
    */
   readonly currentDeploymentVersion?: WorkerDeploymentVersion;
 
@@ -235,7 +253,22 @@ export interface UnsafeWorkflowInfo {
    */
   readonly now: () => number;
 
+  /**
+   * Whether the workflow is currently replaying.
+   */
   readonly isReplaying: boolean;
+
+  /**
+   * Whether the workflow is currently replaying history events.
+   *
+   * This is similar to {@link isReplaying}, but returns `false` during query handlers and update
+   * validators, which are live read-only operations that should not be considered as replaying
+   * history events.
+   *
+   * When this property is true, workflow log messages are suppressed and sinks defined with
+   * callDuringReplay=false won't get processed.
+   */
+  readonly isReplayingHistoryEvents: boolean;
 }
 
 /**
@@ -304,7 +337,7 @@ export interface ContinueAsNewOptions {
    * Searchable attributes to attach to next Workflow run
    * @deprecated Use {@link typedSearchAttributes} instead.
    */
-  searchAttributes?: SearchAttributes; // eslint-disable-line deprecation/deprecation
+  searchAttributes?: SearchAttributes; // eslint-disable-line @typescript-eslint/no-deprecated
   /**
    * Specifies additional indexed information to attach to the Workflow Execution. More info:
    * https://docs.temporal.io/docs/typescript/search-attributes
@@ -322,48 +355,80 @@ export interface ContinueAsNewOptions {
    *
    * @default 'COMPATIBLE'
    *
-   * @deprecated In favor of the new Worker Deployment API.
-   * @experimental The Worker Versioning API is still being designed. Major changes are expected.
+   * @deprecated Worker Versioning is now deprecated. Please use the Worker Deployment API instead: https://docs.temporal.io/worker-deployments
    */
-  versioningIntent?: VersioningIntent; // eslint-disable-line deprecation/deprecation
+  versioningIntent?: VersioningIntent; // eslint-disable-line @typescript-eslint/no-deprecated
+  /**
+   * Defines the versioning behavior to be used by the first task of a new workflow run in a continue-as-new chain.
+   *
+   * @experimental Versioning semantics with continue-as-new are experimental and may change in the future.
+   */
+  initialVersioningBehavior?: InitialVersioningBehavior;
 }
 
 /**
- * Specifies:
- * - whether cancellation requests are sent to the Child
- * - whether and when a {@link CanceledFailure} is thrown from {@link executeChild} or
- *   {@link ChildWorkflowHandle.result}
+ * Determines:
+ * - whether cancellation requests should be propagated from the Parent Workflow to the Child, and
+ * - whether and when should the Child's cancellation be reported back to the Parent Workflow
+ *   (i.e. at which moment should the {@link executeChild}'s or {@link ChildWorkflowHandle.result}'s
+ *   promise fail with a `ChildWorkflowFailure`, with `cause` set to a `CancelledFailure`).
+ *
+ * Note that this setting only applies to cancellation originating from an external request for the
+ * Parent Workflow itself, or from internal cancellation of the `CancellationScope` in which the
+ * Child Workflow call was made. Eventual Cancellation of a Child Workflow on completion of the
+ * Parent Workflow is controlled by the {@link ParentClosePolicy} setting.
  *
- * @default {@link ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED}
+ * @default ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED
  */
-export type ChildWorkflowCancellationType =
-  (typeof ChildWorkflowCancellationType)[keyof typeof ChildWorkflowCancellationType];
+// MAINTENANCE: Keep this typedoc in sync with the `ChildWorkflowOptions.cancellationType` field
 export const ChildWorkflowCancellationType = {
   /**
-   * Don't send a cancellation request to the Child.
+   * Do not propagate cancellation requests to the Child, and immediately report cancellation
+   * to the caller.
    */
   ABANDON: 'ABANDON',
 
   /**
-   * Send a cancellation request to the Child. Immediately throw the error.
+   * Propagate cancellation request from the Parent Workflow to the Child, yet _immediately_ report
+   * cancellation to the caller, i.e. without waiting for the server to confirm the cancellation
+   * request.
+   *
+   * Note that this cancellation type provides no guarantee, from the Parent-side, that the
+   * cancellation request will actually be atomically added to the Child workflow's history.
+   * In particular, the Child may complete (either successfully or uncessfully) before the
+   * cancellation is delivered, resulting in a situation where the Parent workflow thinks its child
+   * was cancelled, but the child actually completed successfully.
+   *
+   * To guarantee that the Child will eventually be notified of the cancellation request,
+   * use {@link WAIT_CANCELLATION_REQUESTED}.
    */
   TRY_CANCEL: 'TRY_CANCEL',
 
   /**
-   * Send a cancellation request to the Child. The Child may respect cancellation, in which case an error will be thrown
-   * when cancellation has completed, and {@link isCancellation}(error) will be true. On the other hand, the Child may
-   * ignore the cancellation request, in which case an error might be thrown with a different cause, or the Child may
-   * complete successfully.
+   * Propagate cancellation request from the Parent Workflow to the Child, then wait for the server
+   * to confirm that the Child Workflow cancellation request was recorded in its history.
    *
-   * @default
+   * This cancellation type guarantees that the Child will eventually be notified of the
+   * cancellation request (that is, unless the Child terminates inbetween due to unexpected causes).
    */
-  WAIT_CANCELLATION_COMPLETED: 'WAIT_CANCELLATION_COMPLETED',
+  WAIT_CANCELLATION_REQUESTED: 'WAIT_CANCELLATION_REQUESTED',
 
   /**
-   * Send a cancellation request to the Child. Throw the error once the Server receives the Child cancellation request.
+   * Propagate cancellation request from the Parent Workflow to the Child, then wait for completion
+   * of the Child Workflow.
+   *
+   * The Child may respect cancellation, in which case the Parent's `executeChild` or
+   * `ChildWorkflowHandle.result` promise will fail with a `ChildWorkflowFailure`, with `cause`
+   * set to a `CancelledFailure`. On the other hand, the Child may ignore the cancellation request,
+   * in which case the corresponding promise will either resolve with a result (if Child completed
+   * successfully) or reject with a different cause (if Child completed uncessfully).
+   *
+   * @default
    */
-  WAIT_CANCELLATION_REQUESTED: 'WAIT_CANCELLATION_REQUESTED',
+  WAIT_CANCELLATION_COMPLETED: 'WAIT_CANCELLATION_COMPLETED',
 } as const;
+export type ChildWorkflowCancellationType =
+  (typeof ChildWorkflowCancellationType)[keyof typeof ChildWorkflowCancellationType];
 
 // ts-prune-ignore-next
 export const [encodeChildWorkflowCancellationType, decodeChildWorkflowCancellationType] = makeProtoEnumConverters<
@@ -387,7 +452,6 @@ export const [encodeChildWorkflowCancellationType, decodeChildWorkflowCancellati
  *
  * @see {@link https://docs.temporal.io/concepts/what-is-a-parent-close-policy/ | Parent Close Policy}
  */
-export type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
 export const ParentClosePolicy = {
   /**
    * When the Parent is Closed, the Child is Terminated.
@@ -413,29 +477,30 @@ export const ParentClosePolicy = {
    *
    * @deprecated Either leave property `undefined`, or set an explicit policy instead.
    */
-  PARENT_CLOSE_POLICY_UNSPECIFIED: undefined, // eslint-disable-line deprecation/deprecation
+  PARENT_CLOSE_POLICY_UNSPECIFIED: undefined,
 
   /**
    * When the Parent is Closed, the Child is Terminated.
    *
    * @deprecated Use {@link ParentClosePolicy.TERMINATE} instead.
    */
-  PARENT_CLOSE_POLICY_TERMINATE: 'TERMINATE', // eslint-disable-line deprecation/deprecation
+  PARENT_CLOSE_POLICY_TERMINATE: 'TERMINATE',
 
   /**
    * When the Parent is Closed, nothing is done to the Child.
    *
    * @deprecated Use {@link ParentClosePolicy.ABANDON} instead.
    */
-  PARENT_CLOSE_POLICY_ABANDON: 'ABANDON', // eslint-disable-line deprecation/deprecation
+  PARENT_CLOSE_POLICY_ABANDON: 'ABANDON',
 
   /**
    * When the Parent is Closed, the Child is Cancelled.
    *
    * @deprecated Use {@link ParentClosePolicy.REQUEST_CANCEL} instead.
    */
-  PARENT_CLOSE_POLICY_REQUEST_CANCEL: 'REQUEST_CANCEL', // eslint-disable-line deprecation/deprecation
+  PARENT_CLOSE_POLICY_REQUEST_CANCEL: 'REQUEST_CANCEL',
 } as const;
+export type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
 
 // ts-prune-ignore-next
 export const [encodeParentClosePolicy, decodeParentClosePolicy] = makeProtoEnumConverters<
@@ -471,19 +536,26 @@ export interface ChildWorkflowOptions extends Omit<CommonWorkflowOptions, 'workf
   taskQueue?: string;
 
   /**
-   * Specifies:
-   * - whether cancellation requests are sent to the Child
-   * - whether and when an error is thrown from {@link executeChild} or
-   *   {@link ChildWorkflowHandle.result}
+   * Determines:
+   * - whether cancellation requests should be propagated from the Parent Workflow to the Child, and
+   * - whether and when should the Child's cancellation be reported back to the Parent Workflow
+   *   (i.e. at which moment should the {@link executeChild}'s or {@link ChildWorkflowHandle.result}'s
+   *   promise fail with a `ChildWorkflowFailure`, with `cause` set to a `CancelledFailure`).
+   *
+   * Note that this setting only applies to cancellation originating from an external request for the
+   * Parent Workflow itself, or from internal cancellation of the `CancellationScope` in which the
+   * Child Workflow call was made. Eventual Cancellation of a Child Workflow on completion of the
+   * Parent Workflow is controlled by the {@link ParentClosePolicy} setting.
    *
-   * @default {@link ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED}
+   * @default ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED
    */
+  // MAINTENANCE: Keep this typedoc in sync with the `ChildWorkflowCancellationType` enum
   cancellationType?: ChildWorkflowCancellationType;
 
   /**
    * Specifies how the Child reacts to the Parent Workflow reaching a Closed state.
    *
-   * @default {@link ParentClosePolicy.PARENT_CLOSE_POLICY_TERMINATE}
+   * @default ParentClosePolicy.PARENT_CLOSE_POLICY_TERMINATE
    */
   parentClosePolicy?: ParentClosePolicy;
 
@@ -493,10 +565,9 @@ export interface ChildWorkflowOptions extends Omit<CommonWorkflowOptions, 'workf
    *
    * @default 'COMPATIBLE'
    *
-   * @deprecated In favor of the new Worker Deployment API.
-   * @experimental The Worker Versioning API is still being designed. Major changes are expected.
+   * @deprecated Worker Versioning is now deprecated. Please use the Worker Deployment API instead: https://docs.temporal.io/worker-deployments
    */
-  versioningIntent?: VersioningIntent; // eslint-disable-line deprecation/deprecation
+  versioningIntent?: VersioningIntent; // eslint-disable-line @typescript-eslint/no-deprecated
 }
 
 export type RequiredChildWorkflowOptions = Required<Pick<ChildWorkflowOptions, 'workflowId' | 'cancellationType'>> & {
@@ -581,6 +652,7 @@ export interface WorkflowCreateOptionsInternal extends WorkflowCreateOptions {
   sourceMap: RawSourceMap;
   registeredActivityNames: Set<string>;
   getTimeOfDay(): bigint;
+  stackTracesEnabled: boolean;
 }
 
 /**

package/src/internals.ts

@@ -457,6 +457,8 @@ export class Activator implements ActivationHandler {
 
   public readonly workflowSandboxDestructors: (() => void)[] = [];
 
+  protected readonly stackTracesEnabled: boolean;
+
   constructor({
     info,
     now,
@@ -465,6 +467,7 @@ export class Activator implements ActivationHandler {
     getTimeOfDay,
     randomnessSeed,
     registeredActivityNames,
+    stackTracesEnabled,
   }: WorkflowCreateOptionsInternal) {
     this.getTimeOfDay = getTimeOfDay;
     this.info = info;
@@ -473,6 +476,7 @@ export class Activator implements ActivationHandler {
     this.sourceMap = sourceMap;
     this.random = alea(randomnessSeed);
     this.registeredActivityNames = registeredActivityNames;
+    this.stackTracesEnabled = stackTracesEnabled;
   }
 
   /**
@@ -483,6 +487,9 @@ export class Activator implements ActivationHandler {
   }
 
   protected getStackTraces(): Stack[] {
+    if (!this.stackTracesEnabled) {
+      throw new IllegalStateError('Workflow stack traces are not enabled on this worker');
+    }
     const { childToParent, promiseToStack } = this.promiseStackStore;
     const internalNodes = [...childToParent.values()].reduce((acc, curr) => {
       for (const p of curr) {
@@ -858,12 +865,26 @@ export class Activator implements ActivationHandler {
       let input: UpdateInput;
       try {
         if (runValidator && entry.validator) {
-          const validate = composeInterceptors(
-            interceptors,
-            'validateUpdate',
-            this.validateUpdateNextHandler.bind(this, entry.validator)
-          );
-          validate(makeInput());
+          // Temporarily mark as not replaying history events during validator execution
+          // so that logging is permitted. Validators are live read-only operations.
+          const wasReplayingHistoryEvents = this.info.unsafe.isReplayingHistoryEvents;
+          this.mutateWorkflowInfo((info) => ({
+            ...info,
+            unsafe: { ...info.unsafe, isReplayingHistoryEvents: false },
+          }));
+          try {
+            const validate = composeInterceptors(
+              interceptors,
+              'validateUpdate',
+              this.validateUpdateNextHandler.bind(this, entry.validator)
+            );
+            validate(makeInput());
+          } finally {
+            this.mutateWorkflowInfo((info) => ({
+              ...info,
+              unsafe: { ...info.unsafe, isReplayingHistoryEvents: wasReplayingHistoryEvents },
+            }));
+          }
         }
         input = makeInput();
       } catch (error) {
@@ -930,7 +951,6 @@ export class Activator implements ActivationHandler {
       const update = this.bufferedUpdates.shift();
       if (update) {
         this.rejectUpdate(
-          /* eslint-disable @typescript-eslint/no-non-null-assertion */
           update.protocolInstanceId!,
           ApplicationFailure.nonRetryable(`No registered handler for update: ${update.name}`)
         );
@@ -997,7 +1017,7 @@ export class Activator implements ActivationHandler {
     while (bufferedSignals.length) {
       if (this.defaultSignalHandler) {
         // We have a default signal handler, so all signals are dispatchable
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+
         this.signalWorkflow(bufferedSignals.shift()!);
       } else {
         const foundIndex = bufferedSignals.findIndex((signal) => this.signalHandlers.has(signal.signalName as string));

package/src/metrics.ts

@@ -48,6 +48,9 @@ class WorkflowMetricMeterImpl implements MetricMeter {
 }
 
 class WorkflowMetricCounter implements MetricCounter {
+  public readonly kind = 'counter';
+  public readonly valueType = 'int';
+
   constructor(
     public readonly name: string,
     public readonly unit: string | undefined,
@@ -70,6 +73,8 @@ class WorkflowMetricCounter implements MetricCounter {
 }
 
 class WorkflowMetricHistogram implements MetricHistogram {
+  public readonly kind = 'histogram';
+
   constructor(
     public readonly name: string,
     public readonly valueType: NumericMetricValueType,
@@ -93,6 +98,8 @@ class WorkflowMetricHistogram implements MetricHistogram {
 }
 
 class WorkflowMetricGauge implements MetricGauge {
+  public readonly kind = 'gauge';
+
   constructor(
     public readonly name: string,
     public readonly valueType: NumericMetricValueType,

package/src/nexus.ts

@@ -2,6 +2,8 @@ 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 { makeProtoEnumConverters } from '@temporalio/common/lib/internal-workflow/enums-helpers';
+import type { coresdk } from '@temporalio/proto';
 import { CancellationScope } from './cancellation-scope';
 import { getActivator } from './global-attributes';
 import { untrackPromise } from './stack-helpers';
@@ -12,7 +14,7 @@ import { StartNexusOperationInput, StartNexusOperationOutput, StartNexusOperatio
  *
  * @experimental Nexus support in Temporal SDK is experimental.
  */
-export interface NexusClient<T extends nexus.ServiceDefinition> {
+export interface NexusServiceClient<T extends nexus.ServiceDefinition> {
   /**
    * Start a Nexus Operation and wait for its completion taking a {@link nexus.operation}.
    * Returns the operation's result.
@@ -102,9 +104,9 @@ export interface NexusOperationHandle<T> {
 }
 
 /**
- * Options for {@link createNexusClient}.
+ * Options for {@link createNexusServiceClient}.
  */
-export interface NexusClientOptions<T> {
+export interface NexusServiceClientOptions<T> {
   endpoint: string;
   service: T;
 }
@@ -114,8 +116,10 @@ export interface NexusClientOptions<T> {
  *
  * @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> {
+export function createNexusServiceClient<T extends nexus.ServiceDefinition>(
+  options: NexusServiceClientOptions<T>
+): NexusServiceClient<T> {
+  class NexusServiceClientImpl<T extends nexus.ServiceDefinition> implements NexusServiceClient<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']>]>,
@@ -146,17 +150,18 @@ export function createNexusClient<T extends nexus.ServiceDefinition>(options: Ne
         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.
+      // The interceptor returns a Promise<StartNexusOperationOutput>, with the result promise contained
+      // in that Output object. As a consequence of this, the result promise/completion does not exist
+      // until the StartNexusOperation event is received. This is totally different from what we did in
+      // ChildWorkflow, but is much cleaner from the interceptors point of view.
       const { token, result: resultPromise } = await execute({
         endpoint: options.endpoint,
         service: options.service.name,
         operation: opName,
-        options: operationOptions ?? {},
+        options: {
+          ...operationOptions,
+          cancellationType: operationOptions?.cancellationType ?? 'WAIT_CANCELLATION_COMPLETED',
+        },
         headers: {},
         seq,
         input,
@@ -173,7 +178,7 @@ export function createNexusClient<T extends nexus.ServiceDefinition>(options: Ne
     }
   }
 
-  return new NexusClientImpl<T>();
+  return new NexusServiceClientImpl<T>();
 }
 
 function startNexusOperationNextHandler({
@@ -220,7 +225,9 @@ function startNexusOperationNextHandler({
         nexusHeader: headers,
         input: activator.payloadConverter.toPayload(input),
         scheduleToCloseTimeout: msOptionalToTs(options?.scheduleToCloseTimeout),
-        // FIXME(nexus-post-initial-release): cancellationType is not supported yet
+        scheduleToStartTimeout: msOptionalToTs(options?.scheduleToStartTimeout),
+        startToCloseTimeout: msOptionalToTs(options?.startToCloseTimeout),
+        cancellationType: encodeNexusOperationCancellationType(options?.cancellationType),
       },
       userMetadata: userMetadataToPayload(activator.payloadConverter, options?.summary, undefined),
     });
@@ -231,3 +238,76 @@ function startNexusOperationNextHandler({
     });
   });
 }
+
+/**
+ * Determines:
+ * - whether cancellation requests should be propagated from the Workflow to the Nexus Operation
+ * - whether and when should the Operation's cancellation be reported back to the Workflow
+ *   (i.e. at which moment should the operation's result promise fail with a `NexusOperationFailure`,
+ *   with `cause` set to a `CancelledFailure`).
+ *
+ * Note that this setting only applies to cancellation originating from an external request for the
+ * Workflow itself, or from internal cancellation of the `CancellationScope` in which the
+ * Operation call was made.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+// MAINTENANCE: Keep this typedoc in sync with the `StartNexusOperationOptions.cancellationType` field
+export const NexusOperationCancellationType = {
+  /**
+   * Do not propagate cancellation requests to the Nexus Operation, and immediately report
+   * cancellation to the caller.
+   */
+  ABANDON: 'ABANDON',
+
+  /**
+   * Initiate a cancellation request for the Nexus operation and immediately report cancellation to
+   * the caller. Note that it doesn't guarantee that cancellation is delivered to the operation if
+   * calling workflow exits before the delivery is done. If you want to ensure that cancellation is
+   * delivered to the operation, use {@link WAIT_CANCELLATION_REQUESTED}.
+   *
+   * Propagate cancellation request from the Workflow to the Operation, yet _immediately_ report
+   * cancellation to the caller, i.e. without waiting for the server to confirm the cancellation
+   * request.
+   *
+   * Note that this cancellation type provides no guarantee, from the Workflow-side, that the
+   * cancellation request will be delivered to the Operation Handler. In particular, either the
+   * Operation or the Workflow may complete (either successfully or uncessfully) before the
+   * cancellation request is delivered, resulting in a situation where the Operation completed
+   * successfully, but the Workflow thinks it was cancelled.
+   *
+   * To guarantee that the Operation will eventually be notified of the cancellation request,
+   * use {@link WAIT_CANCELLATION_REQUESTED}.
+   */
+  TRY_CANCEL: 'TRY_CANCEL',
+
+  /**
+   * Propagate cancellation request from the Workflow to the Operation, then wait for the server
+   * to confirm that the Operation cancellation request was delivered to the Operation Handler.
+   */
+  WAIT_CANCELLATION_REQUESTED: 'WAIT_CANCELLATION_REQUESTED',
+
+  /**
+   * Propagate cancellation request from the Workflow to the Operation, then wait for completion
+   * of the Operation.
+   */
+  WAIT_CANCELLATION_COMPLETED: 'WAIT_CANCELLATION_COMPLETED',
+} as const;
+export type NexusOperationCancellationType =
+  (typeof NexusOperationCancellationType)[keyof typeof NexusOperationCancellationType];
+
+const [encodeNexusOperationCancellationType, _] = makeProtoEnumConverters<
+  coresdk.nexus.NexusOperationCancellationType,
+  typeof coresdk.nexus.NexusOperationCancellationType,
+  keyof typeof coresdk.nexus.NexusOperationCancellationType,
+  typeof NexusOperationCancellationType,
+  ''
+>(
+  {
+    [NexusOperationCancellationType.WAIT_CANCELLATION_COMPLETED]: 0,
+    [NexusOperationCancellationType.ABANDON]: 1,
+    [NexusOperationCancellationType.TRY_CANCEL]: 2,
+    [NexusOperationCancellationType.WAIT_CANCELLATION_REQUESTED]: 3,
+  } as const,
+  ''
+);

package/src/trigger.ts

@@ -10,8 +10,23 @@ import { untrackPromise } from './stack-helpers';
  * Useful for e.g. waiting for unblocking a Workflow from a Signal.
  *
  * @example
- * <!--SNIPSTART typescript-trigger-workflow-->
- * <!--SNIPEND-->
+ * ```ts
+ * import { defineSignal, setHandler, sleep, Trigger } from '@temporalio/workflow';
+ *
+ * const completeUserInteraction = defineSignal('completeUserInteraction');
+ *
+ * export async function waitOnUser(userId: string): Promise<void> {
+ *   const userInteraction = new Trigger<boolean>();
+ *
+ *   // programmatically resolve Trigger
+ *   setHandler(completeUserInteraction, () => userInteraction.resolve(true));
+ *
+ *   const userInteracted = await Promise.race([userInteraction, sleep('30 days')]);
+ *   if (!userInteracted) {
+ *     await sendReminderEmail(userId);
+ *   }
+ * }
+ * ```
  */
 export class Trigger<T> implements PromiseLike<T> {
   // Typescript does not realize that the promise executor is run synchronously in the constructor