Wait for an event

Some work can’t go on 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 goes on 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:

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

  const review = await nelkap.step.wait<{
    approved: boolean;
  }>(`refund_${orderId}`);

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

When the manager answers, your app emits the event:

await nelkap.emit({
  event: 'refund.reviewed',
  payload: { approved: true },
  wakeOn: `refund_${orderId}`,
});

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

Choose the 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:

refund_${orderId} for the review of a refund.
email_confirmed_${userId} for a confirmation link.
export_done_${exportId} for 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.

Make sure the run waits first

An event only wakes the runs already waiting on its key when it arrives. An event emitted before the run reaches its wait doesn’t wake it later. So trigger what you wait for in the step just before the wait, like the email that asks the manager for a review. The run is waiting long before anyone can answer.

Several runs on the same key

An event wakes every run waiting on its key, not just one. To wake a single run, make the key unique to it, for example with the ID of what it works on.

Wait more than once

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.

How long a run can wait

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:

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<{
    approved: boolean;
  }>(`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 gone on, and the late event wakes nothing. Otherwise, the run goes on with approved: false.

Cancel a waiting run

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

Get started

Concepts

Frameworks

Triggers

Write workflows

Deploy

Monitor

Manage

Help

Wait for an event

Wait on a key

Choose the key

Make sure the run waits first

Several runs on the same key

Wait more than once

How long a run can wait

Cancel a waiting run

​Wait on a key

​Choose the key

​Make sure the run waits first

​Several runs on the same key

​Wait more than once

​How long a run can wait

​Cancel a waiting run

Wait on a key

Choose the key

Make sure the run waits first

Several runs on the same key

Wait more than once

How long a run can wait

Cancel a waiting run