@temporalio/workflow 1.7.4 → 1.8.1

package/src/worker-interface.ts

@@ -10,7 +10,7 @@ import type { coresdk } from '@temporalio/proto';
 import { disableStorage } from './cancellation-scope';
 import { DeterminismViolationError } from './errors';
 import { WorkflowInterceptorsFactory } from './interceptors';
-import { WorkflowCreateOptionsWithSourceMap, WorkflowInfo } from './interfaces';
+import { WorkflowCreateOptionsInternal, WorkflowInfo } from './interfaces';
 import { Activator, getActivator } from './internals';
 import { SinkCall } from './sinks';
 import { setActivatorUntyped } from './global-attributes';
@@ -92,7 +92,7 @@ export function overrideGlobals(): void {
  *
  * Sets required internal state and instantiates the workflow and interceptors.
  */
-export function initRuntime(options: WorkflowCreateOptionsWithSourceMap): void {
+export function initRuntime(options: WorkflowCreateOptionsInternal): void {
   const info: WorkflowInfo = fixPrototypes(options.info);
   info.unsafe.now = OriginalDate.now;
   const activator = new Activator({ ...options, info });
@@ -137,12 +137,12 @@ export function initRuntime(options: WorkflowCreateOptionsWithSourceMap): void {
 
   const mod = importWorkflows();
   const workflowFn = mod[info.workflowType];
-  const defaultWorfklowFn = mod['default'];
+  const defaultWorkflowFn = mod['default'];
 
   if (typeof workflowFn === 'function') {
     activator.workflow = workflowFn;
-  } else if (typeof defaultWorfklowFn === 'function') {
-    activator.workflow = defaultWorfklowFn;
+  } else if (typeof defaultWorkflowFn === 'function') {
+    activator.workflow = defaultWorkflowFn;
   } else {
     const details =
       workflowFn === undefined

package/src/workflow.ts

@@ -2,6 +2,7 @@ import {
   ActivityFunction,
   ActivityOptions,
   compileRetryPolicy,
+  extractWorkflowType,
   IllegalStateError,
   LocalActivityOptions,
   mapToPayloads,
@@ -11,13 +12,16 @@ import {
   SignalDefinition,
   toPayloads,
   UntypedActivities,
+  VersioningIntent,
   WithWorkflowArgs,
   Workflow,
   WorkflowResultType,
   WorkflowReturnType,
 } from '@temporalio/common';
-import { msOptionalToTs, msToNumber, msToTs, tsToMs } from '@temporalio/common/lib/time';
+import { assertNever } from '@temporalio/common/lib/type-helpers';
+import { Duration, msOptionalToTs, msToNumber, msToTs, tsToMs } from '@temporalio/common/lib/time';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
+import { coresdk } from '@temporalio/proto';
 import { CancellationScope, registerSleepImplementation } from './cancellation-scope';
 import {
   ActivityInput,
@@ -37,8 +41,8 @@ import {
   Handler,
   WorkflowInfo,
 } from './interfaces';
-import { LocalActivityDoBackoff, getActivator, maybeGetActivator } from './internals';
-import { Sinks } from './sinks';
+import { Activator, LocalActivityDoBackoff, getActivator, maybeGetActivator } from './internals';
+import { LoggerSinks, Sinks } from './sinks';
 import { untrackPromise } from './stack-helpers';
 import { ChildWorkflowHandle, ExternalWorkflowHandle } from './workflow-handle';
 
@@ -107,8 +111,8 @@ function timerNextHandler(input: TimerInput) {
  * @param ms sleep duration - number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}.
  * If given a negative number or 0, value will be set to 1.
  */
-export function sleep(ms: number | string): Promise<void> {
-  const activator = getActivator();
+export function sleep(ms: Duration): Promise<void> {
+  const activator = assertInWorkflowContext('Workflow.sleep(...) may only be used from a Workflow Execution');
   const seq = activator.nextSeqs.timer++;
 
   const durationMs = Math.max(1, msToNumber(ms));
@@ -130,11 +134,6 @@ function validateActivityOptions(options: ActivityOptions): void {
 // Use same validation we use for normal activities
 const validateLocalActivityOptions = validateActivityOptions;
 
-/**
- * Hooks up activity promise to current cancellation scope and completion callbacks.
- *
- * Returns `false` if the current scope is already cancelled.
- */
 /**
  * Push a scheduleActivity command into activator accumulator and register completion
  */
@@ -176,6 +175,7 @@ function scheduleActivityNextHandler({ options, args, headers, seq, activityType
         headers,
         cancellationType: options.cancellationType,
         doNotEagerlyExecute: !(options.allowEagerDispatch ?? true),
+        versioningIntent: versioningIntentToProto(options.versioningIntent),
       },
     });
     activator.completions.activity.set(seq, {
@@ -198,6 +198,11 @@ async function scheduleLocalActivityNextHandler({
   originalScheduleTime,
 }: LocalActivityInput): Promise<unknown> {
   const activator = getActivator();
+  // Eagerly fail the local activity (which will in turn fail the workflow task.
+  // Do not fail on replay where the local activities may not be registered on the replay worker.
+  if (!workflowInfo().unsafe.isReplaying && !activator.registeredActivityNames.has(activityType)) {
+    throw new ReferenceError(`Local activity of type '${activityType}' not registered on worker`);
+  }
   validateLocalActivityOptions(options);
 
   return new Promise((resolve, reject) => {
@@ -250,7 +255,9 @@ async function scheduleLocalActivityNextHandler({
  * @hidden
  */
 export function scheduleActivity<R>(activityType: string, args: any[], options: ActivityOptions): Promise<R> {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.scheduleActivity(...) may only be used from a Workflow Execution'
+  );
   if (options === undefined) {
     throw new TypeError('Got empty activity options');
   }
@@ -275,7 +282,9 @@ export async function scheduleLocalActivity<R>(
   args: any[],
   options: LocalActivityOptions
 ): Promise<R> {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.scheduleLocalActivity(...) may only be used from a Workflow Execution'
+  );
   if (options === undefined) {
     throw new TypeError('Got empty activity options');
   }
@@ -365,6 +374,7 @@ function startChildWorkflowExecutionNextHandler({
           ? mapToPayloads(searchAttributePayloadConverter, options.searchAttributes)
           : undefined,
         memo: options.memo && mapToPayloads(activator.payloadConverter, options.memo),
+        versioningIntent: versioningIntentToProto(options.versioningIntent),
       },
     });
     activator.completions.childWorkflowStart.set(seq, {
@@ -504,7 +514,7 @@ export type ActivityInterfaceFor<T> = {
  * });
  *
  * export function execute(): Promise<void> {
- *   const response = await httpGet('http://example.com');
+ *   const response = await httpGet("http://example.com");
  *   // ...
  * }
  * ```
@@ -574,7 +584,9 @@ const CONDITION_0_PATCH = '__sdk_internal_patch_number:1';
  * It takes a Workflow ID and optional run ID.
  */
 export function getExternalWorkflowHandle(workflowId: string, runId?: string): ExternalWorkflowHandle {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.getExternalWorkflowHandle(...) may only be used from a Workflow Execution. Consider using Client.workflow.getHandle(...) instead.)'
+  );
   return {
     workflowId,
     runId,
@@ -696,9 +708,11 @@ export async function startChild<T extends Workflow>(
   workflowTypeOrFunc: string | T,
   options?: WithWorkflowArgs<T, ChildWorkflowOptions>
 ): Promise<ChildWorkflowHandle<T>> {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.startChild(...) may only be used from a Workflow Execution. Consider using Client.workflow.start(...) instead.)'
+  );
   const optionsWithDefaults = addDefaultWorkflowOptions(options ?? ({} as any));
-  const workflowType = typeof workflowTypeOrFunc === 'string' ? workflowTypeOrFunc : workflowTypeOrFunc.name;
+  const workflowType = extractWorkflowType(workflowTypeOrFunc);
   const execute = composeInterceptors(
     activator.interceptors.outbound,
     'startChildWorkflowExecution',
@@ -795,9 +809,11 @@ export async function executeChild<T extends Workflow>(
   workflowTypeOrFunc: string | T,
   options?: WithWorkflowArgs<T, ChildWorkflowOptions>
 ): Promise<WorkflowResultType<T>> {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.executeChild(...) may only be used from a Workflow Execution. Consider using Client.workflow.execute(...) instead.'
+  );
   const optionsWithDefaults = addDefaultWorkflowOptions(options ?? ({} as any));
-  const workflowType = typeof workflowTypeOrFunc === 'string' ? workflowTypeOrFunc : workflowTypeOrFunc.name;
+  const workflowType = extractWorkflowType(workflowTypeOrFunc);
   const execute = composeInterceptors(
     activator.interceptors.outbound,
     'startChildWorkflowExecution',
@@ -841,7 +857,8 @@ export async function executeChild<T extends Workflow>(
  * }
  */
 export function workflowInfo(): WorkflowInfo {
-  return getActivator().info;
+  const activator = assertInWorkflowContext('Workflow.workflowInfo(...) may only be used from a Workflow Execution.');
+  return activator.info;
 }
 
 /**
@@ -874,8 +891,8 @@ export function inWorkflowContext(): boolean {
  * export function myWorkflow() {
  *   return {
  *     async execute() {
- *       logger.info('hey ho');
- *       logger.error('lets go');
+ *       logger.info("hey ho");
+ *       logger.error("lets go");
  *     }
  *   };
  * }
@@ -891,11 +908,14 @@ export function proxySinks<T extends Sinks>(): T {
           {
             get(_, fnName) {
               return (...args: any[]) => {
-                const activator = getActivator();
+                const activator = assertInWorkflowContext(
+                  'Proxied sinks functions may only be used from a Workflow Execution.'
+                );
                 activator.sinkCalls.push({
                   ifaceName: ifaceName as string,
                   fnName: fnName as string,
-                  args,
+                  // Only available from node 17.
+                  args: (globalThis as any).structuredClone ? (globalThis as any).structuredClone(args) : args,
                 });
               };
             },
@@ -916,8 +936,10 @@ export function proxySinks<T extends Sinks>(): T {
 export function makeContinueAsNewFunc<F extends Workflow>(
   options?: ContinueAsNewOptions
 ): (...args: Parameters<F>) => Promise<never> {
-  const activator = getActivator();
-  const info = workflowInfo();
+  const activator = assertInWorkflowContext(
+    'Workflow.continueAsNew(...) and Workflow.makeContinueAsNewFunc(...) may only be used from a Workflow Execution.'
+  );
+  const info = activator.info;
   const { workflowType, taskQueue, ...rest } = options ?? {};
   const requiredOptions = {
     workflowType: workflowType ?? info.workflowType,
@@ -939,6 +961,7 @@ export function makeContinueAsNewFunc<F extends Workflow>(
           : undefined,
         workflowRunTimeout: msOptionalToTs(options.workflowRunTimeout),
         workflowTaskTimeout: msOptionalToTs(options.workflowTaskTimeout),
+        versioningIntent: versioningIntentToProto(options.versioningIntent),
       });
     });
     return fn({
@@ -1040,7 +1063,9 @@ export function deprecatePatch(patchId: string): void {
 }
 
 function patchInternal(patchId: string, deprecated: boolean): boolean {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.patch(...) and Workflow.deprecatePatch may only be used from a Workflow Execution.'
+  );
   // Patch operation does not support interception at the moment, if it did,
   // this would be the place to start the interception chain
 
@@ -1066,14 +1091,15 @@ function patchInternal(patchId: string, deprecated: boolean): boolean {
  *
  * @returns a boolean indicating whether the condition was true before the timeout expires
  */
-export function condition(fn: () => boolean, timeout: number | string): Promise<boolean>;
+export function condition(fn: () => boolean, timeout: Duration): Promise<boolean>;
 
 /**
  * Returns a Promise that resolves when `fn` evaluates to `true`.
  */
 export function condition(fn: () => boolean): Promise<void>;
 
-export async function condition(fn: () => boolean, timeout?: number | string): Promise<void | boolean> {
+export async function condition(fn: () => boolean, timeout?: Duration): Promise<void | boolean> {
+  assertInWorkflowContext('Workflow.condition(...) may only be used from a Workflow Execution.');
   // Prior to 1.5.0, `condition(fn, 0)` was treated as equivalent to `condition(fn, undefined)`
   if (timeout === 0 && !patched(CONDITION_0_PATCH)) {
     return conditionInner(fn);
@@ -1161,7 +1187,7 @@ export function setHandler<Ret, Args extends any[], T extends SignalDefinition<A
   def: T,
   handler: Handler<Ret, Args, T> | undefined
 ): void {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext('Workflow.setHandler(...) may only be used from a Workflow Execution.');
   if (def.type === 'signal') {
     if (typeof handler === 'function') {
       activator.signalHandlers.set(def.name, handler as any);
@@ -1194,7 +1220,9 @@ export function setHandler<Ret, Args extends any[], T extends SignalDefinition<A
  * @param handler a function that will handle signals for non-registered signal names, or `undefined` to unset the handler.
  */
 export function setDefaultSignalHandler(handler: DefaultSignalHandler | undefined): void {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.setDefaultSignalHandler(...) may only be used from a Workflow Execution.'
+  );
   if (typeof handler === 'function') {
     activator.defaultSignalHandler = handler;
     activator.dispatchBufferedSignals();
@@ -1235,7 +1263,9 @@ export function setDefaultSignalHandler(handler: DefaultSignalHandler | undefine
  * @param searchAttributes The Record to merge. Use a value of `[]` to clear a Search Attribute.
  */
 export function upsertSearchAttributes(searchAttributes: SearchAttributes): void {
-  const activator = getActivator();
+  const activator = assertInWorkflowContext(
+    'Workflow.upsertSearchAttributes(...) may only be used from a Workflow Execution.'
+  );
 
   const mergedSearchAttributes = { ...activator.info.searchAttributes, ...searchAttributes };
   if (!mergedSearchAttributes) {
@@ -1253,3 +1283,61 @@ export function upsertSearchAttributes(searchAttributes: SearchAttributes): void
 
 export const stackTraceQuery = defineQuery<string>('__stack_trace');
 export const enhancedStackTraceQuery = defineQuery<EnhancedStackTrace>('__enhanced_stack_trace');
+
+const loggerSinks = proxySinks<LoggerSinks>();
+
+/**
+ * Symbol used by the SDK logger to extract a timestamp from log attributes.
+ * Also defined in `worker/logger.ts` - intentionally not shared.
+ */
+const LogTimestamp = Symbol.for('log_timestamp');
+
+/**
+ * Default workflow logger.
+ * This logger is replay-aware and will omit log messages on workflow replay.
+ * The messages emitted by this logger are funnelled to the worker's `defaultSinks`, which are installed by default.
+ *
+ * Note that since sinks are used to power this logger, any log attributes must be transferable via the
+ * {@link https://nodejs.org/api/worker_threads.html#worker_threads_port_postmessage_value_transferlist | postMessage}
+ * API.
+ *
+ * `defaultSinks` accepts a user logger and defaults to the `Runtime`'s logger.
+ *
+ * See the documentation for `WorkerOptions`, `defaultSinks`, and `Runtime` for more information.
+ */
+export const log: LoggerSinks['defaultWorkerLogger'] = Object.fromEntries(
+  (['trace', 'debug', 'info', 'warn', 'error'] as Array<keyof LoggerSinks['defaultWorkerLogger']>).map((level) => {
+    return [
+      level,
+      (message: string, attrs?: Record<string, unknown>) => {
+        const activator = assertInWorkflowContext('Workflow.log(...) may only be used from a Workflow Execution.');
+        const getLogAttributes = composeInterceptors(activator.interceptors.outbound, 'getLogAttributes', (a) => a);
+        return loggerSinks.defaultWorkerLogger[level](message, {
+          // Inject the call time in nanosecond resolution as expected by the worker logger.
+          [LogTimestamp]: activator.getTimeOfDay(),
+          ...getLogAttributes({}),
+          ...attrs,
+        });
+      },
+    ];
+  })
+) as any;
+
+function assertInWorkflowContext(message: string): Activator {
+  const activator = maybeGetActivator();
+  if (activator == null) throw new IllegalStateError(message);
+  return activator;
+}
+
+function versioningIntentToProto(intent: VersioningIntent | undefined): coresdk.common.VersioningIntent {
+  switch (intent) {
+    case 'DEFAULT':
+      return coresdk.common.VersioningIntent.DEFAULT;
+    case 'COMPATIBLE':
+      return coresdk.common.VersioningIntent.COMPATIBLE;
+    case undefined:
+      return coresdk.common.VersioningIntent.UNSPECIFIED;
+    default:
+      assertNever('Unexpected VersioningIntent', intent);
+  }
+}