@temporalio/workflow 1.0.0-rc.0 → 1.0.0-rc.1

package/src/index.ts

@@ -0,0 +1,91 @@
+/**
+ * This library provides tools required for authoring workflows.
+ *
+ * ## Usage
+ * See the {@link https://docs.temporal.io/typescript/hello-world#workflows | tutorial} for writing your first workflow.
+ *
+ * ### Timers
+ *
+ * The recommended way of scheduling timers is by using the {@link sleep} function. We've replaced `setTimeout` and
+ * `clearTimeout` with deterministic versions so these are also usable but have a limitation that they don't play well
+ * with {@link https://docs.temporal.io/typescript/workflow-scopes-and-cancellation | cancellation scopes}.
+ *
+ * <!--SNIPSTART typescript-sleep-workflow-->
+ * <!--SNIPEND-->
+ *
+ * ### Activities
+ *
+ * To schedule Activities, use {@link proxyActivities} to obtain an Activity function and call.
+ *
+ * <!--SNIPSTART typescript-schedule-activity-workflow-->
+ * <!--SNIPEND-->
+ *
+ * ### 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.
+ *
+ * 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`.
+ *
+ * #### Implementation
+ *
+ * <!--SNIPSTART typescript-workflow-signal-implementation-->
+ * <!--SNIPEND-->
+ *
+ * ### Deterministic built-ins
+ * It is safe to call `Math.random()` and `Date()` in workflow code as they are replaced with deterministic versions. We
+ * also provide a deterministic {@link uuid4} function for convenience.
+ *
+ * ### [Cancellation and scopes](https://docs.temporal.io/typescript/workflow-scopes-and-cancellation)
+ * - {@link CancellationScope}
+ * - {@link Trigger}
+ *
+ * ### [Sinks](https://docs.temporal.io/typescript/sinks)
+ * - {@link Sinks}
+ *
+ * @module
+ */
+
+export {
+  ActivityFailure,
+  ApplicationFailure,
+  CancelledFailure,
+  ChildWorkflowFailure,
+  defaultPayloadConverter,
+  PayloadConverter,
+  rootCause,
+  ServerFailure,
+  TemporalFailure,
+  TerminatedFailure,
+  TimeoutFailure,
+} from '@temporalio/common';
+export {
+  ActivityCancellationType,
+  ActivityFunction,
+  ActivityInterface, // eslint-disable-line deprecation/deprecation
+  ActivityOptions,
+  RetryPolicy,
+  UntypedActivities,
+} from '@temporalio/internal-workflow-common';
+export * from '@temporalio/internal-workflow-common/lib/errors';
+export * from '@temporalio/internal-workflow-common/lib/interfaces';
+export * from '@temporalio/internal-workflow-common/lib/workflow-handle';
+export * from '@temporalio/internal-workflow-common/lib/workflow-options';
+export { AsyncLocalStorage, CancellationScope, CancellationScopeOptions, ROOT_SCOPE } from './cancellation-scope';
+export * from './errors';
+export * from './interceptors';
+export {
+  ChildWorkflowCancellationType,
+  ChildWorkflowOptions,
+  ContinueAsNew,
+  ContinueAsNewOptions,
+  ParentClosePolicy,
+  ParentWorkflowInfo,
+  WorkflowInfo,
+} from './interfaces';
+export { Sink, SinkCall, SinkFunction, Sinks } from './sinks';
+export { Trigger } from './trigger';
+export * from './workflow';
+export { ChildWorkflowHandle, ExternalWorkflowHandle } from './workflow-handle';

package/src/interceptors.ts

