@temporalio/workflow 1.10.3 → 1.11.1

package/lib/flags.d.ts

@@ -14,5 +14,23 @@ export declare const SdkFlags: {
      * @since Introduced in 1.10.2/1.11.0.
      */
     readonly NonCancellableScopesAreShieldedFromPropagation: SdkFlag;
+    /**
+     * Prior to 1.11.0, when processing a Workflow activation, the SDK would execute `notifyHasPatch`
+     * and `signalWorkflow` jobs in distinct phases, before other types of jobs. The primary reason
+     * behind that multi-phase algorithm was to avoid the possibility that a Workflow execution might
+     * complete before all incoming signals have been dispatched (at least to the point that the
+     * _synchronous_ part of the handler function has been executed).
+     *
+     * This flag replaces that multi-phase algorithm with a simpler one where jobs are simply sorted as
+     * `(signals and updates) -> others`, but without processing them as distinct batches (i.e. without
+     * leaving/reentering the VM context between each group, which automatically triggers the execution
+     * of all outstanding microtasks). That single-phase approach resolves a number of quirks of the
+     * former algorithm, and yet still satisfies to the original requirement of ensuring that every
+     * `signalWorkflow` jobs - and now `doUpdate` jobs as well - have been given a proper chance to
+     * execute before the Workflow main function might completes.
+     *
+     * @since Introduced in 1.11.0. This change is not rollback-safe.
+     */
+    readonly ProcessWorkflowActivationJobsAsSingleBatch: SdkFlag;
 };
 export declare function assertValidFlag(id: number): void;

package/lib/flags.js

