@temporalio/common - npm Package Compare versions

Comparing version 1.0.0-rc.0 to 1.0.0-rc.1

lib/converter/data-converter.d.ts

@@ -8,5 +8,5 @@ import { PayloadCodec } from './payload-codec';
  * The default `DataConverter` supports `undefined`, `Uint8Array`, and JSON serializables (so if
- * [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description)
- * works, the default data converter will work). Protobufs are supported via [this
- * API](https://docs.temporal.io/typescript/data-converters#protobufs).
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default data converter will work). Protobufs are supported via
+ * {@link https://docs.temporal.io/typescript/data-converters#protobufs | this API}.
  *
@@ -13,0 +13,0 @@ * Use a custom `DataConverter` to control the contents of your {@link Payload}s. Common reasons for using a custom

lib/converter/payload-converter.d.ts

@@ -5,3 +5,3 @@ import { Payload } from './types';
  *
- * This is called inside the [Workflow isolate](https://docs.temporal.io/typescript/determinism).
+ * This is called inside the {@link https://docs.temporal.io/typescript/determinism | Workflow isolate}.
  * To write async code or use Node APIs (or use packages that use Node APIs), use a {@link PayloadCodec}.
@@ -8,0 +8,0 @@ */

lib/converter/payload-converters.d.ts

@@ -59,4 +59,5 @@ import { PayloadConverter } from './payload-converter';
 /**
- * The default {@link PayloadConverter} used by the SDK.
- * Supports `Uint8Array` and JSON serializables (so if [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) works, the default payload converter will work).
+ * The default {@link PayloadConverter} used by the SDK. Supports `Uint8Array` and JSON serializables (so if
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default payload converter will work).
  *
@@ -63,0 +64,0 @@ * To also support Protobufs, create a custom payload converter with {@link DefaultPayloadConverter}:

lib/converter/payload-converters.js

@@ -115,4 +115,5 @@ "use strict";
 /**
- * The default {@link PayloadConverter} used by the SDK.
- * Supports `Uint8Array` and JSON serializables (so if [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) works, the default payload converter will work).
+ * The default {@link PayloadConverter} used by the SDK. Supports `Uint8Array` and JSON serializables (so if
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default payload converter will work).
  *
@@ -119,0 +120,0 @@ * To also support Protobufs, create a custom payload converter with {@link DefaultPayloadConverter}:

lib/failure.d.ts

@@ -53,23 +53,24 @@ import type { temporal } from '@temporalio/proto';
 /**
- * Application failure is used to communicate application specific failures between Workflows and
- * Activities.
+ * `ApplicationFailure`s are used to communicate application-specific failures in Workflows and Activities.
  *
- * Throw this exception to have full control over type and details if the exception delivered to
- * the caller workflow or client.
+ * The {@link type} property is matched against {@link RetryPolicy.nonRetryableErrorTypes} to determine if an instance
+ * of this error is retryable. Another way to avoid retrying is by setting the {@link nonRetryable} flag to `true`.
  *
- * Any unhandled exception which doesn't extend {@link TemporalFailure} is converted to an
- * instance of this class before being returned to a caller.
+ * In Workflows, if you throw a non-`ApplicationFailure`, the Workflow Task will fail and be retried. If you throw an
+ * `ApplicationFailure`, the Workflow Execution will fail.
  *
- * The {@link type} property is used by {@link temporal.common.RetryOptions} to determine if
- * an instance of this exception is non retryable. Another way to avoid retrying an exception of
- * this type is by setting {@link nonRetryable} flag to `true`.
+ * In Activities, you can either throw an `ApplicationFailure` or another `Error` to fail the Activity Task. In the
+ * latter case, the `Error` will be converted to an `ApplicationFailure`. If the
+ * {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the
+ * `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
+ * Workflow.
  *
- * The conversion of an exception that doesn't extend {@link TemporalFailure} to an
- * ApplicationFailure is done as following:
+ * The conversion of an error that doesn't extend {@link TemporalFailure} to an `ApplicationFailure` is done as
+ * following:
  *
- * - type is set to the exception full type name.
- * - message is set to the exception message
- * - nonRetryable is set to false
- * - details are set to null
- * - stack trace is copied from the original exception
+ * - `type` is set to `error.constructor?.name ?? error.name`
+ * - `message` is set to `error.message`
+ * - `nonRetryable` is set to false
+ * - `details` are set to null
+ * - stack trace is copied from the original error
  */
@@ -83,22 +84,19 @@ export declare class ApplicationFailure extends TemporalFailure {
     /**
-     * New ApplicationFailure with {@link nonRetryable} flag set to false. Note that this
-     * exception still can be not retried by the service if its type is included into doNotRetry
-     * property of the correspondent retry policy.
+     * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to false. Note that this error will still
+     * not be retried if its `type` is included in {@link RetryPolicy.nonRetryableErrorTypes}.
      *
-     * @param message optional error message
-     * @param type optional error type that is used by {@link RetryOptions.nonRetryableErrorTypes}.
-     * @param details optional details about the failure. They are serialized using the same approach
-     *     as arguments and results.
+     * @param message Optional error message
+     * @param type Optional error type (used by {@link RetryPolicy.nonRetryableErrorTypes})
+     * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}.
      */
     static retryable(message: string | undefined, type?: string, ...details: unknown[]): ApplicationFailure;
     /**
-     * New ApplicationFailure with {@link nonRetryable} flag set to true.
+     * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to true.
      *
-     * It means that this exception is not going to be retried even if it is not included into
-     * retry policy doNotRetry list.
+     * When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if `type` is not
+     * listed in {@link RetryPolicy.nonRetryableErrorTypes}).
      *
-     * @param message optional error message
-     * @param type optional error type
-     * @param details optional details about the failure. They are serialized using the same approach
-     *     as arguments and results.
+     * @param message Optional error message
+     * @param type Optional error type
+     * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}.
      */
@@ -108,3 +106,7 @@ static nonRetryable(message: string | undefined, type?: string, ...details: unknown[]): ApplicationFailure;
 /**
- * Used as the cause for when a Workflow or Activity has been cancelled
+ * 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
+ * your Workflow/Activity Execution will not receive further Cancellation requests.
+ *
+ * When a Workflow or Activity has been successfully cancelled, a `CancelledFailure` will be the `cause`.
  */
@@ -117,3 +119,3 @@ export declare class CancelledFailure extends TemporalFailure {
 /**
- * Used as the cause for when a Workflow has been terminated
+ * Used as the `cause` when a Workflow has been terminated
  */
@@ -134,4 +136,4 @@ export declare class TerminatedFailure extends TemporalFailure {
 /**
- * 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 is {@link TimeoutFailure}.
+ * 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}.
  *
@@ -145,7 +147,8 @@ * This exception is expected to be thrown only by the framework code.
     readonly identity: string | undefined;
+    readonly name: string;
     constructor(activityType: string, activityId: string | undefined, retryState: RetryState, identity: string | undefined, cause?: Error);
 }
 /**
- * Contains information about an child workflow failure. Always contains the original reason for the
- * failure as its cause. For example if a child workflow was terminated the cause is {@link TerminatedFailure}.
+ * 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}.
  *
@@ -159,2 +162,3 @@ * This exception is expected to be thrown only by the framework code.
     readonly retryState: RetryState;
+    readonly name: string;
     constructor(namespace: string | undefined, execution: WorkflowExecution, workflowType: string, retryState: RetryState, cause?: Error);
@@ -177,2 +181,10 @@ }
  *
+ * If `err` was already a `ApplicationFailure`, returns the original error.
+ *
+ * Otherwise returns an `ApplicationFailure` with `String(err)` as the message.
+ */
+export declare function ensureApplicationFailure(err: unknown): ApplicationFailure;
+/**
+ * If `err` is an Error it is turned into an `ApplicationFailure`.
+ *
  * If `err` was already a `TemporalFailure`, returns the original error.
@@ -198,7 +210,7 @@ *
 /**
- * Get the root cause (string) of given error `err`.
+ * Get the root cause message of given `error`.
  *
- * In case `err` is a {@link TemporalFailure}, recurse the cause chain and return the root's message.
- * Otherwise, return `err.message`.
+ * In case `error` is a {@link TemporalFailure}, recurse the `cause` chain and return the root `cause.message`.
+ * Otherwise, return `error.message`.
  */
-export declare function rootCause(err: unknown): string | undefined;
+export declare function rootCause(error: unknown): string | undefined;

lib/failure.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.rootCause = exports.failureToError = exports.failureToErrorInner = exports.optionalFailureToOptionalError = exports.ensureTemporalFailure = exports.errorToFailure = exports.cutoffStackTrace = exports.optionalErrorToOptionalFailure = exports.ChildWorkflowFailure = exports.ActivityFailure = exports.TimeoutFailure = exports.TerminatedFailure = exports.CancelledFailure = exports.ApplicationFailure = exports.ServerFailure = exports.TemporalFailure = exports.RetryState = exports.TimeoutType = exports.FAILURE_SOURCE = void 0;
+exports.rootCause = exports.failureToError = exports.failureToErrorInner = exports.optionalFailureToOptionalError = exports.ensureTemporalFailure = exports.ensureApplicationFailure = exports.errorToFailure = exports.cutoffStackTrace = exports.optionalErrorToOptionalFailure = exports.ChildWorkflowFailure = exports.ActivityFailure = exports.TimeoutFailure = exports.TerminatedFailure = exports.CancelledFailure = exports.ApplicationFailure = exports.ServerFailure = exports.TemporalFailure = exports.RetryState = exports.TimeoutType = exports.FAILURE_SOURCE = void 0;
 const internal_workflow_common_1 = require("@temporalio/internal-workflow-common");
@@ -62,23 +62,24 @@ const payload_converter_1 = require("./converter/payload-converter");
 /**
- * Application failure is used to communicate application specific failures between Workflows and
- * Activities.
+ * `ApplicationFailure`s are used to communicate application-specific failures in Workflows and Activities.
  *
- * Throw this exception to have full control over type and details if the exception delivered to
- * the caller workflow or client.
+ * The {@link type} property is matched against {@link RetryPolicy.nonRetryableErrorTypes} to determine if an instance
+ * of this error is retryable. Another way to avoid retrying is by setting the {@link nonRetryable} flag to `true`.
  *
- * Any unhandled exception which doesn't extend {@link TemporalFailure} is converted to an
- * instance of this class before being returned to a caller.
+ * In Workflows, if you throw a non-`ApplicationFailure`, the Workflow Task will fail and be retried. If you throw an
+ * `ApplicationFailure`, the Workflow Execution will fail.
  *
- * The {@link type} property is used by {@link temporal.common.RetryOptions} to determine if
- * an instance of this exception is non retryable. Another way to avoid retrying an exception of
- * this type is by setting {@link nonRetryable} flag to `true`.
+ * In Activities, you can either throw an `ApplicationFailure` or another `Error` to fail the Activity Task. In the
+ * latter case, the `Error` will be converted to an `ApplicationFailure`. If the
+ * {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the
+ * `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
+ * Workflow.
  *
- * The conversion of an exception that doesn't extend {@link TemporalFailure} to an
- * ApplicationFailure is done as following:
+ * The conversion of an error that doesn't extend {@link TemporalFailure} to an `ApplicationFailure` is done as
+ * following:
  *
- * - type is set to the exception full type name.
- * - message is set to the exception message
- * - nonRetryable is set to false
- * - details are set to null
- * - stack trace is copied from the original exception
+ * - `type` is set to `error.constructor?.name ?? error.name`
+ * - `message` is set to `error.message`
+ * - `nonRetryable` is set to false
+ * - `details` are set to null
+ * - stack trace is copied from the original error
  */
@@ -94,10 +95,8 @@ class ApplicationFailure extends TemporalFailure {
     /**
-     * New ApplicationFailure with {@link nonRetryable} flag set to false. Note that this
-     * exception still can be not retried by the service if its type is included into doNotRetry
-     * property of the correspondent retry policy.
+     * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to false. Note that this error will still
+     * not be retried if its `type` is included in {@link RetryPolicy.nonRetryableErrorTypes}.
      *
-     * @param message optional error message
-     * @param type optional error type that is used by {@link RetryOptions.nonRetryableErrorTypes}.
-     * @param details optional details about the failure. They are serialized using the same approach
-     *     as arguments and results.
+     * @param message Optional error message
+     * @param type Optional error type (used by {@link RetryPolicy.nonRetryableErrorTypes})
+     * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}.
      */
@@ -108,11 +107,10 @@ static retryable(message, type, ...details) {
     /**
-     * New ApplicationFailure with {@link nonRetryable} flag set to true.
+     * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to true.
      *
-     * It means that this exception is not going to be retried even if it is not included into
-     * retry policy doNotRetry list.
+     * When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if `type` is not
+     * listed in {@link RetryPolicy.nonRetryableErrorTypes}).
      *
-     * @param message optional error message
-     * @param type optional error type
-     * @param details optional details about the failure. They are serialized using the same approach
-     *     as arguments and results.
+     * @param message Optional error message
+     * @param type Optional error type
+     * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}.
      */
@@ -125,3 +123,7 @@ static nonRetryable(message, type, ...details) {
 /**
- * Used as the cause for when a Workflow or Activity has been cancelled
+ * 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
+ * your Workflow/Activity Execution will not receive further Cancellation requests.
+ *
+ * When a Workflow or Activity has been successfully cancelled, a `CancelledFailure` will be the `cause`.
  */
@@ -137,3 +139,3 @@ class CancelledFailure extends TemporalFailure {
 /**
- * Used as the cause for when a Workflow has been terminated
+ * Used as the `cause` when a Workflow has been terminated
  */
@@ -160,4 +162,4 @@ class TerminatedFailure extends TemporalFailure {
 /**
- * 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 is {@link TimeoutFailure}.
+ * 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}.
  *
@@ -173,2 +175,3 @@ * This exception is expected to be thrown only by the framework code.
         this.identity = identity;
+        this.name = 'ActivityFailure';
     }
@@ -178,4 +181,4 @@ }
 /**
- * Contains information about an child workflow failure. Always contains the original reason for the
- * failure as its cause. For example if a child workflow was terminated the cause is {@link TerminatedFailure}.
+ * 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}.
  *
@@ -191,2 +194,3 @@ * This exception is expected to be thrown only by the framework code.
         this.retryState = retryState;
+        this.name = 'ChildWorkflowFailure';
     }
@@ -336,11 +340,11 @@ }
  *
- * If `err` was already a `TemporalFailure`, returns the original error.
+ * If `err` was already a `ApplicationFailure`, returns the original error.
  *
  * Otherwise returns an `ApplicationFailure` with `String(err)` as the message.
  */
-function ensureTemporalFailure(err) {
-    if (err instanceof TemporalFailure) {
+function ensureApplicationFailure(err) {
+    if (err instanceof ApplicationFailure) {
         return err;
     }
-    else if (err instanceof Error) {
+    if (err instanceof Error) {
         const name = err.constructor?.name ?? err.name;
@@ -357,2 +361,16 @@ const failure = new ApplicationFailure(err.message, name, false);
 }
+exports.ensureApplicationFailure = ensureApplicationFailure;
+/**
+ * If `err` is an Error it is turned into an `ApplicationFailure`.
+ *
+ * If `err` was already a `TemporalFailure`, returns the original error.
+ *
+ * Otherwise returns an `ApplicationFailure` with `String(err)` as the message.
+ */
+function ensureTemporalFailure(err) {
+    if (err instanceof TemporalFailure) {
+        return err;
+    }
+    return ensureApplicationFailure(err);
+}
 exports.ensureTemporalFailure = ensureTemporalFailure;
@@ -417,16 +435,16 @@ /**
 /**
- * Get the root cause (string) of given error `err`.
+ * Get the root cause message of given `error`.
  *
- * In case `err` is a {@link TemporalFailure}, recurse the cause chain and return the root's message.
- * Otherwise, return `err.message`.
+ * In case `error` is a {@link TemporalFailure}, recurse the `cause` chain and return the root `cause.message`.
+ * Otherwise, return `error.message`.
  */
-function rootCause(err) {
-    if (err instanceof TemporalFailure) {
-        return err.cause ? rootCause(err.cause) : err.message;
+function rootCause(error) {
+    if (error instanceof TemporalFailure) {
+        return error.cause ? rootCause(error.cause) : error.message;
     }
-    if (err instanceof Error) {
-        return err.message;
+    if (error instanceof Error) {
+        return error.message;
     }
-    if (typeof err === 'string') {
-        return err;
+    if (typeof error === 'string') {
+        return error;
     }
@@ -433,0 +451,0 @@ return undefined;

lib/protobufs.d.ts

 /**
  * Entry point for classes and utilities related to using
- * [Protobufs](https://docs.temporal.io/typescript/data-converters#protobufs) for serialization.
+ * {@link https://docs.temporal.io/typescript/data-converters#protobufs | Protobufs} for serialization.
  *
@@ -13,2 +13,2 @@ * Import from `@temporalio/common/lib/protobufs`, for example:
 export * from './converter/protobuf-payload-converters';
-export * from './converter/patch-protobuf-root';
+export { patchProtobufRoot } from '@temporalio/proto/lib/patch-protobuf-root';

lib/protobufs.js

 "use strict";
 /**
  * Entry point for classes and utilities related to using
- * [Protobufs](https://docs.temporal.io/typescript/data-converters#protobufs) for serialization.
+ * {@link https://docs.temporal.io/typescript/data-converters#protobufs | Protobufs} for serialization.
  *
@@ -28,5 +28,7 @@ * Import from `@temporalio/common/lib/protobufs`, for example:
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchProtobufRoot = void 0;
 // Don't export from index, so we save space in Workflow bundles of users who don't use Protobufs
 __exportStar(require("./converter/protobuf-payload-converters"), exports);
-__exportStar(require("./converter/patch-protobuf-root"), exports);
+var patch_protobuf_root_1 = require("@temporalio/proto/lib/patch-protobuf-root");
+Object.defineProperty(exports, "patchProtobufRoot", { enumerable: true, get: function () { return patch_protobuf_root_1.patchProtobufRoot; } });
 //# sourceMappingURL=protobufs.js.map

package.json

 {
   "name": "@temporalio/common",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.1",
   "description": "Common library for code that's used across the Client, Worker, and/or Workflow",
@@ -15,5 +15,7 @@ "main": "lib/index.js",
   "dependencies": {
-    "@temporalio/internal-workflow-common": "^1.0.0-rc.0",
-    "@temporalio/proto": "^1.0.0-rc.0",
-    "proto3-json-serializer": "^0.1.6"
+    "@opentelemetry/api": "^1.0.3",
+    "@temporalio/internal-workflow-common": "^1.0.0-rc.1",
+    "@temporalio/proto": "^1.0.0-rc.1",
+    "proto3-json-serializer": "^1.0.2",
+    "protobufjs": "6.11.2"
   },
@@ -27,6 +29,7 @@ "bugs": {
   },
-  "devDependencies": {
-    "protobufjs": "^6.11.2"
-  },
-  "gitHead": "c25e91309b980f2118df4048d760306982019871"
+  "files": [
+    "src",
+    "lib"
+  ],
+  "gitHead": "723de0fbc7a04e68084ec99453578e7027eb3803"
 }

src/converter/data-converter.ts

@@ -10,5 +10,5 @@ import { PayloadCodec } from './payload-codec';
  * The default `DataConverter` supports `undefined`, `Uint8Array`, and JSON serializables (so if
- * [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description)
- * works, the default data converter will work). Protobufs are supported via [this
- * API](https://docs.temporal.io/typescript/data-converters#protobufs).
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default data converter will work). Protobufs are supported via
+ * {@link https://docs.temporal.io/typescript/data-converters#protobufs | this API}.
  *
@@ -15,0 +15,0 @@ * Use a custom `DataConverter` to control the contents of your {@link Payload}s. Common reasons for using a custom

src/converter/payload-converter.ts

@@ -6,3 +6,3 @@ import { Payload } from './types';
  *
- * This is called inside the [Workflow isolate](https://docs.temporal.io/typescript/determinism).
+ * This is called inside the {@link https://docs.temporal.io/typescript/determinism | Workflow isolate}.
  * To write async code or use Node APIs (or use packages that use Node APIs), use a {@link PayloadCodec}.
@@ -9,0 +9,0 @@ */

src/converter/payload-converters.ts

@@ -140,4 +140,5 @@ import { PayloadConverterError, ValueError } from '@temporalio/internal-workflow-common';
 /**
- * The default {@link PayloadConverter} used by the SDK.
- * Supports `Uint8Array` and JSON serializables (so if [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) works, the default payload converter will work).
+ * The default {@link PayloadConverter} used by the SDK. Supports `Uint8Array` and JSON serializables (so if
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default payload converter will work).
  *
@@ -144,0 +145,0 @@ * To also support Protobufs, create a custom payload converter with {@link DefaultPayloadConverter}:

src/failure.ts

@@ -73,23 +73,24 @@ import { checkExtends, hasOwnProperties, isRecord } from '@temporalio/internal-workflow-common';
 /**
- * Application failure is used to communicate application specific failures between Workflows and
- * Activities.
+ * `ApplicationFailure`s are used to communicate application-specific failures in Workflows and Activities.
  *
- * Throw this exception to have full control over type and details if the exception delivered to
- * the caller workflow or client.
+ * The {@link type} property is matched against {@link RetryPolicy.nonRetryableErrorTypes} to determine if an instance
+ * of this error is retryable. Another way to avoid retrying is by setting the {@link nonRetryable} flag to `true`.
  *
- * Any unhandled exception which doesn't extend {@link TemporalFailure} is converted to an
- * instance of this class before being returned to a caller.
+ * In Workflows, if you throw a non-`ApplicationFailure`, the Workflow Task will fail and be retried. If you throw an
+ * `ApplicationFailure`, the Workflow Execution will fail.
  *
- * The {@link type} property is used by {@link temporal.common.RetryOptions} to determine if
- * an instance of this exception is non retryable. Another way to avoid retrying an exception of
- * this type is by setting {@link nonRetryable} flag to `true`.
+ * In Activities, you can either throw an `ApplicationFailure` or another `Error` to fail the Activity Task. In the
+ * latter case, the `Error` will be converted to an `ApplicationFailure`. If the
+ * {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the
+ * `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
+ * Workflow.
  *
- * The conversion of an exception that doesn't extend {@link TemporalFailure} to an
- * ApplicationFailure is done as following:
+ * The conversion of an error that doesn't extend {@link TemporalFailure} to an `ApplicationFailure` is done as
+ * following:
  *
- * - type is set to the exception full type name.
- * - message is set to the exception message
- * - nonRetryable is set to false
- * - details are set to null
- * - stack trace is copied from the original exception
+ * - `type` is set to `error.constructor?.name ?? error.name`
+ * - `message` is set to `error.message`
+ * - `nonRetryable` is set to false
+ * - `details` are set to null
+ * - stack trace is copied from the original error
  */
@@ -110,10 +111,8 @@ export class ApplicationFailure extends TemporalFailure {
   /**
-   * New ApplicationFailure with {@link nonRetryable} flag set to false. Note that this
-   * exception still can be not retried by the service if its type is included into doNotRetry
-   * property of the correspondent retry policy.
+   * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to false. Note that this error will still
+   * not be retried if its `type` is included in {@link RetryPolicy.nonRetryableErrorTypes}.
    *
-   * @param message optional error message
-   * @param type optional error type that is used by {@link RetryOptions.nonRetryableErrorTypes}.
-   * @param details optional details about the failure. They are serialized using the same approach
-   *     as arguments and results.
+   * @param message Optional error message
+   * @param type Optional error type (used by {@link RetryPolicy.nonRetryableErrorTypes})
+   * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}.
    */
@@ -125,11 +124,10 @@ public static retryable(message: string | undefined, type?: string, ...details: unknown[]): ApplicationFailure {
   /**
-   * New ApplicationFailure with {@link nonRetryable} flag set to true.
+   * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to true.
    *
-   * It means that this exception is not going to be retried even if it is not included into
-   * retry policy doNotRetry list.
+   * When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if `type` is not
+   * listed in {@link RetryPolicy.nonRetryableErrorTypes}).
    *
-   * @param message optional error message
-   * @param type optional error type
-   * @param details optional details about the failure. They are serialized using the same approach
-   *     as arguments and results.
+   * @param message Optional error message
+   * @param type Optional error type
+   * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}.
    */
@@ -142,3 +140,7 @@ public static nonRetryable(message: string | undefined, type?: string, ...details: unknown[]): ApplicationFailure {
 /**
- * Used as the cause for when a Workflow or Activity has been cancelled
+ * 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
+ * your Workflow/Activity Execution will not receive further Cancellation requests.
+ *
+ * When a Workflow or Activity has been successfully cancelled, a `CancelledFailure` will be the `cause`.
  */
@@ -154,3 +156,3 @@ export class CancelledFailure extends TemporalFailure {
 /**
- * Used as the cause for when a Workflow has been terminated
+ * Used as the `cause` when a Workflow has been terminated
  */
@@ -181,4 +183,4 @@ export class TerminatedFailure extends TemporalFailure {
 /**
- * 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 is {@link TimeoutFailure}.
+ * 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}.
  *
@@ -188,2 +190,4 @@ * This exception is expected to be thrown only by the framework code.
 export class ActivityFailure extends TemporalFailure {
+  public readonly name: string = 'ActivityFailure';
+
   public constructor(
@@ -201,4 +205,4 @@ public readonly activityType: string,
 /**
- * Contains information about an child workflow failure. Always contains the original reason for the
- * failure as its cause. For example if a child workflow was terminated the cause is {@link TerminatedFailure}.
+ * 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}.
  *
@@ -208,2 +212,4 @@ * This exception is expected to be thrown only by the framework code.
 export class ChildWorkflowFailure extends TemporalFailure {
+  public readonly name: string = 'ChildWorkflowFailure';
+
   public constructor(
@@ -370,10 +376,11 @@ public readonly namespace: string | undefined,
  *
- * If `err` was already a `TemporalFailure`, returns the original error.
+ * If `err` was already a `ApplicationFailure`, returns the original error.
  *
  * Otherwise returns an `ApplicationFailure` with `String(err)` as the message.
  */
-export function ensureTemporalFailure(err: unknown): TemporalFailure {
-  if (err instanceof TemporalFailure) {
+export function ensureApplicationFailure(err: unknown): ApplicationFailure {
+  if (err instanceof ApplicationFailure) {
     return err;
-  } else if (err instanceof Error) {
+  }
+  if (err instanceof Error) {
     const name = err.constructor?.name ?? err.name;
@@ -391,2 +398,16 @@ const failure = new ApplicationFailure(err.message, name, false);
 /**
+ * If `err` is an Error it is turned into an `ApplicationFailure`.
+ *
+ * If `err` was already a `TemporalFailure`, returns the original error.
+ *
+ * Otherwise returns an `ApplicationFailure` with `String(err)` as the message.
+ */
+export function ensureTemporalFailure(err: unknown): TemporalFailure {
+  if (err instanceof TemporalFailure) {
+    return err;
+  }
+  return ensureApplicationFailure(err);
+}
+
+/**
  * Converts a Failure proto message to a JS Error object if defined or returns undefined.
@@ -494,18 +515,18 @@ */
 /**
- * Get the root cause (string) of given error `err`.
+ * Get the root cause message of given `error`.
  *
- * In case `err` is a {@link TemporalFailure}, recurse the cause chain and return the root's message.
- * Otherwise, return `err.message`.
+ * In case `error` is a {@link TemporalFailure}, recurse the `cause` chain and return the root `cause.message`.
+ * Otherwise, return `error.message`.
  */
-export function rootCause(err: unknown): string | undefined {
-  if (err instanceof TemporalFailure) {
-    return err.cause ? rootCause(err.cause) : err.message;
+export function rootCause(error: unknown): string | undefined {
+  if (error instanceof TemporalFailure) {
+    return error.cause ? rootCause(error.cause) : error.message;
   }
-  if (err instanceof Error) {
-    return err.message;
+  if (error instanceof Error) {
+    return error.message;
   }
-  if (typeof err === 'string') {
-    return err;
+  if (typeof error === 'string') {
+    return error;
   }
   return undefined;
 }

src/protobufs.ts

 /**
  * Entry point for classes and utilities related to using
- * [Protobufs](https://docs.temporal.io/typescript/data-converters#protobufs) for serialization.
+ * {@link https://docs.temporal.io/typescript/data-converters#protobufs | Protobufs} for serialization.
  *
@@ -15,2 +15,2 @@ * Import from `@temporalio/common/lib/protobufs`, for example:
 export * from './converter/protobuf-payload-converters';
-export * from './converter/patch-protobuf-root';
+export { patchProtobufRoot } from '@temporalio/proto/lib/patch-protobuf-root';

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Dev dependency count

0

decreased by-100%

Number of package files

59

increased by3.51%

Lines of code

3559

increased by13.02%

Worsened metrics

Total package byte prevSize

192518

decreased by-7.09%

Dependency count

5

increased by66.67%

Dependency changes

• + Added@opentelemetry/api@^1.0.3

• + Addedprotobufjs@6.11.2

• + Added@opentelemetry/api@1.9.0(transitive)

• + Addedproto3-json-serializer@1.1.1(transitive)

• + Addedprotobufjs@6.11.2(transitive)

• - Removedproto3-json-serializer@0.1.9(transitive)

• - Removedprotobufjs@6.11.4(transitive)

• Updated@temporalio/internal-workflow-common@^1.0.0-rc.1

• Updated@temporalio/proto@^1.0.0-rc.1

• Updatedproto3-json-serializer@^1.0.2