Sleep

Pause a run for minutes, days, or months, with nothing running in your app while it waits.

A run can stop for a set time, then resume: a reminder three days after sign-up, a follow-up a week after an order, a new attempt an hour after a failure. While it sleeps, your app has nothing running and nothing in memory. Nelkap keeps the run, and calls your app again when the time is up.

To pause until something happens rather than for a set time, see Wait for an event.

Sleep for a duration

Call step.sleep with a duration:

nelkap/workflows/send-trial-reminder.ts

import { sendTrialEndingEmail } from '../../emails';
import { nelkap } from '../client';

export async function sendTrialReminder(userId: string) {
  await nelkap.step.sleep('11 days');

  await nelkap.step.run('reminder', () =>
    sendTrialEndingEmail(userId),
  );
}

Started when a trial begins, this run sleeps for 11 days, then sends the reminder. The sleep ends the call: the code after it runs in a later call, once the 11 days are over.

Durations

A duration is a whole number and a unit, like 30 seconds or 3 days. The unit can be singular or plural.

Unit	Example	How it’s counted
second, minute, hour	90 seconds, 2 hours	As an exact length of time.
day, week	3 days, 1 week	As 24 hours and 7 days, whatever the daylight saving time.
month, year	6 months, 1 year	On the calendar, in UTC: 1 month from January 15 ends on February 15.

A month from January 31 runs past the end of February and ends in early March. A sleep lasts up to a year.

Wake-up time

Nelkap checks sleeping runs every minute, so a run resumes within a minute after its time is up. A sleep of a few seconds therefore lasts up to a minute.

When the run wakes, Nelkap calls your app, and your workflow runs from its first line: the steps before the sleep return their saved results, the sleep returns at once, and the work after it runs.

For a pause shorter than a minute, like a second between two requests to a rate-limited API, wait inside the step that makes the requests. The step holds the call open meanwhile, so keep such pauses short.

Sleep until a date

step.sleep takes a duration. To sleep until a date, work out the duration in a step, so every call of the run gets the same one:

export async function remindBeforeEvent(event: {
  id: string;
  startsAt: string;
}) {
  const hours = await nelkap.step.run(
    'hours left',
    () => {
      const hoursUntilStart =
        (Date.parse(event.startsAt) - Date.now()) /
        3_600_000;

      return Math.max(
        0,
        Math.floor(hoursUntilStart) - 24,
      );
    },
  );

  await nelkap.step.sleep(`${hours} hours`);

  await nelkap.step.run('reminder', () =>
    sendEventReminder(event.id),
  );
}

This run sends its reminder a day before the event. The number of hours is saved, so a later call doesn’t compute a new one from a later time. If the event is less than a day away, the duration is 0 hours, and the sleep returns at once, without pausing the run.

Sleep names

A sleep is saved like a step, named after its duration. When a run reaches two sleeps of 1 day, the first matches the first saved one, and the second matches the second.

Changing a sleep’s duration in your code changes its name. A run that already slept reaches it on its next call as a new sleep, and pauses a second time. See Versioning.

Errors

Error	When
Error	The duration isn’t a whole number and a unit, like 1.5 days or tomorrow.
NelkapError badRequest	The sleep would last more than a year.

Like any error your workflow doesn’t catch, either one fails the run. Every code is described in Errors.

Cancel a sleeping run

While a run sleeps, you can cancel it from its page, for example when the user upgrades before the trial reminder goes out. See Cancel a run.