Re: [heycam/webidl] Import (and fix) the promises guide (#490)

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 https://github.com/w3ctag/promises-guide/issues/56#issuecomment-438499875
  - 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 https://github.com/w3ctag/promises-guide/issues/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 https://github.com/w3ctag/promises-guide/pull/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 https://github.com/w3ctag/promises-guide/issues/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.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/heycam/webidl/issues/490#issuecomment-455578146