@temporalio/activity 1.1.0 → 1.4.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-->
@@ -49,14 +71,13 @@
 /// <reference types="node" />
 import { AbortSignal } from 'abort-controller';
 import { AsyncLocalStorage } from 'async_hooks';
-export { CancelledFailure, ApplicationFailure } from '@temporalio/common';
 export { ActivityFunction, ActivityInterface, // eslint-disable-line deprecation/deprecation
-UntypedActivities, errorMessage, errorCode, } from '@temporalio/internal-workflow-common';
+ApplicationFailure, CancelledFailure, UntypedActivities, } from '@temporalio/common';
 /**
  * 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 +239,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-->
@@ -48,20 +70,17 @@
  * @module
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = exports.asyncLocalStorage = exports.CompleteAsyncError = exports.errorCode = exports.errorMessage = exports.ApplicationFailure = exports.CancelledFailure = void 0;
-const internal_workflow_common_1 = require("@temporalio/internal-workflow-common");
+exports.Context = exports.asyncLocalStorage = exports.CompleteAsyncError = exports.CancelledFailure = exports.ApplicationFailure = void 0;
 const async_hooks_1 = require("async_hooks");
+const time_1 = require("@temporalio/common/lib/time");
 var common_1 = require("@temporalio/common");
-Object.defineProperty(exports, "CancelledFailure", { enumerable: true, get: function () { return common_1.CancelledFailure; } });
 Object.defineProperty(exports, "ApplicationFailure", { enumerable: true, get: function () { return common_1.ApplicationFailure; } });
-var internal_workflow_common_2 = require("@temporalio/internal-workflow-common");
-Object.defineProperty(exports, "errorMessage", { enumerable: true, get: function () { return internal_workflow_common_2.errorMessage; } });
-Object.defineProperty(exports, "errorCode", { enumerable: true, get: function () { return internal_workflow_common_2.errorCode; } });
+Object.defineProperty(exports, "CancelledFailure", { enumerable: true, get: function () { return common_1.CancelledFailure; } });
 /**
  * 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,13 +156,13 @@ 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) {
         let handle;
         const timer = new Promise((resolve) => {
-            handle = setTimeout(resolve, (0, internal_workflow_common_1.msToNumber)(ms));
+            handle = setTimeout(resolve, (0, time_1.msToNumber)(ms));
         });
         return Promise.race([this.cancelled.finally(() => clearTimeout(handle)), timer]);
     }

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;;;AAGH,6CAAgD;AAChD,sDAAyD;AAEzD,6CAM4B;AAH1B,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAIlB;;;;;;;;;;;;;;;;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,iBAAU,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.4.0",
   "description": "Temporal.io SDK Activity sub-package",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,8 +13,7 @@
   "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.4.0",
     "abort-controller": "^3.0.0"
   },
   "bugs": {
@@ -28,5 +27,5 @@
     "src",
     "lib"
   ],
-  "gitHead": "132f23a47a93fecf3f39836b31f08ea837b30320"
+  "gitHead": "4b757ebbc052f327cc37e5693f46c8127c156b0c"
 }

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-->
@@ -47,23 +69,23 @@
  * @module
  */
 
-import { msToNumber } from '@temporalio/internal-workflow-common';
 import { AbortSignal } from 'abort-controller';
 import { AsyncLocalStorage } from 'async_hooks';
-export { CancelledFailure, ApplicationFailure } from '@temporalio/common';
+import { msToNumber } from '@temporalio/common/lib/time';
+
 export {
   ActivityFunction,
   ActivityInterface, // eslint-disable-line deprecation/deprecation
+  ApplicationFailure,
+  CancelledFailure,
   UntypedActivities,
-  errorMessage,
-  errorCode,
-} from '@temporalio/internal-workflow-common';
+} from '@temporalio/common';
 
 /**
  * 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> {