@temporalio/activity 1.8.6 → 1.9.0

package/lib/index.d.ts

@@ -99,77 +99,77 @@ export declare const asyncLocalStorage: AsyncLocalStorage<Context>;
  * Holds information about the current Activity Execution. Retrieved inside an Activity with `Context.current().info`.
  */
 export interface Info {
-    taskToken: Uint8Array;
+    readonly taskToken: Uint8Array;
     /**
      * Base64 encoded `taskToken`
      */
-    base64TaskToken: string;
-    activityId: string;
+    readonly base64TaskToken: string;
+    readonly activityId: string;
     /**
      * Exposed Activity function name
      */
-    activityType: string;
+    readonly activityType: string;
     /**
      * The namespace this Activity is running in
      */
-    activityNamespace: string;
+    readonly activityNamespace: string;
     /**
      * Attempt number for this activity
      */
-    attempt: number;
+    readonly attempt: number;
     /**
      * Whether this activity is scheduled in local or remote mode
      */
-    isLocal: boolean;
+    readonly isLocal: boolean;
     /**
      * Information about the Workflow that scheduled the Activity
      */
-    workflowExecution: {
-        workflowId: string;
-        runId: string;
+    readonly workflowExecution: {
+        readonly workflowId: string;
+        readonly runId: string;
     };
     /**
      * The namespace of the Workflow that scheduled this Activity
      */
-    workflowNamespace: string;
+    readonly workflowNamespace: string;
     /**
      * The module name of the Workflow that scheduled this Activity
      */
-    workflowType: string;
+    readonly workflowType: string;
     /**
      * Timestamp for when this Activity was scheduled in milliseconds
      */
-    scheduledTimestampMs: number;
+    readonly scheduledTimestampMs: number;
     /**
      * Timeout for this Activity from schedule to close in milliseconds.
      */
-    scheduleToCloseTimeoutMs: number;
+    readonly scheduleToCloseTimeoutMs: number;
     /**
      * Timeout for this Activity from start to close in milliseconds
      */
-    startToCloseTimeoutMs: number;
+    readonly startToCloseTimeoutMs: number;
     /**
      * Timestamp for when the current attempt of this Activity was scheduled in milliseconds
      */
-    currentAttemptScheduledTimestampMs: number;
+    readonly currentAttemptScheduledTimestampMs: number;
     /**
      * Heartbeat timeout in milliseconds.
      * If this timeout is defined, the Activity must heartbeat before the timeout is reached.
      * The Activity must **not** heartbeat in case this timeout is not defined.
      */
-    heartbeatTimeoutMs?: number;
+    readonly heartbeatTimeoutMs?: number;
     /**
      * 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;
+    readonly heartbeatDetails: any;
     /**
      * Task Queue the Activity is scheduled in.
      *
      * For Local Activities, this is set to the Workflow's Task Queue.
      */
-    taskQueue: string;
+    readonly taskQueue: string;
 }
 /**
  * Activity Context, used to:
@@ -182,14 +182,21 @@ export interface Info {
  * Call `Context.current()` from Activity code in order to get the current Activity's Context.
  */
 export declare class Context {
+    /**
+     * Gets the context of the current Activity.
+     *
+     * Uses {@link https://nodejs.org/docs/latest-v14.x/api/async_hooks.html#async_hooks_class_asynclocalstorage | AsyncLocalStorage} under the hood to make it accessible in nested callbacks and promises.
+     */
+    static current(): Context;
     /**
      * Holds information about the current executing Activity.
      */
-    info: Info;
+    readonly info: Info;
     /**
-     * Await this promise in an Activity to get notified of cancellation.
+     * A Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The promise
+     * is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of cancellation.
      *
-     * This promise will never resolve—it will only be rejected with a {@link CancelledFailure}.
+     * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
      *
      * @see [Cancellation](/api/namespaces/activity#cancellation)
      */
@@ -204,6 +211,8 @@ export declare class Context {
      * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
      * to abort a child process, as well as other built-in node modules and modules found on npm.
      *
+     * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
+     *
      * @see [Cancellation](/api/namespaces/activity#cancellation)
      */
     readonly cancellationSignal: AbortSignal;
@@ -214,14 +223,17 @@ export declare class Context {
     /**
      * 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).
+     * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the current Activity context
+     * will automatically be included as metadata on every log entries, and some key events of the Activity's lifecycle
+     * will automatically be logged (at 'DEBUG' level for most messages; 'WARN' for failures).
+     *
+     * To customize log attributes, register a {@link ActivityOutboundCallsInterceptor} that intercepts the
+     * `getLogAttributes()` method.
      *
-     * 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.
+     * Modifying the context logger (eg. `context.log = myCustomLogger` or by an {@link ActivityInboundLogInterceptor}
+     * with a custom logger as argument) is deprecated. Doing so will prevent automatic inclusion of custom log attributes
+     * through the `getLogAttributes()` interceptor. To customize _where_ log messages are sent, set the
+     * {@link Runtime.logger} property instead.
      */
     log: Logger;
     /**
@@ -229,7 +241,7 @@ export declare class Context {
      *
      * @ignore
      */
-    constructor(info: Info, cancelled: Promise<never>, cancellationSignal: AbortSignal, heartbeat: (details?: any) => void, logger: Logger);
+    constructor(info: Info, cancelled: Promise<never>, cancellationSignal: AbortSignal, heartbeat: (details?: any) => void, log: Logger);
     /**
      * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
      *
@@ -251,17 +263,69 @@ export declare class Context {
      * :warning: Cancellation is not propagated from this function, use {@link cancelled} or {@link cancellationSignal} to
      * subscribe to cancellation notifications.
      */
-    heartbeat(details?: unknown): void;
-    /**
-     * Gets the context of the current Activity.
-     *
-     * Uses {@link https://nodejs.org/docs/latest-v14.x/api/async_hooks.html#async_hooks_class_asynclocalstorage | AsyncLocalStorage} under the hood to make it accessible in nested callbacks and promises.
-     */
-    static current(): Context;
+    readonly heartbeat: (details?: unknown) => void;
     /**
      * Helper function for sleeping in an Activity.
      * @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: Duration): Promise<void>;
+    readonly sleep: (ms: Duration) => Promise<void>;
 }
+/**
+ * The current Activity's context.
+ */
+export declare function activityInfo(): Info;
+/**
+ * The logger for this Activity.
+ *
+ * This is a shortcut for `Context.current().log` (see {@link Context.log}).
+ */
+export declare const log: Logger;
+/**
+ * Helper function for sleeping in an Activity.
+ *
+ * This is a shortcut for `Context.current().sleep(ms)` (see {@link Context.sleep}).
+ *
+ * @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
+ */
+export declare function sleep(ms: Duration): Promise<void>;
+/**
+ * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
+ *
+ * If an Activity times out, then during the next retry, the last value of `details` is available at
+ * {@link Info.heartbeatDetails}. This acts as a periodic checkpoint mechanism for the progress of an Activity.
+ *
+ * If an Activity times out on the final retry (relevant in cases in which {@link RetryPolicy.maximumAttempts} is
+ * set), the Activity function call in the Workflow code will throw an {@link ActivityFailure} with the `cause`
+ * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
+ * {@link TimeoutFailure.lastHeartbeatDetails}.
+ *
+ * This is a shortcut for `Context.current().heatbeat(ms)` (see {@link Context.heartbeat}).
+ */
+export declare function heartbeat(details?: unknown): void;
+/**
+ * Return a Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The
+ * promise is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of
+ * cancellation.
+ *
+ * Note that to get notified of cancellation, an activity must _also_ do {@link Context.heartbeat}.
+ *
+ * This is a shortcut for `Context.current().cancelled` (see {@link Context.cancelled}).
+ */
+export declare function cancelled(): Promise<never>;
+/**
+ * Return an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to
+ * react to Activity cancellation.
+ *
+ * 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, as well as other built-in node modules and modules found on npm.
+ *
+ * Note that to get notified of cancellation, an activity must _also_ do {@link Context.heartbeat}.
+ *
+ * This is a shortcut for `Context.current().cancellationSignal` (see {@link Context.cancellationSignal}).
+ */
+export declare function cancellationSignal(): AbortSignal;

package/lib/index.js

@@ -76,7 +76,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = exports.asyncLocalStorage = exports.CompleteAsyncError = exports.CancelledFailure = exports.ApplicationFailure = void 0;
+exports.cancellationSignal = exports.cancelled = exports.heartbeat = exports.sleep = exports.log = exports.activityInfo = exports.Context = exports.asyncLocalStorage = exports.CompleteAsyncError = exports.CancelledFailure = exports.ApplicationFailure = void 0;
+// Keep this around until we drop support for Node 14.
 require("abort-controller/polyfill"); // eslint-disable-line import/no-unassigned-import
 const node_async_hooks_1 = require("node:async_hooks");
 const time_1 = require("@temporalio/common/lib/time");
@@ -103,10 +104,10 @@ Object.defineProperty(exports, "CancelledFailure", { enumerable: true, get: func
  */
 let CompleteAsyncError = class CompleteAsyncError extends Error {
 };
-CompleteAsyncError = __decorate([
+exports.CompleteAsyncError = CompleteAsyncError;
+exports.CompleteAsyncError = CompleteAsyncError = __decorate([
     (0, type_helpers_1.SymbolBasedInstanceOfError)('CompleteAsyncError')
 ], CompleteAsyncError);
-exports.CompleteAsyncError = CompleteAsyncError;
 // Make it safe to use @temporalio/activity with multiple versions installed.
 const asyncLocalStorageSymbol = Symbol.for('__temporal_activity_context_storage__');
 if (!globalThis[asyncLocalStorageSymbol]) {
@@ -124,42 +125,6 @@ exports.asyncLocalStorage = globalThis[asyncLocalStorageSymbol];
  * Call `Context.current()` from Activity code in order to get the current Activity's Context.
  */
 class Context {
-    /**
-     * **Not** meant to instantiated by Activity code, used by the worker.
-     *
-     * @ignore
-     */
-    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.
-     *
-     * If an Activity times out, then during the next retry, the last value of `details` is available at
-     * {@link Info.heartbeatDetails}. This acts as a periodic checkpoint mechanism for the progress of an Activity.
-     *
-     * If an Activity times out on the final retry (relevant in cases in which {@link RetryPolicy.maximumAttempts} is
-     * set), the Activity function call in the Workflow code will throw an {@link ActivityFailure} with the `cause`
-     * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
-     * {@link TimeoutFailure.lastHeartbeatDetails}.
-     *
-     * 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);
-    }
     /**
      * Gets the context of the current Activity.
      *
@@ -173,17 +138,148 @@ class Context {
         return store;
     }
     /**
-     * Helper function for sleeping in an Activity.
-     * @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
+     * **Not** meant to instantiated by Activity code, used by the worker.
+     *
+     * @ignore
      */
-    sleep(ms) {
-        let handle;
-        const timer = new Promise((resolve) => {
-            handle = setTimeout(resolve, (0, time_1.msToNumber)(ms));
-        });
-        return Promise.race([this.cancelled.finally(() => clearTimeout(handle)), timer]);
+    constructor(info, cancelled, cancellationSignal, heartbeat, log) {
+        /**
+         * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
+         *
+         * If an Activity times out, then during the next retry, the last value of `details` is available at
+         * {@link Info.heartbeatDetails}. This acts as a periodic checkpoint mechanism for the progress of an Activity.
+         *
+         * If an Activity times out on the final retry (relevant in cases in which {@link RetryPolicy.maximumAttempts} is
+         * set), the Activity function call in the Workflow code will throw an {@link ActivityFailure} with the `cause`
+         * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
+         * {@link TimeoutFailure.lastHeartbeatDetails}.
+         *
+         * 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.
+         */
+        this.heartbeat = (details) => {
+            this.heartbeatFn(details);
+        };
+        /**
+         * Helper function for sleeping in an Activity.
+         * @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
+         */
+        this.sleep = (ms) => {
+            let handle;
+            const timer = new Promise((resolve) => {
+                handle = setTimeout(resolve, (0, time_1.msToNumber)(ms));
+            });
+            return Promise.race([this.cancelled.finally(() => clearTimeout(handle)), timer]);
+        };
+        this.info = info;
+        this.cancelled = cancelled;
+        this.cancellationSignal = cancellationSignal;
+        this.heartbeatFn = heartbeat;
+        this.log = log;
     }
 }
 exports.Context = Context;
+/**
+ * The current Activity's context.
+ */
+function activityInfo() {
+    // For consistency with workflow.workflowInfo(), we want activityInfo() to be a function, rather than a const object.
+    return Context.current().info;
+}
+exports.activityInfo = activityInfo;
+/**
+ * The logger for this Activity.
+ *
+ * This is a shortcut for `Context.current().log` (see {@link Context.log}).
+ */
+exports.log = {
+    // Context.current().log may legitimately change during the lifetime of an Activity, so we can't
+    // just initialize that field to the value of Context.current().log and move on. Hence this indirection.
+    log(level, message, meta) {
+        return Context.current().log.log(level, message, meta);
+    },
+    trace(message, meta) {
+        return Context.current().log.trace(message, meta);
+    },
+    debug(message, meta) {
+        return Context.current().log.debug(message, meta);
+    },
+    info(message, meta) {
+        return Context.current().log.info(message, meta);
+    },
+    warn(message, meta) {
+        return Context.current().log.warn(message, meta);
+    },
+    error(message, meta) {
+        return Context.current().log.error(message, meta);
+    },
+};
+/**
+ * Helper function for sleeping in an Activity.
+ *
+ * This is a shortcut for `Context.current().sleep(ms)` (see {@link Context.sleep}).
+ *
+ * @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
+ */
+function sleep(ms) {
+    return Context.current().sleep(ms);
+}
+exports.sleep = sleep;
+/**
+ * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
+ *
+ * If an Activity times out, then during the next retry, the last value of `details` is available at
+ * {@link Info.heartbeatDetails}. This acts as a periodic checkpoint mechanism for the progress of an Activity.
+ *
+ * If an Activity times out on the final retry (relevant in cases in which {@link RetryPolicy.maximumAttempts} is
+ * set), the Activity function call in the Workflow code will throw an {@link ActivityFailure} with the `cause`
+ * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
+ * {@link TimeoutFailure.lastHeartbeatDetails}.
+ *
+ * This is a shortcut for `Context.current().heatbeat(ms)` (see {@link Context.heartbeat}).
+ */
+function heartbeat(details) {
+    Context.current().heartbeat(details);
+}
+exports.heartbeat = heartbeat;
+/**
+ * Return a Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The
+ * promise is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of
+ * cancellation.
+ *
+ * Note that to get notified of cancellation, an activity must _also_ do {@link Context.heartbeat}.
+ *
+ * This is a shortcut for `Context.current().cancelled` (see {@link Context.cancelled}).
+ */
+function cancelled() {
+    return Context.current().cancelled;
+}
+exports.cancelled = cancelled;
+/**
+ * Return an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to
+ * react to Activity cancellation.
+ *
+ * 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, as well as other built-in node modules and modules found on npm.
+ *
+ * Note that to get notified of cancellation, an activity must _also_ do {@link Context.heartbeat}.
+ *
+ * This is a shortcut for `Context.current().cancellationSignal` (see {@link Context.cancellationSignal}).
+ */
+function cancellationSignal() {
+    return Context.current().cancellationSignal;
+}
+exports.cancellationSignal = cancellationSignal;
 //# sourceMappingURL=index.js.map

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;AAErD,sDAAyD;AACzD,sEAAiF;AAEjF,6CAM4B;AAH1B,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAIlB;;;;;;;;;;;;;;;;GAgBG;AAEI,IAAM,kBAAkB,GAAxB,MAAM,kBAAmB,SAAQ,KAAK;CAAG,CAAA;AAAnC,kBAAkB;IAD9B,IAAA,yCAA0B,EAAC,oBAAoB,CAAC;GACpC,kBAAkB,CAAiB;AAAnC,gDAAkB;AAE/B,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;AAgF1G;;;;;;;;;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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;;;;;;;;;AAEH,sDAAsD;AACtD,qCAAmC,CAAC,kDAAkD;AACtF,uDAAqD;AAErD,sDAAyD;AACzD,sEAAiF;AAEjF,6CAM4B;AAH1B,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAIlB;;;;;;;;;;;;;;;;GAgBG;AAEI,IAAM,kBAAkB,GAAxB,MAAM,kBAAmB,SAAQ,KAAK;CAAG,CAAA;AAAnC,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,yCAA0B,EAAC,oBAAoB,CAAC;GACpC,kBAAkB,CAAiB;AAEhD,6EAA6E;AAC7E,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;AACpF,IAAI,CAAE,UAAkB,CAAC,uBAAuB,CAAC,EAAE,CAAC;IACjD,UAAkB,CAAC,uBAAuB,CAAC,GAAG,IAAI,oCAAiB,EAAW,CAAC;AAClF,CAAC;AAEY,QAAA,iBAAiB,GAAgC,UAAkB,CAAC,uBAAuB,CAAC,CAAC;AAgF1G;;;;;;;;;GASG;AACH,MAAa,OAAO;IAClB;;;;OAIG;IACI,MAAM,CAAC,OAAO;QACnB,MAAM,KAAK,GAAG,yBAAiB,CAAC,QAAQ,EAAE,CAAC;QAC3C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAuDD;;;;OAIG;IACH,YACE,IAAU,EACV,SAAyB,EACzB,kBAA+B,EAC/B,SAAkC,EAClC,GAAW;QASb;;;;;;;;;;;;;;;;;;;;WAoBG;QACa,cAAS,GAAG,CAAC,OAAiB,EAAQ,EAAE;YACtD,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC,CAAC;QAEF;;;;WAIG;QACa,UAAK,GAAG,CAAC,EAAY,EAAiB,EAAE;YACtD,IAAI,MAAsB,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAC1C,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,IAAA,iBAAU,EAAC,EAAE,CAAC,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC;YACH,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;QACnF,CAAC,CAAC;QA3CA,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,GAAG,CAAC;IACjB,CAAC;CAuCF;AA3HD,0BA2HC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,qHAAqH;IACrH,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC;AAChC,CAAC;AAHD,oCAGC;AAED;;;;GAIG;AACU,QAAA,GAAG,GAAW;IACzB,gGAAgG;IAChG,wGAAwG;IACxG,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAAkB;QACtD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACzD,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,IAAkB;QACtC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,IAAkB;QACtC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,SAAgB,KAAK,CAAC,EAAY;IAChC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC;AAFD,sBAEC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,SAAS,CAAC,OAAiB;IACzC,OAAO,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC;AAFD,8BAEC;AAED;;;;;;;;GAQG;AACH,SAAgB,SAAS;IACvB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC;AACrC,CAAC;AAFD,8BAEC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,kBAAkB;IAChC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,kBAAkB,CAAC;AAC9C,CAAC;AAFD,gDAEC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/activity",
-  "version": "1.8.6",
+  "version": "1.9.0",
   "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.8.6",
+    "@temporalio/common": "1.9.0",
     "abort-controller": "^3.0.0"
   },
   "bugs": {
@@ -32,5 +32,5 @@
     "src",
     "lib"
   ],
-  "gitHead": "1e95cf92ec5e6efffb7aedb064ea46be05df0c14"
+  "gitHead": "5096976287616207edcd3e4281a2a5e1f7393e33"
 }

package/src/index.ts

@@ -69,9 +69,10 @@
  * @module
  */
 
+// Keep this around until we drop support for Node 14.
 import 'abort-controller/polyfill'; // eslint-disable-line import/no-unassigned-import
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { Logger, Duration } from '@temporalio/common';
+import { Logger, Duration, LogLevel, LogMetadata } from '@temporalio/common';
 import { msToNumber } from '@temporalio/common/lib/time';
 import { SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
 
@@ -115,78 +116,78 @@ export const asyncLocalStorage: AsyncLocalStorage<Context> = (globalThis as any)
  * Holds information about the current Activity Execution. Retrieved inside an Activity with `Context.current().info`.
  */
 export interface Info {
-  taskToken: Uint8Array;
+  readonly taskToken: Uint8Array;
   /**
    * Base64 encoded `taskToken`
    */
-  base64TaskToken: string;
-  activityId: string;
+  readonly base64TaskToken: string;
+  readonly activityId: string;
   /**
    * Exposed Activity function name
    */
-  activityType: string;
+  readonly activityType: string;
   /**
    * The namespace this Activity is running in
    */
-  activityNamespace: string;
+  readonly activityNamespace: string;
   /**
    * Attempt number for this activity
    */
-  attempt: number;
+  readonly attempt: number;
   /**
    * Whether this activity is scheduled in local or remote mode
    */
-  isLocal: boolean;
+  readonly isLocal: boolean;
   /**
    * Information about the Workflow that scheduled the Activity
    */
-  workflowExecution: {
-    workflowId: string;
-    runId: string;
+  readonly workflowExecution: {
+    readonly workflowId: string;
+    readonly runId: string;
   };
   /**
    * The namespace of the Workflow that scheduled this Activity
    */
-  workflowNamespace: string;
+  readonly workflowNamespace: string;
   /**
    * The module name of the Workflow that scheduled this Activity
    */
-  workflowType: string;
+  readonly workflowType: string;
   /**
    * Timestamp for when this Activity was scheduled in milliseconds
    */
-  scheduledTimestampMs: number;
+  readonly scheduledTimestampMs: number;
   /**
    * Timeout for this Activity from schedule to close in milliseconds.
    */
-  scheduleToCloseTimeoutMs: number;
+  readonly scheduleToCloseTimeoutMs: number;
   /**
    * Timeout for this Activity from start to close in milliseconds
    */
-  startToCloseTimeoutMs: number;
+  readonly startToCloseTimeoutMs: number;
   /**
    * Timestamp for when the current attempt of this Activity was scheduled in milliseconds
    */
-  currentAttemptScheduledTimestampMs: number;
+  readonly currentAttemptScheduledTimestampMs: number;
   /**
    * Heartbeat timeout in milliseconds.
    * If this timeout is defined, the Activity must heartbeat before the timeout is reached.
    * The Activity must **not** heartbeat in case this timeout is not defined.
    */
-  heartbeatTimeoutMs?: number;
+  readonly heartbeatTimeoutMs?: number;
   /**
    * 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;
+  readonly heartbeatDetails: any;
 
   /**
    * Task Queue the Activity is scheduled in.
    *
    * For Local Activities, this is set to the Workflow's Task Queue.
    */
-  taskQueue: string;
+  readonly taskQueue: string;
 }
 
 /**
@@ -200,18 +201,34 @@ export interface Info {
  * Call `Context.current()` from Activity code in order to get the current Activity's Context.
  */
 export class Context {
+  /**
+   * Gets the context of the current Activity.
+   *
+   * Uses {@link https://nodejs.org/docs/latest-v14.x/api/async_hooks.html#async_hooks_class_asynclocalstorage | AsyncLocalStorage} under the hood to make it accessible in nested callbacks and promises.
+   */
+  public static current(): Context {
+    const store = asyncLocalStorage.getStore();
+    if (store === undefined) {
+      throw new Error('Activity context not initialized');
+    }
+    return store;
+  }
+
   /**
    * Holds information about the current executing Activity.
    */
-  public info: Info;
+  public readonly info: Info;
+
   /**
-   * Await this promise in an Activity to get notified of cancellation.
+   * A Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The promise
+   * is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of cancellation.
    *
-   * This promise will never resolve—it will only be rejected with a {@link CancelledFailure}.
+   * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
    *
    * @see [Cancellation](/api/namespaces/activity#cancellation)
    */
   public readonly cancelled: Promise<never>;
+
   /**
    * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to react to
    * Activity cancellation.
@@ -222,24 +239,31 @@ export class Context {
    * {@link https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options child_process}
    * to abort a child process, as well as other built-in node modules and modules found on npm.
    *
+   * Note that to get notified of cancellation, an activity must _also_ {@link Context.heartbeat}.
+   *
    * @see [Cancellation](/api/namespaces/activity#cancellation)
    */
   public readonly cancellationSignal: AbortSignal;
+
   /**
    * 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).
+   * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the current Activity context
+   * will automatically be included as metadata on every log entries, and some key events of the Activity's lifecycle
+   * 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.
+   * To customize log attributes, register a {@link ActivityOutboundCallsInterceptor} that intercepts the
+   * `getLogAttributes()` method.
+   *
+   * Modifying the context logger (eg. `context.log = myCustomLogger` or by an {@link ActivityInboundLogInterceptor}
+   * with a custom logger as argument) is deprecated. Doing so will prevent automatic inclusion of custom log attributes
+   * through the `getLogAttributes()` interceptor. To customize _where_ log messages are sent, set the
+   * {@link Runtime.logger} property instead.
    */
   public log: Logger;
 
@@ -253,13 +277,13 @@ export class Context {
     cancelled: Promise<never>,
     cancellationSignal: AbortSignal,
     heartbeat: (details?: any) => void,
-    logger: Logger
+    log: Logger
   ) {
     this.info = info;
     this.cancelled = cancelled;
     this.cancellationSignal = cancellationSignal;
     this.heartbeatFn = heartbeat;
-    this.log = logger;
+    this.log = log;
   }
 
   /**
@@ -283,33 +307,116 @@ export class Context {
    * :warning: Cancellation is not propagated from this function, use {@link cancelled} or {@link cancellationSignal} to
    * subscribe to cancellation notifications.
    */
-  public heartbeat(details?: unknown): void {
+  public readonly heartbeat = (details?: unknown): void => {
     this.heartbeatFn(details);
-  }
-
-  /**
-   * Gets the context of the current Activity.
-   *
-   * Uses {@link https://nodejs.org/docs/latest-v14.x/api/async_hooks.html#async_hooks_class_asynclocalstorage | AsyncLocalStorage} under the hood to make it accessible in nested callbacks and promises.
-   */
-  public static current(): Context {
-    const store = asyncLocalStorage.getStore();
-    if (store === undefined) {
-      throw new Error('Activity context not initialized');
-    }
-    return store;
-  }
+  };
 
   /**
    * Helper function for sleeping in an Activity.
    * @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: Duration): Promise<void> {
+  public readonly sleep = (ms: Duration): Promise<void> => {
     let handle: NodeJS.Timeout;
     const timer = new Promise<void>((resolve) => {
       handle = setTimeout(resolve, msToNumber(ms));
     });
     return Promise.race([this.cancelled.finally(() => clearTimeout(handle)), timer]);
-  }
+  };
+}
+
+/**
+ * The current Activity's context.
+ */
+export function activityInfo(): Info {
+  // For consistency with workflow.workflowInfo(), we want activityInfo() to be a function, rather than a const object.
+  return Context.current().info;
+}
+
+/**
+ * The logger for this Activity.
+ *
+ * This is a shortcut for `Context.current().log` (see {@link Context.log}).
+ */
+export const log: Logger = {
+  // Context.current().log may legitimately change during the lifetime of an Activity, so we can't
+  // just initialize that field to the value of Context.current().log and move on. Hence this indirection.
+  log(level: LogLevel, message: string, meta?: LogMetadata): any {
+    return Context.current().log.log(level, message, meta);
+  },
+  trace(message: string, meta?: LogMetadata): any {
+    return Context.current().log.trace(message, meta);
+  },
+  debug(message: string, meta?: LogMetadata): any {
+    return Context.current().log.debug(message, meta);
+  },
+  info(message: string, meta?: LogMetadata): any {
+    return Context.current().log.info(message, meta);
+  },
+  warn(message: string, meta?: LogMetadata): any {
+    return Context.current().log.warn(message, meta);
+  },
+  error(message: string, meta?: LogMetadata): any {
+    return Context.current().log.error(message, meta);
+  },
+};
+
+/**
+ * Helper function for sleeping in an Activity.
+ *
+ * This is a shortcut for `Context.current().sleep(ms)` (see {@link Context.sleep}).
+ *
+ * @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
+ */
+export function sleep(ms: Duration): Promise<void> {
+  return Context.current().sleep(ms);
+}
+
+/**
+ * Send a {@link https://docs.temporal.io/concepts/what-is-an-activity-heartbeat | heartbeat} from an Activity.
+ *
+ * If an Activity times out, then during the next retry, the last value of `details` is available at
+ * {@link Info.heartbeatDetails}. This acts as a periodic checkpoint mechanism for the progress of an Activity.
+ *
+ * If an Activity times out on the final retry (relevant in cases in which {@link RetryPolicy.maximumAttempts} is
+ * set), the Activity function call in the Workflow code will throw an {@link ActivityFailure} with the `cause`
+ * attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
+ * {@link TimeoutFailure.lastHeartbeatDetails}.
+ *
+ * This is a shortcut for `Context.current().heatbeat(ms)` (see {@link Context.heartbeat}).
+ */
+export function heartbeat(details?: unknown): void {
+  Context.current().heartbeat(details);
+}
+
+/**
+ * Return a Promise that fails with a {@link CancelledFailure} when cancellation of this activity is requested. The
+ * promise is guaranteed to never successfully resolve. Await this promise in an Activity to get notified of
+ * cancellation.
+ *
+ * Note that to get notified of cancellation, an activity must _also_ do {@link Context.heartbeat}.
+ *
+ * This is a shortcut for `Context.current().cancelled` (see {@link Context.cancelled}).
+ */
+export function cancelled(): Promise<never> {
+  return Context.current().cancelled;
+}
+
+/**
+ * Return an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that can be used to
+ * react to Activity cancellation.
+ *
+ * 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, as well as other built-in node modules and modules found on npm.
+ *
+ * Note that to get notified of cancellation, an activity must _also_ do {@link Context.heartbeat}.
+ *
+ * This is a shortcut for `Context.current().cancellationSignal` (see {@link Context.cancellationSignal}).
+ */
+export function cancellationSignal(): AbortSignal {
+  return Context.current().cancellationSignal;
 }