JSIDL vs WebIDL

[marcoscaceres]

So, if Streams are supposed to be a ES-level thing, then using the non-existent JS IDL may be ok (though the TC39 crowd will likely raise some eyebrows). However, I think it should be dumped in preference for a reference implementation of some sort, as is commonly the case for ES features (at least, that's what I've seen in their Wiki).

If this is supposed to be a browser API, then I don't think we should be so quick to abandon WebIDL (at least, this is not the spec to have this fight!).

During the last Mozilla summit, a lot of folks from Mozilla met up to talk about JSIDL and WebIDL and its future. At Mozilla, we are very sympathetic to the issues with WebIDL (given that @heycam and Boris edit the spec, they know all the warts). However, we feel that evolving WebIDL to fix its issues is a better approach than just throwing the baby out with the bath water. Browser vendors have invested a lot in their WebIDL infrastructure: from code generation to automated testing, so it's a bit presumptuous that browser makers would just abandon all that stuff - more likely what will happen is that someone (like me) will have to rewrite all the JS IDL as WebIDL so that the spec can be implemented in something like Gecko.

I would urge you to consider adding WebIDL to the Streams and help us fix WebIDL instead. We all know it sucks, but we just don't know what all the problems with JSIDL will be (or if it will get any traction at all) - and given that it doesn't really exist yet, it's to early to simply start using it.

If anything, we could do them in parallel or something.

[domenic]

I think the only way to use WebIDL would be to change most return types to "any" and all parameter types to optional any. Do you think that's reasonable? It seems strictly less useful than the current pseudo-JSIDL in the repo.

[marcoscaceres]

No, the reasonable thing to do is to put in the value types you need and then file bugs on WebIDL. It can't be that the rest of the platform can cope with WebIDL but this API can't. That said, having the pseudo-JSIDL in there certainly helps expose the issues with WebIDL - which is why I think we should have both.

However, I think it's more important to have the machinery worked out first so I don't want us to waste time on this right now. This may come back as an issue if we move to both standardize and implement. It may also confuse folks that will be trying to build on top of this API with WebIDL (e.g., Serial, Raw Sockets).

[domenic]

I've removed the reference to JSIDL in the readme, since I think that was just setting up a needless conflict. Instead I made it clear that the loose definition language I am using is just meant to be an illustrative guide, and that the formalization will occur in the same style as the ECMAScript spec.

We can use this issue to track things that cannot be done in WebIDL currently, as a means of giving feedback to the WebIDL team, if desired. Then, as a low-priority after-it's-finalized task, we can try to retrofit an augmented-WebIDL interface onto the full spec, in the interests of ensuring WebIDL is up to the task.

To get the ball rolling on things WebIDL cannot do, see #46 (comment).

[domenic]

This has evolved to something closer to an ES6 class definition, with no types:

https://streams.spec.whatwg.org/#class-definition

I'll leave this open to track eventual WebIDL-ification though.

[youennf]

To be noted that WebIDL usually prescribes function/attribute properties to be enumerable, which is not what streams is doing.

[annevk]

I doubt IDL is still being considered at this point, but I talked a bit with @smaug---- trying to get through the issues he has reading the specification.

I think in part it's because the "class description" lacks a lot of the context IDL gives.

IDL tells you what arguments (types) are and what members end up returning (again types). These bits of information often make it very clear what the flow of a class is like and help understand how things fit together.

If we could convey that somehow in a "class description" I think that'd be a huge help.

The other thing I found personally lacking is links from the "class description" members to where they are defined.

[domenic]

The class description is meant to be for web developers, not for implementers.

[smaug----]

So? Whoever reads a spec should be able to rather quickly to understand what the API is doing. IDL-based specs tend to be rather good with that, since it is often enough to just see the idl to get the big picture. That is very much lacking in the Streams spec.

[domenic]

I think you have a very different idea of how web developers understand JavaScript than actually occurs. Web IDL is generally impenetrable to them, whereas actual ES6 class syntax that mimics what they would interact with in real life is much more helpful.

[annevk]

Doesn't API documentation generally define return values and argument types? I doubt anyone would not want that. Nobody is asking for IDL btw, just high-level object description and links from the description to the definitions.

[smaug----]

Web IDL is generally impenetrable to them

Why you think so? The syntax https://streams.spec.whatwg.org/#rs-class-definition is clearly less informative than webidl-like syntax. I don't mind if we replace 'interface' with 'class', that isn't really relevant. But it matters how much the syntax tells about the behavior. Without any type information it is really hard to understand from the class definition what is supposed to happen.

[ricea]

What proportion of web developers read specs?

Anecdotally, I read specs when I'm implementing or debugging. When I simply want to use something, I search MDN.

[saschanaz]

I think the only way to use WebIDL would be to change most return types to "any" and all parameter types to optional any

TypeScript type definition file uses any in just 6 places. I think we can do this also on WebIDL.

[ricea]

@saschanaz Nitpicking, there are some things in that file which are more restrictive than the standard actually requires. In some cases, this is probably useful, for example:

write?(chunk: any, controller?: WritableStreamDefaultController): void | Promise<any>;

You can return a thenable or actually anything you want from write(). So in practice the return type is any. However, the restriction imposed by the type checker is probably useful in catching bugs.

[saschanaz]

Oh, I thought that 4.2.3 and 4.8.9 says it returns Promise or undefined.

write(chunk, controller) is called when a new chunk of data is ready to be written to the underlying sink. It can return a promise to signal success or failure of the write operation.

Let sinkWritePromise be ! PromiseInvokeOrNoop(controller.[[underlyingSink]], "write", « chunk, controller »).

PromiseInvokeOrNoop is a specialized version of promise-calling that both works on methods and returns a promise for undefined when the method is not present.

[ricea]

Oh, I thought that 4.2.3 and 4.8.9 says it returns Promise or undefined.

The "Note" section in 4.2.3 is non-normative, and priority is given to making it easy-to-understand. See #566.

Chasing the definition of PromiseInvokeOrNoop, we get

4. Let returnValue be InvokeOrNoop(O, P, args).
5. If returnValue is an abrupt completion, return a promise rejected with returnValue.[[Value]].
6. Otherwise, return a promise resolved with returnValue.[[Value]].

Chasing "a promise resolved", we see

"A promise resolved with x" or "x resolved as a promise" is shorthand for the result of Promise.resolve(x), using the initial value of Promise.resolve.

Tracing through the ES spec is exhausting, but you'll eventually end up here: https://tc39.github.io/ecma262/#sec-promise-resolve-functions which explains how Promise.resolve handles different types of value.

[saschanaz]

You mean Promise.resolve and Promise.reject return anything other than Promise?

[domenic]

No, it accepts anything. The return value of write() is passed to Promise.resolve(), which accepts any value, not just void | Promise<any>

[saschanaz]

Ah yes, I misunderstood. Sorry.

[domenic]

Let's move this discussion to #963, wherein I contemplate switching to Web IDL.