streamsapi.js externs: Sink / Source types too strict?

[ricea]

All the Promise-returning methods for ReadableStreamSource and ReadableStreamSink can actually return thenables.

This means that, for example, the return type specified here is too strict:

/** @type {(undefined|function(*):(!Promise<*>|undefined))} */
ReadableStreamSource.prototype.cancel;

I haven't actually had a real problem with this, I just work on the Streams standard. It may well be that there's no need to make this requirement more relaxed.

[vobruba-martin]

Spec doesn't say anything about thenables. Or am I missing something here? https://streams.spec.whatwg.org/

[ricea]

It doesn't mention it explicitly. I brought this up in whatwg/streams#566 and it doesn't seem it's going to be made explicit. You need to follow the algorithms to find out what the exact semantics are. For example, the cancel method is called at https://streams.spec.whatwg.org/#rs-default-controller-private-cancel and https://streams.spec.whatwg.org/#rs-default-controller-private-cancel. In both places it is called via PromiseInvokeOrNoop() where the important step is

5. Otherwise, return a promise resolved with returnValue.[[Value]].

"a promise resolved with" links to https://www.w3.org/2001/tag/doc/promises-guide/#a-promise-resolved-with which then refers to Promise.resolve() in the ecmascript spec. I found it challenging to find the part of the ecmascript spec which says that Promise.resolve() converts a thenable to a Promise, but it does.

To save you the time of chasing them down, all Source and Sink methods which are documented as "can return a promise" are called via PromiseInvokeOrNoop() or PromiseInvokeOrFallbackOrNoop() and so can return a thenable.