Re: [whatwg/streams] add @@asyncIterator to ReadableStream (#954)

domenic commented on this pull request.



> @@ -866,6 +868,84 @@ option. If <code><a for="underlying source">type</a></code> is set to <code>unde
   </code></pre>
 </div>
 
+<!-- Bikeshed doesn't let us mark this up correctly: https://github.com/tabatkins/bikeshed/issues/1344 -->
+<h5 id="rs-asynciterator" for="ReadableStream">[@@asyncIterator]({ <var>preventCancel</var> = false } = {})</h5>
+
+<div class="note">
+  The <code>@@asyncIterator</code> method creates a <a>default reader</a> and <a lt="locked to a reader">locks</a> the
+  stream to the new reader. While the stream is locked, no other reader can be acquired until this one is <a
+  lt="release a read lock">released</a>.
+
+  This functionality is especially useful for creating abstractions that desire the ability to consume a stream in its
+  entirety. By getting a reader for the stream, you can ensure nobody else can interleave reads with yours or cancel
+  the stream, which would interfere with your abstraction.

This copy-pasted text seems not as useful as the old text.

> @@ -866,6 +868,84 @@ option. If <code><a for="underlying source">type</a></code> is set to <code>unde
   </code></pre>
 </div>
 
+<!-- Bikeshed doesn't let us mark this up correctly: https://github.com/tabatkins/bikeshed/issues/1344 -->
+<h5 id="rs-asynciterator" for="ReadableStream">[@@asyncIterator]({ <var>preventCancel</var> = false } = {})</h5>

What happened to getIterator()?

> +</div>
+
+<emu-alg>
+  1. If ! IsReadableStream(*this*) is *false*, throw a *TypeError* exception.
+  1. Let _reader_ be ? AcquireReadableStreamDefaultReader(*this*).
+  1. Let _iterator_ be ! ObjectCreate(`<a idl>ReadableStreamAsyncIteratorPrototype</a>`).
+  1. Set _iterator_.[[asyncIteratorReader]] to _reader_.
+  1. Set _iterator_.[[preventCancel]] to ! ToBoolean(_preventCancel_).
+  1. Return _iterator_.
+</emu-alg>
+
+<h3 id="rs-asynciterator-prototype" interface
+lt="ReadableStreamAsyncIteratorPrototype">ReadableStreamAsyncIteratorPrototype</h3>
+
+{{ReadableStreamAsyncIteratorPrototype}} is an ordinary object that is used by {{ReadableStream/[@@asyncIterator]()}} to
+construct the objects it returns. Instances of {{ReadableStreamAsyncIteratorPrototype}} implmenet the {{AsyncIterator}}

Typo "implement" (maybe my fault).

> +  1. If ! IsReadableStreamAsyncIterator(*this*) is *false*, throw a *TypeError* exception.
+  1. Let _reader_ be *this*.[[asyncIteratorReader]].
+  1. If _reader_.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
+  1. Return ! ReadableStreamDefaultReaderRead(_reader_, *true*).
+</emu-alg>
+
+<h4 id="rs-asynciterator-prototype-return" method
+for="ReadableStreamAsyncIteratorPrototype">return( <var>value</var> )</h4>
+
+<emu-alg>
+  1. If ! IsReadableStreamAsyncIterator(*this*) is *false*, throw a *TypeError* exception.
+  1. Let _reader_ be *this*.[[asyncIteratorReader]].
+  1. If *this*.[[preventCancel]] is *false*, then:
+    1. If _reader_.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError*
+    exception.
+    1. Let _result_ be ! ReadableStreamReaderGenericCancel(_reader_, _value_).

This needs to be transformed by a fulfillment handler that returns `! ReadableStreamCreateReadResult(_value_, *true*, *true*)`

> +  1. If _reader_.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
+  1. Return ! ReadableStreamDefaultReaderRead(_reader_, *true*).
+</emu-alg>
+
+<h4 id="rs-asynciterator-prototype-return" method
+for="ReadableStreamAsyncIteratorPrototype">return( <var>value</var> )</h4>
+
+<emu-alg>
+  1. If ! IsReadableStreamAsyncIterator(*this*) is *false*, throw a *TypeError* exception.
+  1. Let _reader_ be *this*.[[asyncIteratorReader]].
+  1. If *this*.[[preventCancel]] is *false*, then:
+    1. If _reader_.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError*
+    exception.
+    1. Let _result_ be ! ReadableStreamReaderGenericCancel(_reader_, _value_).
+  1. Otherwise,
+    1. Let _result_ be ! ReadableStreamCreateReadResult(_value_, *true*, *true*).

This needs to be a promise resolved with...

> @@ -403,6 +403,8 @@ like
     <a href="#rs-pipe-through">pipeThrough</a>({ writable, readable }, options)
     <a href="#rs-pipe-to">pipeTo</a>(dest, { preventClose, preventAbort, preventCancel } = {})
     <a href="#rs-tee">tee</a>()

You need to import the cross-reference links from https://github.com/whatwg/streams/pull/950/files#diff-ec9cfa5f3f35ec1f84feb2e59686c34dR21

-- 
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/954#pullrequestreview-153464052