sleep

Pause workflow execution for a duration or until a specific time

Sleep within a workflow for a given duration or until a specific date. This is a durable sleep that persists across workflow suspensions and resumptions.

Signature

function sleep(duration: StringValue): Promise<void>
function sleep(date: Date): Promise<void>
function sleep(durationMs: number): Promise<void>

Parameters

duration · StringValue

A duration string in the format of "1000ms", "1s", "1m", "1h", or "1d".

date · Date

A Date object representing when to resume. Must be a future date.

durationMs · number

The duration to sleep for in milliseconds.

Returns

Promise<void> · Promise<void>

A promise that resolves when the sleep duration has elapsed.

Usage

Sleep with Duration String

Pause for a human-readable duration:

import { sleep } from 'workflow';

export async function workflowWithSleep() {
  "use workflow";

  console.log('Starting...');
  
  await sleep('5s');
  console.log('After 5 seconds');
  
  await sleep('2m');
  console.log('After 2 minutes');
  
  await sleep('1h');
  console.log('After 1 hour');
  
  await sleep('1d');
  console.log('After 1 day');
}

Sleep with Milliseconds

Pause for a specific number of milliseconds:

import { sleep } from 'workflow';

export async function workflowWithMsSleep() {
  "use workflow";

  console.log('Starting...');
  
  await sleep(5000); // 5 seconds
  console.log('After 5000ms');
  
  await sleep(60000); // 1 minute
  console.log('After 60000ms');
}

Sleep Until Specific Date

Pause until a specific point in time:

import { sleep } from 'workflow';

export async function workflowWithDateSleep() {
  "use workflow";

  const tomorrow = new Date();
  tomorrow.setDate(tomorrow.getDate() + 1);
  tomorrow.setHours(9, 0, 0, 0); // 9 AM tomorrow
  
  console.log('Sleeping until:', tomorrow);
  await sleep(tomorrow);
  console.log('Good morning!');
}

Retry Pattern

Implement exponential backoff:

import { sleep } from 'workflow';

export async function workflowWithRetry() {
  "use workflow";

  let attempt = 0;
  const maxAttempts = 5;
  
  while (attempt < maxAttempts) {
    try {
      await processData();
      break;
    } catch (error) {
      attempt++;
      if (attempt < maxAttempts) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        console.log(`Attempt ${attempt} failed, retrying in ${delay}ms`);
        await sleep(delay);
      }
    }
  }
}

Schedule Future Task

Schedule work for a specific time:

import { sleep } from 'workflow';

export async function scheduledWorkflow(scheduledTime: Date) {
  "use workflow";

  console.log('Waiting for scheduled time:', scheduledTime);
  await sleep(scheduledTime);
  
  console.log('Executing scheduled task');
  await executeTask();
}

Polling with Delays

Poll an external system with delays:

import { sleep } from 'workflow';

export async function pollingWorkflow() {
  "use workflow";

  let status = 'pending';
  
  while (status === 'pending') {
    status = await checkStatus();
    console.log('Status:', status);
    
    if (status === 'pending') {
      await sleep('30s'); // Poll every 30 seconds
    }
  }
  
  console.log('Final status:', status);
}

Rate Limiting

Control the rate of operations:

import { sleep } from 'workflow';

export async function rateLimitedWorkflow(items: string[]) {
  "use workflow";

  for (const item of items) {
    await processItem(item);
    await sleep('1s'); // Rate limit to 1 item per second
  }
}

Duration Format

The sleep function accepts duration strings in the following formats:

• "1000ms" - Milliseconds
• "1s" - Seconds
• "1m" - Minutes
• "1h" - Hours
• "1d" - Days

You can also combine units: "1h 30m", "2d 3h", etc.

Notes

• Can only be called inside a workflow function (with "use workflow")
• This is a durable sleep that persists across workflow suspensions
• The workflow will be suspended during sleep and resumed when the duration elapses
• Sleep uses timer events in the event log for durability
• When sleeping until a date, the date must be in the future
• Very long sleep durations (months/years) are supported

Related

• RetryableError - Control step retry timing