@temporalio/workflow 1.12.2 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/workflow",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "Temporal.io SDK Workflow sub-package",
   "keywords": [
     "temporal",
@@ -22,8 +22,9 @@
   "types": "lib/index.d.ts",
   "scripts": {},
   "dependencies": {
-    "@temporalio/common": "1.12.2",
-    "@temporalio/proto": "1.12.2"
+    "@temporalio/common": "1.13.0",
+    "@temporalio/proto": "1.13.0",
+    "nexus-rpc": "^0.0.1"
   },
   "devDependencies": {
     "source-map": "^0.7.4"
@@ -38,5 +39,5 @@
     "src",
     "lib"
   ],
-  "gitHead": "98393e00b714b8d44a3dc25714d313d3366f4c50"
+  "gitHead": "cf7c1e7d70f0c775f1382fd335b8bd721495f8cc"
 }

package/src/errors.ts

@@ -1,4 +1,4 @@
-import { ActivityFailure, CancelledFailure, ChildWorkflowFailure } from '@temporalio/common';
+import { ActivityFailure, CancelledFailure, ChildWorkflowFailure, NexusOperationFailure } from '@temporalio/common';
 import { SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
 import { coresdk } from '@temporalio/proto';
 
@@ -30,6 +30,7 @@ export class LocalActivityDoBackoff extends Error {
 export function isCancellation(err: unknown): boolean {
   return (
     err instanceof CancelledFailure ||
-    ((err instanceof ActivityFailure || err instanceof ChildWorkflowFailure) && err.cause instanceof CancelledFailure)
+    ((err instanceof ActivityFailure || err instanceof ChildWorkflowFailure || err instanceof NexusOperationFailure) &&
+      err.cause instanceof CancelledFailure)
   );
 }

package/src/index.ts

@@ -109,7 +109,11 @@ export * from './workflow';
 export { ChildWorkflowHandle, ExternalWorkflowHandle } from './workflow-handle';
 export { metricMeter } from './metrics';
 
-// Anything below this line is deprecated
+export { createNexusClient, NexusClientOptions, NexusClient, NexusOperationHandle } from './nexus';
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Deprecated APIs
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
 export {
   /**

package/src/interceptors.ts

@@ -1,13 +1,12 @@
 /**
- * Type definitions and generic helpers for interceptors.
- *
- * The Workflow specific interceptors are defined here.
+ * Type definitions for Workflow interceptors.
  *
  * @module
  */
 
 import {
   ActivityOptions,
+  Duration,
   Headers,
   LocalActivityOptions,
   MetricTags,
@@ -20,14 +19,83 @@ import { ChildWorkflowOptionsWithDefaults, ContinueAsNewOptions } from './interf
 
 export { Next, Headers };
 
-/** Input for WorkflowInboundCallsInterceptor.execute */
+/**
+ * A function that instantiates {@link WorkflowInterceptors}.
+ *
+ * Workflow interceptor modules should export an `interceptors` function of this type.
+ *
+ * @example
+ *
+ * ```ts
+ * export function interceptors(): WorkflowInterceptors {
+ *   return {
+ *     inbound: [],   // Populate with list of inbound interceptor implementations
+ *     outbound: [],  // Populate with list of outbound interceptor implementations
+ *     internals: [], // Populate with list of internals interceptor implementations
+ *   };
+ * }
+ * ```
+ */
+export type WorkflowInterceptorsFactory = () => WorkflowInterceptors;
+
+/**
+ * A mapping from interceptor type to an optional list of interceptor implementations
+ */
+export interface WorkflowInterceptors {
+  inbound?: WorkflowInboundCallsInterceptor[];
+  outbound?: WorkflowOutboundCallsInterceptor[];
+  internals?: WorkflowInternalsInterceptor[];
+}
+
+// Workflow Inbound Calls Interceptors /////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Implement any of these methods to intercept Workflow inbound calls like execution, and signal and query handling.
+ */
+export interface WorkflowInboundCallsInterceptor {
+  /**
+   * Called when Workflow execute method is called
+   *
+   * @return result of the Workflow execution
+   */
+  execute?: (input: WorkflowExecuteInput, next: Next<WorkflowInboundCallsInterceptor, 'execute'>) => Promise<unknown>;
+
+  /**
+   * Called when Update handler is called
+   *
+   * @return result of the Update
+   */
+  handleUpdate?: (input: UpdateInput, next: Next<WorkflowInboundCallsInterceptor, 'handleUpdate'>) => Promise<unknown>;
+
+  /**
+   * Called when update validator called
+   */
+  validateUpdate?: (input: UpdateInput, next: Next<WorkflowInboundCallsInterceptor, 'validateUpdate'>) => void;
+
+  /**
+   * Called when signal is delivered to a Workflow execution
+   */
+  handleSignal?: (input: SignalInput, next: Next<WorkflowInboundCallsInterceptor, 'handleSignal'>) => Promise<void>;
+
+  /**
+   * Called when a Workflow is queried
+   *
+   * @return result of the query
+   */
+  handleQuery?: (input: QueryInput, next: Next<WorkflowInboundCallsInterceptor, 'handleQuery'>) => Promise<unknown>;
+}
+
+/**
+ * Input for {@link WorkflowInboundCallsInterceptor.execute}.
+ */
 export interface WorkflowExecuteInput {
   readonly args: unknown[];
   readonly headers: Headers;
 }
 
-/** Input for WorkflowInboundCallsInterceptor.handleUpdate and
- * WorkflowInboundCallsInterceptor.validateUpdate */
+/**
+ * Input for {@link WorkflowInboundCallsInterceptor.handleUpdate} and {@link WorkflowInboundCallsInterceptor.validateUpdate}.
+ */
 export interface UpdateInput {
   readonly updateId: string;
   readonly name: string;
@@ -35,14 +103,18 @@ export interface UpdateInput {
   readonly headers: Headers;
 }
 
-/** Input for WorkflowInboundCallsInterceptor.handleSignal */
+/**
+ * Input for {@link WorkflowInboundCallsInterceptor.handleSignal}.
+ */
 export interface SignalInput {
   readonly signalName: string;
   readonly args: unknown[];
   readonly headers: Headers;
 }
 
-/** Input for WorkflowInboundCallsInterceptor.handleQuery */
+/**
+ * Input for {@link WorkflowInboundCallsInterceptor.handleQuery}.
+ */
 export interface QueryInput {
   readonly queryId: string;
   readonly queryName: string;
@@ -50,38 +122,123 @@ export interface QueryInput {
   readonly headers: Headers;
 }
 
+// Workflow Outbound Calls Interceptors /////////////////////////////////////////////////////////////////////////////////
+
 /**
- * Implement any of these methods to intercept Workflow inbound calls like execution, and signal and query handling.
+ * Implement any of these methods to intercept Workflow code calls to the Temporal APIs, like scheduling an activity
+ * and starting a timer.
  */
-export interface WorkflowInboundCallsInterceptor {
+export interface WorkflowOutboundCallsInterceptor {
   /**
-   * Called when Workflow execute method is called
+   * Called when Workflow starts a timer.
+   */
+  startTimer?: (input: TimerInput, next: Next<WorkflowOutboundCallsInterceptor, 'startTimer'>) => Promise<void>;
+
+  /**
+   * Called when Workflow schedules an Activity.
    *
-   * @return result of the Workflow execution
+   * @return result of the activity execution
    */
-  execute?: (input: WorkflowExecuteInput, next: Next<this, 'execute'>) => Promise<unknown>;
+  scheduleActivity?: (
+    input: ActivityInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'scheduleActivity'>
+  ) => Promise<unknown>;
 
-  /** Called when Update handler is called
+  /**
+   * Called when Workflow schedules a local Activity.
    *
-   * @return result of the Update
+   * @return result of the activity execution
    */
-  handleUpdate?: (input: UpdateInput, next: Next<this, 'handleUpdate'>) => Promise<unknown>;
+  scheduleLocalActivity?: (
+    input: LocalActivityInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'scheduleLocalActivity'>
+  ) => Promise<unknown>;
 
-  /** Called when update validator called */
-  validateUpdate?: (input: UpdateInput, next: Next<this, 'validateUpdate'>) => void;
+  /**
+   * Called when Workflow starts a Nexus Operation.
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  startNexusOperation?: (
+    input: StartNexusOperationInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'startNexusOperation'>
+  ) => Promise<StartNexusOperationOutput>;
 
-  /** Called when signal is delivered to a Workflow execution */
-  handleSignal?: (input: SignalInput, next: Next<this, 'handleSignal'>) => Promise<void>;
+  /**
+   * Called when Workflow starts a child workflow execution.
+   *
+   * The interceptor function returns 2 promises:
+   * - The first resolves with the `runId` when the child workflow has started or rejects if failed to start.
+   * - The second resolves with the workflow result when the child workflow completes or rejects on failure.
+   */
+  startChildWorkflowExecution?: (
+    input: StartChildWorkflowExecutionInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'startChildWorkflowExecution'>
+  ) => Promise<[Promise<string>, Promise<unknown>]>;
 
   /**
-   * Called when a Workflow is queried
+   * Called when Workflow signals a child or external Workflow.
+   */
+  signalWorkflow?: (
+    input: SignalWorkflowInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'signalWorkflow'>
+  ) => Promise<void>;
+
+  /**
+   * Called when Workflow calls continueAsNew.
+   */
+  continueAsNew?: (
+    input: ContinueAsNewInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'continueAsNew'>
+  ) => Promise<never>;
+
+  /**
+   * Called on each invocation of the `workflow.log` methods.
    *
-   * @return result of the query
+   * The attributes returned in this call are attached to every log message.
    */
-  handleQuery?: (input: QueryInput, next: Next<this, 'handleQuery'>) => Promise<unknown>;
+  getLogAttributes?: (
+    input: GetLogAttributesInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'getLogAttributes'>
+  ) => Record<string, unknown>;
+
+  /**
+   * Called once every time a metric is emitted from a Workflow metric (ie. a metric created
+   * from {@link workflow.metricMeter}).
+   *
+   * Tags returned by this hook are _prepended_ to tags defined at the metric level and tags
+   * defined on the emitter function itself.
+   */
+  getMetricTags?: (
+    input: GetMetricTagsInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'getMetricTags'>
+  ) => MetricTags;
+}
+
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.startTimer}
+ */
+export interface TimerInput {
+  readonly durationMs: number;
+  readonly seq: number;
+  readonly options?: TimerOptions;
+}
+
+/**
+ * Options for starting a timer (i.e. sleep)
+ */
+export interface TimerOptions {
+  /**
+   * A fixed, single line summary of the command's purpose
+   *
+   * @experimental User metadata is a new API and susceptible to change.
+   */
+  readonly summary?: string;
 }
 
-/** Input for WorkflowOutboundCallsInterceptor.scheduleActivity */
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.scheduleActivity}.
+ */
 export interface ActivityInput {
   readonly activityType: string;
   readonly args: unknown[];
@@ -90,7 +247,9 @@ export interface ActivityInput {
   readonly seq: number;
 }
 
-/** Input for WorkflowOutboundCallsInterceptor.scheduleLocalActivity */
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.scheduleLocalActivity}.
+ */
 export interface LocalActivityInput {
   readonly activityType: string;
   readonly args: unknown[];
@@ -101,40 +260,77 @@ export interface LocalActivityInput {
   readonly attempt: number;
 }
 
-/** Input for WorkflowOutboundCallsInterceptor.startChildWorkflowExecution */
-export interface StartChildWorkflowExecutionInput {
-  readonly workflowType: string;
-  readonly options: ChildWorkflowOptionsWithDefaults;
-  readonly headers: Headers;
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.startNexusOperation}.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface StartNexusOperationInput {
+  readonly input: unknown;
+  readonly endpoint: string;
+  readonly service: string;
+  readonly options: StartNexusOperationOptions;
+  readonly operation: string;
   readonly seq: number;
+  readonly headers: Record<string, string>;
 }
 
-/** Input for WorkflowOutboundCallsInterceptor.startTimer */
-export interface TimerInput {
-  readonly durationMs: number;
-  readonly seq: number;
-  readonly options?: TimerOptions;
-}
+/**
+ * Options for starting a Nexus Operation.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface StartNexusOperationOptions {
+  /**
+   * The end to end timeout for the Nexus Operation.
+   *
+   * Optional: defaults to the maximum allowed by the Temporal server.
+   */
+  readonly scheduleToCloseTimeout?: Duration;
 
-/** Options for starting a timer (i.e. sleep) */
-export interface TimerOptions {
-  /** @experimental A fixed, single line summary of the command's purpose */
+  /**
+   * A fixed, single-line summary for this Nexus Operation that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and susceptible to change.
+   */
   readonly summary?: string;
 }
 
 /**
- * Same as ContinueAsNewOptions but workflowType must be defined
+ * Output for {@link WorkflowOutboundCallsInterceptor.startNexusOperation}.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
  */
-export type ContinueAsNewInputOptions = ContinueAsNewOptions & Required<Pick<ContinueAsNewOptions, 'workflowType'>>;
+export interface StartNexusOperationOutput {
+  /**
+   * The token for the Nexus Operation.
+   *
+   * Undefined if the Nexus Operation completed synchronously, in which case the {@link result}
+   * will be immediately resolved.
+   */
+  readonly token?: string;
 
-/** Input for WorkflowOutboundCallsInterceptor.continueAsNew */
-export interface ContinueAsNewInput {
-  readonly args: unknown[];
+  /**
+   * A promise that will resolve when the Nexus Operation completes, either with the result of the
+   * Operation if it completed successfully, or a failure if the Nexus Operation failed.
+   */
+  readonly result: Promise<unknown>;
+}
+
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.startChildWorkflowExecution}.
+ */
+export interface StartChildWorkflowExecutionInput {
+  readonly workflowType: string;
+  readonly options: ChildWorkflowOptionsWithDefaults;
   readonly headers: Headers;
-  readonly options: ContinueAsNewInputOptions;
+  readonly seq: number;
 }
 
-/** Input for WorkflowOutboundCallsInterceptor.signalWorkflow */
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.signalWorkflow}.
+ */
 export interface SignalWorkflowInput {
   readonly seq: number;
   readonly signalName: string;
@@ -151,90 +347,31 @@ export interface SignalWorkflowInput {
       };
 }
 
-/** Input for WorkflowOutboundCallsInterceptor.getLogAttributes */
-export type GetLogAttributesInput = Record<string, unknown>;
-
-/** Input for WorkflowOutboundCallsInterceptor.getMetricTags */
-export type GetMetricTagsInput = MetricTags;
-
 /**
- * Implement any of these methods to intercept Workflow code calls to the Temporal APIs, like scheduling an activity and starting a timer
+ * Input for {@link WorkflowOutboundCallsInterceptor.continueAsNew}.
  */
-export interface WorkflowOutboundCallsInterceptor {
-  /**
-   * Called when Workflow schedules an Activity
-   *
-   * @return result of the activity execution
-   */
-  scheduleActivity?: (input: ActivityInput, next: Next<this, 'scheduleActivity'>) => Promise<unknown>;
-
-  /**
-   * Called when Workflow schedules a local Activity
-   *
-   * @return result of the activity execution
-   */
-  scheduleLocalActivity?: (input: LocalActivityInput, next: Next<this, 'scheduleLocalActivity'>) => Promise<unknown>;
-
-  /**
-   * Called when Workflow starts a timer
-   */
-  startTimer?: (input: TimerInput, next: Next<this, 'startTimer'>) => Promise<void>;
-
-  /**
-   * Called when Workflow calls continueAsNew
-   */
-  continueAsNew?: (input: ContinueAsNewInput, next: Next<this, 'continueAsNew'>) => Promise<never>;
-
-  /**
-   * Called when Workflow signals a child or external Workflow
-   */
-  signalWorkflow?: (input: SignalWorkflowInput, next: Next<this, 'signalWorkflow'>) => Promise<void>;
-
-  /**
-   * Called when Workflow starts a child workflow execution, the interceptor function returns 2 promises:
-   *
-   * - The first resolves with the `runId` when the child workflow has started or rejects if failed to start.
-   * - The second resolves with the workflow result when the child workflow completes or rejects on failure.
-   */
-  startChildWorkflowExecution?: (
-    input: StartChildWorkflowExecutionInput,
-    next: Next<this, 'startChildWorkflowExecution'>
-  ) => Promise<[Promise<string>, Promise<unknown>]>;
-
-  /**
-   * Called on each invocation of the `workflow.log` methods.
-   *
-   * The attributes returned in this call are attached to every log message.
-   */
-  getLogAttributes?: (input: GetLogAttributesInput, next: Next<this, 'getLogAttributes'>) => Record<string, unknown>;
-
-  /**
-   * Called once every time a metric is emitted from a Workflow metric (ie. a metric created
-   * from {@link workflow.metricMeter}).
-   *
-   * Tags returned by this hook are _prepended_ to tags defined at the metric level and tags
-   * defined on the emitter function itself.
-   */
-  getMetricTags?: (input: GetMetricTagsInput, next: Next<this, 'getMetricTags'>) => MetricTags;
+export interface ContinueAsNewInput {
+  readonly args: unknown[];
+  readonly headers: Headers;
+  readonly options: ContinueAsNewInputOptions;
 }
 
-/** Input for WorkflowInternalsInterceptor.concludeActivation */
-export interface ConcludeActivationInput {
-  commands: coresdk.workflow_commands.IWorkflowCommand[];
-}
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.continueAsNew}.
+ */
+export type ContinueAsNewInputOptions = ContinueAsNewOptions & Required<Pick<ContinueAsNewOptions, 'workflowType'>>;
 
-/** Output for WorkflowInternalsInterceptor.concludeActivation */
-export type ConcludeActivationOutput = ConcludeActivationInput;
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.getLogAttributes}.
+ */
+export type GetLogAttributesInput = Record<string, unknown>;
 
-/** Input for WorkflowInternalsInterceptor.activate */
-export interface ActivateInput {
-  activation: coresdk.workflow_activation.IWorkflowActivation;
-  batchIndex: number;
-}
+/**
+ * Input for {@link WorkflowOutboundCallsInterceptor.getMetricTags}.
+ */
+export type GetMetricTagsInput = MetricTags;
 
-/** Input for WorkflowInternalsInterceptor.dispose */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface DisposeInput {}
+// Workflow Internals Interceptors /////////////////////////////////////////////////////////////////////////////////////
 
 /**
  * Interceptor for the internals of the Workflow runtime.
@@ -265,29 +402,27 @@ export interface WorkflowInternalsInterceptor {
 }
 
 /**
- * A mapping from interceptor type to an optional list of interceptor implementations
+ * Input for {@link WorkflowInternalsInterceptor.activate}
  */
-export interface WorkflowInterceptors {
-  inbound?: WorkflowInboundCallsInterceptor[];
-  outbound?: WorkflowOutboundCallsInterceptor[];
-  internals?: WorkflowInternalsInterceptor[];
+export interface ActivateInput {
+  readonly activation: coresdk.workflow_activation.IWorkflowActivation;
+  readonly batchIndex: number;
 }
 
 /**
- * A function that returns {@link WorkflowInterceptors} and takes no arguments.
- *
- * Workflow interceptor modules should export an `interceptors` function of this type.
- *
- * @example
- *
- * ```ts
- * export function interceptors(): WorkflowInterceptors {
- *   return {
- *     inbound: [],   // Populate with list of interceptor implementations
- *     outbound: [],  // Populate with list of interceptor implementations
- *     internals: [], // Populate with list of interceptor implementations
- *   };
- * }
- * ```
+ * Input for {@link WorkflowInternalsInterceptor.dispose}
  */
-export type WorkflowInterceptorsFactory = () => WorkflowInterceptors;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DisposeInput {}
+
+/**
+ * Input for {@link WorkflowInternalsInterceptor.concludeActivation}
+ */
+export interface ConcludeActivationInput {
+  readonly commands: coresdk.workflow_commands.IWorkflowCommand[];
+}
+
+/**
+ * Output for {@link WorkflowInternalsInterceptor.concludeActivation}
+ */
+export type ConcludeActivationOutput = ConcludeActivationInput;