@temporalio/activity 1.7.4 → 1.8.1

package/lib/index.d.ts

@@ -72,8 +72,10 @@
 /// <reference types="node" />
 import 'abort-controller/polyfill';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { Logger, Duration } from '@temporalio/common';
 export { ActivityFunction, ActivityInterface, // eslint-disable-line deprecation/deprecation
 ApplicationFailure, CancelledFailure, UntypedActivities, } from '@temporalio/common';
+declare const isCompleteAsyncError: unique symbol;
 /**
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
@@ -94,8 +96,15 @@ ApplicationFailure, CancelledFailure, UntypedActivities, } from '@temporalio/com
 export declare class CompleteAsyncError extends Error {
     readonly name: string;
     constructor();
+    /**
+     * Marker to determine whether an error is an instance of CompleteAsyncError.
+     */
+    protected readonly [isCompleteAsyncError] = true;
+    /**
+     * Instanceof check that works when multiple versions of @temporalio/activity are installed.
+     */
+    static is(error: unknown): error is CompleteAsyncError;
 }
-/** @ignore */
 export declare const asyncLocalStorage: AsyncLocalStorage<Context>;
 /**
  * Holds information about the current Activity Execution. Retrieved inside an Activity with `Context.current().info`.
@@ -144,10 +153,8 @@ export interface Info {
     scheduledTimestampMs: number;
     /**
      * Timeout for this Activity from schedule to close in milliseconds.
-     *
-     * Might be undefined for local activities.
      */
-    scheduleToCloseTimeoutMs?: number;
+    scheduleToCloseTimeoutMs: number;
     /**
      * Timeout for this Activity from start to close in milliseconds
      */
