Import (and fix) the promises guide

[annevk]

Most of the algorithms in https://www.w3.org/2001/tag/doc/promises-guide for resolving and rejecting should be part of IDL (and formalized in the process). Resolving from "in parallel" should be something that HTML defines I think.

[tobie]

Mmm. I was sure we already had an open issue for this but can't find it.

[annevk]

It's not linked from w3ctag/promises-guide#27 (and now this is).

[domenic]

As background, one of the major things wrong with the promises guide is that it was written before I was bought into the Web IDL ecosystem, so it tries to be usable from JS specs as well. A lot of the definitions take as arguments JS values or JS functions, whereas you really want to be using them with IDL values or lists of steps.

https://www.w3.org/2001/tag/doc/promises-guide#shorthand-phrases is the section in question, mainly.

Here is what I would do for this issue, if I had the time to do so.

• Redefine "a promise resolved with" to use PromiseResolve(%Promise%, x converted from Web IDL to JS).
  • Potentially separate out two variants of it "A promise resolved with" can unexpectedly run JavaScript w3ctag/promises-guide#56 (comment)
  • Nobody uses "x resolved as a promise"; delete that
• Redefine "a promise rejected with" to use %Promise_reject%.
• Fix all call sites of "resolve a promise" etc. to explicitly queue a task, instead of the current implicit task queuing. This fixes Promise-manipulation shorthands have underdefined behavior w3ctag/promises-guide#52.
• Make the Web IDL promise type a wrapper around a PromiseCapability record, not just a JS Promise object.
• Formalize "resolve" and "reject" on Web IDL promise types using the [[Resolve]] and [[Reject]] record fields. Insert type conversions as appropriate. Potentially separate out "resolved with" and "resolved with an arbitrary value".
• Re-do Web IDL's "perform some steps once a promise is settled" to use PerformPromiseThen (with no resultCapability).
  • Add examples of how to use "perform some steps once a promise is settled". Draw on existing usages of "upon fulfillment" and "upon rejection" in promise-heavy specs (e.g. Streams, Service Worker, maybe HTML) to ensure that this pattern is ergonomic.
  • If the pattern is not ergonomic, then update "upon fulfillment" and "upon rejection" to be specializations of "perform some steps once a promise is settled". If it is ergonomic, delete those terms and update all specs to use "perform some steps once a promise is settled".
  • Fix "perform some steps once a promise is settled" to handle type conversion errors in step 2.2.2.
• Formalize "transforming" in terms of PerformPromiseThen with a resultCapability. This will require care around the various conversions involved. Be sure to survey existing usages to make sure they're compatible.
• Import "wait for all" and "get a promise for waiting for all". Those were recently rewritten in Re-do "waiting for all" w3ctag/promises-guide#55 so they should be on OK ground; they just need some conversions between Web IDL and JS type systems.
• Promise-calling may be obsolete (subsumed by "invoking" a callback type with a Promise return value). Survey any existing usages. They may be all in streams, in which case it can move there.
• Add realm arguments to the newly-formalized mechanisms, per Uses of "resolving x as a promise" and so forth need to specify the global w3ctag/promises-guide#46 and possibly some other issues.
• Deal with https://www.w3.org/2001/tag/doc/promises-guide#examples. Some options:
  • Delete
  • Keep as a reference for JS developers, gutting all spec-person-facing content.
  • Rewrite to be Web IDL-based, using the new algorithms
  • Rewrite to be Web IDL-based, and move it into the Web IDL spec
• Do another pass through the guide to make it more Web IDL focused.

I think this could be done relatively piecemeal. Some steps are definitely separable (e.g. fixing realm usage, separating two variants of resolve, maybe fixing the task-queuing). You could also do it definition by definition, if you were willing to add a warning to the promises guide saying "during the transition period, these not-yet-migrated definitions will sometimes be used on Web IDL promise types; if so, that roughly means this."

[Ms2ger]

Make the Web IDL promise type a wrapper around a PromiseCapability record, not just a JS Promise object.

Is there a way to get this record out of an arbitrary Promise object? I believe this would be needed for https://heycam.github.io/webidl/#es-to-promise (as it exists today), since Promise.resolve() returns its argument if it already is a promise.

[domenic]

It seems like using https://tc39.github.io/ecma262/#sec-createresolvingfunctions (and then adding a [[Promise]] field to the result) would work, although I'm a bit unsure about the consequences of a promise floating around with multiple resolve/reject functions associated with it (one from user code and one from the UA).

Ideally UA code should not be resolving/rejecting user-provided promises. So maybe there is a better structure than the one I outlined above, hmm.

For example, [[Resolve]] and [[Reject]] could be null for user-provided promises, and the first steps of "resolve a promise"/"reject a promise" could assert they are non-null, i.e. assert that the promise was UA-created and not user-created?