Provide guidance on ordering of promises and equivalent events

[jakearchibald]

Some APIs have promises that have an equivalent event. Eg, the web animation API has a finish event and a finished promise. It feels like we should encourage a particular order here.

IMO, the goals are:

• The ordering between events and related promises is predictable.
• There shouldn't be an opportunity for the browser to do unrelated things (such as other tasks, or rendering) between the event listener callbacks and the promise reaction callbacks.

I think that means the order has to be:

1. Queue task
   1. Dispatch event.
   2. Resolve promise.

These must be done in the same task, otherwise the browser may render in between, or run other tasks. If the promise resolves first, the reaction callbacks will be called after the first event listener, but not the second, which seems weird. You could work around this by forcing a microtask checkout between resolving the promise and dispatching the event, but this seems weird again. Besides, event dispatching is synchronous, and promise reactions are asynchronous, so for the same thing I'd expect the synchronous thing to happen first.

[annevk]

https://w3ctag.github.io/design-principles/#promises-and-events (although the wording there isn't ideal).

(I'm not sure we should continue maintaining the promises guide. Putting things into design-principles and IDL directly is prolly better at this point.)