Skip to main content

Failure detection - TypeScript SDK feature guide

This page shows how to do the following:

Workflow Timeouts​

How to set Workflow Timeouts using the Temporal TypeScript SDK

Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution.

Workflow Timeouts are set when starting a Workflow using either the Client or Workflow API.

The following properties can be set on the WorkflowOptions when starting a Workflow using either the Client or Workflow API:

await client.workflow.start(example, {
  taskQueue,
  workflowId,
  // Set Workflow Timeout duration
  workflowExecutionTimeout: '1 day',
  // workflowRunTimeout: '1 minute',
  // workflowTaskTimeout: '30 seconds',
});

Workflow retries​

How to set Workflow retries using the Temporal TypeScript SDK

A Retry Policy can work in cooperation with the timeouts to provide fine controls to optimize the execution experience.

Use a Retry Policy to retry a Workflow Execution in the event of a failure.

Workflow Executions do not retry by default, and Retry Policies should be used with Workflow Executions only in certain situations.

The Retry Policy can be set through the WorkflowOptions.retry property when starting a Workflow using either the Client or Workflow API.

const handle = await client.workflow.start(example, {
  taskQueue,
  workflowId,
  retry: {
    maximumAttempts: 3,
    maximumInterval: '30 seconds',
  },
});

Activity Timeouts​

How to set Activity Timeouts using the Temporal TypeScript SDK

Each Activity Timeout controls the maximum duration of a different aspect of an Activity Execution.

The following Timeouts are available in the Activity Options:

An Activity Execution must have either the Start-To-Close or the Schedule-To-Close Timeout set.

The following properties can be set on the ActivityOptions when creating Activity proxy functions using the proxyActivities() API:

const { myActivity } = proxyActivities<typeof activities>({
  scheduleToCloseTimeout: '5m',
  // startToCloseTimeout: "30s", // recommended
  // scheduleToStartTimeout: "60s",
});

Activity Retry Policy​

How to set an Activity Retry Policy using the Temporal TypeScript SDK

A Retry Policy works in cooperation with the timeouts to provide fine controls to optimize the execution experience.

Activity Executions are automatically associated with a default Retry Policy if a custom one is not provided.

To set an Activity's Retry Policy in TypeScript, assign the ActivityOptions.retry property when creating the corresponding Activity proxy function using the proxyActivities() API.

const { myActivity } = proxyActivities<typeof activities>({
  // ...
  retry: {
    initialInterval: '10s',
    maximumAttempts: 5,
  },
});

Activity next Retry delay​

How to override the next Retry delay following an Activity failure using the Temporal TypeScript SDK

The time to wait after a retryable Activity failure until the next retry is attempted is normally determined by that Activity's Retry Policy. However, an Activity may override that duration when explicitly failing with an ApplicationFailure by setting a next Retry delay.

To override the next Retry delay for an ApplicationFailure thrown by an Activity in TypeScript, provide the nextRetryDelay property on the object argument of the ApplicationFailure.create() factory method.

throw ApplicationFailure.create({
  // ...
  nextRetryDelay: '15s',
});

Heartbeat an Activity​

How to Heartbeat an Activity using the Temporal TypeScript SDK

An Activity Heartbeat is a ping from the Worker Process that is executing the Activity to the Temporal Service. Each Heartbeat informs the Temporal Service that the Activity Execution is making progress and the Worker has not crashed. If the Temporal Service does not receive a Heartbeat within a Heartbeat Timeout time period, the Activity will be considered as timed out and another Activity Task Execution may be scheduled according to the Retry Policy.

Activity Cancellations are delivered to Activities from the Temporal Service when they Heartbeat. Activities that don't Heartbeat can't get notified of Cancellation requests.

Heartbeats may not always be sent to the Temporal Service—they may be throttled by the Worker. Heartbeat throttling may lead to Cancellation getting delivered later than expected.

To Heartbeat an Activity Execution in TypeScript, call the heartbeat() function from the Activity implementation.

export async function myActivity(): Promise<void> {
  for (let progress = 1; progress <= 1000; ++progress) {
    // Do something that takes time
    await sleep('1s');

    heartbeat();
  }
}

An Activity may optionally checkpoint its progression, by providing a details argument to the heartbeat() function. Should the Activity Execution times out and gets retried, then the Temporal Server will provide the details from the last Heartbeat it received to the next Activity Execution. This can be used to allow the Activity to efficiently resume its work.

export async function myActivity(): Promise<void> {
  // Resume work from latest heartbeat, if there's one, or start from 1 otherwise
  const startingPoint = activityInfo().heartbeatDetails?.progress ?? 1;

  for (let progress = startingPoint; progress <= 1000; ++progress) {
    // Do something that takes time
    await sleep('1s');

    heartbeat({ progress });
  }
}

Activity Heartbeat Timeout​

How to set a Heartbeat Timeout using the Temporal TypeScript SDK

A Heartbeat Timeout works in conjunction with Activity Heartbeats. If the Temporal Server doesn't receive a Heartbeat before expiration of the Heartbeat Timeout, the Activity is considered as timed out and another Activity Task Execution may be scheduled according to the Retry Policy.

To set an Activity's Heartbeat Timeout in TypeScript, set the ActivityOptions.heartbeatTimeout property when creating the corresponding Activity proxy functions using the proxyActivities() API.

const { myLongRunningActivity } = proxyActivities<typeof activities>({
  // ...
  heartbeatTimeout: '30s',
});