Add typed ReadableStream<type> and WritableStream<type>

[jan-ivar]

The WebTransport spec is full of WebIDL with comments like this one (third line):

interface mixin UnidirectionalStreamsTransport {
  Promise<SendStream> createUnidirectionalStream(optional SendStreamParameters parameters = {});
  /* a ReadableStream of ReceiveStream objects */
  readonly attribute ReadableStream incomingUnidirectionalStreams;
};

Without this comment, it'd be hard to reason about what incomingUnidirectionalStreams gives you.

I think ReadableStream and WritableStream deserve the same treatment as Promise here:

interface mixin UnidirectionalStreamsTransport {
  Promise<SendStream> createUnidirectionalStream(optional SendStreamParameters parameters = {});
  readonly attribute ReadableStream<ReceiveStream> incomingUnidirectionalStreams;
};

This would follow a tradition of making I/O types part of an API's code signature, helping readers reason about call sites.

[domenic]

I'm -1 on this, as comments (i.e. things which don't impact the binding generation) are best done as actual comments. You can write

readonly attribute ReadableStream /* of ReceiveStream */ incomingUnidirectionalStreams;

or similar if you'd prefer brevity.

In particular, the problem here is that you could write ReadableStream<bool> in your IDL, or ReadableStream<ReceiveStream>; it wouldn't matter. There's nothing in the spec infrastructure, or implementation infrastructure, to enforce that your ReadableStream contains a given type.

We're actually discussing perhaps removing the <T> syntax for promises as well, since we've discovered that implementations don't seem to do anything with it: see #943 and #782.

[jan-ivar]

In particular, the problem here is that you could write ReadableStream<bool> in your IDL, or ReadableStream<ReceiveStream>; it wouldn't matter.

@domenic Except it would, because WebIDL is normative, whereas comments are (probably?) not.

In a perfect world where every API is backed by a precise algorithm, this might not matter, but that's not always the case.

There's nothing in the spec infrastructure, or implementation infrastructure, to enforce that your ReadableStream contains a given type.

Verification in bindings seems harder to do for outputs than inputs, yet there's precedence for using WebIDL to normatively specify aspects of outputs even when they can't be enforced.

Specifically, the webrtc-stats spec uses required in output dictionaries like RTCRtpStreamStats to denote members user agents MUST implement, even though this isn't easily enforceable by WebIDL infrastructure.

Limiting what we can declare in WebIDL based on tooling's ability to enforce it today seems backwards to me, because WebIDL would appear to have declarative value even without any bindings at all.

We're actually discussing perhaps removing the syntax for promises as well, since we've discovered that implementations don't seem to do anything with it: see #943 and #782.

That seems unfortunate. Is there a link for this discussion? Maybe implementations should do something about it instead?

[jan-ivar]

Additionally, for streams, chunk types may vary unless otherwise specified, so for APIs where they never will, it would seem useful to declare that they don't (or maybe using ReadableStream<any> if they do).