@temporalio/workflow 1.0.0-rc.0 → 1.0.1

package/src/trigger.ts

@@ -0,0 +1,49 @@
+import { CancellationScope } from './cancellation-scope';
+import { untrackPromise } from './stack-helpers';
+
+/**
+ * A `PromiseLike` helper which exposes its `resolve` and `reject` methods.
+ *
+ * Trigger is CancellationScope-aware: it is linked to the current scope on
+ * construction and throws when that scope is cancelled.
+ *
+ * Useful for e.g. waiting for unblocking a Workflow from a Signal.
+ *
+ * @example
+ * <!--SNIPSTART typescript-trigger-workflow-->
+ * <!--SNIPEND-->
+ */
+export class Trigger<T> implements PromiseLike<T> {
+  // Typescript does not realize that the promise executor is run synchronously in the constructor
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  public readonly resolve: (value: T | PromiseLike<T>) => void;
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  public readonly reject: (reason?: any) => void;
+  protected readonly promise: Promise<T>;
+
+  constructor() {
+    this.promise = new Promise<T>((resolve, reject) => {
+      const scope = CancellationScope.current();
+      if (scope.consideredCancelled || scope.cancellable) {
+        untrackPromise(scope.cancelRequested.catch(reject));
+      }
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      this.resolve = resolve;
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      this.reject = reject;
+    });
+    // Avoid unhandled rejections
+    untrackPromise(this.promise.catch(() => undefined));
+  }
+
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null
+  ): PromiseLike<TResult1 | TResult2> {
+    return this.promise.then(onfulfilled, onrejected);
+  }
+}

package/src/worker-interface.ts

