@temporalio/common/lib/activity-options.d.ts

Common library for code that's used across the Client, Worker, and/or Workflow

import type { coresdk } from '@temporalio/proto';
import { RetryPolicy } from './retry-policy';
import { Duration } from './time';
import { VersioningIntent } from './versioning-intent';
import { Priority } from './priority';
/**
 * Determines:
 * - whether cancellation requests should be propagated from the current Workflow to the Activity; and
 * - when should the Activity cancellation be reported to Workflow (i.e. at which moment should the
 *   Activity call's promise fail with an `ActivityFailure`, with `cause` set to a `CancelledFailure`).
 *
 * Note that this setting only applies to cancellation originating from cancellation being
 * externally requested on the Workflow itself, or from internal cancellation of the
 * `CancellationScope` in which the Activity call was made. Termination of a Workflow Execution
 * always results in cancellation of its outstanding Activity executions, regardless of those
 * Activities' {@link ActivityCancellationType} settings.
 *
 * @default ActivityCancellationType.WAIT_CANCELLATION_COMPLETED
 */
export declare const ActivityCancellationType: {
    /**
     * Do not propagate cancellation requests to the Activity, and immediately report cancellation
     * to the caller.
     */
    readonly ABANDON: "ABANDON";
    /**
     * Propagate cancellation request from the Workflow to the Activity, yet _immediately_ report
     * cancellation to the caller, i.e. without waiting for the server to confirm the cancellation
     * request.
     *
     * Note that this cancellation type provides no guarantee, from the Workflow-side, that the
     * cancellation request will actually be delivered to the Activity; e.g. the calling Workflow
     * may exit before the delivery is completed, or the Activity may complete (either successfully
     * or uncessfully) before the cancellation is delivered, resulting in a situation where the
     * workflow thinks the activity was cancelled, but the activity actually completed successfully.
     *
     * To ensure that the Workflow is properly informed of the Activity's final state (i.e. either
     * completion or cancellation), use {@link WAIT_CANCELLATION_COMPLETED}.
     */
    readonly TRY_CANCEL: "TRY_CANCEL";
    /**
     * Propagate cancellation request from the Workflow to the Activity, and wait for the activity
     * to complete its execution (either successfully, uncessfully, or as cancelled).
     *
     * Note that the Activity must heartbeat to receive a cancellation notification. This can block
     * the Workflow's cancellation for a long time if the Activity doesn't heartbeat or chooses to
     * ignore the cancellation request.
     */
    readonly WAIT_CANCELLATION_COMPLETED: "WAIT_CANCELLATION_COMPLETED";
};
export type ActivityCancellationType = (typeof ActivityCancellationType)[keyof typeof ActivityCancellationType];
export declare const encodeActivityCancellationType: (input: coresdk.workflow_commands.ActivityCancellationType | import("./type-helpers").RemovePrefix<"", "ABANDON" | "TRY_CANCEL" | "WAIT_CANCELLATION_COMPLETED"> | null | undefined) => coresdk.workflow_commands.ActivityCancellationType | undefined, decodeActivityCancellationType: (input: coresdk.workflow_commands.ActivityCancellationType | null | undefined) => import("./type-helpers").RemovePrefix<"", "ABANDON" | "TRY_CANCEL" | "WAIT_CANCELLATION_COMPLETED"> | undefined;
/**
 * Options for remote activity invocation
 */
