Wait for an event

Pause a run until something happens, like a person’s answer or another system’s callback, then resume with what it sent.

Some work can’t continue until something happens outside it: a manager approves a refund, a customer confirms an email address, another system finishes a job. A run can wait for that moment, for minutes or for months. While it waits, your app has nothing running. When the event arrives, the run resumes with the event’s payload in hand.

Wait on a key

A run waits on a key that you choose. Your app wakes it by emitting an event with the same key:

nelkap/workflows/refund-order.ts

import {
  askManagerToReview,
  refundPayment,
  sendRefundedEmail,
} from '../../refunds';
import { nelkap } from '../client';

type Review = {
  approved: boolean;
};

export async function refundOrder(orderId: string) {
  await nelkap.step.run('review request', () =>
    askManagerToReview(orderId),
  );

  const review = await nelkap.step.wait<Review>(
    `refund_${orderId}`,
  );

  if (review.approved) {
    await nelkap.step.run('refund', () => refundPayment(orderId));

    await nelkap.step.run('refunded email', () =>
      sendRefundedEmail(orderId),
    );
  }
}

When the manager answers, your app emits the event, for example from the route that receives the answer:

app/refunds.ts

import { nelkap } from '../nelkap';

export async function reviewRefund(
  orderId: string,
  approved: boolean,
) {
  await nelkap.emit({
    event: 'refund.reviewed',
    payload: { approved: approved },
    wakeOn: `refund_${orderId}`,
  });
}

The run resumes, and step.wait returns the event’s payload: here, the manager’s decision. If the event has no payload, step.wait returns null.

The type you give step.wait, here Review, isn’t checked when the event arrives. It describes the payload your app emits, so keep the two in sync.

Choosing a key

Build the key from what the run waits for, like the order it’s about. Your app can then emit the event from anywhere, without knowing the run’s ID:

Key	The run waits for
refund_${orderId}	The review of a refund.
email_confirmed_${userId}	A click on a confirmation link.
export_done_${exportId}	The end of another system’s job.

A key is up to 256 characters. The run’s page shows the key it’s waiting on, next to its status.

Events sent before the wait

An event wakes only the runs already waiting on its key when it arrives. An event emitted before the run reaches its wait isn’t kept for it, and the run keeps waiting.

So ask for what you wait for in the step just before the wait, like the email that asks the manager for a review. The run reaches its wait right after that step, long before anyone can answer.

Shared keys

An event wakes every run waiting on its key, not just one. That’s useful to release many runs at once, like every order waiting for a warehouse to reopen. To wake a single run, make the key unique to it, for example with the ID of what it works on.

Multiple waits

A run can wait several times, on the same key or on different ones. Waits on the same key are matched in order, so a run that waits on reply_${ticketId} in a loop gets each reply in turn, as long as each one arrives while the run is waiting.

Timeouts

A run waits up to a year. After that, it fails with waitExpired.

To give up sooner, start a second workflow that sleeps for the time you allow, then emits the event itself, with a payload that says the time ran out:

nelkap/workflows/refund-order.ts

export async function refundOrder(orderId: string) {
  await nelkap.step.run('review request', () =>
    askManagerToReview(orderId),
  );

  await nelkap.step.run('deadline', () =>
    nelkap.run(expireReview, orderId),
  );

  const review = await nelkap.step.wait<Review>(
    `refund_${orderId}`,
  );

  if (review.approved) {
    await nelkap.step.run('refund', () => refundPayment(orderId));
  }
}

export async function expireReview(orderId: string) {
  await nelkap.step.sleep('7 days');

  await nelkap.step.run('expire', () =>
    nelkap.emit({
      event: 'refund.expired',
      payload: { approved: false },
      wakeOn: `refund_${orderId}`,
    }),
  );
}

Register both workflows. If the manager answers within 7 days, the refund run has already resumed, and the late event wakes nothing. Otherwise, the run resumes with approved: false.

Errors

Error	When
NelkapError badRequest	The key is empty, or longer than 256 characters.

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

Cancel a waiting run

While a run waits, you can cancel it from its page, for example when the customer withdraws a request. See Cancel a run.