ReadableStream[Symbol.asyncIterator] path to stability

[benjamingr]

Hey,

As after landing unhandledRejection I'd like to investigate and gather some community feedback about our API for Symbol.asyncIterator as well as identify possible problems before we make the feature non-experimental. I'd like to aim for Node v12 is a good target for marking the API as stable.

My current plan (which I'd love feedback on) is to:

• Use code search to identify for await usage in Node projects using ReadableStream, analyze it and post findings.
• Post a request for people that are using the feature to provide feedback. Interview those people and gather use cases, current usage and what they're doing.
• Identify requirements for stabilizing the API and suggest a plan for marking the API as stable.

What do you think?

cc @bmeurer @mcollina @zenparsing @nodejs/streams

[targos]

I'm going to try and migrate a small project in a few months. The code is private but I'll be happy to provide feedback.

[benjamingr]

Here are questions I was hoping to ask people, please edit in your own

• How are you currently utilizing async iterators?
• What native and community modules do you commonly use async iterators with?
• Have you noticed any semantic issues with Symbol.asyncIterator?
• Have you found the Symbol.asyncIterator semantics clear and convenient?
• Has performance been an issue with Symbol.asyncIterator? Have there been any cases where you were unable to use Symbol.asyncIterator because of it?
• Is there anything else you'd like to tell us about your ReadableStream usage?

Of course, suggestions to remove/replace these are also welcome

[benjamingr]

Also, if you're interested and we have time, we can do this in time for the Berlin collaborator summit and discuss it there - if it magically aligns for everyone.

[mcollina]

Definitely +1 to all of what you said.

I think the folllwing are also needed:

1. make sure that our semantics matches the ones of WHATWG streams. Ideally code that uses this language construct should work the same.
2. export it in readable-stream@3, and get significant usage on that (this is a big to-do).
3. verify our implementation also works when transpiled (should be) to browsers/node that do not support it.

We can drop the experimental flag in the 10 lts cycle without problems.

[benjamingr]

make sure that our semantics matches the ones of WHATWG streams. Ideally code that uses this language construct should work the same.

@annevk @domenic - what would be the correct way for Node to verify that our semantics match WHATWG expectations?

[annevk]

I suspect you can make use of https://github.com/whatwg/streams/tree/master/reference-implementation (in particular the tests).

[annevk]

The tests are located at https://github.com/w3c/web-platform-tests/tree/master/streams.

[benjamingr]

I created a Google Form, I'll start distributing it later https://goo.gl/forms/BCcCoM81wtpcRWg12

[mcollina]

@benjamingr Should we remove experimental for Node 10? I fear we are not really getting any feedback atm, or everybody is happy with it.

[benjamingr]

@mcollina the feedback I've been getting is that only a few people are actually using it - but those who are are pretty happy. Also that the google form I did was way too to answer lol. I did try to solicit feedback but did not get much other than "works fine" :/

[benjamingr]

Personally I'm + 0.5 on removing experimental - it's not as if we have a lot of wiggle room in the semantics of streams with async iterators anyway.

[mcollina]

I think there is value in having it out of experimental before Node 10 goes LTS.

[benjamingr]

@mcollina feel free to ping me in the PR for a LGTM :)