Document issues with Concurrent Listeners in `Promise.race` and Event Loop Behavior

[manualy]

Hi,

I’m encountering an issue with handling multiple user interaction options in my application. Specifically, I want to allow users to interact via either callbackQueries or messages. To achieve this, I’ve been using Promise.race([Promise1, Promise2]) to wait for the first resolved interaction.

The issue occurs after several conversational flows, where unused listeners appear to linger in the event loop, delaying the triggering of the next interaction. As a result, I have to repeat the unused interaction multiple times before the current listener is activated.

I suspect this might be a bug, but it would also be great if a feature for handling multiple conversation choices could be added.

Thanks for your time, and I look forward to your insights on this!

[KnorpelSenf]

It is not a good idea to use Promise.race for this. A wait call will always wait for an update, no matter if you use this update or not. By design, Promise.race throws away the results of all promises but the first one to resolve. This means that your code will wait for updates and then swallow them.

This is explained in more detail at #1190. I also added a code example there.

A better idea to wait for either a callback query or a message is to do

const ctx = await conversation.waitFor(["callback_query:data", "message"])
if (ctx.has("message")) {
  // handle message
} else if (ctx.has("callback_query:data")) {
  // handle callback query
} else {
  ctx satisfies never // exhaustiveness check
}

which does not use concurrent promises at all.

[manualy]

It works!

I think adding some information about this to the documentation could be helpful.

Thanks again for your help!

[KnorpelSenf]

I'll transfer this over to the website repo so we can keep this issue as a reminder to improve the docs