@@ -0,0 +1,239 @@
+/**
+ * Type definitions and generic helpers for interceptors.
+ *
+ * The Workflow specific interceptors are defined here.
+ *
+ * @module
+ */
+
+import { WorkflowExecution } from '@temporalio/common';
+import { ActivityOptions, Headers, LocalActivityOptions, Next, Timestamp } from '@temporalio/internal-workflow-common';
+import type { coresdk } from '@temporalio/proto';
+import { ChildWorkflowOptionsWithDefaults, ContinueAsNewOptions } from './interfaces';
+
+export { Next, Headers };
+
+/** Input for WorkflowInboundCallsInterceptor.execute */
+export interface WorkflowExecuteInput {
+  readonly args: unknown[];
+  readonly headers: Headers;
+}
+
+/** Input for WorkflowInboundCallsInterceptor.handleSignal */
+export interface SignalInput {
+  readonly signalName: string;
+  readonly args: unknown[];
+  readonly headers: Headers;
+}
+
+/** Input for WorkflowInboundCallsInterceptor.handleQuery */
+export interface QueryInput {
+  readonly queryId: string;
+  readonly queryName: string;
+  readonly args: unknown[];
+  readonly headers: Headers;
+}
+
+/**
+ * Implement any of these methods to intercept Workflow inbound calls like execution, and signal and query handling.
+ */
+export interface WorkflowInboundCallsInterceptor {
+  /**
+   * Called when Workflow execute method is called
+   *
+   * @return result of the Workflow execution
+   */
+  execute?: (input: WorkflowExecuteInput, next: Next<this, 'execute'>) => Promise<unknown>;
+
+  /** Called when signal is delivered to a Workflow execution */
+  handleSignal?: (input: SignalInput, next: Next<this, 'handleSignal'>) => Promise<void>;
+
+  /**
+   * Called when a Workflow is queried
+   *
+   * @return result of the query
+   */
+  handleQuery?: (input: QueryInput, next: Next<this, 'handleQuery'>) => Promise<unknown>;
+}
+
+/** Input for WorkflowOutboundCallsInterceptor.scheduleActivity */
+export interface ActivityInput {
+  readonly activityType: string;
+  readonly args: unknown[];
+  readonly options: ActivityOptions;
+  readonly headers: Headers;
+  readonly seq: number;
+}
+
+/** Input for WorkflowOutboundCallsInterceptor.scheduleLocalActivity */
+export interface LocalActivityInput {
+  readonly activityType: string;
+  readonly args: unknown[];
+  readonly options: LocalActivityOptions;
+  readonly headers: Headers;
+  readonly seq: number;
+  readonly originalScheduleTime?: Timestamp;
+  readonly attempt: number;
+}
+
+/** Input for WorkflowOutboundCallsInterceptor.startChildWorkflowExecution */
+export interface StartChildWorkflowExecutionInput {
+  readonly workflowType: string;
+  readonly options: ChildWorkflowOptionsWithDefaults;
+  readonly headers: Headers;
+  readonly seq: number;
+}
+
+/** Input for WorkflowOutboundCallsInterceptor.startTimer */
+export interface TimerInput {
+  readonly durationMs: number;
+  readonly seq: number;
+}
+
+/**
+ * Same as ContinueAsNewOptions but workflowType must be defined
+ */
+export type ContinueAsNewInputOptions = ContinueAsNewOptions & Required<Pick<ContinueAsNewOptions, 'workflowType'>>;
+
+/** Input for WorkflowOutboundCallsInterceptor.continueAsNew */
+export interface ContinueAsNewInput {
+  readonly args: unknown[];
+  readonly headers: Headers;
+  readonly options: ContinueAsNewInputOptions;
+}
+
+/** Input for WorkflowOutboundCallsInterceptor.signalWorkflow */
+export interface SignalWorkflowInput {
+  readonly seq: number;
+  readonly signalName: string;
+  readonly args: unknown[];
+  readonly headers: Headers;
+  readonly target:
+    | {
+        readonly type: 'external';
+        readonly workflowExecution: WorkflowExecution;
+      }
+    | {
+        readonly type: 'child';
+        readonly childWorkflowId: string;
+      };
+}
+
+/**
+ * Implement any of these methods to intercept Workflow code calls to the Temporal APIs, like scheduling an activity and starting a timer
+ */
+export interface WorkflowOutboundCallsInterceptor {
+  /**
+   * Called when Workflow schedules an Activity
+   *
+   * @return result of the activity execution
+   */
+  scheduleActivity?: (input: ActivityInput, next: Next<this, 'scheduleActivity'>) => Promise<unknown>;
+
+  /**
+   * Called when Workflow schedules a local Activity
+   *
+   * @return result of the activity execution
+   */
+  scheduleLocalActivity?: (input: LocalActivityInput, next: Next<this, 'scheduleLocalActivity'>) => Promise<unknown>;
+
+  /**
+   * Called when Workflow starts a timer
+   */
+  startTimer?: (input: TimerInput, next: Next<this, 'startTimer'>) => Promise<void>;
+
+  /**
+   * Called when Workflow calls continueAsNew
+   */
+  continueAsNew?: (input: ContinueAsNewInput, next: Next<this, 'continueAsNew'>) => Promise<never>;
+
+  /**
+   * Called when Workflow signals a child or external Workflow
+   */
+  signalWorkflow?: (input: SignalWorkflowInput, next: Next<this, 'signalWorkflow'>) => Promise<void>;
+
+  /**
+   * Called when Workflow starts a child workflow execution, the interceptor function returns 2 promises:
+   *
+   * - The first resolves with the `runId` when the child workflow has started or rejects if failed to start.
+   * - The second resolves with the workflow result when the child workflow completes or rejects on failure.
+   */
+  startChildWorkflowExecution?: (
+    input: StartChildWorkflowExecutionInput,
+    next: Next<this, 'startChildWorkflowExecution'>
+  ) => Promise<[Promise<string>, Promise<unknown>]>;
+}
+
+/** Input for WorkflowInternalsInterceptor.concludeActivation */
+export interface ConcludeActivationInput {
+  commands: coresdk.workflow_commands.IWorkflowCommand[];
+}
+
+/** Output for WorkflowInternalsInterceptor.concludeActivation */
+export type ConcludeActivationOutput = ConcludeActivationInput;
+
+/** Input for WorkflowInternalsInterceptor.activate */
+export interface ActivateInput {
+  activation: coresdk.workflow_activation.IWorkflowActivation;
+  batchIndex: number;
+}
+
+/** Input for WorkflowInternalsInterceptor.dispose */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface DisposeInput {}
+
+/**
+ * Interceptor for the internals of the Workflow runtime.
+ *
+ * Use to manipulate or trace Workflow activations.
+ *
+ * @experimental
+ */
+export interface WorkflowInternalsInterceptor {
+  /**
+   * Called when the Workflow runtime runs a WorkflowActivationJob.
+   */
+  activate?(input: ActivateInput, next: Next<this, 'activate'>): void;
+
+  /**
+   * Called after all `WorkflowActivationJob`s have been processed for an activation.
+   *
+   * Can manipulate the commands generated by the Workflow
+   */
+  concludeActivation?(input: ConcludeActivationInput, next: Next<this, 'concludeActivation'>): ConcludeActivationOutput;
+
+  /**
+   * Called before disposing the Workflow isolate context.
+   *
+   * Implement this method to perform any resource cleanup.
+   */
+  dispose?(input: DisposeInput, next: Next<this, 'dispose'>): Promise<void>;
+}
+
+/**
+ * A mapping from interceptor type to an optional list of interceptor implementations
+ */
+export interface WorkflowInterceptors {
+  inbound?: WorkflowInboundCallsInterceptor[];
+  outbound?: WorkflowOutboundCallsInterceptor[];
+  internals?: WorkflowInternalsInterceptor[];
+}
+
+/**
+ * A function that returns {@link WorkflowInterceptors} and takes no arguments.
+ *
+ * Workflow interceptor modules should export an `interceptors` function of this type.
+ *
+ * @example
+ *
+ * ```ts
+ * export function interceptors(): WorkflowInterceptors {
+ *   return {
+ *     inbound: [],   // Populate with list of interceptor implementations
+ *     outbound: [],  // Populate with list of interceptor implementations
+ *     internals: [], // Populate with list of interceptor implementations
+ *   };
+ * }
+ * ```
+ */
+export type WorkflowInterceptorsFactory = () => WorkflowInterceptors;

