WebIDL usage example

[marcoscaceres]

The WebIDL spec is not very clear on the usage of the Promise<t> type. After reading the WebIDL spec, I had assumed that I could express both the resolve type and the error type:

//this is wrong
Promise<(undefined or DOMException)> requestBookmark ();

It would be nice if this doc contained some IDL examples too. And pointed out that there is no way to express what the reject type is going to be in WebIDL. You have to do it in Prose.

[domenic]

@heycam, would you be willing to summarize all the things people should know about using promises in WebIDL? Perhaps briefly here in this issue and I'll transcribe it into longhand for the guide?

[heycam]

Sorry I overlooked your CC here. These are the important points about how Promise<T> is handled in Web IDL at the moment:

• You write Promise types as Promise<T> where T can be any type, and specifies the types of values you can resolve with.
• When passing a JS value to something expecting a Promise<T>, it will be converted by passing it to Promise.resolve (that looks to have been renamed to Promise.cast in the last draft?).
• In prose, for a platform object to do something when a promise passed in by the author is settled, you can link to this "perform steps once promise is settled" term. You would say something like "Once promise has been settled: if promise was fulfilled with value v, do blah; otherwise, if promise was rejected with reason r, do blah." Here v would be an IDL value of type T, and r is effectively of IDL type any and if you want to do anything particular with that you'll need to check its type in prose yourself. The "once promise has been settled" term expands out to calling then() on the Promise object with callbacks representing the fulfilled/rejected branches of the prose.
• It occurs to me that I don't have terms to link to for resolving/rejecting a promise value from prose. I guess these can be the terms that you've already defined in your "writing specs using promises" document.

Let me know if you think anything is missing or if I should change anything.

[domenic]

Thanks @heycam. It looks like there is some duplication between this guide's "prose shorthands" and WebIDL. I am not sure exactly what is the best thing to do with that.

What does the "T" do? If I pass Promise.resolve(5) to a function accepting a Promise<DOMString>, what happens? What about if I pass Promise.resolve(window) to a function accepting Promise<HTMLElement>? What affect, if any, does it have on return type---e.g. if I return Promise.resolve(10) from a method said to return Promise<DOMString>, what happens? And the same question with window vs. HTMLElement.

As for Promise.resolve vs. Promise.cast, as of January Promise.cast was killed in favor of Promise.resolve taking over its former role. I still owe you an abstract operation you can call instead of "the built-in value of Promise.resolve" or similar.

[heycam]

The T does do something, when in prose you invoke the "when the promise is settled" wording. Step 2.2 will convert the value JS value to the IDL type, so that will do the type coercion and possibly throw. So passing Promise.resolve(5) will end up converting the JS Number value 5 to an IDL DOMString value (stringifying it) for the prose to use.

Passing Promise.resolve(window) to something expecting Promise<HTMLElement> will not throw at some point. I guess I'm unclear when that is. :) Will the "run something when the promise is settled" be guaranteed to run in a subsequent event loop iteration, so that the actual call where you pass in the promise object won't throw?

[domenic]

Will the "run something when the promise is settled" be guaranteed to run in a subsequent event loop iteration, so that the actual call where you pass in the promise object won't throw?

Yeah, since it runs inside an onFulfilled or onRejected handler, the code will be guaranteed to run in a future turn, and any exceptions thrown there will be transformed into rejections of the promise returned from that then invocation.

It sounds like the T has no effect on return values, correct?

[heycam]

Return values from where? If you have say

callback Promise<DOMString> Something();

interface OtherThing {
  void f(Something x);
};

and the definition of OtherThing.f says to call x and then do something once the promise has been settled, then the value you will work with in prose has been coerced into an IDL DOMString value already. So that's just like the platform object taking a Promise<DOMString> argument from the earlier comment.

If you mean something like this:

interface Something {
  Promise<DOMString> f();
};

then it is up to the prose for Something.f to create a promise object and return it, and resolve or reject it at some point. If prose resolves it, it should be doing so with an IDL value, and so it should already be of type DOMString. (Otherwise it's a spec error.) Having terms in Web IDL to create the promise object and resolve/reject it, at the IDL level, is something that I still need to add.