Add @@asyncIterator to ReadableStream

index.bs

@@ -18,6 +18,8 @@ spec:promises-guide; type:dfn;
 <pre class="anchors">
 urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
     text: %Uint8Array%; url: #sec-typedarray-objects; type: constructor
+    text: %AsyncIteratorPrototype%; url: #sec-asynciteratorprototype; type: interface
+    text: AsyncIterator; url: #sec-asynciterator-interface; type: interface
     text: ArrayBuffer; url: #sec-arraybuffer-objects; type: interface
     text: DataView; url: #sec-dataview-objects; type: interface
     text: Number; url: #sec-ecmascript-language-types-number-type; type: interface
@@ -404,6 +406,8 @@ like
                 { preventClose, preventAbort, preventCancel, signal } = {})
     <a href="#rs-pipe-to">pipeTo</a>(dest, { preventClose, preventAbort, preventCancel, signal } = {})
     <a href="#rs-tee">tee</a>()
+
+    <a href="#rs-asynciterator">[@@asyncIterator]</a>({ preventCancel } = {})
   }
 </code></pre>
 
@@ -792,6 +796,90 @@ option. If <code><a for="underlying source">type</a></code> is set to <code>unde
   </code></pre>
 </div>
 
+<h5 id="rs-asynciterator" method for="ReadableStream">getIterator({ <var>preventCancel</var> = false } = {})</h5>
+
+<div class="note">
+  The <code>getIterator</code> method returns an async iterator which can be used to consume the stream. The
+  {{ReadableStreamDefaultReaderAsyncIteratorPrototype/return()}} method of this iterator object will, by default,
+  <a lt="cancel a readable stream">cancel</a> the stream; it will also release the reader.
+</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>
+
+<!-- Bikeshed doesn't let us mark this up correctly: https://github.com/tabatkins/bikeshed/issues/1344 -->
+<h5 id="rs-asynciterator" for="ReadableStream">[@@asyncIterator]()</h5>
+
+<p class="note">
+  The <code>@@asyncIterator</code> method is an alias of {{ReadableStreamDefaultReader/getIterator()}}.
+</p>
+
+The initial value of the <code>@@asyncIterator</code> method is the same function object as the initial value of the
+{{ReadableStream/getIterator()}} method.
+
+<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}} implement the {{AsyncIterator}}
+abstract interface from the JavaScript specification. [[!ECMASCRIPT]]
+
+The {{ReadableStreamAsyncIteratorPrototype}} object must have its \[[Prototype]] internal slot set to
+{{%AsyncIteratorPrototype%}}.
+
+<h4 id="default-reader-asynciterator-prototype-internal-slots">Internal slots</h4>
+Objects created by {{ReadableStream/[@@asyncIterator]()}}, using {{ReadableStreamAsyncIteratorPrototype}} as their
+prototype, are created with the internal slots described in the following table:
+<table>
+  <thead>
+    <tr>
+      <th>Internal Slot</th>
+      <th>Description (<em>non-normative</em>)</th>
+    </tr>
+  </thead>
+  <tr>
+    <td>\[[asyncIteratorReader]]
+    <td class="non-normative">A {{ReadableStreamDefaultReader}} instance
+  </tr>
+  <tr>
+    <td>\[[preventCancel]]
+    <td class="non-normative">A boolean value indicating if the stream will be <a lt="cancel a readable
+    stream">canceled</a> when the async iterator's {{ReadableStreamAsyncIteratorPrototype/return()}} method is called
+  </tr>
+</table>
+
+<h4 id="rs-asynciterator-prototype-next" method for="ReadableStreamAsyncIteratorPrototype">next()</h4>
+
+<emu-alg>
+  1. If ! IsReadableStreamAsyncIterator(*this*) is *false*, return <a>a promise rejected with</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*, return <a>a promise rejected with</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. If _reader_.[[readRequests]] is not empty, return <a>a promise rejected with</a> a *TypeError* exception.
+  1. If *this*.[[preventCancel]] is *false*, then:
+    1. Let _result_ be ! ReadableStreamReaderGenericCancel(_reader_, _value_).
+    1. Perform ! ReadableStreamReaderGenericRelease(_reader_).
+    1. Return the result of <a>transforming</a> _result_ by a fulfillment handler that returns !
+    ReadableStreamCreateReadResult(_value_, *true*, *true*).
+  1. Perform ! ReadableStreamReaderGenericRelease(_reader_).
+  1. Return <a>a promise resolved with</a> ! ReadableStreamCreateReadResult(_value_, *true*, *true*).
+</emu-alg>
+
 <h3 id="rs-abstract-ops">General readable stream abstract operations</h3>
 
 The following abstract operations, unlike most in this specification, are meant to be generally useful by other
