@temporalio/common 1.8.0 → 1.8.2

package/src/failure.ts

@@ -1,5 +1,5 @@
 import type { temporal } from '@temporalio/proto';
-import { checkExtends, isRecord } from './type-helpers';
+import { checkExtends, errorMessage, isRecord, SymbolBasedInstanceOfError } from './type-helpers';
 
 export const FAILURE_SOURCE = 'TypeScriptSDK';
 export type ProtoFailure = temporal.api.failure.v1.IFailure;
@@ -35,8 +35,6 @@ checkExtends<RetryState, temporal.api.enums.v1.RetryState>();
 
 export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
 
-const isTemporalFailure = Symbol.for('__temporal_isTemporalFailure');
-
 /**
  * Represents failures that can cross Workflow and Activity boundaries.
  *
@@ -44,8 +42,8 @@ const isTemporalFailure = Symbol.for('__temporal_isTemporalFailure');
  *
  * The only child class you should ever throw from your code is {@link ApplicationFailure}.
  */
+@SymbolBasedInstanceOfError('TemporalFailure')
 export class TemporalFailure extends Error {
-  public readonly name: string = 'TemporalFailure';
   /**
    * The original failure that constructed this error.
    *
@@ -56,45 +54,16 @@ export class TemporalFailure extends Error {
   constructor(message?: string | undefined | null, public readonly cause?: Error) {
     super(message ?? undefined);
   }
-
-  /**
-   * Marker to determine whether an error is an instance of TemporalFailure.
-   */
-  protected readonly [isTemporalFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is TemporalFailure {
-    return error instanceof TemporalFailure || (error instanceof Error && (error as any)[isTemporalFailure]);
-  }
 }
 
-const isServerFailure = Symbol.for('__temporal_isServerFailure');
-
 /** Exceptions originated at the Temporal service. */
+@SymbolBasedInstanceOfError('ServerFailure')
 export class ServerFailure extends TemporalFailure {
-  public readonly name: string = 'ServerFailure';
-
   constructor(message: string | undefined, public readonly nonRetryable: boolean, cause?: Error) {
     super(message, cause);
   }
-
-  /**
-   * Marker to determine whether an error is an instance of ServerFailure.
-   */
-  protected readonly [isServerFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is ServerFailure {
-    return error instanceof ServerFailure || (error instanceof Error && (error as any)[isServerFailure]);
-  }
 }
 
-const isApplicationFailure = Symbol.for('__temporal_isApplicationFailure');
-
 /**
  * `ApplicationFailure`s are used to communicate application-specific failures in Workflows and Activities.
  *
@@ -117,9 +86,8 @@ const isApplicationFailure = Symbol.for('__temporal_isApplicationFailure');
  * `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
  * Workflow.
  */
+@SymbolBasedInstanceOfError('ApplicationFailure')
 export class ApplicationFailure extends TemporalFailure {
-  public readonly name: string = 'ApplicationFailure';
-
   /**
    * Alternatively, use {@link fromError} or {@link create}.
    */
@@ -133,18 +101,6 @@ export class ApplicationFailure extends TemporalFailure {
     super(message, cause);
   }
 
-  /**
-   * Marker to determine whether an error is an instance of ApplicationFailure.
-   */
-  protected readonly [isApplicationFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is ApplicationFailure {
-    return error instanceof ApplicationFailure || (error instanceof Error && (error as any)[isApplicationFailure]);
-  }
-
   /**
    * Create a new `ApplicationFailure` from an Error object.
    *
@@ -223,8 +179,6 @@ export interface ApplicationFailureOptions {
   cause?: Error;
 }
 
-const isCancelledFailure = Symbol.for('__temporal_isCancelledFailure');
-
 /**
  * This error is thrown when Cancellation has been requested. To allow Cancellation to happen, let it propagate. To
  * ignore Cancellation, catch it and continue executing. Note that Cancellation can only be requested a single time, so
@@ -232,59 +186,28 @@ const isCancelledFailure = Symbol.for('__temporal_isCancelledFailure');
  *
  * When a Workflow or Activity has been successfully cancelled, a `CancelledFailure` will be the `cause`.
  */
+@SymbolBasedInstanceOfError('CancelledFailure')
 export class CancelledFailure extends TemporalFailure {
-  public readonly name: string = 'CancelledFailure';
-
   constructor(message: string | undefined, public readonly details: unknown[] = [], cause?: Error) {
     super(message, cause);
   }
-
-  /**
-   * Marker to determine whether an error is an instance of CancelledFailure.
-   */
-  protected readonly [isCancelledFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is CancelledFailure {
-    return error instanceof CancelledFailure || (error instanceof Error && (error as any)[isCancelledFailure]);
-  }
 }
 
-const isTerminatedFailure = Symbol.for('__temporal_isTerminatedFailure');
-
 /**
  * Used as the `cause` when a Workflow has been terminated
  */
+@SymbolBasedInstanceOfError('TerminatedFailure')
 export class TerminatedFailure extends TemporalFailure {
-  public readonly name: string = 'TerminatedFailure';
-
   constructor(message: string | undefined, cause?: Error) {
     super(message, cause);
   }
-
-  /**
-   * Marker to determine whether an error is an instance of TerminatedFailure.
-   */
-  protected readonly [isTerminatedFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is TerminatedFailure {
-    return error instanceof TerminatedFailure || (error instanceof Error && (error as any)[isTerminatedFailure]);
-  }
 }
 
-const isTimeoutFailure = Symbol.for('__temporal_isTimeoutFailure');
-
 /**
  * Used to represent timeouts of Activities and Workflows
  */
+@SymbolBasedInstanceOfError('TimeoutFailure')
 export class TimeoutFailure extends TemporalFailure {
-  public readonly name: string = 'TimeoutFailure';
-
   constructor(
     message: string | undefined,
     public readonly lastHeartbeatDetails: unknown,
@@ -292,31 +215,16 @@ export class TimeoutFailure extends TemporalFailure {
   ) {
     super(message);
   }
-
-  /**
-   * Marker to determine whether an error is an instance of TimeoutFailure.
-   */
-  protected readonly [isTimeoutFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is TimeoutFailure {
-    return error instanceof TimeoutFailure || (error instanceof Error && (error as any)[isTimeoutFailure]);
-  }
 }
 
-const isActivityFailure = Symbol.for('__temporal_isActivityFailure');
-
 /**
  * Contains information about an Activity failure. Always contains the original reason for the failure as its `cause`.
  * For example, if an Activity timed out, the cause will be a {@link TimeoutFailure}.
  *
  * This exception is expected to be thrown only by the framework code.
  */
+@SymbolBasedInstanceOfError('ActivityFailure')
 export class ActivityFailure extends TemporalFailure {
-  public readonly name: string = 'ActivityFailure';
-
   public constructor(
     message: string | undefined,
     public readonly activityType: string,
@@ -327,31 +235,16 @@ export class ActivityFailure extends TemporalFailure {
   ) {
     super(message, cause);
   }
-
-  /**
-   * Marker to determine whether an error is an instance of ActivityFailure.
-   */
-  protected readonly [isActivityFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is ActivityFailure {
-    return error instanceof ActivityFailure || (error instanceof Error && (error as any)[isActivityFailure]);
-  }
 }
 
-const isChildWorkflowFailure = Symbol.for('__temporal_isChildWorkflowFailure');
-
 /**
  * Contains information about a Child Workflow failure. Always contains the reason for the failure as its {@link cause}.
  * For example, if the Child was Terminated, the `cause` is a {@link TerminatedFailure}.
  *
  * This exception is expected to be thrown only by the framework code.
  */
+@SymbolBasedInstanceOfError('ChildWorkflowFailure')
 export class ChildWorkflowFailure extends TemporalFailure {
-  public readonly name: string = 'ChildWorkflowFailure';
-
   public constructor(
     public readonly namespace: string | undefined,
     public readonly execution: WorkflowExecution,
@@ -361,18 +254,6 @@ export class ChildWorkflowFailure extends TemporalFailure {
   ) {
     super('Child Workflow execution failed', cause);
   }
-
-  /**
-   * Marker to determine whether an error is an instance of ChildWorkflowFailure.
-   */
-  protected readonly [isChildWorkflowFailure] = true;
-
-  /**
-   * Instanceof check that works when multiple versions of @temporalio/common are installed.
-   */
-  static is(error: unknown): error is ChildWorkflowFailure {
-    return error instanceof ChildWorkflowFailure || (error instanceof Error && (error as any)[isChildWorkflowFailure]);
-  }
 }
 
 /**
@@ -385,7 +266,7 @@ export class ChildWorkflowFailure extends TemporalFailure {
  * - `stack`: `error.stack` or `''`
  */
 export function ensureApplicationFailure(error: unknown): ApplicationFailure {
-  if (ApplicationFailure.is(error)) {
+  if (error instanceof ApplicationFailure) {
     return error;
   }
 
@@ -404,7 +285,7 @@ export function ensureApplicationFailure(error: unknown): ApplicationFailure {
  * Otherwise returns an `ApplicationFailure` with `String(err)` as the message.
  */
 export function ensureTemporalFailure(err: unknown): TemporalFailure {
-  if (TemporalFailure.is(err)) {
+  if (err instanceof TemporalFailure) {
     return err;
   }
   return ensureApplicationFailure(err);
@@ -417,14 +298,8 @@ export function ensureTemporalFailure(err: unknown): TemporalFailure {
  * Otherwise, return `error.message`.
  */
 export function rootCause(error: unknown): string | undefined {
-  if (TemporalFailure.is(error)) {
+  if (error instanceof TemporalFailure) {
     return error.cause ? rootCause(error.cause) : error.message;
   }
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (typeof error === 'string') {
-    return error;
-  }
-  return undefined;
+  return errorMessage(error);
 }

package/src/index.ts

@@ -23,6 +23,7 @@ export * from './retry-policy';
 export { type Timestamp, Duration, StringValue } from './time';
 export * from './workflow-handle';
 export * from './workflow-options';
+export * from './versioning-intent';
 
 /**
  * Encode a UTF-8 string into a Uint8Array

package/src/type-helpers.ts

@@ -21,7 +21,6 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-// ts-prune-ignore-next
 export function hasOwnProperty<X extends Record<string, unknown>, Y extends PropertyKey>(
   record: X,
   prop: Y
@@ -36,15 +35,27 @@ export function hasOwnProperties<X extends Record<string, unknown>, Y extends Pr
   return props.every((prop) => prop in record);
 }
 
+export function isError(error: unknown): error is Error {
+  return (
+    isRecord(error) &&
+    typeof error.name === 'string' &&
+    typeof error.message === 'string' &&
+    (error.stack == null || typeof error.stack === 'string')
+  );
+}
+
+export function isAbortError(error: unknown): error is Error & { name: 'AbortError' } {
+  return isError(error) && error.name === 'AbortError';
+}
+
 /**
  * Get `error.message` (or `undefined` if not present)
  */
 export function errorMessage(error: unknown): string | undefined {
-  if (typeof error === 'string') {
-    return error;
-  }
-  if (error instanceof Error) {
+  if (isError(error)) {
     return error.message;
+  } else if (typeof error === 'string') {
+    return error;
   }
   return undefined;
 }
@@ -52,16 +63,17 @@ export function errorMessage(error: unknown): string | undefined {
 interface ErrorWithCode {
   code: string;
 }
+
+function isErrorWithCode(error: unknown): error is ErrorWithCode {
+  return isRecord(error) && typeof error.code === 'string';
+}
+
 /**
  * Get `error.code` (or `undefined` if not present)
  */
 export function errorCode(error: unknown): string | undefined {
-  if (
-    typeof error === 'object' &&
-    (error as ErrorWithCode).code !== undefined &&
-    typeof (error as ErrorWithCode).code === 'string'
-  ) {
-    return (error as ErrorWithCode).code;
+  if (isErrorWithCode(error)) {
+    return error.code;
   }
 
   return undefined;
@@ -73,3 +85,58 @@ export function errorCode(error: unknown): string | undefined {
 export function assertNever(msg: string, x: never): never {
   throw new TypeError(msg + ': ' + x);
 }
+
+export type Class<E extends Error> = {
+  new (...args: any[]): E;
+  prototype: E;
+};
+
+/**
+ * A decorator to be used on error classes. It adds the 'name' property AND provides a custom
+ * 'instanceof' handler that works correctly across execution contexts.
+ *
+ * ### Details ###
+ *
+ * According to the EcmaScript's spec, the default behavior of JavaScript's `x instanceof Y` operator is to walk up the
+ * prototype chain of object 'x', checking if any constructor in that hierarchy is _exactly the same object_ as the
+ * constructor function 'Y'.
+ *
+ * Unfortunately, it happens in various situations that different constructor function objects get created for what
+ * appears to be the very same class. This leads to surprising behavior where `instanceof` returns false though it is
+ * known that the object is indeed an instance of that class. One particular case where this happens is when constructor
+ * 'Y' belongs to a different realm than the constuctor with which 'x' was instantiated. Another case is when two copies
+ * of the same library gets loaded in the same realm.
+ *
+ * In practice, this tends to cause issues when crossing the workflow-sandboxing boundary (since Node's vm module
+ * really creates new execution realms), as well as when running tests using Jest (see https://github.com/jestjs/jest/issues/2549
+ * for some details on that one).
+ *
+ * This function injects a custom 'instanceof' handler into the prototype of 'clazz', which is both cross-realm safe and
+ * cross-copies-of-the-same-lib safe. It works by adding a special symbol property to the prototype of 'clazz', and then
+ * checking for the presence of that symbol.
+ */
+export function SymbolBasedInstanceOfError<E extends Error>(markerName: string): (clazz: Class<E>) => void {
+  return (clazz: Class<E>): void => {
+    const marker = Symbol.for(`__temporal_is${markerName}`);
+
+    Object.defineProperty(clazz.prototype, 'name', { value: markerName, enumerable: true });
+    Object.defineProperty(clazz.prototype, marker, { value: true, enumerable: false });
+    Object.defineProperty(clazz, Symbol.hasInstance, {
+      // eslint-disable-next-line object-shorthand
+      value: function (this: any, error: object): boolean {
+        if (this === clazz) {
+          return isRecord(error) && (error as any)[marker] === true;
+        } else {
+          // 'this' must be a _subclass_ of clazz that doesn't redefined [Symbol.hasInstance], so that it inherited
+          // from clazz's [Symbol.hasInstance]. If we don't handle this particular situation, then
+          // `x instanceof SubclassOfParent` would return true for any instance of 'Parent', which is clearly wrong.
+          //
+          // Ideally, it'd be preferable to avoid this case entirely, by making sure that all subclasses of 'clazz'
+          // redefine [Symbol.hasInstance], but we can't enforce that. We therefore fallback to the default instanceof
+          // behavior (which is NOT cross-realm safe).
+          return this.prototype.isPrototypeOf(error); // eslint-disable-line no-prototype-builtins
+        }
+      },
+    });
+  };
+}

package/src/versioning-intent.ts

@@ -0,0 +1,18 @@
+/**
+ * Indicates whether the user intends certain commands to be run on a compatible worker Build Id
+ * version or not.
+ *
+ * `COMPATIBLE` indicates that the command should run on a worker with compatible version if
+ * possible. It may not be possible if the target task queue does not also have knowledge of the
+ * current worker's Build Id.
+ *
+ * `DEFAULT` indicates that the command should run on the target task queue's current
+ * overall-default Build Id.
+ *
+ * Where this type is accepted optionally, an unset value indicates that the SDK should choose the
+ * most sensible default behavior for the type of command, accounting for whether the command will
+ * be run on the same task queue as the current worker.
+ *
+ * @experimental
+ */
+export type VersioningIntent = 'COMPATIBLE' | 'DEFAULT';