@@ -198,10 +205,11 @@ export declare class Context {
      * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
      * Activity cancellation.
      *
-     * Used by {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
+     * This can be passed in to libraries such as
+     * {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
      * in-progress request and
      * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
-     * to abort a child process, and is supported by some other libraries as well.
+     * to abort a child process, as well as other built-in node modules and modules found on npm.
      *
      * @see [Cancellation](/api/namespaces/activity#cancellation)
      */
@@ -210,12 +218,25 @@ export declare class Context {
      * The heartbeat implementation, injected via the constructor.
      */
     protected readonly heartbeatFn: (details?: any) => void;
+    /**
+     * The logger for this Activity.
+     *
+     * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). If the {@link ActivityInboundLogInterceptor}
+     * is installed (by default, it is; see {@link WorkerOptions.interceptors}), then various attributes from the current
+     * Activity context will automatically be included as metadata on every log entries, and some key events of the
+     * Activity's life cycle will automatically be logged (at 'DEBUG' level for most messages; 'WARN' for failures).
+     *
+     * To use a different Logger, either overwrite this property from an Activity Interceptor, or explicitly register the
+     * `ActivityInboundLogInterceptor` with your custom Logger. You may also subclass `ActivityInboundLogInterceptor` to
+     * customize attributes that are emitted as metadata.
+     */
+    log: Logger;
     /**
      * **Not** meant to instantiated by Activity code, used by the worker.
      *
      * @ignore
      */
-    constructor(info: Info, cancelled: Promise<never>, cancellationSignal: AbortSignal, heartbeat: (details?: any) => void);
+    constructor(info: Info, cancelled: Promise<never>, cancellationSignal: AbortSignal, heartbeat: (details?: any) => void, logger: Logger);
     /**
      * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
      *
@@ -229,7 +250,13 @@ export declare class Context {
      *
      * Calling `heartbeat()` from a Local Activity has no effect.
      *
+     * The SDK automatically throttles heartbeat calls to the server with a duration of 80% of the specified activity
+     * heartbeat timeout. Throttling behavior may be customized with the `{@link maxHeartbeatThrottleInterval | https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#maxheartbeatthrottleinterval} and {@link defaultHeartbeatThrottleInterval | https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#defaultheartbeatthrottleinterval} worker options.
+     *
      * Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
+     *
+     * :warning: Cancellation is not propagated from this function, use {@link cancelled} or {@link cancellationSignal} to
+     * subscribe to cancellation notifications.
      */
     heartbeat(details?: unknown): void;
     /**
@@ -243,5 +270,5 @@ export declare class Context {
      * @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>;
+    sleep(ms: Duration): Promise<void>;
 }

package/lib/index.js

@@ -69,6 +69,7 @@
  *
  * @module
  */
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Context = exports.asyncLocalStorage = exports.CompleteAsyncError = exports.CancelledFailure = exports.ApplicationFailure = void 0;
 require("abort-controller/polyfill"); // eslint-disable-line import/no-unassigned-import
@@ -77,6 +78,7 @@ const time_1 = require("@temporalio/common/lib/time");
 var common_1 = require("@temporalio/common");
 Object.defineProperty(exports, "ApplicationFailure", { enumerable: true, get: function () { return common_1.ApplicationFailure; } });
 Object.defineProperty(exports, "CancelledFailure", { enumerable: true, get: function () { return common_1.CancelledFailure; } });
+const isCompleteAsyncError = Symbol.for('__temporal_isCompleteAsyncError');
 /**
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
@@ -98,11 +100,26 @@ class CompleteAsyncError extends Error {
     constructor() {
         super();
         this.name = 'CompleteAsyncError';
+        /**
+         * Marker to determine whether an error is an instance of CompleteAsyncError.
+         */
+        this[_a] = true;
+    }
+    /**
+     * Instanceof check that works when multiple versions of @temporalio/activity are installed.
+     */
+    static is(error) {
+        return error instanceof CompleteAsyncError || error?.[isCompleteAsyncError] === true;
     }
 }
 exports.CompleteAsyncError = CompleteAsyncError;
-/** @ignore */
-exports.asyncLocalStorage = new node_async_hooks_1.AsyncLocalStorage();
+_a = isCompleteAsyncError;
+// Make it safe to use @temporalio/activity with multiple versions installed.
+const asyncLocalStorageSymbol = Symbol.for('__temporal_activity_context_storage__');
+if (!globalThis[asyncLocalStorageSymbol]) {
+    globalThis[asyncLocalStorageSymbol] = new node_async_hooks_1.AsyncLocalStorage();
+}
+exports.asyncLocalStorage = globalThis[asyncLocalStorageSymbol];
 /**
  * Activity Context, used to:
  *
@@ -119,11 +136,12 @@ class Context {
      *
      * @ignore
      */
-    constructor(info, cancelled, cancellationSignal, heartbeat) {
+    constructor(info, cancelled, cancellationSignal, heartbeat, logger) {
         this.info = info;
         this.cancelled = cancelled;
         this.cancellationSignal = cancellationSignal;
         this.heartbeatFn = heartbeat;
+        this.log = logger;
     }
     /**
      * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
@@ -138,7 +156,13 @@ class Context {
      *
      * Calling `heartbeat()` from a Local Activity has no effect.
      *
+     * The SDK automatically throttles heartbeat calls to the server with a duration of 80% of the specified activity
+     * heartbeat timeout. Throttling behavior may be customized with the `{@link maxHeartbeatThrottleInterval | https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#maxheartbeatthrottleinterval} and {@link defaultHeartbeatThrottleInterval | https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#defaultheartbeatthrottleinterval} worker options.
+     *
      * Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
+     *
+     * :warning: Cancellation is not propagated from this function, use {@link cancelled} or {@link cancellationSignal} to
+     * subscribe to cancellation notifications.
      */
     heartbeat(details) {
         this.heartbeatFn(details);

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;;;AAEH,qCAAmC,CAAC,kDAAkD;AACtF,uDAAqD;AACrD,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,oCAAiB,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;;;;AAEH,qCAAmC,CAAC,kDAAkD;AACtF,uDAAqD;AAErD,sDAAyD;AAEzD,6CAM4B;AAH1B,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAIlB,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAG3C;QACE,KAAK,EAAE,CAAC;QAHM,SAAI,GAAW,oBAAoB,CAAC;QAMpD;;WAEG;QACgB,QAAsB,GAAG,IAAI,CAAC;IALjD,CAAC;IAOD;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,KAAc;QACtB,OAAO,KAAK,YAAY,kBAAkB,IAAK,KAAa,EAAE,CAAC,oBAAoB,CAAC,KAAK,IAAI,CAAC;IAChG,CAAC;CACF;AAlBD,gDAkBC;KARqB,oBAAoB;AAU1C,6EAA6E;AAC7E,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;AACpF,IAAI,CAAE,UAAkB,CAAC,uBAAuB,CAAC,EAAE;IAChD,UAAkB,CAAC,uBAAuB,CAAC,GAAG,IAAI,oCAAiB,EAAW,CAAC;CACjF;AAEY,QAAA,iBAAiB,GAAgC,UAAkB,CAAC,uBAAuB,CAAC,CAAC;AA4E1G;;;;;;;;;GASG;AACH,MAAa,OAAO;IA4ClB;;;;OAIG;IACH,YACE,IAAU,EACV,SAAyB,EACzB,kBAA+B,EAC/B,SAAkC,EAClC,MAAc;QAEd,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;QAC7B,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;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,EAAY;QACvB,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;AAjHD,0BAiHC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/activity",
-  "version": "1.7.4",
+  "version": "1.8.1",
   "description": "Temporal.io SDK Activity sub-package",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,7 +13,7 @@
   "author": "Temporal Technologies Inc. <sdk@temporal.io>",
   "license": "MIT",
   "dependencies": {
-    "@temporalio/common": "1.7.4",
+    "@temporalio/common": "1.8.1",
     "abort-controller": "^3.0.0"
   },
   "bugs": {
@@ -32,5 +32,5 @@
     "src",
     "lib"
   ],
-  "gitHead": "fb4088a8174b60b7a3fc7763ed39dbfc514a3e56"
+  "gitHead": "97808111bbec478260e915726bb9730a489f8fa4"
 }

package/src/index.ts

@@ -71,6 +71,7 @@
 
 import 'abort-controller/polyfill'; // eslint-disable-line import/no-unassigned-import
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { Logger, Duration } from '@temporalio/common';
 import { msToNumber } from '@temporalio/common/lib/time';
 
 export {
@@ -81,6 +82,8 @@ export {
   UntypedActivities,
 } from '@temporalio/common';
 
+const isCompleteAsyncError = Symbol.for('__temporal_isCompleteAsyncError');
+
 /**
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
@@ -104,10 +107,27 @@ export class CompleteAsyncError extends Error {
   constructor() {
     super();
   }
+
+  /**
+   * Marker to determine whether an error is an instance of CompleteAsyncError.
+   */
+  protected readonly [isCompleteAsyncError] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/activity are installed.
+   */
+  static is(error: unknown): error is CompleteAsyncError {
+    return error instanceof CompleteAsyncError || (error as any)?.[isCompleteAsyncError] === true;
+  }
 }
 
-/** @ignore */
-export const asyncLocalStorage = new AsyncLocalStorage<Context>();
+// Make it safe to use @temporalio/activity with multiple versions installed.
+const asyncLocalStorageSymbol = Symbol.for('__temporal_activity_context_storage__');
+if (!(globalThis as any)[asyncLocalStorageSymbol]) {
+  (globalThis as any)[asyncLocalStorageSymbol] = new AsyncLocalStorage<Context>();
+}
+
+export const asyncLocalStorage: AsyncLocalStorage<Context> = (globalThis as any)[asyncLocalStorageSymbol];
 
 /**
  * Holds information about the current Activity Execution. Retrieved inside an Activity with `Context.current().info`.
@@ -156,10 +176,8 @@ export interface Info {
   scheduledTimestampMs: number;
   /**
    * Timeout for this Activity from schedule to close in milliseconds.
-   *
-   * Might be undefined for local activities.
    */
-  scheduleToCloseTimeoutMs?: number;
+  scheduleToCloseTimeoutMs: number;
   /**
    * Timeout for this Activity from start to close in milliseconds
    */
@@ -212,10 +230,11 @@ export class Context {
    * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
    * Activity cancellation.
    *
-   * Used by {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
+   * This can be passed in to libraries such as
+   * {@link https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal | fetch} to abort an
    * in-progress request and
    * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
-   * to abort a child process, and is supported by some other libraries as well.
+   * to abort a child process, as well as other built-in node modules and modules found on npm.
    *
    * @see [Cancellation](/api/namespaces/activity#cancellation)
    */
@@ -224,6 +243,19 @@ export class Context {
    * The heartbeat implementation, injected via the constructor.
    */
   protected readonly heartbeatFn: (details?: any) => void;
+  /**
+   * The logger for this Activity.
+   *
+   * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). If the {@link ActivityInboundLogInterceptor}
+   * is installed (by default, it is; see {@link WorkerOptions.interceptors}), then various attributes from the current
+   * Activity context will automatically be included as metadata on every log entries, and some key events of the
+   * Activity's life cycle will automatically be logged (at 'DEBUG' level for most messages; 'WARN' for failures).
+   *
+   * To use a different Logger, either overwrite this property from an Activity Interceptor, or explicitly register the
+   * `ActivityInboundLogInterceptor` with your custom Logger. You may also subclass `ActivityInboundLogInterceptor` to
+   * customize attributes that are emitted as metadata.
+   */
+  public log: Logger;
 
   /**
    * **Not** meant to instantiated by Activity code, used by the worker.
@@ -234,12 +266,14 @@ export class Context {
     info: Info,
     cancelled: Promise<never>,
     cancellationSignal: AbortSignal,
-    heartbeat: (details?: any) => void
+    heartbeat: (details?: any) => void,
+    logger: Logger
   ) {
     this.info = info;
     this.cancelled = cancelled;
     this.cancellationSignal = cancellationSignal;
     this.heartbeatFn = heartbeat;
+    this.log = logger;
   }
 
   /**
@@ -255,7 +289,13 @@ export class Context {
    *
    * Calling `heartbeat()` from a Local Activity has no effect.
    *
+   * The SDK automatically throttles heartbeat calls to the server with a duration of 80% of the specified activity
+   * heartbeat timeout. Throttling behavior may be customized with the `{@link maxHeartbeatThrottleInterval | https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#maxheartbeatthrottleinterval} and {@link defaultHeartbeatThrottleInterval | https://typescript.temporal.io/api/interfaces/worker.WorkerOptions#defaultheartbeatthrottleinterval} worker options.
+   *
    * Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
+   *
+   * :warning: Cancellation is not propagated from this function, use {@link cancelled} or {@link cancellationSignal} to
+   * subscribe to cancellation notifications.
    */
   public heartbeat(details?: unknown): void {
     this.heartbeatFn(details);
@@ -279,7 +319,7 @@ export class Context {
    * @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> {
+  public sleep(ms: Duration): Promise<void> {
     let handle: NodeJS.Timeout;
     const timer = new Promise<void>((resolve) => {
       handle = setTimeout(resolve, msToNumber(ms));