@@ -0,0 +1,273 @@
+/**
+ * Exported functions for the Worker to interact with the Workflow isolate
+ *
+ * @module
+ */
+import { errorToFailure as _errorToFailure, ProtoFailure } from '@temporalio/common';
+import { composeInterceptors, IllegalStateError, msToTs, tsToMs } from '@temporalio/internal-workflow-common';
+import type { coresdk } from '@temporalio/proto';
+import { alea } from './alea';
+import { storage } from './cancellation-scope';
+import { DeterminismViolationError } from './errors';
+import { WorkflowInterceptorsFactory } from './interceptors';
+import { WorkflowInfo } from './interfaces';
+import { InterceptorsImportFunc, state, WorkflowsImportFunc } from './internals';
+import { SinkCall } from './sinks';
+
+// Export the type for use on the "worker" side
+export { PromiseStackStore } from './internals';
+
+export interface WorkflowCreateOptions {
+  info: WorkflowInfo;
+  randomnessSeed: number[];
+  now: number;
+  patches: string[];
+}
+
+export interface ImportFunctions {
+  importWorkflows: WorkflowsImportFunc;
+  importInterceptors: InterceptorsImportFunc;
+}
+export function setImportFuncs({ importWorkflows, importInterceptors }: ImportFunctions): void {
+  state.importWorkflows = importWorkflows;
+  state.importInterceptors = importInterceptors;
+}
+
+export function overrideGlobals(): void {
+  const global = globalThis as any;
+  // Mock any weak reference because GC is non-deterministic and the effect is observable from the Workflow.
+  // WeakRef is implemented in V8 8.4 which is embedded in node >=14.6.0.
+  // Workflow developer will get a meaningful exception if they try to use these.
+  global.WeakRef = function () {
+    throw new DeterminismViolationError('WeakRef cannot be used in Workflows because v8 GC is non-deterministic');
+  };
+  global.FinalizationRegistry = function () {
+    throw new DeterminismViolationError(
+      'FinalizationRegistry cannot be used in Workflows because v8 GC is non-deterministic'
+    );
+  };
+
+  const OriginalDate = globalThis.Date;
+
+  global.Date = function (...args: unknown[]) {
+    if (args.length > 0) {
+      return new (OriginalDate as any)(...args);
+    }
+    return new OriginalDate(state.now);
+  };
+
+  global.Date.now = function () {
+    return state.now;
+  };
+
+  global.Date.parse = OriginalDate.parse.bind(OriginalDate);
+  global.Date.UTC = OriginalDate.UTC.bind(OriginalDate);
+
+  global.Date.prototype = OriginalDate.prototype;
+
+  /**
+   * @param ms sleep duration -  number of milliseconds. If given a negative number, value will be set to 1.
+   */
+  global.setTimeout = function (cb: (...args: any[]) => any, ms: number, ...args: any[]): number {
+    ms = Math.max(1, ms);
+    const seq = state.nextSeqs.timer++;
+    // Create a Promise for AsyncLocalStorage to be able to track this completion using promise hooks.
+    new Promise((resolve, reject) => {
+      state.completions.timer.set(seq, { resolve, reject });
+      state.pushCommand({
+        startTimer: {
+          seq,
+          startToFireTimeout: msToTs(ms),
+        },
+      });
+    }).then(
+      () => cb(...args),
+      () => undefined /* ignore cancellation */
+    );
+    return seq;
+  };
+
+  global.clearTimeout = function (handle: number): void {
+    state.nextSeqs.timer++;
+    state.completions.timer.delete(handle);
+    state.pushCommand({
+      cancelTimer: {
+        seq: handle,
+      },
+    });
+  };
+
+  // state.random is mutable, don't hardcode its reference
+  Math.random = () => state.random();
+}
+
+/**
+ * Initialize the isolate runtime.
+ *
+ * Sets required internal state and instantiates the workflow and interceptors.
+ */
+export async function initRuntime({ info, randomnessSeed, now, patches }: WorkflowCreateOptions): Promise<void> {
+  const global = globalThis as any;
+  // Set the runId globally on the context so it can be retrieved in the case
+  // of an unhandled promise rejection.
+  global.__TEMPORAL__.runId = info.runId;
+  // Set the promiseStackStore so promises can be tracked
+  global.__TEMPORAL__.promiseStackStore = {
+    promiseToStack: new Map(),
+    childToParent: new Map(),
+  };
+
+  state.info = info;
+  state.now = now;
+  state.random = alea(randomnessSeed);
+
+  if (info.unsafe.isReplaying) {
+    for (const patch of patches) {
+      state.knownPresentPatches.add(patch);
+    }
+  }
+
+  // webpack doesn't know what to bundle given a dynamic import expression, so we can't do:
+  // state.payloadConverter = (await import(payloadConverterPath)).payloadConverter;
+  // @ts-expect-error this is a webpack alias to payloadConverterPath
+  const customPayloadConverter = (await import('__temporal_custom_payload_converter')).payloadConverter;
+  // The `payloadConverter` export is validated in the Worker
+  if (customPayloadConverter !== undefined) {
+    state.payloadConverter = customPayloadConverter;
+  }
+
+  const { importWorkflows, importInterceptors } = state;
+  if (importWorkflows === undefined || importInterceptors === undefined) {
+    throw new IllegalStateError('Workflow has not been initialized');
+  }
+
+  const interceptors = await importInterceptors();
+  for (const mod of interceptors) {
+    const factory: WorkflowInterceptorsFactory = mod.interceptors;
+    if (factory !== undefined) {
+      if (typeof factory !== 'function') {
+        throw new TypeError(`interceptors must be a function, got: ${factory}`);
+      }
+      const interceptors = factory();
+      state.interceptors.inbound.push(...(interceptors.inbound ?? []));
+      state.interceptors.outbound.push(...(interceptors.outbound ?? []));
+      state.interceptors.internals.push(...(interceptors.internals ?? []));
+    }
+  }
+
+  const mod = await importWorkflows();
+  const workflow = mod[info.workflowType];
+  if (typeof workflow !== 'function') {
+    throw new TypeError(`'${info.workflowType}' is not a function`);
+  }
+  state.workflow = workflow;
+}
+
+/**
+ * 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 {
+  const intercept = composeInterceptors(state.interceptors.internals, 'activate', ({ activation, batchIndex }) => {
+    if (batchIndex === 0) {
+      if (state.info === undefined) {
+        throw new IllegalStateError('Workflow has not been initialized');
+      }
+      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
+        state.now = tsToMs(activation.timestamp);
+      }
+      if (activation.historyLength == null) {
+        throw new TypeError('Got activation with no historyLength');
+      }
+      state.info.unsafe.isReplaying = activation.isReplaying ?? false;
+      state.info.historyLength = activation.historyLength;
+    }
+
+    // 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');
+      }
+
+      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 (state.completed && job.variant !== 'queryWorkflow') {
+        return;
+      }
+      state.activator[job.variant](variant as any /* TS can't infer this type */);
+      tryUnblockConditions();
+    }
+  });
+  intercept({
+    activation,
+    batchIndex,
+  });
+}
+
+/**
+ * Conclude a single activation.
+ * Should be called after processing all activation jobs and queued microtasks.
+ *
+ * Activation failures are handled in the main Node.js isolate.
+ */
+export function concludeActivation(): coresdk.workflow_completion.IWorkflowActivationCompletion {
+  const intercept = composeInterceptors(state.interceptors.internals, 'concludeActivation', (input) => input);
+  const { info } = state;
+  const { commands } = intercept({ commands: state.commands });
+  state.commands = [];
+  return {
+    runId: info?.runId,
+    successful: { commands },
+  };
+}
+
+export function getAndResetSinkCalls(): SinkCall[] {
+  return state.getAndResetSinkCalls();
+}
+
+/**
+ * Loop through all blocked conditions, evaluate and unblock if possible.
+ *
+ * @returns number of unblocked conditions.
+ */
+export function tryUnblockConditions(): number {
+  let numUnblocked = 0;
+  for (;;) {
+    const prevUnblocked = numUnblocked;
+    for (const [seq, cond] of state.blockedConditions.entries()) {
+      if (cond.fn()) {
+        cond.resolve();
+        numUnblocked++;
+        // It is safe to delete elements during map iteration
+        state.blockedConditions.delete(seq);
+      }
+    }
+    if (prevUnblocked === numUnblocked) {
+      break;
+    }
+  }
+  return numUnblocked;
+}
+
+export async function dispose(): Promise<void> {
+  const dispose = composeInterceptors(state.interceptors.internals, 'dispose', async () => {
+    storage.disable();
+  });
+  await dispose({});
+}
+
+export function errorToFailure(err: unknown): ProtoFailure {
+  return _errorToFailure(err, state.payloadConverter);
+}

