@temporalio/activity 1.1.0 → 1.3.0

package/lib/index.d.ts

@@ -15,15 +15,37 @@
  *
  * ### Cancellation
  *
- * Activity Cancellation serves three purposes:
+ * Activity Cancellation:
  *
- * - It lets an Activity know it doesn't need to keep doing work.
- * - It gives the Activity time to clean up any resources it has created.
+ * - lets the Activity know it doesn't need to keep doing work, and
+ * - gives the Activity time to clean up any resources it has created.
  *
- * Activities may receive Cancellation only if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * Activities can only receive Cancellation if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
  * (which can't heartbeat but receive Cancellation anyway).
  *
- * There are two ways to handle Activity cancellation:
+ * An Activity may receive Cancellation if:
+ *
+ * - The Workflow scope containing the Activity call was requested to be Cancelled and
+ *   {@link ActivityOptions.cancellationType} was **not** set to {@link ActivityCancellationType.ABANDON}. The scope can
+ *   be cancelled in either of the following ways:
+ *   - The entire Workflow was Cancelled (via {@link WorkflowHandle.cancel}).
+ *   - Calling {@link CancellationScope.cancel}) from inside a Workflow.
+ * - The Worker has started to shut down. Shutdown is initiated by either:
+ *   - One of the {@link RuntimeOptions.shutdownSignals} was sent to the process.
+ *   - {@link Worker.shutdown | `Worker.shutdown()`} was called.
+ * - The Activity was considered failed by the Server because any of the Activity timeouts have triggered (for example,
+ *   the Server didn't receive a heartbeat within the {@link ActivityOptions.heartbeatTimeout}). The
+ *   {@link CancelledFailure} will have `message: 'TIMED_OUT'`.
+ * - An Activity sends a heartbeat with `Context.current().heartbeat()` and the heartbeat details can't be converted by
+ *   the Worker's configured {@link DataConverter}.
+ * - The Workflow Run reached a {@link https://docs.temporal.io/workflows#status | Closed state}, in which case the
+ *   {@link CancelledFailure} will have `message: 'NOT_FOUND'`.
+ *
+ * The reason for the Cancellation is available at {@link CancelledFailure.message} or
+ * {@link Context#cancellationSignal | Context.cancellationSignal.reason}.
+ *
+ * There are two ways to handle Activity Cancellation:
+ *
  * 1. await on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
  * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
@@ -31,7 +53,7 @@
  *
  * ### Examples
  *
- * #### An Activity that sends progress heartbeats and can be cancelled
+ * #### An Activity that sends progress heartbeats and can be Cancelled
  *
  * <!--SNIPSTART typescript-activity-fake-progress-->
  * <!--SNIPEND-->
@@ -56,7 +78,7 @@ UntypedActivities, errorMessage, errorCode, } from '@temporalio/internal-workflo
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
  * The Activity can then be completed asynchronously (from anywhere—usually outside the Worker) using
- * {@link AsyncCompletionClient}.
+ * {@link Client.activity}.
  *
  * @example
  *
@@ -218,7 +240,7 @@ export declare class Context {
     static current(): Context;
     /**
      * Helper function for sleeping in an Activity.
-     * @param ms Sleep duration: an {@link https://www.npmjs.com/package/ms | ms}-formatted string or number of milliseconds
+     * @param ms Sleep duration: number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
      * @returns A Promise that either resolves when `ms` is reached or rejects when the Activity is cancelled
      */
     sleep(ms: number | string): Promise<void>;

package/lib/index.js

@@ -16,15 +16,37 @@
  *
  * ### Cancellation
  *
- * Activity Cancellation serves three purposes:
+ * Activity Cancellation:
  *
- * - It lets an Activity know it doesn't need to keep doing work.
- * - It gives the Activity time to clean up any resources it has created.
+ * - lets the Activity know it doesn't need to keep doing work, and
+ * - gives the Activity time to clean up any resources it has created.
  *
- * Activities may receive Cancellation only if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * Activities can only receive Cancellation if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
  * (which can't heartbeat but receive Cancellation anyway).
  *
- * There are two ways to handle Activity cancellation:
+ * An Activity may receive Cancellation if:
+ *
+ * - The Workflow scope containing the Activity call was requested to be Cancelled and
+ *   {@link ActivityOptions.cancellationType} was **not** set to {@link ActivityCancellationType.ABANDON}. The scope can
+ *   be cancelled in either of the following ways:
+ *   - The entire Workflow was Cancelled (via {@link WorkflowHandle.cancel}).
+ *   - Calling {@link CancellationScope.cancel}) from inside a Workflow.
+ * - The Worker has started to shut down. Shutdown is initiated by either:
+ *   - One of the {@link RuntimeOptions.shutdownSignals} was sent to the process.
+ *   - {@link Worker.shutdown | `Worker.shutdown()`} was called.
+ * - The Activity was considered failed by the Server because any of the Activity timeouts have triggered (for example,
+ *   the Server didn't receive a heartbeat within the {@link ActivityOptions.heartbeatTimeout}). The
+ *   {@link CancelledFailure} will have `message: 'TIMED_OUT'`.
+ * - An Activity sends a heartbeat with `Context.current().heartbeat()` and the heartbeat details can't be converted by
+ *   the Worker's configured {@link DataConverter}.
+ * - The Workflow Run reached a {@link https://docs.temporal.io/workflows#status | Closed state}, in which case the
+ *   {@link CancelledFailure} will have `message: 'NOT_FOUND'`.
+ *
+ * The reason for the Cancellation is available at {@link CancelledFailure.message} or
+ * {@link Context#cancellationSignal | Context.cancellationSignal.reason}.
+ *
+ * There are two ways to handle Activity Cancellation:
+ *
  * 1. await on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
  * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
@@ -32,7 +54,7 @@
  *
  * ### Examples
  *
- * #### An Activity that sends progress heartbeats and can be cancelled
+ * #### An Activity that sends progress heartbeats and can be Cancelled
  *
  * <!--SNIPSTART typescript-activity-fake-progress-->
  * <!--SNIPEND-->
@@ -61,7 +83,7 @@ Object.defineProperty(exports, "errorCode", { enumerable: true, get: function ()
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
  * The Activity can then be completed asynchronously (from anywhere—usually outside the Worker) using
- * {@link AsyncCompletionClient}.
+ * {@link Client.activity}.
  *
  * @example
  *
@@ -137,7 +159,7 @@ class Context {
     }
     /**
      * Helper function for sleeping in an Activity.
-     * @param ms Sleep duration: an {@link https://www.npmjs.com/package/ms | ms}-formatted string or number of milliseconds
+     * @param ms Sleep duration: number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
      * @returns A Promise that either resolves when `ms` is reached or rejects when the Activity is cancelled
      */
     sleep(ms) {

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;;;AAEH,mFAAkE;AAElE,6CAAgD;AAChD,6CAA0E;AAAjE,0GAAA,gBAAgB,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAC7C,iFAM8C;AAF5C,wHAAA,YAAY,OAAA;AACZ,qHAAA,SAAS,OAAA;AAGX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAG3C;QACE,KAAK,EAAE,CAAC;QAHM,SAAI,GAAW,oBAAoB,CAAC;IAIpD,CAAC;CACF;AAND,gDAMC;AAED,cAAc;AACD,QAAA,iBAAiB,GAAG,IAAI,+BAAiB,EAAW,CAAC;AA8ElE;;;;;;;;;GASG;AACH,MAAa,OAAO;IA8BlB;;;;OAIG;IACH,YACE,IAAU,EACV,SAAyB,EACzB,kBAA+B,EAC/B,SAAkC;QAElC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,SAAS,CAAC,OAAiB;QAChC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,OAAO;QACnB,MAAM,KAAK,GAAG,yBAAiB,CAAC,QAAQ,EAAE,CAAC;QAC3C,IAAI,KAAK,KAAK,SAAS,EAAE;YACvB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;SACrD;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,EAAmB;QAC9B,IAAI,MAAsB,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC1C,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,IAAA,qCAAU,EAAC,EAAE,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IACnF,CAAC;CACF;AA3FD,0BA2FC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;;;AAEH,mFAAkE;AAElE,6CAAgD;AAChD,6CAA0E;AAAjE,0GAAA,gBAAgB,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAC7C,iFAM8C;AAF5C,wHAAA,YAAY,OAAA;AACZ,qHAAA,SAAS,OAAA;AAGX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAG3C;QACE,KAAK,EAAE,CAAC;QAHM,SAAI,GAAW,oBAAoB,CAAC;IAIpD,CAAC;CACF;AAND,gDAMC;AAED,cAAc;AACD,QAAA,iBAAiB,GAAG,IAAI,+BAAiB,EAAW,CAAC;AA8ElE;;;;;;;;;GASG;AACH,MAAa,OAAO;IA8BlB;;;;OAIG;IACH,YACE,IAAU,EACV,SAAyB,EACzB,kBAA+B,EAC/B,SAAkC;QAElC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,SAAS,CAAC,OAAiB;QAChC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,OAAO;QACnB,MAAM,KAAK,GAAG,yBAAiB,CAAC,QAAQ,EAAE,CAAC;QAC3C,IAAI,KAAK,KAAK,SAAS,EAAE;YACvB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;SACrD;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,EAAmB;QAC9B,IAAI,MAAsB,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC1C,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,IAAA,qCAAU,EAAC,EAAE,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IACnF,CAAC;CACF;AA3FD,0BA2FC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/activity",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Temporal.io SDK Activity sub-package",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,8 +13,8 @@
   "author": "Temporal Technologies Inc. <sdk@temporal.io>",
   "license": "MIT",
   "dependencies": {
-    "@temporalio/common": "^1.1.0",
-    "@temporalio/internal-workflow-common": "^1.1.0",
+    "@temporalio/common": "^1.3.0",
+    "@temporalio/internal-workflow-common": "^1.3.0",
     "abort-controller": "^3.0.0"
   },
   "bugs": {
@@ -28,5 +28,5 @@
     "src",
     "lib"
   ],
-  "gitHead": "132f23a47a93fecf3f39836b31f08ea837b30320"
+  "gitHead": "966d51d3545a5e84102190f5b762160b9dfe99c2"
 }

package/src/index.ts

@@ -15,15 +15,37 @@
  *
  * ### Cancellation
  *
- * Activity Cancellation serves three purposes:
+ * Activity Cancellation:
  *
- * - It lets an Activity know it doesn't need to keep doing work.
- * - It gives the Activity time to clean up any resources it has created.
+ * - lets the Activity know it doesn't need to keep doing work, and
+ * - gives the Activity time to clean up any resources it has created.
  *
- * Activities may receive Cancellation only if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * Activities can only receive Cancellation if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
  * (which can't heartbeat but receive Cancellation anyway).
  *
- * There are two ways to handle Activity cancellation:
+ * An Activity may receive Cancellation if:
+ *
+ * - The Workflow scope containing the Activity call was requested to be Cancelled and
+ *   {@link ActivityOptions.cancellationType} was **not** set to {@link ActivityCancellationType.ABANDON}. The scope can
+ *   be cancelled in either of the following ways:
+ *   - The entire Workflow was Cancelled (via {@link WorkflowHandle.cancel}).
+ *   - Calling {@link CancellationScope.cancel}) from inside a Workflow.
+ * - The Worker has started to shut down. Shutdown is initiated by either:
+ *   - One of the {@link RuntimeOptions.shutdownSignals} was sent to the process.
+ *   - {@link Worker.shutdown | `Worker.shutdown()`} was called.
+ * - The Activity was considered failed by the Server because any of the Activity timeouts have triggered (for example,
+ *   the Server didn't receive a heartbeat within the {@link ActivityOptions.heartbeatTimeout}). The
+ *   {@link CancelledFailure} will have `message: 'TIMED_OUT'`.
+ * - An Activity sends a heartbeat with `Context.current().heartbeat()` and the heartbeat details can't be converted by
+ *   the Worker's configured {@link DataConverter}.
+ * - The Workflow Run reached a {@link https://docs.temporal.io/workflows#status | Closed state}, in which case the
+ *   {@link CancelledFailure} will have `message: 'NOT_FOUND'`.
+ *
+ * The reason for the Cancellation is available at {@link CancelledFailure.message} or
+ * {@link Context#cancellationSignal | Context.cancellationSignal.reason}.
+ *
+ * There are two ways to handle Activity Cancellation:
+ *
  * 1. await on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
  * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
@@ -31,7 +53,7 @@
  *
  * ### Examples
  *
- * #### An Activity that sends progress heartbeats and can be cancelled
+ * #### An Activity that sends progress heartbeats and can be Cancelled
  *
  * <!--SNIPSTART typescript-activity-fake-progress-->
  * <!--SNIPEND-->
@@ -63,7 +85,7 @@ export {
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
  * The Activity can then be completed asynchronously (from anywhere—usually outside the Worker) using
- * {@link AsyncCompletionClient}.
+ * {@link Client.activity}.
  *
  * @example
  *
@@ -254,7 +276,7 @@ export class Context {
 
   /**
    * Helper function for sleeping in an Activity.
-   * @param ms Sleep duration: an {@link https://www.npmjs.com/package/ms | ms}-formatted string or number of milliseconds
+   * @param ms Sleep duration: number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @returns A Promise that either resolves when `ms` is reached or rejects when the Activity is cancelled
    */
   public sleep(ms: number | string): Promise<void> {