package/src/interfaces.ts

@@ -0,0 +1,272 @@
+import { RetryPolicy, TemporalFailure } from '@temporalio/common';
+import { checkExtends, CommonWorkflowOptions, SearchAttributes } from '@temporalio/internal-workflow-common';
+import type { coresdk } from '@temporalio/proto';
+
+/**
+ * Workflow Execution information
+ */
+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;
+
+  /**
+   * ID of a single Workflow run
+   */
+  runId: string;
+
+  /**
+   * Workflow function's name
+   */
+  workflowType: string;
+
+  /**
+   * Indexed information attached to the Workflow Execution
+   */
+  searchAttributes: SearchAttributes;
+
+  /**
+   * Non-indexed information attached to the Workflow Execution
+   */
+  memo?: Record<string, unknown>;
+
+  /**
+   * Parent Workflow info (present if this is a Child Workflow)
+   */
+  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;
+
+  /**
+   * Failure from the previous Run (present when this Run is a retry, or the last Run of a Cron Workflow failed)
+   */
+  lastFailure?: TemporalFailure;
+
+  /**
+   * Task queue this Workflow is executing on
+   */
+  taskQueue: string;
+
+  /**
+   * Namespace this Workflow is executing in
+   */
+  namespace: string;
+
+  /**
+   * Run Id of the first Run in this Execution Chain
+   */
+  firstExecutionRunId: string;
+
+  /**
+   * The last Run Id in this Execution Chain
+   */
+  continuedFromExecutionRunId?: string;
+
+  // TODO expose from Core
+  /**
+   * Time at which the Workflow Run started
+   */
+  // startTime: Date;
+
+  /**
+   * Milliseconds after which the Workflow Execution is automatically terminated by Temporal Server. Set via {@link WorkflowOptions.workflowExecutionTimeout}.
+   */
+  executionTimeoutMs?: number;
+
+  /**
+   * Time at which the Workflow Execution expires
+   */
+  executionExpirationTime?: Date;
+
+  /**
+   * Milliseconds after which the Workflow Run is automatically terminated by Temporal Server. Set via {@link WorkflowOptions.workflowRunTimeout}.
+   */
+  runTimeoutMs?: number;
+
+  /**
+   * Maximum execution time of a Workflow Task in milliseconds. Set via {@link WorkflowOptions.workflowTaskTimeout}.
+   */
+  taskTimeoutMs: number;
+
+  /**
+   * Retry Policy for this Execution. Set via {@link WorkflowOptions.retry}.
+   */
+  retryPolicy?: RetryPolicy;
+
+  /**
+   * Starts at 1 and increments for every retry if there is a `retryPolicy`
+   */
+  attempt: number;
+
+  /**
+   * Cron Schedule for this Execution. Set via {@link WorkflowOptions.cronSchedule}.
+   */
+  cronSchedule?: string;
+
+  /**
+   * Milliseconds between Cron Runs
+   */
+  cronScheduleToScheduleInterval?: number;
+}
+
+export interface ParentWorkflowInfo {
+  workflowId: string;
+  runId: string;
+  namespace: string;
+}
+
+/**
+ * Not an actual error, used by the Workflow runtime to abort execution when {@link continueAsNew} is called
+ */
+export class ContinueAsNew extends Error {
+  public readonly name = 'ContinueAsNew';
+
+  constructor(public readonly command: coresdk.workflow_commands.IContinueAsNewWorkflowExecution) {
+    super('Workflow continued as new');
+  }
+}
+
+/**
+ * Options for continuing a Workflow as new
+ */
+export interface ContinueAsNewOptions {
+  /**
+   * A string representing the Workflow type name, e.g. the filename in the Node.js SDK or class name in Java
+   */
+  workflowType?: string;
+  /**
+   * Task queue to continue the Workflow in
+   */
+  taskQueue?: string;
+  /**
+   * Timeout for the entire Workflow run
+   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   */
+  workflowRunTimeout?: string;
+  /**
+   * Timeout for a single Workflow task
+   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   */
+  workflowTaskTimeout?: string;
+  /**
+   * Non-searchable attributes to attach to next Workflow run
+   */
+  memo?: Record<string, any>;
+  /**
+   * Searchable attributes to attach to next Workflow run
+   */
+  searchAttributes?: SearchAttributes;
+}
+
+/**
+ * Specifies:
+ * - whether cancellation requests are sent to the Child
+ * - whether and when a {@link CanceledFailure} is thrown from {@link executeChild} or
+ *   {@link ChildWorkflowHandle.result}
+ *
+ * @default {@link ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED}
+ */
+export enum ChildWorkflowCancellationType {
+  /**
+   * Don't send a cancellation request to the Child.
+   */
+  ABANDON = 0,
+
+  /**
+   * Send a cancellation request to the Child. Immediately throw the error.
+   */
+  TRY_CANCEL = 1,
+
+  /**
+   * Send a cancellation request to the Child. The Child may respect cancellation, in which case an error will be thrown
+   * when cancellation has completed, and {@link isCancellation}(error) will be true. On the other hand, the Child may
+   * ignore the cancellation request, in which case an error might be thrown with a different cause, or the Child may
+   * complete successfully.
+   *
+   * @default
+   */
+  WAIT_CANCELLATION_COMPLETED = 2,
+
+  /**
+   * Send a cancellation request to the Child. Throw the error once the Server receives the Child cancellation request.
+   */
+  WAIT_CANCELLATION_REQUESTED = 3,
+}
+
+checkExtends<coresdk.child_workflow.ChildWorkflowCancellationType, ChildWorkflowCancellationType>();
+
+/**
+ * How a Child Workflow reacts to the Parent Workflow reaching a Closed state.
+ *
+ * @see {@link https://docs.temporal.io/concepts/what-is-a-parent-close-policy/ | Parent Close Policy}
+ */
+export enum ParentClosePolicy {
+  /**
+   * If a `ParentClosePolicy` is set to this, or is not set at all, the server default value will be used.
+   */
+  PARENT_CLOSE_POLICY_UNSPECIFIED = 0,
+
+  /**
+   * When the Parent is Closed, the Child is Terminated.
+   *
+   * @default
+   */
+  PARENT_CLOSE_POLICY_TERMINATE = 1,
+
+  /**
+   * When the Parent is Closed, nothing is done to the Child.
+   */
+  PARENT_CLOSE_POLICY_ABANDON = 2,
+
+  /**
+   * When the Parent is Closed, the Child is Cancelled.
+   */
+  PARENT_CLOSE_POLICY_REQUEST_CANCEL = 3,
+}
+
+checkExtends<coresdk.child_workflow.ParentClosePolicy, ParentClosePolicy>();
+
+export interface ChildWorkflowOptions extends CommonWorkflowOptions {
+  /**
+   * Workflow id to use when starting. If not specified a UUID is generated. Note that it is
+   * dangerous as in case of client side retries no deduplication will happen based on the
+   * generated id. So prefer assigning business meaningful ids if possible.
+   */
+  workflowId?: string;
+
+  /**
+   * Task queue to use for Workflow tasks. It should match a task queue specified when creating a
+   * `Worker` that hosts the Workflow code.
+   */
+  taskQueue?: string;
+
+  /**
+   * Specifies:
+   * - whether cancellation requests are sent to the Child
+   * - whether and when an error is thrown from {@link executeChild} or
+   *   {@link ChildWorkflowHandle.result}
+   *
+   * @default {@link ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED}
+   */
+  cancellationType?: ChildWorkflowCancellationType;
+
+  /**
+   * Specifies how the Child reacts to the Parent Workflow reaching a Closed state.
+   *
+   * @default {@link ParentClosePolicy.PARENT_CLOSE_POLICY_TERMINATE}
+   */
+  parentClosePolicy?: ParentClosePolicy;
+}
+
+export type RequiredChildWorkflowOptions = Required<Pick<ChildWorkflowOptions, 'workflowId' | 'cancellationType'>> & {
+  args: unknown[];
+};
+
+export type ChildWorkflowOptionsWithDefaults = ChildWorkflowOptions & RequiredChildWorkflowOptions;