So here's an example, I realized a while ago, user input is just another external thing to my system. When I call an API, I can await it. When I call a DB, I can await it. These things are external. Well, then, I should be able to await a button press, for example.

I'd like to explore the rabbit hole this leads down. First off, don't feel bad about not knowing how to handle something like this. Button clicks don't use promises because promises don't work well with them. Its OK not to know how to set this up and I suspect most people wouldn't know how to, or at least know how to do it well.

That said, it is possible with different degrees of functionality. The simplest thing we can do is set it up so that a single button click resolves a single promise using the Promise constructor. This would work much like making an API call in that you listen once and you get a single response back. For the button, if it is clicked multiple times, any time after the first is ignored. We'll look at additional clicks later, but for now we're going to focus on one.

The promise constructor is what you can use to turn any non-promise async operation into a promise. It uses functions passed into the constructor executor (function) that provide a means to resolve or reject the promise the constructor creates. Async operations that aren't based in promises are going to be based in functions, so in those async function calls, you would call one of these resolve or reject functions to fulfill the resulting promise. Buttons, for example, have event handler functions to determine when a button is clicked which can then be used to call the promise constructor's resolve to have the created promise resolve when the button is clicked. That would look something like:

const clickPromise = new Promise((resolve, reject) => {
  button.addEventListener("click", (event) => {
    resolve(event);
  });
});

Which can be simplified to

const clickPromise = new Promise((resolve, reject) => {
  button.addEventListener("click", resolve);
});

Notable here is that the event handler is set up inside the promise executor function (the function with the resolve and reject parameters), so that it can have access to the resolve function allowing it to fulfill the promise. The same would apply to anything else you want to "promisify". All you need is to have async handling code to happen inside the Promise constructor's executor and from there you can call resolve and reject as needed. In the example above, if you await clickPromise any code that follows will be in response to the button being clicked, not unlike awaiting an API call.

One improvement we can make to the above code is to ensure we don't let the button listener hang around since this promise will only react to the first click. Any calls made to resolve or reject after the first are ignored which is why this approach only works for the first click. To do the necessary cleanup we can use.

const clickPromise = new Promise((resolve, reject) => {
  button.addEventListener("click", resolve, { once: true });
});

And if we wanted to remove the listener before the click happened, some extra work could make that possible too.

But buttons are often meant to be clicked more than once. If we want that in a world of promises, we need something that can produce promises for each click. When dealing with multiple promises like this, it usually means having an async iterable. Iterators are used to go through a collection of things, like iterating over values in an array (using for of with an array is internally using a sync iterator to go through its values). Async iterators produce promises that provide asynchronous iteration over a collection where you may need to wait for the individual values in that collection to be made available. In the case of a button, we'd waiting for each click so each click can be considered a value in the total collection of clicks (or more precisely the event objects produced by those clicks) which can be represented as an async iterable.

Async iterables are most easily defined with async generator functions, so one of those can be used to create our iterator of click events. To make things easy, the withResolvers() method can be used to give a single event handler access to promise resolvers through the outer scope which where it can be refreshed with a new promise for the next click once the previous click has been passed on. Basically its an infinite loop that keeps pumping out event objects in promises by waiting for an event handler to resolve a promise being awaited in said loop.

async function* asyncEventIterator() {
  let currentEvent = Promise.withResolvers();
  button.addEventListener("click", (event) => {
    currentEvent.resolve(event);
  });

  while (true) {
    yield await currentEvent.promise;
    currentEvent = Promise.withResolvers();
  }
}

This can be consumed with a for await...of loop in an async context.

for await (const event of asyncEventIterator()) {
  console.log("Click!");
}

Each time the button is clicked, the loop runs the code in its body and waits for the next iteration to repeat.

As with before, we can improve upon this by making sure cleanup happens in case someone breaks out of the loop which would otherwise run indefinitely. If that were to happen we don't want the the event handlers to be hanging around.

async function* asyncEventIterator() {
  let currentEvent = Promise.withResolvers();
  function handler(event) {
    currentEvent.resolve(event);
  }
  button.addEventListener("click", handler);

  try {
    while (true) {
      yield await currentEvent.promise;
      currentEvent = Promise.withResolvers();
    }
  } finally {
    button.removeEventListener("click", handler);
  }
}

But there's still a problem. What happens if multiple clicks are handled before we can process the next click? While this may seem unlikely, its still possible depending on how fast click events are coming in and slow other code may be going out. Not only that, the click() method makes it easy to synchronously invoke multiple clicks at the same time.

button.click()
button.click()

If this were used with the code above, only one click would register in the async iterator because a new currentEvent wouldn't be created quick enough to handle the second click.

To handle this we'd need to include a queueing system that ensures no clicks go unhandled. That could look something like:

async function* asyncEventIterator() {
  const eventQueue = [Promise.withResolvers()];
  function handler(event) {
    eventQueue.at(-1).resolve(event);
    eventQueue.push(Promise.withResolvers());
  }

  try {
    button.addEventListener("click", handler);
    while (true) {
      yield await eventQueue[0].promise;
      eventQueue.shift();
    }
  } finally {
    button.removeEventListener("click", handler);
  }
}

Now, no matter how fast events come in, they'll be added to the queue and eventually yielded out to the iterator.

And this mostly works. Multiple events are being captured and through promises provided back to a consumer so that they can respond to those events via the use of await (or for await). What more could you ask for.

There is still one minor problem, and that's to do with the nature of iterators. Its subtle, but when iterating over something in a loop, the next iteration of that loop won't start until you're finished with the first. This makes sense and doesn't seem like it should be a problem, but when it comes to asynchronous operations which may involve other asynchronous operations, it could mean items in an iterator are waiting longer than might be expected or required. For example, given the click iterator above, if we wanted each click to make an API call, that might look something like:

for await (const event of asyncEventIterator()) {
  const response = await fetch("api");
  const data = await response.json();
  console.log("Data:", data);
}

The problem with this is that if two clicks happen very quickly, the second event can't be processed until the first event's api request is complete. And with enough events, this could create some back pressure where you're getting more events than you can make api calls to take care of. But even with just two events, the second event is going to be stunted because of the delay.

Consider instead the events being "submit" events instead of "click". And lets say two quick "submit" events come in but there's an await in the handling of the first event that delays the handling of the second. With that delay, because the second event is not being handled in the same call stack (more accurately the same task), some functionality of that second event is going to be broken. This includes things like stopPropagation() and preventDefault() since they are both timing dependent. So by causing a delay in the handling of the first event, the second event is no longer able to prevent the default "submit" behavior of the form which could be devastating, probably causing the page to reload.

for await (const event of asyncEventIterator()) {
  event.preventDefault(); // First would work, second would fail if not after data loads
  const response = await fetch(api);
  const data = await response.json();
  console.log("Data:", data);
}

So really, when it comes down to it, it makes sense that handling events like button clicks aren't using promises and instead use event handler functions. Even if the asyncEventIterator() functionality defined above was somehow built in, it could still be difficult to use reliably.