@@ -910,6 +998,15 @@ readable stream is <a>locked to a reader</a>.
   1. Return *true*.
 </emu-alg>
 
+<h4 id="is-readable-stream-asynciterator" aoid="IsReadableStreamAsyncIterator" nothrow
+export>IsReadableStreamAsyncIterator ( <var>x</var> )</h4>
+
+<emu-alg>
+  1. If Type(_x_) is not Object, return *false*.
+  1. If _x_ does not have a [[asyncIteratorReader]] internal slot, return *false*.
+  1. Return *true*.
+</emu-alg>
+
 <h4 id="readable-stream-tee" aoid="ReadableStreamTee" throws export>ReadableStreamTee ( <var>stream</var>,
 <var>cloneForBranch2</var> )</h4>
 

reference-implementation/lib/readable-stream.js

@@ -158,8 +158,56 @@ class ReadableStream {
     const branches = ReadableStreamTee(this, false);
     return createArrayFromList(branches);
   }
+
+  getIterator({ preventCancel = false } = {}) {
+    if (IsReadableStream(this) === false) {
+      throw streamBrandCheckException('getIterator');
+    }
+    const reader = AcquireReadableStreamDefaultReader(this);
+    const iterator = Object.create(ReadableStreamAsyncIteratorPrototype);
+    iterator._asyncIteratorReader = reader;
+    iterator._preventCancel = Boolean(preventCancel);
+    return iterator;
+  }
 }
 
+const AsyncIteratorPrototype = Object.getPrototypeOf(Object.getPrototypeOf(async function* () {}).prototype);
+const ReadableStreamAsyncIteratorPrototype = Object.setPrototypeOf({
+  next() {
+    if (IsReadableStreamAsyncIterator(this) === false) {
+      return Promise.reject(streamAsyncIteratorBrandCheckException('next'));
+    }
+    const reader = this._asyncIteratorReader;
+    if (reader._ownerReadableStream === undefined) {
+      return Promise.reject(readerLockException('iterate'));
+    }
+    return ReadableStreamDefaultReaderRead(reader, true);
+  },
+
+  return(value) {
+    if (IsReadableStreamAsyncIterator(this) === false) {
+      return Promise.reject(streamAsyncIteratorBrandCheckException('next'));
+    }
+    const reader = this._asyncIteratorReader;
+    if (reader._ownerReadableStream === undefined) {
+      return Promise.reject(readerLockException('finish iterating'));
+    }
+    if (reader._readRequests.length > 0) {
+      return Promise.reject(new TypeError(
+        'Tried to release a reader lock when that reader has pending read() calls un-settled'));
+    }
+    if (this._preventCancel === false) {
+      const result = ReadableStreamReaderGenericCancel(reader, value);
+      ReadableStreamReaderGenericRelease(reader);
+      return result.then(() => ReadableStreamCreateReadResult(value, true, true));
+    }
+    ReadableStreamReaderGenericRelease(reader);
+    return Promise.resolve(ReadableStreamCreateReadResult(value, true, true));
+  }
+}, AsyncIteratorPrototype);
+
+ReadableStream.prototype[Symbol.asyncIterator] = ReadableStream.prototype.getIterator;
+
 module.exports = {
   CreateReadableByteStream,
   CreateReadableStream,
@@ -255,6 +303,18 @@ function IsReadableStreamLocked(stream) {
   return true;
 }
 
+function IsReadableStreamAsyncIterator(x) {
+  if (!typeIsObject(x)) {
+    return false;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(x, '_asyncIteratorReader')) {
+    return false;
+  }
+
+  return true;
+}
+
 function ReadableStreamPipeTo(source, dest, preventClose, preventAbort, preventCancel, signal) {
   assert(IsReadableStream(source) === true);
   assert(IsWritableStream(dest) === true);
@@ -2063,6 +2123,10 @@ function streamBrandCheckException(name) {
   return new TypeError(`ReadableStream.prototype.${name} can only be used on a ReadableStream`);
 }
 
+function streamAsyncIteratorBrandCheckException(name) {
+  return new TypeError(`ReadableStreamAsyncIterator.${name} can only be used on a ReadableSteamAsyncIterator`);
+}
+
 // Helper functions for the readers.
 
 function readerLockException(name) {