Promises (Re: New Editor's Draft of MediaStream Image Capture)

On 9/4/14 10:22 PM, Robert O'Callahan wrote:
> On Fri, Sep 5, 2014 at 1:36 PM, Jan-Ivar Bruaroey <jib@mozilla.com 
> <mailto:jib@mozilla.com>>wrote:
>
>      Why don't we just get rid of the non-Promises API? I think at
>     this point it's totally OK for specs to depend on Promises.
>
>     +1. Were you thinking of just ImageCapture or gUM too?
>
>
> Both I guess.

I agree. I think it's prudent to revisit this now before we remove 
prefixes. Promises weren't ready a year ago, but that's changed [3] and 
they're an embarrassingly obvious fit for gUM, ImageCapture and 
peerConnection. Also, if we don't nip consistency arguments in the bud, 
it sounds like we'll miss out on promises on methods yet to be added as 
well (replaceTrack).

I see a couple of ways to do this, but the approach I would pick as far 
as the spec goes is to flip the specs to promises cold-turkey, and let 
UAs implement "transition APIs" for the next year that essentially both 
return promises AND optionally let you pass in callbacks at the same 
time, for backwards compatibility.

The cold-turkey webidl pattern for the spec:
--------------------------------------------

Before:
     callback FooSuccessCallback = void (Bar bar);
     void foo (FooSuccessCallback successCallback, CommonErrorCallback 
errorCallback);

After:
     Promise<Bar> foo ();


The "transition API" for UAs for the next year: [4]
-----------------------------------------------

After:
     callback FooSuccessCallback = void (Bar bar);
     Promise<Bar> foo (FooSuccessCallback successCallback, 
CommonErrorCallback errorCallback);

Implementation is easy: we stuff any passed-in callbacksinto the .then() 
of the promise before returning it.

There's help available for spec writers on this here [1][2].

.: Jan-Ivar :.

[1] https://github.com/w3ctag/promises-guide/blob/master/README.md
[2] https://github.com/w3ctag/promises-guide/issues/24Rob

[3] On negatives: The few open issues still being discussed in the 
promises spec AFAICT seems to deal with updating webidl to streamline 
errors when callbacks are used so users wont have to contend with both 
thrown and returned errors, and maybe error types?  which matches our 
remaining weak areas of figuring out error types and handling - so we 
wouldn't pick up any baggage - and it may actually help if we could 
offload these details on to the promises and webidl specs and the nice 
folks there.

[4] createOffer is a bit of a challenge with its options argument coming 
after the callbacks. I'm looking into that.