@temporalio/activity 1.0.1 → 1.3.0

package/lib/index.d.ts

@@ -15,19 +15,45 @@
  *
  * ### Cancellation
  *
- * Activities may be cancelled only if they {@link Context.heartbeat | emit heartbeats}.
+ * Activity Cancellation:
+ *
+ * - 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 can only receive Cancellation if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * (which can't heartbeat but receive Cancellation anyway).
+ *
+ * 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:
  *
- * 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}.
+ *    {@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
- *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that
- *    supports it.
+ *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### 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-->
@@ -52,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
  *
@@ -133,12 +159,15 @@ export interface Info {
      */
     heartbeatTimeoutMs?: number;
     /**
-     * Hold the details supplied to the last heartbeat on previous attempts of this Activity.
-     * Use this in order to resume your Activity from checkpoint.
+     * The {@link Context.heartbeat | details} from the last recorded heartbeat from the last attempt of this Activity.
+     *
+     * Use this to resume your Activity from a checkpoint.
      */
     heartbeatDetails: any;
     /**
-     * Task queue the Activity is scheduled in, set to the Workflow's task queue in case of local Activity.
+     * Task Queue the Activity is scheduled in.
+     *
+     * For Local Activities, this is set to the Workflow's Task Queue.
      */
     taskQueue: string;
 }
@@ -198,7 +227,9 @@ export declare class Context {
      * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
      * {@link TimeoutFailure.lastHeartbeatDetails}.
      *
-     * Activities must heartbeat in order to receive cancellation.
+     * Calling `heartbeat()` from a Local Activity has no effect.
+     *
+     * Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
      */
     heartbeat(details?: unknown): void;
     /**
@@ -209,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,19 +16,45 @@
  *
  * ### Cancellation
  *
- * Activities may be cancelled only if they {@link Context.heartbeat | emit heartbeats}.
+ * Activity Cancellation:
+ *
+ * - 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 can only receive Cancellation if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * (which can't heartbeat but receive Cancellation anyway).
+ *
+ * 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:
  *
- * 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}.
+ *    {@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
- *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that
- *    supports it.
+ *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### 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-->
@@ -57,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
  *
@@ -112,7 +138,9 @@ class Context {
      * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
      * {@link TimeoutFailure.lastHeartbeatDetails}.
      *
-     * Activities must heartbeat in order to receive cancellation.
+     * Calling `heartbeat()` from a Local Activity has no effect.
+     *
+     * Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
      */
     heartbeat(details) {
         this.heartbeatFn(details);
@@ -131,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;;;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;AA2ElE;;;;;;;;;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;;;;;;;;;;;;OAYG;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;AAzFD,0BAyFC"}
+{"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.0.1",
+  "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.0.1",
-    "@temporalio/internal-workflow-common": "^1.0.1",
+    "@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": "a1dae539e72b6b088b400998d7bef482e8ed52f1"
+  "gitHead": "966d51d3545a5e84102190f5b762160b9dfe99c2"
 }

package/src/index.ts

@@ -15,19 +15,45 @@
  *
  * ### Cancellation
  *
- * Activities may be cancelled only if they {@link Context.heartbeat | emit heartbeats}.
+ * Activity Cancellation:
+ *
+ * - 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 can only receive Cancellation if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * (which can't heartbeat but receive Cancellation anyway).
+ *
+ * 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:
  *
- * 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}.
+ *    {@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
- *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that
- *    supports it.
+ *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### 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-->
@@ -59,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
  *
@@ -145,13 +171,16 @@ export interface Info {
    */
   heartbeatTimeoutMs?: number;
   /**
-   * Hold the details supplied to the last heartbeat on previous attempts of this Activity.
-   * Use this in order to resume your Activity from checkpoint.
+   * The {@link Context.heartbeat | details} from the last recorded heartbeat from the last attempt of this Activity.
+   *
+   * Use this to resume your Activity from a checkpoint.
    */
   heartbeatDetails: any;
 
   /**
-   * Task queue the Activity is scheduled in, set to the Workflow's task queue in case of local Activity.
+   * Task Queue the Activity is scheduled in.
+   *
+   * For Local Activities, this is set to the Workflow's Task Queue.
    */
   taskQueue: string;
 }
@@ -224,7 +253,9 @@ export class Context {
    * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
    * {@link TimeoutFailure.lastHeartbeatDetails}.
    *
-   * Activities must heartbeat in order to receive cancellation.
+   * Calling `heartbeat()` from a Local Activity has no effect.
+   *
+   * Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
    */
   public heartbeat(details?: unknown): void {
     this.heartbeatFn(details);
@@ -245,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> {