@@ -13,7 +13,25 @@ exports.SdkFlags = {
      *
      * @since Introduced in 1.10.2/1.11.0.
      */
-    NonCancellableScopesAreShieldedFromPropagation: defineFlag(1, false),
+    NonCancellableScopesAreShieldedFromPropagation: defineFlag(1, true),
+    /**
+     * Prior to 1.11.0, when processing a Workflow activation, the SDK would execute `notifyHasPatch`
+     * and `signalWorkflow` jobs in distinct phases, before other types of jobs. The primary reason
+     * behind that multi-phase algorithm was to avoid the possibility that a Workflow execution might
+     * complete before all incoming signals have been dispatched (at least to the point that the
+     * _synchronous_ part of the handler function has been executed).
+     *
+     * This flag replaces that multi-phase algorithm with a simpler one where jobs are simply sorted as
+     * `(signals and updates) -> others`, but without processing them as distinct batches (i.e. without
+     * leaving/reentering the VM context between each group, which automatically triggers the execution
+     * of all outstanding microtasks). That single-phase approach resolves a number of quirks of the
+     * former algorithm, and yet still satisfies to the original requirement of ensuring that every
+     * `signalWorkflow` jobs - and now `doUpdate` jobs as well - have been given a proper chance to
+     * execute before the Workflow main function might completes.
+     *
+     * @since Introduced in 1.11.0. This change is not rollback-safe.
+     */
+    ProcessWorkflowActivationJobsAsSingleBatch: defineFlag(2, true),
 };
 function defineFlag(id, def) {
     const flag = { id, default: def };

package/lib/flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":";;;AAKA,MAAM,aAAa,GAAyB,IAAI,GAAG,EAAE,CAAC;AAEzC,QAAA,QAAQ,GAAG;IACtB;;;;;;;;;OASG;IACH,8CAA8C,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC;CAC5D,CAAC;AAEX,SAAS,UAAU,CAAC,EAAU,EAAE,GAAY;IAC1C,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAClC,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,eAAe,CAAC,EAAU;IACxC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC;AAFD,0CAEC"}
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":";;;AAKA,MAAM,aAAa,GAAyB,IAAI,GAAG,EAAE,CAAC;AAEzC,QAAA,QAAQ,GAAG;IACtB;;;;;;;;;OASG;IACH,8CAA8C,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC;IAEnE;;;;;;;;;;;;;;;;OAgBG;IACH,0CAA0C,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC;CACvD,CAAC;AAEX,SAAS,UAAU,CAAC,EAAU,EAAE,GAAY;IAC1C,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAClC,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,eAAe,CAAC,EAAU;IACxC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC;AAFD,0CAEC"}

package/lib/index.d.ts

@@ -57,7 +57,7 @@ export * from '@temporalio/common/lib/workflow-options';
 export { AsyncLocalStorage, CancellationScope, CancellationScopeOptions } from './cancellation-scope';
 export * from './errors';
 export * from './interceptors';
-export { ChildWorkflowCancellationType, ChildWorkflowOptions, ContinueAsNew, ContinueAsNewOptions, EnhancedStackTrace, FileLocation, FileSlice, ParentClosePolicy, ParentWorkflowInfo, SDKInfo, StackTrace, UnsafeWorkflowInfo, WorkflowInfo, } from './interfaces';
+export { ChildWorkflowCancellationType, ChildWorkflowOptions, ContinueAsNew, ContinueAsNewOptions, EnhancedStackTrace, StackTraceFileLocation, StackTraceFileSlice, ParentClosePolicy, ParentWorkflowInfo, StackTraceSDKInfo, StackTrace, UnsafeWorkflowInfo, WorkflowInfo, } from './interfaces';
 export { proxySinks, Sink, SinkCall, SinkFunction, Sinks } from './sinks';
 export { log } from './logs';
 export { Trigger } from './trigger';

package/lib/interfaces.d.ts

@@ -1,5 +1,5 @@
 import type { RawSourceMap } from 'source-map';
-import { RetryPolicy, TemporalFailure, CommonWorkflowOptions, SearchAttributes, SignalDefinition, UpdateDefinition, QueryDefinition, Duration, VersioningIntent } from '@temporalio/common';
+import { RetryPolicy, TemporalFailure, CommonWorkflowOptions, HandlerUnfinishedPolicy, SearchAttributes, SignalDefinition, UpdateDefinition, QueryDefinition, Duration, VersioningIntent } from '@temporalio/common';
 import type { coresdk } from '@temporalio/proto';
 /**
  * Workflow Execution information
@@ -149,6 +149,21 @@ export interface UnsafeWorkflowInfo {
     readonly now: () => number;
     readonly isReplaying: boolean;
 }
+/**
+ * Information about a workflow update.
+ *
+ * @experimental
+ */
+export interface UpdateInfo {
+    /**
+     *  A workflow-unique identifier for this update.
+     */
+    readonly id: string;
+    /**
+     *  The update type name.
+     */
+    readonly name: string;
+}
 export interface ParentWorkflowInfo {
     workflowId: string;
     runId: string;
@@ -298,32 +313,32 @@ export type RequiredChildWorkflowOptions = Required<Pick<ChildWorkflowOptions, '
     args: unknown[];
 };
 export type ChildWorkflowOptionsWithDefaults = ChildWorkflowOptions & RequiredChildWorkflowOptions;
-export interface SDKInfo {
+export interface StackTraceSDKInfo {
     name: string;
     version: string;
 }
 /**
  * Represents a slice of a file starting at lineOffset
  */
-export interface FileSlice {
+export interface StackTraceFileSlice {
     /**
-     * slice of a file with `\n` (newline) line terminator.
+     * Only used possible to trim the file without breaking syntax highlighting.
      */
-    content: string;
+    line_offset: number;
     /**
-     * Only used possible to trim the file without breaking syntax highlighting.
+     * slice of a file with `\n` (newline) line terminator.
      */
-    lineOffset: number;
+    content: string;
 }
 /**
  * A pointer to a location in a file
  */
-export interface FileLocation {
+export interface StackTraceFileLocation {
     /**
      * Path to source file (absolute or relative).
      * When using a relative path, make sure all paths are relative to the same root.
      */
-    filePath?: string;
+    file_path?: string;
     /**
      * If possible, SDK should send this, required for displaying the code location.
      */
@@ -336,22 +351,26 @@ export interface FileLocation {
      * Function name this line belongs to (if applicable).
      * Used for falling back to stack trace view.
      */
-    functionName?: string;
+    function_name?: string;
+    /**
+     * Flag to mark this as internal SDK code and hide by default in the UI.
+     */
+    internal_code: boolean;
 }
 export interface StackTrace {
-    locations: FileLocation[];
+    locations: StackTraceFileLocation[];
 }
 /**
  * Used as the result for the enhanced stack trace query
  */
 export interface EnhancedStackTrace {
-    sdk: SDKInfo;
+    sdk: StackTraceSDKInfo;
     /**
      * Mapping of file path to file contents.
      * SDK may choose to send no, some or all sources.
      * Sources might be trimmed, and some time only the file(s) of the top element of the trace will be sent.
      */
-    sources: Record<string, FileSlice[]>;
+    sources: Record<string, StackTraceFileSlice[]>;
     stacks: StackTrace[];
 }
 export interface WorkflowCreateOptions {
@@ -359,6 +378,7 @@ export interface WorkflowCreateOptions {
     randomnessSeed: number[];
     now: number;
     patches: string[];
+    sdkFlags: number[];
     showStackTraceSources: boolean;
 }
 export interface WorkflowCreateOptionsInternal extends WorkflowCreateOptions {
@@ -389,6 +409,7 @@ export type QueryHandlerOptions = {
  */
 export type SignalHandlerOptions = {
     description?: string;
+    unfinishedPolicy?: HandlerUnfinishedPolicy;
 };
 /**
  * A validator and description of an update handler.
@@ -396,6 +417,7 @@ export type SignalHandlerOptions = {
 export type UpdateHandlerOptions<Args extends any[]> = {
     validator?: UpdateValidator<Args>;
     description?: string;
+    unfinishedPolicy?: HandlerUnfinishedPolicy;
 };
 export interface ActivationCompletion {
     commands: coresdk.workflow_commands.IWorkflowCommand[];

package/lib/interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";;;;;;;;;AAYA,sEAA+F;AA0L/F;;GAEG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAc,SAAQ,KAAK;IACtC,YAA4B,OAAkE;QAC5F,KAAK,CAAC,2BAA2B,CAAC,CAAC;QADT,YAAO,GAAP,OAAO,CAA2D;IAE9F,CAAC;CACF,CAAA;AAJY,sCAAa;wBAAb,aAAa;IADzB,IAAA,yCAA0B,EAAC,eAAe,CAAC;GAC/B,aAAa,CAIzB;AA2CD;;;;;;;GAOG;AACH,IAAY,6BAyBX;AAzBD,WAAY,6BAA6B;IACvC;;OAEG;IACH,uFAAW,CAAA;IAEX;;OAEG;IACH,6FAAc,CAAA;IAEd;;;;;;;OAOG;IACH,+HAA+B,CAAA;IAE/B;;OAEG;IACH,+HAA+B,CAAA;AACjC,CAAC,EAzBW,6BAA6B,6CAA7B,6BAA6B,QAyBxC;AAED,IAAA,2BAAY,GAAuF,CAAC;AACpG,IAAA,2BAAY,GAAuF,CAAC;AAEpG;;;;GAIG;AACH,IAAY,iBAsBX;AAtBD,WAAY,iBAAiB;IAC3B;;OAEG;IACH,+GAAmC,CAAA;IAEnC;;;;OAIG;IACH,2GAAiC,CAAA;IAEjC;;OAEG;IACH,uGAA+B,CAAA;IAE/B;;OAEG;IACH,qHAAsC,CAAA;AACxC,CAAC,EAtBW,iBAAiB,iCAAjB,iBAAiB,QAsB5B;AAED,IAAA,2BAAY,GAA+D,CAAC;AAC5E,IAAA,2BAAY,GAA+D,CAAC"}
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";;;;;;;;;AAaA,sEAA+F;AA2M/F;;GAEG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAc,SAAQ,KAAK;IACtC,YAA4B,OAAkE;QAC5F,KAAK,CAAC,2BAA2B,CAAC,CAAC;QADT,YAAO,GAAP,OAAO,CAA2D;IAE9F,CAAC;CACF,CAAA;AAJY,sCAAa;wBAAb,aAAa;IADzB,IAAA,yCAA0B,EAAC,eAAe,CAAC;GAC/B,aAAa,CAIzB;AA2CD;;;;;;;GAOG;AACH,IAAY,6BAyBX;AAzBD,WAAY,6BAA6B;IACvC;;OAEG;IACH,uFAAW,CAAA;IAEX;;OAEG;IACH,6FAAc,CAAA;IAEd;;;;;;;OAOG;IACH,+HAA+B,CAAA;IAE/B;;OAEG;IACH,+HAA+B,CAAA;AACjC,CAAC,EAzBW,6BAA6B,6CAA7B,6BAA6B,QAyBxC;AAED,IAAA,2BAAY,GAAuF,CAAC;AACpG,IAAA,2BAAY,GAAuF,CAAC;AAEpG;;;;GAIG;AACH,IAAY,iBAsBX;AAtBD,WAAY,iBAAiB;IAC3B;;OAEG;IACH,+GAAmC,CAAA;IAEnC;;;;OAIG;IACH,2GAAiC,CAAA;IAEjC;;OAEG;IACH,uGAA+B,CAAA;IAE/B;;OAEG;IACH,qHAAsC,CAAA;AACxC,CAAC,EAtBW,iBAAiB,iCAAjB,iBAAiB,QAsB5B;AAED,IAAA,2BAAY,GAA+D,CAAC;AAC5E,IAAA,2BAAY,GAA+D,CAAC"}

package/lib/internals.d.ts

@@ -1,15 +1,15 @@
 import type { RawSourceMap } from 'source-map';
-import { FailureConverter, PayloadConverter, Workflow, WorkflowQueryAnnotatedType, WorkflowSignalAnnotatedType, WorkflowUpdateAnnotatedType, ProtoFailure } from '@temporalio/common';
+import { FailureConverter, PayloadConverter, HandlerUnfinishedPolicy, Workflow, WorkflowQueryAnnotatedType, WorkflowSignalAnnotatedType, WorkflowUpdateAnnotatedType, ProtoFailure, WorkflowUpdateType, WorkflowUpdateValidatorType } from '@temporalio/common';
 import type { coresdk } from '@temporalio/proto';
 import { RNG } from './alea';
 import { RootCancellationScope } from './cancellation-scope';
 import { QueryInput, SignalInput, UpdateInput, WorkflowExecuteInput, WorkflowInterceptors } from './interceptors';
-import { DefaultSignalHandler, FileLocation, WorkflowInfo, WorkflowCreateOptionsInternal, ActivationCompletion } from './interfaces';
+import { DefaultSignalHandler, StackTraceFileLocation, WorkflowInfo, WorkflowCreateOptionsInternal, ActivationCompletion } from './interfaces';
 import { type SinkCall } from './sinks';
 import { SdkFlag } from './flags';
 export interface Stack {
     formatted: string;
-    structured: FileLocation[];
+    structured: StackTraceFileLocation[];
 }
 /**
  * Global store to track promise stacks for stack trace query
@@ -33,10 +33,31 @@ export type ActivationHandlerFunction<K extends keyof coresdk.workflow_activatio
 export type ActivationHandler = {
     [P in keyof coresdk.workflow_activation.IWorkflowActivationJob]: ActivationHandlerFunction<P>;
 };
+/**
+ * Information about an update or signal handler execution.
+ */
+interface MessageHandlerExecution {
+    name: string;
+    unfinishedPolicy: HandlerUnfinishedPolicy;
+    id?: string;
+}
 /**
  * Keeps all of the Workflow runtime state like pending completions for activities and timers.
  *
  * Implements handlers for all workflow activation jobs.
+ *
+ * Note that most methods in this class are meant to be called only from within the VM.
+ *
+ * However, a few methods may be called directly from outside the VM (essentially from `vm-shared.ts`).
+ * These methods are specifically marked with a comment and require careful consideration, as the
+ * execution context may not properly reflect that of the target workflow execution (e.g.: with Reusable
+ * VMs, the `global` may not have been swapped to those of that workflow execution; the active microtask
+ * queue may be that of the thread/process, rather than the queue of that VM context; etc). Consequently,
+ * methods that are meant to be called from outside of the VM must not do any of the following:
+ *
+ * - Access any global variable;
+ * - Create Promise objects, use async/await, or otherwise schedule microtasks;
+ * - Call user-defined functions, including any form of interceptor.
  */
 export declare class Activator implements ActivationHandler {
     /**
@@ -62,14 +83,6 @@ export declare class Activator implements ActivationHandler {
      * Holds buffered signal calls until a handler is registered
      */
     readonly bufferedSignals: coresdk.workflow_activation.ISignalWorkflow[];
-    /**
-     * Holds buffered query calls until a handler is registered.
-     *
-     * **IMPORTANT** queries are only buffered until workflow is started.
-     * This is required because async interceptors might block workflow function invocation
-     * which delays query handler registration.
-     */
-    protected readonly bufferedQueries: coresdk.workflow_activation.IQueryWorkflow[];
     /**
      * Mapping of update name to handler and validator
      */
@@ -78,6 +91,18 @@ export declare class Activator implements ActivationHandler {
      * Mapping of signal name to handler
      */
     readonly signalHandlers: Map<string, WorkflowSignalAnnotatedType>;
+    /**
+     * Mapping of in-progress updates to handler execution information.
+     */
+    readonly inProgressUpdates: Map<string, MessageHandlerExecution>;
+    /**
+     * Mapping of in-progress signals to handler execution information.
+     */
+    readonly inProgressSignals: Map<number, MessageHandlerExecution>;
+    /**
+     * A sequence number providing unique identifiers for signal handler executions.
+     */
+    protected signalHandlerExecutionSeq: number;
     /**
      * A signal handler that catches calls for non-registered signal names.
      */
@@ -120,12 +145,6 @@ export declare class Activator implements ActivationHandler {
      * Was this Workflow cancelled?
      */
     protected cancelled: boolean;
-    /**
-     * This is tracked to allow buffering queries until a workflow function is called.
-     * TODO(bergundy): I don't think this makes sense since queries run last in an activation and must be responded to in
-     * the same activation.
-     */
-    protected workflowFunctionWasCalled: boolean;
     /**
      * The next (incremental) sequence to assign when generating completable commands
      */
@@ -140,6 +159,7 @@ export declare class Activator implements ActivationHandler {
     };
     /**
      * This is set every time the workflow executes an activation
+     * May be accessed and modified from outside the VM.
      */
     now: number;
     /**
@@ -148,6 +168,7 @@ export declare class Activator implements ActivationHandler {
     workflow?: Workflow;
     /**
      * Information about the current Workflow
+     * May be accessed from outside the VM.
      */
     info: WorkflowInfo;
     /**
@@ -174,9 +195,15 @@ export declare class Activator implements ActivationHandler {
      */
     readonly getTimeOfDay: () => bigint;
     readonly registeredActivityNames: Set<string>;
-    constructor({ info, now, showStackTraceSources, sourceMap, getTimeOfDay, randomnessSeed, patches, registeredActivityNames, }: WorkflowCreateOptionsInternal);
+    constructor({ info, now, showStackTraceSources, sourceMap, getTimeOfDay, sdkFlags, randomnessSeed, patches, registeredActivityNames, }: WorkflowCreateOptionsInternal);
+    /**
+     * May be invoked from outside the VM.
+     */
     mutateWorkflowInfo(fn: (info: WorkflowInfo) => WorkflowInfo): void;
     protected getStackTraces(): Stack[];
+    /**
+     * May be invoked from outside the VM.
+     */
     getAndResetSinkCalls(): SinkCall[];
     /**
      * Buffer a Workflow command to be collected at the end of the current activation.
@@ -195,8 +222,8 @@ export declare class Activator implements ActivationHandler {
     protected queryWorkflowNextHandler({ queryName, args }: QueryInput): Promise<unknown>;
     queryWorkflow(activation: coresdk.workflow_activation.IQueryWorkflow): void;
     doUpdate(activation: coresdk.workflow_activation.IDoUpdate): void;
-    protected updateNextHandler({ name, args }: UpdateInput): Promise<unknown>;
-    protected validateUpdateNextHandler({ name, args }: UpdateInput): void;
+    protected updateNextHandler(handler: WorkflowUpdateType, { args }: UpdateInput): Promise<unknown>;
+    protected validateUpdateNextHandler(validator: WorkflowUpdateValidatorType | undefined, { args }: UpdateInput): void;
     dispatchBufferedUpdates(): void;
     rejectBufferedUpdates(): void;
     signalWorkflowNextHandler({ signalName, args }: SignalInput): Promise<void>;
@@ -204,10 +231,20 @@ export declare class Activator implements ActivationHandler {
     dispatchBufferedSignals(): void;
     resolveSignalExternalWorkflow(activation: coresdk.workflow_activation.IResolveSignalExternalWorkflow): void;
     resolveRequestCancelExternalWorkflow(activation: coresdk.workflow_activation.IResolveRequestCancelExternalWorkflow): void;
+    warnIfUnfinishedHandlers(): void;
     updateRandomSeed(activation: coresdk.workflow_activation.IUpdateRandomSeed): void;
     notifyHasPatch(activation: coresdk.workflow_activation.INotifyHasPatch): void;
     patchInternal(patchId: string, deprecated: boolean): boolean;
+    /**
+     * Called early while handling an activation to register known flags.
+     * May be invoked from outside the VM.
+     */
     addKnownFlags(flags: number[]): void;
+    /**
+     * Check if a flag is known to the Workflow Execution; if not, enable the flag if workflow
+     * is not replaying and the flag is configured to be enabled by default.
+     * May be invoked from outside the VM.
+     */
     hasFlag(flag: SdkFlag): boolean;
     removeFromCache(): void;
     /**
@@ -228,3 +265,4 @@ export declare class Activator implements ActivationHandler {
     errorToFailure(err: unknown): ProtoFailure;
     failureToError(failure: ProtoFailure): Error;
 }
+export {};