export interface ActivityOptions {
    /**
     * Identifier to use for tracking the activity in Workflow history.
     * The `activityId` can be accessed by the activity function.
     * Does not need to be unique.
     *
     * @default an incremental sequence number
     */
    activityId?: string;
    /**
     * Task queue name.
     *
     * @default current worker task queue
     */
    taskQueue?: string;
    /**
     * Heartbeat interval. Activity must heartbeat before this interval passes after a last heartbeat or activity start.
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     */
    heartbeatTimeout?: Duration;
    /**
     * RetryPolicy that define how activity is retried in case of failure. If this is not set, then the server-defined default activity retry policy will be used. To ensure zero retries, set maximum attempts to 1.
     */
    retry?: RetryPolicy;
    /**
     * Maximum time of a single Activity execution attempt. Note that the Temporal Server doesn't detect Worker process
     * failures directly: instead, it relies on this timeout to detect that an Activity didn't complete on time. Therefore, this
     * timeout should be as short as the longest possible execution of the Activity body. Potentially long-running
     * Activities must specify {@link heartbeatTimeout} and call {@link activity.Context.heartbeat} periodically for
     * timely failure detection.
     *
     * Either this option or {@link scheduleToCloseTimeout} is required.
     *
     * @default `scheduleToCloseTimeout` or unlimited
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     */
    startToCloseTimeout?: Duration;
    /**
     * Time that the Activity Task can stay in the Task Queue before it is picked up by a Worker. Do not specify this timeout unless using host-specific Task Queues for Activity Tasks are being used for routing.
     * `scheduleToStartTimeout` is always non-retryable. Retrying after this timeout doesn't make sense as it would just put the Activity Task back into the same Task Queue.
     *
     * @default `scheduleToCloseTimeout` or unlimited
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     */
    scheduleToStartTimeout?: Duration;
    /**
     * Total time that a workflow is willing to wait for the Activity to complete.
     * `scheduleToCloseTimeout` limits the total time of an Activity's execution including retries (use {@link startToCloseTimeout} to limit the time of a single attempt).
     *
     * Either this option or {@link startToCloseTimeout} is required.
     *
     * @default unlimited
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     */
    scheduleToCloseTimeout?: Duration;
    /**
     * Determines:
     * - whether cancellation requests should be propagated from the current Workflow to the Activity; and
     * - when should the Activity cancellation be reported to Workflow (i.e. at which moment should the
     *   Activity call's promise fail with an `ActivityFailure`, with `cause` set to a `CancelledFailure`).
     *
     * Note that this setting only applies to cancellation originating from cancellation being
     * externally requested on the Workflow itself, or from internal cancellation of the
     * `CancellationScope` in which the Activity call was made. Termination of a Workflow Execution
     * always results in cancellation of its outstanding Activity executions, regardless of those
     * Activities' {@link ActivityCancellationType} settings.
     *
     * @default ActivityCancellationType.WAIT_CANCELLATION_COMPLETED
     */
    cancellationType?: ActivityCancellationType;
    /**
     * Eager dispatch is an optimization that improves the throughput and load on the server for scheduling Activities.
     * When used, the server will hand out Activity tasks back to the Worker when it completes a Workflow task.
     * It is available from server version 1.17 behind the `system.enableActivityEagerExecution` feature flag.
     *
     * Eager dispatch will only be used if `allowEagerDispatch` is enabled (the default) and {@link taskQueue} is either
     * omitted or the same as the current Workflow.
     *
     * @default true
     */
    allowEagerDispatch?: boolean;
    /**
     * When using the Worker Versioning feature, specifies whether this Activity should run on a
     * worker with a compatible Build Id or not. See {@link VersioningIntent}.
     *
     * @default 'COMPATIBLE'
     *
     * @deprecated Worker Versioning is now deprecated. Please use the Worker Deployment API instead: https://docs.temporal.io/worker-deployments
     */
    versioningIntent?: VersioningIntent;
    /**
     * A fixed, single-line summary for this workflow execution that may appear in the UI/CLI.
     * This can be in single-line Temporal markdown format.
     *
     * @experimental User metadata is a new API and susceptible to change.
     */
    summary?: string;
    /**
     * Priority of this activity
     */
    priority?: Priority;
}
/**
 * Options for local activity invocation
 */
export interface LocalActivityOptions {
    /**
     * RetryPolicy that defines how an activity is retried in case of failure. If this is not set, then the SDK-defined default activity retry policy will be used.
     * Note that local activities are always executed at least once, even if maximum attempts is set to 1 due to Workflow task retries.
     */
    retry?: RetryPolicy;
    /**
     * Maximum time the local activity is allowed to execute after the task is dispatched. This
     * timeout is always retryable.
     *
     * Either this option or {@link scheduleToCloseTimeout} is required.
     * If set, this must be <= {@link scheduleToCloseTimeout}, otherwise, it will be clamped down.
     *
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     */
    startToCloseTimeout?: Duration;
    /**
     * Limits time the local activity can idle internally before being executed. That can happen if
     * the worker is currently at max concurrent local activity executions. This timeout is always
     * non retryable as all a retry would achieve is to put it back into the same queue. Defaults
     * to {@link scheduleToCloseTimeout} if not specified and that is set. Must be <=
     * {@link scheduleToCloseTimeout} when set, otherwise, it will be clamped down.
     *
     * @default unlimited
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     */
    scheduleToStartTimeout?: Duration;
    /**
     * Indicates how long the caller is willing to wait for local activity completion. Limits how
     * long retries will be attempted.
     *
     * Either this option or {@link startToCloseTimeout} is required.
     *
     * @default unlimited
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     */
    scheduleToCloseTimeout?: Duration;
    /**
     * If the activity is retrying and backoff would exceed this value, a server side timer will be scheduled for the next attempt.
     * Otherwise, backoff will happen internally in the SDK.
     *
     * @default 1 minute
     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
     **/
    localRetryThreshold?: Duration;
    /**
     * Determines:
     * - whether cancellation requests should be propagated from the current Workflow to the Activity; and
     * - when should the Activity cancellation be reported to Workflow (i.e. at which moment should the
     *   Activity call's promise fail with an `ActivityFailure`, with `cause` set to a `CancelledFailure`).
     *
     * Note that this setting only applies to cancellation originating from cancellation being
     * externally requested on the Workflow itself, or from internal cancellation of the
     * `CancellationScope` in which the Activity call was made. Termination of a Workflow Execution
     * always results in cancellation of its outstanding Activity executions, regardless of those
     * Activities' {@link ActivityCancellationType} settings.
     *
     * @default ActivityCancellationType.WAIT_CANCELLATION_COMPLETED
     */
    cancellationType?: ActivityCancellationType;
    /**
     * A fixed, single-line summary for this workflow execution that may appear in the UI/CLI.
     * This can be in single-line Temporal markdown format.
     *
     * @experimental User metadata is a new API and susceptible to change.
     */
    summary?: string;
}