290 lines
15 KiB
TypeScript
290 lines
15 KiB
TypeScript
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;
|