@temporalio/workflow 1.10.3 → 1.11.0

package/src/worker-interface.ts

@@ -4,15 +4,14 @@
  * @module
  */
 import { IllegalStateError } from '@temporalio/common';
-import { tsToMs } from '@temporalio/common/lib/time';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
 import { coresdk } from '@temporalio/proto';
 import { disableStorage } from './cancellation-scope';
+import { disableUpdateStorage } from './update-scope';
 import { WorkflowInterceptorsFactory } from './interceptors';
 import { WorkflowCreateOptionsInternal } from './interfaces';
 import { Activator } from './internals';
 import { setActivatorUntyped, getActivator } from './global-attributes';
-import { type SinkCall } from './sinks';
 
 // Export the type for use on the "worker" side
 export { PromiseStackStore } from './internals';
@@ -33,7 +32,7 @@ export function initRuntime(options: WorkflowCreateOptionsInternal): void {
       unsafe: { ...options.info.unsafe, now: OriginalDate.now },
     }),
   });
-  // There's on activator per workflow instance, set it globally on the context.
+  // There's one activator per workflow instance, set it globally on the context.
   // We do this before importing any user code so user code can statically reference @temporalio/workflow functions
   // as well as Date and Math.random.
   setActivatorUntyped(activator);
@@ -110,66 +109,26 @@ function fixPrototypes<X>(obj: X): X {
 
 /**
  * Run a chunk of activation jobs
- * @returns a boolean indicating whether job was processed or ignored
  */
-export function activate(activation: coresdk.workflow_activation.WorkflowActivation, batchIndex: number): void {
+export function activate(activation: coresdk.workflow_activation.IWorkflowActivation, batchIndex: number): void {
   const activator = getActivator();
-  const intercept = composeInterceptors(activator.interceptors.internals, 'activate', ({ activation, batchIndex }) => {
-    if (batchIndex === 0) {
-      if (!activation.jobs) {
-        throw new TypeError('Got activation with no jobs');
-      }
-      if (activation.timestamp != null) {
-        // timestamp will not be updated for activation that contain only queries
-        activator.now = tsToMs(activation.timestamp);
-      }
-      activator.addKnownFlags(activation.availableInternalFlags ?? []);
-
-      // The Rust Core ensures that these activation fields are not null
-      activator.mutateWorkflowInfo((info) => ({
-        ...info,
-        historyLength: activation.historyLength as number,
-        // Exact truncation for multi-petabyte histories
-        // historySize === 0 means WFT was generated by pre-1.20.0 server, and the history size is unknown
-        historySize: activation.historySizeBytes?.toNumber() || 0,
-        continueAsNewSuggested: activation.continueAsNewSuggested ?? false,
-        currentBuildId: activation.buildIdForCurrentTask ?? undefined,
-        unsafe: {
-          ...info.unsafe,
-          isReplaying: activation.isReplaying ?? false,
-        },
-      }));
-    }
-
+  const intercept = composeInterceptors(activator.interceptors.internals, 'activate', ({ activation }) => {
     // Cast from the interface to the class which has the `variant` attribute.
     // This is safe because we know that activation is a proto class.
     const jobs = activation.jobs as coresdk.workflow_activation.WorkflowActivationJob[];
 
     for (const job of jobs) {
-      if (job.variant === undefined) {
-        throw new TypeError('Expected job.variant to be defined');
-      }
+      if (job.variant === undefined) throw new TypeError('Expected job.variant to be defined');
 
       const variant = job[job.variant];
-      if (!variant) {
-        throw new TypeError(`Expected job.${job.variant} to be set`);
-      }
-      // The only job that can be executed on a completed workflow is a query.
-      // We might get other jobs after completion for instance when a single
-      // activation contains multiple jobs and the first one completes the workflow.
-      if (activator.completed && job.variant !== 'queryWorkflow') {
-        return;
-      }
+      if (!variant) throw new TypeError(`Expected job.${job.variant} to be set`);
+
       activator[job.variant](variant as any /* TS can't infer this type */);
-      if (shouldUnblockConditions(job)) {
-        tryUnblockConditions();
-      }
+
+      if (job.variant !== 'queryWorkflow') tryUnblockConditions();
     }
   });
-  intercept({
-    activation,
-    batchIndex,
-  });
+  intercept({ activation, batchIndex });
 }
 
 /**
@@ -182,20 +141,18 @@ export function concludeActivation(): coresdk.workflow_completion.IWorkflowActiv
   const activator = getActivator();
   activator.rejectBufferedUpdates();
   const intercept = composeInterceptors(activator.interceptors.internals, 'concludeActivation', (input) => input);
-  const { info } = activator;
   const activationCompletion = activator.concludeActivation();
   const { commands } = intercept({ commands: activationCompletion.commands });
+  if (activator.completed) {
+    activator.warnIfUnfinishedHandlers();
+  }
 
   return {
-    runId: info.runId,
+    runId: activator.info.runId,
     successful: { ...activationCompletion, commands },
   };
 }
 
-export function getAndResetSinkCalls(): SinkCall[] {
-  return getActivator().getAndResetSinkCalls();
-}
-
 /**
  * Loop through all blocked conditions, evaluate and unblock if possible.
  *
@@ -220,16 +177,10 @@ export function tryUnblockConditions(): number {
   return numUnblocked;
 }
 
-/**
- * Predicate used to prevent triggering conditions for non-query and non-patch jobs.
- */
-export function shouldUnblockConditions(job: coresdk.workflow_activation.IWorkflowActivationJob): boolean {
-  return !job.queryWorkflow && !job.notifyHasPatch;
-}
-
 export function dispose(): void {
   const dispose = composeInterceptors(getActivator().interceptors.internals, 'dispose', async () => {
     disableStorage();
+    disableUpdateStorage();
   });
   dispose({});
 }

package/src/workflow.ts

@@ -3,6 +3,7 @@ import {
   ActivityOptions,
   compileRetryPolicy,
   extractWorkflowType,
+  HandlerUnfinishedPolicy,
   LocalActivityOptions,
   mapToPayloads,
   QueryDefinition,
@@ -23,6 +24,7 @@ import { Duration, msOptionalToTs, msToNumber, msToTs, requiredTsToMs } from '@t
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
 import { temporal } from '@temporalio/proto';
 import { CancellationScope, registerSleepImplementation } from './cancellation-scope';
+import { UpdateScope } from './update-scope';
 import {
   ActivityInput,
   LocalActivityInput,
@@ -43,6 +45,7 @@ import {
   SignalHandlerOptions,
   UpdateHandlerOptions,
   WorkflowInfo,
+  UpdateInfo,
 } from './interfaces';
 import { LocalActivityDoBackoff } from './errors';
 import { assertInWorkflowContext, getActivator, maybeGetActivator } from './global-attributes';
@@ -53,7 +56,7 @@ import { ChildWorkflowHandle, ExternalWorkflowHandle } from './workflow-handle';
 registerSleepImplementation(sleep);
 
 /**
- * Adds default values to `workflowId` and `workflowIdReusePolicy` to given workflow options.
+ * Adds default values of `workflowId` and `cancellationType` to given workflow options.
  */
 export function addDefaultWorkflowOptions<T extends Workflow>(
   opts: WithWorkflowArgs<T, ChildWorkflowOptions>
@@ -867,6 +870,19 @@ export function workflowInfo(): WorkflowInfo {
   return activator.info;
 }
 
+/**
+ * Get information about the current update if any.
+ *
+ * @return Info for the current update handler the code calling this is executing
+ * within if any.
+ *
+ * @experimental
+ */
+export function currentUpdateInfo(): UpdateInfo | undefined {
+  assertInWorkflowContext('Workflow.currentUpdateInfo(...) may only be used from a Workflow Execution.');
+  return UpdateScope.current();
+}
+
 /**
  * Returns whether or not code is executing in workflow context
  */
@@ -1080,8 +1096,8 @@ function conditionInner(fn: () => boolean): Promise<void> {
 /**
  * Define an update method for a Workflow.
  *
- * Definitions are used to register handler in the Workflow via {@link setHandler} and to update Workflows using a {@link WorkflowHandle}, {@link ChildWorkflowHandle} or {@link ExternalWorkflowHandle}.
- * Definitions can be reused in multiple Workflows.
+ * A definition is used to register a handler in the Workflow via {@link setHandler} and to update a Workflow using a {@link WorkflowHandle}, {@link ChildWorkflowHandle} or {@link ExternalWorkflowHandle}.
+ * A definition can be reused in multiple Workflows.
  */
 export function defineUpdate<Ret, Args extends any[] = [], Name extends string = string>(
   name: Name
@@ -1095,8 +1111,8 @@ export function defineUpdate<Ret, Args extends any[] = [], Name extends string =
 /**
  * Define a signal method for a Workflow.
  *
- * Definitions are used to register handler in the Workflow via {@link setHandler} and to signal Workflows using a {@link WorkflowHandle}, {@link ChildWorkflowHandle} or {@link ExternalWorkflowHandle}.
- * Definitions can be reused in multiple Workflows.
+ * A definition is used to register a handler in the Workflow via {@link setHandler} and to signal a Workflow using a {@link WorkflowHandle}, {@link ChildWorkflowHandle} or {@link ExternalWorkflowHandle}.
+ * A definition can be reused in multiple Workflows.
  */
 export function defineSignal<Args extends any[] = [], Name extends string = string>(
   name: Name
@@ -1110,8 +1126,8 @@ export function defineSignal<Args extends any[] = [], Name extends string = stri
 /**
  * Define a query method for a Workflow.
  *
- * Definitions are used to register handler in the Workflow via {@link setHandler} and to query Workflows using a {@link WorkflowHandle}.
- * Definitions can be reused in multiple Workflows.
+ * A definition is used to register a handler in the Workflow via {@link setHandler} and to query a Workflow using a {@link WorkflowHandle}.
+ * A definition can be reused in multiple Workflows.
  */
 export function defineQuery<Ret, Args extends any[] = [], Name extends string = string>(
   name: Name
@@ -1178,7 +1194,7 @@ export function setHandler<Ret, Args extends any[], T extends UpdateDefinition<R
 // 1. sdk-core sorts Signal and Update jobs (and Patches) ahead of all other
 //    jobs. Thus if the handler is available at the start of the Activation then
 //    the Signal/Update will be executed before Workflow code is executed. If it
-//    is not, then the Signal/Update calls is pushed to a buffer.
+//    is not, then the Signal/Update calls are pushed to a buffer.
 //
 // 2. On each call to setHandler for a given Signal/Update, we make a pass
 //    through the buffer list. If a buffered job is associated with the just-set
@@ -1226,7 +1242,7 @@ export function setHandler<Ret, Args extends any[], T extends UpdateDefinition<R
 //    Worker polling until after they have verified that both requests have
 //    succeeded.)
 //
-// 5. If an Update has a validation function then it is executed immediately
+// 4. If an Update has a validation function then it is executed immediately
 //    prior to the handler. (Note that the validation function is required to be
 //    synchronous).
 export function setHandler<
@@ -1243,8 +1259,10 @@ export function setHandler<
   if (def.type === 'update') {
     if (typeof handler === 'function') {
       const updateOptions = options as UpdateHandlerOptions<Args> | undefined;
+
       const validator = updateOptions?.validator as WorkflowUpdateValidatorType | undefined;
-      activator.updateHandlers.set(def.name, { handler, validator, description });
+      const unfinishedPolicy = updateOptions?.unfinishedPolicy ?? HandlerUnfinishedPolicy.WARN_AND_ABANDON;
+      activator.updateHandlers.set(def.name, { handler, validator, description, unfinishedPolicy });
       activator.dispatchBufferedUpdates();
     } else if (handler == null) {
       activator.updateHandlers.delete(def.name);
@@ -1253,7 +1271,9 @@ export function setHandler<
     }
   } else if (def.type === 'signal') {
     if (typeof handler === 'function') {
-      activator.signalHandlers.set(def.name, { handler: handler as any, description });
+      const signalOptions = options as SignalHandlerOptions | undefined;
+      const unfinishedPolicy = signalOptions?.unfinishedPolicy ?? HandlerUnfinishedPolicy.WARN_AND_ABANDON;
+      activator.signalHandlers.set(def.name, { handler: handler as any, description, unfinishedPolicy });
       activator.dispatchBufferedSignals();
     } else if (handler == null) {
       activator.signalHandlers.delete(def.name);
@@ -1351,6 +1371,91 @@ export function upsertSearchAttributes(searchAttributes: SearchAttributes): void
   });
 }
 
+/**
+ * Updates this Workflow's Memos by merging the provided `memo` with existing
+ * Memos (as returned by `workflowInfo().memo`).
+ *
+ * New memo is merged by replacing properties of the same name _at the first
+ * level only_. Setting a property to value `undefined` or `null` clears that
+ * key from the Memo.
+ *
+ * For example:
+ *
+ * ```ts
+ * upsertMemo({
+ *   key1: value,
+ *   key3: { subkey1: value }
+ *   key4: value,
+ * });
+ * upsertMemo({
+ *   key2: value
+ *   key3: { subkey2: value }
+ *   key4: undefined,
+ * });
+ * ```
+ *
+ * would result in the Workflow having these Memo:
+ *
+ * ```ts
+ * {
+ *   key1: value,
+ *   key2: value,
+ *   key3: { subkey2: value }  // Note this object was completely replaced
+ *   // Note that key4 was completely removed
+ * }
+ * ```
+ *
+ * @param memo The Record to merge.
+ */
+export function upsertMemo(memo: Record<string, unknown>): void {
+  const activator = assertInWorkflowContext('Workflow.upsertMemo(...) may only be used from a Workflow Execution.');
+
+  if (memo == null) {
+    throw new Error('memo must be a non-null Record');
+  }
+
+  activator.pushCommand({
+    modifyWorkflowProperties: {
+      upsertedMemo: {
+        fields: mapToPayloads(
+          activator.payloadConverter,
+          // Convert null to undefined
+          Object.fromEntries(Object.entries(memo).map(([k, v]) => [k, v ?? undefined]))
+        ),
+      },
+    },
+  });
+
+  activator.mutateWorkflowInfo((info: WorkflowInfo): WorkflowInfo => {
+    return {
+      ...info,
+      memo: Object.fromEntries(
+        Object.entries({
+          ...info.memo,
+          ...memo,
+        }).filter(([_, v]) => v != null)
+      ),
+    };
+  });
+}
+
+/**
+ * Whether update and signal handlers have finished executing.
+ *
+ * Consider waiting on this condition before workflow return or continue-as-new, to prevent
+ * interruption of in-progress handlers by workflow exit:
+ *
+ * ```ts
+ * await workflow.condition(workflow.allHandlersFinished)
+ * ```
+ *
+ * @returns true if there are no in-progress update or signal handler executions.
+ */
+export function allHandlersFinished(): boolean {
+  const activator = assertInWorkflowContext('allHandlersFinished() may only be used from a Workflow Execution.');
+  return activator.inProgressSignals.size === 0 && activator.inProgressUpdates.size === 0;
+}
+
 export const stackTraceQuery = defineQuery<string>('__stack_trace');
 export const enhancedStackTraceQuery = defineQuery<EnhancedStackTrace>('__enhanced_stack_trace');
 export const workflowMetadataQuery = defineQuery<temporal.api.sdk.v1.IWorkflowMetadata>('__temporal_workflow_metadata');