[whatwg/streams] Rewrite to use Web IDL, and generally modernize (#1035)

Normative changes, all stemming from the Web IDL adaptation:

* All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586.

* All classes now have [Symbol.toStringTag] properties. (At least, pending https://github.com/heycam/webidl/pull/357 resolution.) Closes #952.

* All methods and accesors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults.

* For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. Note that the size function is not settable anymore, but highWaterMark has a setter.

* Some functions have changed their length property value.

* Some exceptions are thrown earlier, at argument-conversion time.

Editorial changes:

* All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification.

* Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885.

* The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907.

* Abstract operations are now consistently alphabetized within their section. Closes #684.

* By using Bikeshed's `<div algorithm>` feature, we now get automatic identifier highlighting. Closes #687.

* Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions.

* Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things.

* Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$].

* Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL.

Other bug fixes:

* Web IDL makes constructor behavior clear, so this closes #965.

---

Note to reviewers: this isn't really a fun thing to review. I started by trying to do this incrementally, e.g. removing emu-algify first, then reformatting to WHATWG conventions/modern Bikeshed syntax, then Web IDL-ifying, to make it more reviewable. But this way turned out to be a lot easier for me, and I don't think this would have gotten done if I'd taken the harder route.

The best review strategy I can think of is just to scroll around randomly in the output preview and see if anything catches your eye.

---

TODOs:

- [ ] Add back async iterators, after https://github.com/heycam/webidl/pull/808 arrives.
- [ ] Update the reference implementation. Probably use [webidl2js](https://github.com/jsdom/webidl2js).
- [ ] See what tests break. Update them all.
- [ ] Add idlharness tests.
- [ ] Add tests for the per-global-ness of the queuing strategy functions.
- [ ] (Optional) Consider removing the hand-curated IDs for non-exported abstract operations. They are painful to maintain and don't buy us much.

---

Here's the pull request template, which we should update as we complete the above list of TODOs. I think in particular asking for implementer interest will be more feasible after we have the test changes up, although the "normative changes" list above is reasonable by itself.

- [ ] At least two implementers are interested (and none opposed):
   * …
   * …
- [ ] [Tests](https://github.com/web-platform-tests/wpt) are written and can be reviewed and commented upon at:
   * …
- [ ] [Implementation bugs](https://github.com/whatwg/meta/blob/master/MAINTAINERS.md#handling-pull-requests) are filed:
   * Chrome: …
   * Firefox: …
   * Safari: …

(See [WHATWG Working Mode: Changes](https://whatwg.org/working-mode#changes) for more details.)

You can view, comment on, or merge this pull request online at:

  https://github.com/whatwg/streams/pull/1035


-- Commit Summary --

  * Rewrite to use Web IDL, and generally modernize

-- File Changes --

    M .editorconfig (15)
    M .gitignore (3)
    M .pr-preview.json (6)
    M .travis.yml (2)
    M Makefile (7)
    M README.md (4)
    M index.bs (10797)
    D local-watch.js (83)
    D package.json (11)

-- Patch Links --

https://github.com/whatwg/streams/pull/1035.patch

https://github.com/whatwg/streams/pull/1035.diff


-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/1035