@temporalio/workflow 1.8.6 → 1.9.0

package/src/errors.ts

@@ -1,5 +1,6 @@
 import { ActivityFailure, CancelledFailure, ChildWorkflowFailure } from '@temporalio/common';
 import { SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
+import { coresdk } from '@temporalio/proto';
 
 /**
  * Base class for all workflow errors
@@ -13,6 +14,16 @@ export class WorkflowError extends Error {}
 @SymbolBasedInstanceOfError('DeterminismViolationError')
 export class DeterminismViolationError extends WorkflowError {}
 
+/**
+ * A class that acts as a marker for this special result type
+ */
+@SymbolBasedInstanceOfError('LocalActivityDoBackoff')
+export class LocalActivityDoBackoff extends Error {
+  constructor(public readonly backoff: coresdk.activity_result.IDoBackoff) {
+    super();
+  }
+}
+
 /**
  * Returns whether provided `err` is caused by cancellation
  */

package/src/global-attributes.ts

@@ -1,3 +1,6 @@
+import { IllegalStateError } from '@temporalio/common';
+import { type Activator } from './internals';
+
 export function maybeGetActivatorUntyped(): unknown {
   return (globalThis as any).__TEMPORAL_ACTIVATOR__;
 }
@@ -5,3 +8,21 @@ export function maybeGetActivatorUntyped(): unknown {
 export function setActivatorUntyped(activator: unknown): void {
   (globalThis as any).__TEMPORAL_ACTIVATOR__ = activator;
 }
+
+export function maybeGetActivator(): Activator | undefined {
+  return maybeGetActivatorUntyped() as Activator | undefined;
+}
+
+export function assertInWorkflowContext(message: string): Activator {
+  const activator = maybeGetActivator();
+  if (activator == null) throw new IllegalStateError(message);
+  return activator;
+}
+
+export function getActivator(): Activator {
+  const activator = maybeGetActivator();
+  if (activator === undefined) {
+    throw new IllegalStateError('Workflow uninitialized');
+  }
+  return activator;
+}

package/src/index.ts

@@ -20,18 +20,21 @@
  * <!--SNIPSTART typescript-schedule-activity-workflow-->
  * <!--SNIPEND-->
  *
- * ### Signals and Queries
+ * ### Updates, Signals and Queries
  *
- * To add signal handlers to a Workflow, add a signals property to the exported `workflow` object. Signal handlers can
- * return either `void` or `Promise<void>`, you may schedule activities and timers from a signal handler.
+ * Use {@link setHandler} to set handlers for Updates, Signals, and Queries.
  *
- * To add query handlers to a Workflow, add a queries property to the exported `workflow` object. Query handlers must
- * **not** mutate any variables or generate any commands (like Activities or Timers), they run synchronously and thus
- * **must** return a `Promise`.
+ * Update and Signal handlers can be either async or non-async functions. Update handlers may return a value, but signal
+ * handlers may not (return `void` or `Promise<void>`). You may use Activities, Timers, child Workflows, etc in Update
+ * and Signal handlers, but this should be done cautiously: for example, note that if you await async operations such as
+ * these in an Update or Signal handler, then you are responsible for ensuring that the workflow does not complete first.
+ *
+ * Query handlers may **not** be async functions, and may **not** mutate any variables or use Activities, Timers,
+ * child Workflows, etc.
  *
  * #### Implementation
  *
- * <!--SNIPSTART typescript-workflow-signal-implementation-->
+ * <!--SNIPSTART typescript-workflow-update-signal-query-example-->
  * <!--SNIPEND-->
  *
  * ### More
@@ -98,7 +101,20 @@ export {
   UnsafeWorkflowInfo,
   WorkflowInfo,
 } from './interfaces';
-export { LoggerSinks, Sink, SinkCall, SinkFunction, Sinks } from './sinks';
+export { proxySinks, Sink, SinkCall, SinkFunction, Sinks } from './sinks';
+export { log } from './logs';
 export { Trigger } from './trigger';
 export * from './workflow';
 export { ChildWorkflowHandle, ExternalWorkflowHandle } from './workflow-handle';
+
+// Anything below this line is deprecated
+
+export {
+  /**
+   * @deprecated Do not use LoggerSinks directly. To log from Workflow code, use the `log` object
+   *             exported by the `@temporalio/workflow` package. To capture log messages emitted
+   *             by Workflow code, set the {@link Runtime.logger} property.
+   */
+  // eslint-disable-next-line deprecation/deprecation
+  LoggerSinksDeprecated as LoggerSinks,
+} from './logs';

package/src/interceptors.ts

@@ -18,6 +18,15 @@ export interface WorkflowExecuteInput {
   readonly headers: Headers;
 }
 
+/** Input for WorkflowInboundCallsInterceptor.handleUpdate and
+ * WorkflowInboundCallsInterceptor.validateUpdate */
+export interface UpdateInput {
+  readonly updateId: string;
+  readonly name: string;
+  readonly args: unknown[];
+  readonly headers: Headers;
+}
+
 /** Input for WorkflowInboundCallsInterceptor.handleSignal */
 export interface SignalInput {
   readonly signalName: string;
@@ -44,6 +53,15 @@ export interface WorkflowInboundCallsInterceptor {
    */
   execute?: (input: WorkflowExecuteInput, next: Next<this, 'execute'>) => Promise<unknown>;
 
+  /** Called when Update handler is called
+   *
+   * @return result of the Update
+   */
+  handleUpdate?: (input: UpdateInput, next: Next<this, 'handleUpdate'>) => Promise<unknown>;
+
+  /** Called when update validator called */
+  validateUpdate?: (input: UpdateInput, next: Next<this, 'validateUpdate'>) => void;
+
   /** Called when signal is delivered to a Workflow execution */
   handleSignal?: (input: SignalInput, next: Next<this, 'handleSignal'>) => Promise<void>;
 

package/src/interfaces.ts

@@ -5,6 +5,7 @@ import {
   CommonWorkflowOptions,
   SearchAttributes,
   SignalDefinition,
+  UpdateDefinition,
   QueryDefinition,
   Duration,
   VersioningIntent,
@@ -20,46 +21,46 @@ export interface WorkflowInfo {
    * ID of the Workflow, this can be set by the client during Workflow creation.
    * A single Workflow may run multiple times e.g. when scheduled with cron.
    */
-  workflowId: string;
+  readonly workflowId: string;
 
   /**
    * ID of a single Workflow run
    */
-  runId: string;
+  readonly runId: string;
 
   /**
    * Workflow function's name
    */
-  workflowType: string;
+  readonly workflowType: string;
 
   /**
    * Indexed information attached to the Workflow Execution
    *
    * This value may change during the lifetime of an Execution.
    */
-  searchAttributes: SearchAttributes;
+  readonly searchAttributes: SearchAttributes;
 
   /**
    * Non-indexed information attached to the Workflow Execution
    */
-  memo?: Record<string, unknown>;
+  readonly memo?: Record<string, unknown>;
 
   /**
    * Parent Workflow info (present if this is a Child Workflow)
    */
-  parent?: ParentWorkflowInfo;
+  readonly parent?: ParentWorkflowInfo;
 
   /**
    * Result from the previous Run (present if this is a Cron Workflow or was Continued As New).
    *
    * An array of values, since other SDKs may return multiple values from a Workflow.
    */
-  lastResult?: unknown;
+  readonly lastResult?: unknown;
 
   /**
    * Failure from the previous Run (present when this Run is a retry, or the last Run of a Cron Workflow failed)
    */
-  lastFailure?: TemporalFailure;
+  readonly lastFailure?: TemporalFailure;
 
   /**
    * Length of Workflow history up until the current Workflow Task.
@@ -68,7 +69,7 @@ export interface WorkflowInfo {
    *
    * You may safely use this information to decide when to {@link continueAsNew}.
    */
-  historyLength: number;
+  readonly historyLength: number;
 
   /**
    * Size of Workflow history in bytes until the current Workflow Task.
@@ -79,7 +80,7 @@ export interface WorkflowInfo {
    *
    * You may safely use this information to decide when to {@link continueAsNew}.
    */
-  historySize: number;
+  readonly historySize: number;
 
   /**
    * A hint provided by the current WorkflowTaskStarted event recommending whether to
@@ -89,79 +90,87 @@ export interface WorkflowInfo {
    *
    * Supported only on Temporal Server 1.20+, always `false` on older servers.
    */
-  continueAsNewSuggested: boolean;
+  readonly continueAsNewSuggested: boolean;
 
   /**
    * Task queue this Workflow is executing on
    */
-  taskQueue: string;
+  readonly taskQueue: string;
 
   /**
    * Namespace this Workflow is executing in
    */
-  namespace: string;
+  readonly namespace: string;
 
   /**
    * Run Id of the first Run in this Execution Chain
    */
-  firstExecutionRunId: string;
+  readonly firstExecutionRunId: string;
 
   /**
    * The last Run Id in this Execution Chain
    */
-  continuedFromExecutionRunId?: string;
+  readonly continuedFromExecutionRunId?: string;
 
   /**
    * Time at which this [Workflow Execution Chain](https://docs.temporal.io/workflows#workflow-execution-chain) was started
    */
-  startTime: Date;
+  readonly startTime: Date;
 
   /**
    * Time at which the current Workflow Run started
    */
-  runStartTime: Date;
+  readonly runStartTime: Date;
 
   /**
    * Milliseconds after which the Workflow Execution is automatically terminated by Temporal Server. Set via {@link WorkflowOptions.workflowExecutionTimeout}.
    */
-  executionTimeoutMs?: number;
+  readonly executionTimeoutMs?: number;
 
   /**
    * Time at which the Workflow Execution expires
    */
-  executionExpirationTime?: Date;
+  readonly executionExpirationTime?: Date;
 
   /**
    * Milliseconds after which the Workflow Run is automatically terminated by Temporal Server. Set via {@link WorkflowOptions.workflowRunTimeout}.
    */
-  runTimeoutMs?: number;
+  readonly runTimeoutMs?: number;
 
   /**
    * Maximum execution time of a Workflow Task in milliseconds. Set via {@link WorkflowOptions.workflowTaskTimeout}.
    */
-  taskTimeoutMs: number;
+  readonly taskTimeoutMs: number;
 
   /**
    * Retry Policy for this Execution. Set via {@link WorkflowOptions.retry}.
    */
-  retryPolicy?: RetryPolicy;
+  readonly retryPolicy?: RetryPolicy;
 
   /**
    * Starts at 1 and increments for every retry if there is a `retryPolicy`
    */
-  attempt: number;
+  readonly attempt: number;
 
   /**
    * Cron Schedule for this Execution. Set via {@link WorkflowOptions.cronSchedule}.
    */
-  cronSchedule?: string;
+  readonly cronSchedule?: string;
 
   /**
    * Milliseconds between Cron Runs
    */
-  cronScheduleToScheduleInterval?: number;
+  readonly cronScheduleToScheduleInterval?: number;
+
+  /**
+   * The Build ID of the worker which executed the current Workflow Task. May be undefined if the
+   * task was completed by a worker without a Build ID. If this worker is the one executing this
+   * task for the first time and has a Build ID 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.
+   */
+  readonly currentBuildId?: string;
 
-  unsafe: UnsafeWorkflowInfo;
+  readonly unsafe: UnsafeWorkflowInfo;
 }
 
 /**
@@ -176,9 +185,9 @@ export interface UnsafeWorkflowInfo {
    * The safe version of time is `new Date()` and `Date.now()`, which are set on the first invocation of a Workflow
    * Task and stay constant for the duration of the Task and during replay.
    */
-  now(): number;
+  readonly now: () => number;
 
-  isReplaying: boolean;
+  readonly isReplaying: boolean;
 }
 
 export interface ParentWorkflowInfo {
@@ -231,6 +240,8 @@ export interface ContinueAsNewOptions {
    * When using the Worker Versioning feature, specifies whether this Workflow should
    * Continue-as-New onto a worker with a compatible Build Id or not. See {@link VersioningIntent}.
    *
+   * @default 'COMPATIBLE'
+   *
    * @experimental
    */
   versioningIntent?: VersioningIntent;
@@ -341,6 +352,8 @@ export interface ChildWorkflowOptions extends CommonWorkflowOptions {
    * When using the Worker Versioning feature, specifies whether this Child Workflow should run on
    * a worker with a compatible Build Id or not. See {@link VersioningIntent}.
    *
+   * @default 'COMPATIBLE'
+   *
    * @experimental
    */
   versioningIntent?: VersioningIntent;
@@ -428,19 +441,26 @@ export interface WorkflowCreateOptionsInternal extends WorkflowCreateOptions {
 }
 
 /**
- * A handler function capable of accepting the arguments for a given SignalDefinition or QueryDefinition.
+ * A handler function capable of accepting the arguments for a given UpdateDefinition, SignalDefinition or QueryDefinition.
  */
 export type Handler<
   Ret,
   Args extends any[],
-  T extends SignalDefinition<Args> | QueryDefinition<Ret, Args>
-> = T extends SignalDefinition<infer A>
-  ? (...args: A) => void | Promise<void>
-  : T extends QueryDefinition<infer R, infer A>
-  ? (...args: A) => R
-  : never;
+  T extends UpdateDefinition<Ret, Args> | SignalDefinition<Args> | QueryDefinition<Ret, Args>,
+> = T extends UpdateDefinition<infer R, infer A>
+  ? (...args: A) => R | Promise<R>
+  : T extends SignalDefinition<infer A>
+    ? (...args: A) => void | Promise<void>
+    : T extends QueryDefinition<infer R, infer A>
+      ? (...args: A) => R
+      : never;
 
 /**
- * A handler function accepting signals calls for non-registered signal names.
+ * A handler function accepting signal calls for non-registered signal names.
  */
 export type DefaultSignalHandler = (signalName: string, ...args: unknown[]) => void | Promise<void>;
+
+/**
+ * A validation function capable of accepting the arguments for a given UpdateDefinition.
+ */
+export type UpdateValidator<Args extends any[]> = (...args: Args) => void;