It's a little confusing that the return type of ReadableStream.pipe() is WritableStream in the IDL

[tyoshino]

pipe() chaining is introduced in the spec. The reason why BaseReadableStream.pipe()'s return type is made not void should be to allow for chaining.

But it's a bit confusing that it's WritableStream which doesn't have pipe() method though since it's WritableStream (dest is returned), it should pass any type check and also invocation of pipe() on it should work unless the coder make a mistake (pass non ReadableStream to pipe() and try to chain the result).

If it's intentional, it's nice if there're some clarification comments. Otherwise, fix the return type?

[domenic]

I agree. This is one of the reasons I find IDL (of any type, really) to be a poor medium for specifying JavaScript APIs. What I really want to specify is:

• dest:
  • Has a writableState property, a write method, and a thenable-returning waitForWritable method.
  • If { close: true } is passed (the default), has a close method.
  • If an error occurs, has a dispose method.
• this:
  • Has a readableState property, a read method, and a thenable-returning waitForReadable method.
  • If an error occurs, has an abort method.
• Returns dest.

There will be no other type-checking or coercion restrictions beyond those that occur naturally from the written-out pipe function.

The best approach may be to transition to the ES style of specification, e.g. as in the ES Map spec or the ES promises spec.

In the meantime, indeed a clarifying comment would likely be helpful.