@temporalio/common

import type { temporal } from '@temporalio/proto'; import { Duration } from './time'; export declare const FAILURE_SOURCE = "TypeScriptSDK"; export type ProtoFailure = temporal.api.failure.v1.IFailure; export declare const TimeoutType: { readonly START_TO_CLOSE: "START_TO_CLOSE"; readonly SCHEDULE_TO_START: "SCHEDULE_TO_START"; readonly SCHEDULE_TO_CLOSE: "SCHEDULE_TO_CLOSE"; readonly HEARTBEAT: "HEARTBEAT"; /** @deprecated Use {@link START_TO_CLOSE} instead. */ readonly TIMEOUT_TYPE_START_TO_CLOSE: "START_TO_CLOSE"; /** @deprecated Use {@link SCHEDULE_TO_START} instead. */ readonly TIMEOUT_TYPE_SCHEDULE_TO_START: "SCHEDULE_TO_START"; /** @deprecated Use {@link SCHEDULE_TO_CLOSE} instead. */ readonly TIMEOUT_TYPE_SCHEDULE_TO_CLOSE: "SCHEDULE_TO_CLOSE"; /** @deprecated Use {@link HEARTBEAT} instead. */ readonly TIMEOUT_TYPE_HEARTBEAT: "HEARTBEAT"; /** @deprecated Use `undefined` instead. */ readonly TIMEOUT_TYPE_UNSPECIFIED: undefined; }; export type TimeoutType = (typeof TimeoutType)[keyof typeof TimeoutType]; export declare const encodeTimeoutType: (input: "START_TO_CLOSE" | "SCHEDULE_TO_START" | "SCHEDULE_TO_CLOSE" | "HEARTBEAT" | "TIMEOUT_TYPE_START_TO_CLOSE" | "TIMEOUT_TYPE_SCHEDULE_TO_START" | "TIMEOUT_TYPE_SCHEDULE_TO_CLOSE" | "TIMEOUT_TYPE_HEARTBEAT" | temporal.api.enums.v1.TimeoutType | null | undefined) => temporal.api.enums.v1.TimeoutType | undefined, decodeTimeoutType: (input: temporal.api.enums.v1.TimeoutType | null | undefined) => "START_TO_CLOSE" | "SCHEDULE_TO_START" | "SCHEDULE_TO_CLOSE" | "HEARTBEAT" | undefined; export declare const RetryState: { readonly IN_PROGRESS: "IN_PROGRESS"; readonly NON_RETRYABLE_FAILURE: "NON_RETRYABLE_FAILURE"; readonly TIMEOUT: "TIMEOUT"; readonly MAXIMUM_ATTEMPTS_REACHED: "MAXIMUM_ATTEMPTS_REACHED"; readonly RETRY_POLICY_NOT_SET: "RETRY_POLICY_NOT_SET"; readonly INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR"; readonly CANCEL_REQUESTED: "CANCEL_REQUESTED"; /** @deprecated Use {@link IN_PROGRESS} instead. */ readonly RETRY_STATE_IN_PROGRESS: "IN_PROGRESS"; /** @deprecated Use {@link NON_RETRYABLE_FAILURE} instead. */ readonly RETRY_STATE_NON_RETRYABLE_FAILURE: "NON_RETRYABLE_FAILURE"; /** @deprecated Use {@link TIMEOUT} instead. */ readonly RETRY_STATE_TIMEOUT: "TIMEOUT"; /** @deprecated Use {@link MAXIMUM_ATTEMPTS_REACHED} instead. */ readonly RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED: "MAXIMUM_ATTEMPTS_REACHED"; /** @deprecated Use {@link RETRY_POLICY_NOT_SET} instead. */ readonly RETRY_STATE_RETRY_POLICY_NOT_SET: "RETRY_POLICY_NOT_SET"; /** @deprecated Use {@link INTERNAL_SERVER_ERROR} instead. */ readonly RETRY_STATE_INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR"; /** @deprecated Use {@link CANCEL_REQUESTED} instead. */ readonly RETRY_STATE_CANCEL_REQUESTED: "CANCEL_REQUESTED"; /** @deprecated Use `undefined` instead. */ readonly RETRY_STATE_UNSPECIFIED: undefined; }; export type RetryState = (typeof RetryState)[keyof typeof RetryState]; export declare const encodeRetryState: (input: "IN_PROGRESS" | "NON_RETRYABLE_FAILURE" | "TIMEOUT" | "MAXIMUM_ATTEMPTS_REACHED" | "RETRY_POLICY_NOT_SET" | "INTERNAL_SERVER_ERROR" | "CANCEL_REQUESTED" | "RETRY_STATE_IN_PROGRESS" | "RETRY_STATE_NON_RETRYABLE_FAILURE" | "RETRY_STATE_TIMEOUT" | "RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED" | "RETRY_STATE_RETRY_POLICY_NOT_SET" | "RETRY_STATE_INTERNAL_SERVER_ERROR" | "RETRY_STATE_CANCEL_REQUESTED" | temporal.api.enums.v1.RetryState | null | undefined) => temporal.api.enums.v1.RetryState | undefined, decodeRetryState: (input: temporal.api.enums.v1.RetryState | null | undefined) => "IN_PROGRESS" | "NON_RETRYABLE_FAILURE" | "TIMEOUT" | "MAXIMUM_ATTEMPTS_REACHED" | "RETRY_POLICY_NOT_SET" | "INTERNAL_SERVER_ERROR" | "CANCEL_REQUESTED" | undefined; /** * A category to describe the severity and change the observability behavior of an application failure. * * Currently, observability behavior changes are limited to: * - activities that fail due to a BENIGN application failure emit DEBUG level logs and do not record metrics * * @experimental Category is a new feature and may be subject to change. */ export declare const ApplicationFailureCategory: { readonly BENIGN: "BENIGN"; }; export type ApplicationFailureCategory = (typeof ApplicationFailureCategory)[keyof typeof ApplicationFailureCategory]; export declare const encodeApplicationFailureCategory: (input: "BENIGN" | temporal.api.enums.v1.ApplicationErrorCategory | "APPLICATION_ERROR_CATEGORY_BENIGN" | null | undefined) => temporal.api.enums.v1.ApplicationErrorCategory | undefined, decodeApplicationFailureCategory: (input: temporal.api.enums.v1.ApplicationErrorCategory | null | undefined) => "BENIGN" | undefined; export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution; /** * Represents failures that can cross Workflow and Activity boundaries. * * **Never extend this class or any of its children.** * * The only child class you should ever throw from your code is {@link ApplicationFailure}. */ export declare class TemporalFailure extends Error { readonly cause?: Error | undefined; /** * The original failure that constructed this error. * * Only present if this error was generated from an external operation. */ failure?: ProtoFailure; constructor(message?: string | undefined | null, cause?: Error | undefined); } /** Exceptions originated at the Temporal service. */ export declare class ServerFailure extends TemporalFailure { readonly nonRetryable: boolean; constructor(message: string | undefined, nonRetryable: boolean, cause?: Error); } /** * `ApplicationFailure`s are used to communicate application-specific failures in Workflows and Activities. * * The {@link type} property is matched against {@link RetryPolicy.nonRetryableErrorTypes} to determine if an instance * of this error is retryable. Another way to avoid retrying is by setting the {@link nonRetryable} flag to `true`. * * In Workflows, if you throw a non-`ApplicationFailure`, the Workflow Task will fail and be retried. If you throw an * `ApplicationFailure`, the Workflow Execution will fail. * * In Activities, you can either throw an `ApplicationFailure` or another `Error` to fail the Activity Task. In the * latter case, the `Error` will be converted to an `ApplicationFailure`. The conversion is done as following: * * - `type` is set to `error.constructor?.name ?? error.name` * - `message` is set to `error.message` * - `nonRetryable` is set to false * - `details` are set to null * - stack trace is copied from the original error * * When an {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the * `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the * Workflow. */ export declare class ApplicationFailure extends TemporalFailure { readonly type?: string | undefined | null; readonly nonRetryable?: boolean | undefined | null; readonly details?: unknown[] | undefined | null; readonly nextRetryDelay?: Duration | undefined | null; readonly category?: ApplicationFailureCategory | undefined | null; /** * Alternatively, use {@link fromError} or {@link create}. */ constructor(message?: string | undefined | null, type?: string | undefined | null, nonRetryable?: boolean | undefined | null, details?: unknown[] | undefined | null, cause?: Error, nextRetryDelay?: Duration | undefined | null, category?: ApplicationFailureCategory | undefined | null); /** * Create a new `ApplicationFailure` from an Error object. * * First calls {@link ensureApplicationFailure | `ensureApplicationFailure(error)`} and then overrides any fields * provided in `overrides`. */ static fromError(error: Error | unknown, overrides?: ApplicationFailureOptions): ApplicationFailure; /** * Create a new `ApplicationFailure`. * * By default, will be retryable (unless its `type` is included in {@link RetryPolicy.nonRetryableErrorTypes}). */ static create(options: ApplicationFailureOptions): ApplicationFailure; /** * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to false. Note that this error will still * not be retried if its `type` is included in {@link RetryPolicy.nonRetryableErrorTypes}. * * @param message Optional error message * @param type Optional error type (used by {@link RetryPolicy.nonRetryableErrorTypes}) * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}. */ static retryable(message?: string | null, type?: string | null, ...details: unknown[]): ApplicationFailure; /** * Get a new `ApplicationFailure` with the {@link nonRetryable} flag set to true. * * When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if `type` is not * listed in {@link RetryPolicy.nonRetryableErrorTypes}). * * @param message Optional error message * @param type Optional error type * @param details Optional details about the failure. Serialized by the Worker's {@link PayloadConverter}. */ static nonRetryable(message?: string | null, type?: string | null, ...details: unknown[]): ApplicationFailure; } export interface ApplicationFailureOptions { /** * Error message */ message?: string; /** * Error type (used by {@link RetryPolicy.nonRetryableErrorTypes}) */ type?: string; /** * Whether the current Activity or Workflow can be retried * * @default false */ nonRetryable?: boolean; /** * Details about the failure. Serialized by the Worker's {@link PayloadConverter}. */ details?: unknown[]; /** * If set, overrides the delay until the next retry of this Activity / Workflow Task. * * Retry attempts will still be subject to the maximum retries limit and total time limit defined * by the policy. */ nextRetryDelay?: Duration; /** * Cause of the failure */ cause?: Error; /** * Severity category of the application error. * Affects worker-side logging and metrics behavior of this failure. */ category?: ApplicationFailureCategory; } /** * This error is thrown when Cancellation has been requested. To allow Cancellation to happen, let it propagate. To * ignore Cancellation, catch it and continue executing. Note that Cancellation can only be requested a single time, so * your Workflow/Activity Execution will not receive further Cancellation requests. * * When a Workflow or Activity has been successfully cancelled, a `CancelledFailure` will be the `cause`. */ export declare class CancelledFailure extends TemporalFailure { readonly details: unknown[]; constructor(message: string | undefined, details?: unknown[], cause?: Error); } /** * Used as the `cause` when a Workflow has been terminated */ export declare class TerminatedFailure extends TemporalFailure { constructor(message: string | undefined, cause?: Error); } /** * Used to represent timeouts of Activities and Workflows */ export declare class TimeoutFailure extends TemporalFailure { readonly lastHeartbeatDetails: unknown; readonly timeoutType: TimeoutType; constructor(message: string | undefined, lastHeartbeatDetails: unknown, timeoutType: TimeoutType); } /** * Contains information about an Activity failure. Always contains the original reason for the failure as its `cause`. * For example, if an Activity timed out, the cause will be a {@link TimeoutFailure}. * * This exception is expected to be thrown only by the framework code. */ export declare class ActivityFailure extends TemporalFailure { readonly activityType: string; readonly activityId: string | undefined; readonly retryState: RetryState; readonly identity: string | undefined; constructor(message: string | undefined, activityType: string, activityId: string | undefined, retryState: RetryState, identity: string | undefined, cause?: Error); } /** * Contains information about a Child Workflow failure. Always contains the reason for the failure as its {@link cause}. * For example, if the Child was Terminated, the `cause` is a {@link TerminatedFailure}. * * This exception is expected to be thrown only by the framework code. */ export declare class ChildWorkflowFailure extends TemporalFailure { readonly namespace: string | undefined; readonly execution: WorkflowExecution; readonly workflowType: string; readonly retryState: RetryState; constructor(namespace: string | undefined, execution: WorkflowExecution, workflowType: string, retryState: RetryState, cause?: Error); } /** * Thrown when a Nexus Operation executed inside a Workflow fails. * * @experimental Nexus support in Temporal SDK is experimental. */ export declare class NexusOperationFailure extends TemporalFailure { readonly scheduledEventId: number | undefined; readonly endpoint: string; readonly service: string; readonly operation: string; readonly operationToken: string | undefined; constructor(message: string | undefined, scheduledEventId: number | undefined, endpoint: string, service: string, operation: string, operationToken: string | undefined, cause?: Error); } /** * This exception is thrown in the following cases: * - Workflow with the same Workflow ID is currently running and the {@link WorkflowOptions.workflowIdConflictPolicy} is `WORKFLOW_ID_CONFLICT_POLICY_FAIL` * - There is a closed Workflow with the same Workflow Id and the {@link WorkflowOptions.workflowIdReusePolicy} * is `WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE` * - There is closed Workflow in the `Completed` state with the same Workflow Id and the {@link WorkflowOptions.workflowIdReusePolicy} * is `WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY` */ export declare class WorkflowExecutionAlreadyStartedError extends TemporalFailure { readonly workflowId: string; readonly workflowType: string; constructor(message: string, workflowId: string, workflowType: string); } /** * If `error` is already an `ApplicationFailure`, returns `error`. * * Otherwise, converts `error` into an `ApplicationFailure` with: * * - `message`: `error.message` or `String(error)` * - `type`: `error.constructor.name` or `error.name` * - `stack`: `error.stack` or `''` */ export declare function ensureApplicationFailure(error: unknown): ApplicationFailure; /** * If `err` is an Error it is turned into an `ApplicationFailure`. * * If `err` was already a `TemporalFailure`, returns the original error. * * Otherwise returns an `ApplicationFailure` with `String(err)` as the message. */ export declare function ensureTemporalFailure(err: unknown): TemporalFailure; /** * Get the root cause message of given `error`. * * In case `error` is a {@link TemporalFailure}, recurse the `cause` chain and return the root `cause.message`. * Otherwise, return `error.message`. */ export declare function rootCause(error: unknown): string | undefined;