Repository navigation
JSIDL vs WebIDL #45
Description
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.
Activity
domenic commentedon Nov 11, 2013
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 commentedon Nov 11, 2013
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).
Explain the style of IDL we are using.
domenic commentedon Nov 16, 2013
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 commentedon Oct 6, 2014
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.
Define global properties
youennf commentedon Jul 18, 2016
To be noted that WebIDL usually prescribes function/attribute properties to be enumerable, which is not what streams is doing.
annevk commentedon Oct 21, 2016
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 commentedon Oct 21, 2016
The class description is meant to be for web developers, not for implementers.
smaug---- commentedon Oct 21, 2016
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 commentedon Oct 21, 2016
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 commentedon Oct 21, 2016
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---- commentedon Oct 21, 2016
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 commentedon Oct 24, 2016
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 commentedon Apr 3, 2017
TypeScript type definition file uses
anyin just 6 places. I think we can do this also on WebIDL.ricea commentedon Apr 12, 2017
@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:
You can return a thenable or actually anything you want from
write(). So in practice the return type isany. However, the restriction imposed by the type checker is probably useful in catching bugs.saschanaz commentedon Apr 12, 2017
Oh, I thought that 4.2.3 and 4.8.9 says it returns Promise or undefined.
ricea commentedon Apr 12, 2017
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
Chasing "a promise resolved", we see
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 commentedon Apr 12, 2017
You meanPromise.resolveandPromise.rejectreturn anything other than Promise?domenic commentedon Apr 12, 2017
No, it accepts anything. The return value of write() is passed to Promise.resolve(), which accepts any value, not just
void | Promise<any>saschanaz commentedon Apr 12, 2017
Ah yes, I misunderstood. Sorry.
write method can return anything
domenic commentedon Nov 7, 2018
Let's move this discussion to #963, wherein I contemplate switching to Web IDL.