package/src/workflow-handle.ts

@@ -0,0 +1,63 @@
+import { BaseWorkflowHandle, SignalDefinition, Workflow } from '@temporalio/internal-workflow-common';
+
+/**
+ * Handle representing an external Workflow Execution.
+ *
+ * This handle only has methods `cancel` and `signal`. To call other methods, like `query` and `result`, use
+ * {@link WorkflowClient.getHandle} inside an Activity.
+ */
+export interface ExternalWorkflowHandle {
+  /**
+   * Signal a running Workflow.
+   *
+   * @param def a signal definition as returned from {@link defineSignal} or signal name (string)
+   *
+   * @example
+   * ```ts
+   * await handle.signal(incrementSignal, 3);
+   * ```
+   */
+  signal<Args extends any[] = []>(def: SignalDefinition<Args> | string, ...args: Args): Promise<void>;
+
+  /**
+   * Cancel the external Workflow execution.
+   *
+   * Throws if the Workflow execution does not exist.
+   */
+  cancel(): Promise<void>;
+
+  /**
+   * The workflowId of the external Workflow
+   */
+  readonly workflowId: string;
+
+  /**
+   * An optional runId of the external Workflow
+   */
+  readonly runId?: string;
+}
+
+/**
+ * A client side handle to a single Workflow instance.
+ * It can be used to signal, wait for completion, and cancel a Workflow execution.
+ *
+ * Given the following Workflow definition:
+ * ```ts
+ * export const incrementSignal = defineSignal('increment');
+ * export async function counterWorkflow(initialValue: number): Promise<void>;
+ * ```
+ *
+ * Start a new Workflow execution and get a handle for interacting with it:
+ * ```ts
+ * // Start the Workflow with initialValue of 2.
+ * const handle = await startWorkflow(counterWorkflow, { args: [2] });
+ * await handle.signal(incrementSignal, 2);
+ * await handle.result(); // throws WorkflowExecutionTerminatedError
+ * ```
+ */
+export interface ChildWorkflowHandle<T extends Workflow> extends BaseWorkflowHandle<T> {
+  /**
+   * The runId of the initial run of the bound Workflow
+   */
+  readonly firstExecutionRunId: string;
+}