Add ReadableStreamBYOBReader.prototype.read(view, { min })

index.bs

@@ -447,7 +447,7 @@ particularly important for the data structure described in [[#queue-with-sizes]]
    let offset = 0;
 
    while (offset < buffer.byteLength) {
-     const {value: view, done} =
+     const { value: view, done } =
       await reader.read(new Uint8Array(buffer, offset, buffer.byteLength - offset));
      buffer = view.buffer;
      if (done) {
@@ -467,6 +467,16 @@ particularly important for the data structure described in [[#queue-with-sizes]]
  new {{Uint8Array}}, with that {{ArrayBuffer}} object as its <code>buffer</code> property, the
  offset that bytes were written to as its <code>byteOffset</code> property, and the number of
  bytes that were written as its <code>byteLength</code> property.
+
+ Note that this example is mostly educational. For practical purposes, the
+ {{ReadableStreamBYOBReaderReadOptions/min}} option of {{ReadableStreamBYOBReader/read()}}
+ provides an easier and more direct way to read an exact number of bytes:
+
+ <xmp highlight="js">
+ const reader = readableStream.getReader({ mode: "byob" });
+ const { value: view, done } = await reader.read(new Uint8Array(1024), { min: 1024 });
+ console.log("The first 1024 bytes: ", view);
+ </xmp>
 </div>
 
 <h3 id="rs-class">The {{ReadableStream}} class</h3>
@@ -1313,10 +1323,14 @@ The Web IDL definition for the {{ReadableStreamBYOBReader}} class is given as fo
 interface ReadableStreamBYOBReader {
   constructor(ReadableStream stream);
 
-  Promise<ReadableStreamReadResult> read(ArrayBufferView view);
+  Promise<ReadableStreamReadResult> read(ArrayBufferView view, optional ReadableStreamBYOBReaderReadOptions options = {});
   undefined releaseLock();
 };
 ReadableStreamBYOBReader includes ReadableStreamGenericReader;
+
+dictionary ReadableStreamBYOBReaderReadOptions {
+  [EnforceRange] unsigned long long min = 1;
+};
 </xmp>
 
 <h4 id="byob-reader-internal-slots">Internal slots</h4>
@@ -1376,19 +1390,19 @@ value: newViewOnSameMemory, done: true }</code> for closed streams. If the strea
   <p>If the reader is [=active reader|active=], behaves the same
   <code>|stream|.{{ReadableStream/cancel(reason)|cancel}}(<var ignore>reason</var>)</code>.
 
- <dt><code>{ <var ignore>value</var>, <var ignore>done</var> } = await <var ignore>reader</var>.{{ReadableStreamBYOBReader/read()|read}}(<var ignore>view</var>)</code>
+ <dt><code>{ <var ignore>value</var>, <var ignore>done</var> } = await <var ignore>reader</var>.{{ReadableStreamBYOBReader/read()|read}}(<var ignore>view</var>[, { {{ReadableStreamBYOBReaderReadOptions/min}} }])</code>
  <dd>
-  <p>Attempts to reads bytes into |view|, and returns a promise resolved with the result:
+  <p>Attempts to read bytes into |view|, and returns a promise resolved with the result:
 
   <ul>
    <li>If the chunk does become available, the promise will be fulfilled with an object of the form
-   <code highlight="js">{ value: theChunk, done: false }</code>. In this case, |view| will be
-   [=ArrayBuffer/detached=] and no longer usable, but <code>theChunk</code> will be a new view (of
+   <code highlight="js">{ value: newView, done: false }</code>. In this case, |view| will be
+   [=ArrayBuffer/detached=] and no longer usable, but <code>newView</code> will be a new view (of
    the same type) onto the same backing memory region, with the chunk's data written into it.
 
    <li>If the stream becomes closed, the promise will be fulfilled with an object of the form
-   <code highlight="js">{ value: theChunk, done: true }</code>. In this case, |view| will be
-   [=ArrayBuffer/detached=] and no longer usable, but <code>theChunk</code> will be a new view (of
+   <code highlight="js">{ value: newView, done: true }</code>. In this case, |view| will be
+   [=ArrayBuffer/detached=] and no longer usable, but <code>newView</code> will be a new view (of
    the same type) onto the same backing memory region, with no modifications, to ensure the memory
    is returned to the caller.
 
@@ -1402,6 +1416,14 @@ value: newViewOnSameMemory, done: true }</code> for closed streams. If the strea
   <p>If reading a chunk causes the queue to become empty, more data will be pulled from the
   [=underlying source=].
 
+  <p>If {{ReadableStreamBYOBReaderReadOptions/min}} is given, then the promise will only be
+  fulfilled as soon as the given minimum number of elements are available. Here, the "number of
+  elements" is given by <code>newView</code>'s <code>length</code> (for typed arrays) or
+  <code>newView</code>'s <code>byteLength</code> (for {{DataView}}s). If the stream becomes closed,
+  then the promise is fulfilled with the remaining elements in the stream, which might be fewer than
+  the initially requested amount. If not given, then the promise resolves when at least one element
+  is available.
+
  <dt><code><var ignore>reader</var>.{{ReadableStreamBYOBReader/releaseLock()|releaseLock}}()</code>
  <dd>
   <p>[=release a read lock|Releases the reader's lock=] on the corresponding stream. After the lock
@@ -1424,14 +1446,22 @@ value: newViewOnSameMemory, done: true }</code> for closed streams. If the strea
 </div>
 
 <div algorithm>
- The <dfn id="byob-reader-read" method for="ReadableStreamBYOBReader">read(|view|)</dfn>
+ The <dfn id="byob-reader-read" method for="ReadableStreamBYOBReader">read(|view|, |options|)</dfn>
  method steps are:
 
  1. If |view|.\[[ByteLength]] is 0, return [=a promise rejected with=] a {{TypeError}} exception.
  1. If |view|.\[[ViewedArrayBuffer]].\[[ArrayBufferByteLength]] is 0, return [=a promise rejected
     with=] a {{TypeError}} exception.
  1. If ! [$IsDetachedBuffer$](|view|.\[[ViewedArrayBuffer]]) is true, return
     [=a promise rejected with=] a {{TypeError}} exception.
+ 1. If |options|["{{ReadableStreamBYOBReaderReadOptions/min}}"] is 0, return [=a promise
+     rejected with=] a {{TypeError}} exception.
+ 1. If |view| has a \[[TypedArrayName]] internal slot,
+  1. If |options|["{{ReadableStreamBYOBReaderReadOptions/min}}"] &gt; |view|.\[[ArrayLength]],
+     return [=a promise rejected with=] a {{RangeError}} exception.
+ 1. Otherwise (i.e., it is a {{DataView}}),
+  1. If |options|["{{ReadableStreamBYOBReaderReadOptions/min}}"] &gt; |view|.\[[ByteLength]],
+     return [=a promise rejected with=] a {{RangeError}} exception.
  1. If [=this=].[=ReadableStreamGenericReader/[[stream]]=] is undefined, return [=a promise rejected
     with=] a {{TypeError}} exception.
  1. Let |promise| be [=a new promise=].
@@ -1447,7 +1477,7 @@ value: newViewOnSameMemory, done: true }</code> for closed streams. If the strea
   : [=read-into request/error steps=], given |e|
   ::
    1. [=Reject=] |promise| with |e|.
- 1. Perform ! [$ReadableStreamBYOBReaderRead$]([=this=], |view|, |readIntoRequest|).
+ 1. Perform ! [$ReadableStreamBYOBReaderRead$]([=this=], |view|, |options|["{{ReadableStreamBYOBReaderReadOptions/min}}"], |readIntoRequest|).
  1. Return |promise|.
 </div>
 
@@ -1773,6 +1803,10 @@ has the following [=struct/items=]:
 : <dfn for="pull-into descriptor">bytes filled</dfn>
 :: A nonnegative integer number of bytes that have been written into the [=pull-into
    descriptor/buffer=] so far
+: <dfn for="pull-into descriptor">minimum fill</dfn>
+:: A positive integer representing the minimum number of bytes that must be written into the
+   [=pull-into descriptor/buffer=] before the associated {{ReadableStreamBYOBReader/read()}} request
+   may be fulfilled. By default, this equals the [=pull-into descriptor/element size=].
 : <dfn for="pull-into descriptor">element size</dfn>
 :: A positive integer representing the number of bytes that can be written into the [=pull-into
    descriptor/buffer=] at a time, using views of the type described by the [=pull-into
@@ -1899,12 +1933,35 @@ counterparts for default controllers, as discussed in [[#rs-abstract-ops-used-by
   1. If |buffer| is an abrupt completion,
    1. Perform |readRequest|'s [=read request/error steps=], given |buffer|.\[[Value]].
    1. Return.
-  1. Let |pullIntoDescriptor| be a new [=pull-into descriptor=] with [=pull-into descriptor/buffer=]
-     |buffer|.\[[Value]], [=pull-into descriptor/buffer byte length=] |autoAllocateChunkSize|,
-     [=pull-into descriptor/byte offset=] 0, [=pull-into descriptor/byte length=]
-     |autoAllocateChunkSize|, [=pull-into descriptor/bytes filled=] 0, [=pull-into
-     descriptor/element size=] 1, [=pull-into descriptor/view constructor=] {{%Uint8Array%}}, and
-     [=pull-into descriptor/reader type=] "`default`".
+  1. Let |pullIntoDescriptor| be a new [=pull-into descriptor=] with
+     <dl class="props">
+      <dt>[=pull-into descriptor/buffer=]
+      <dd>|buffer|.\[[Value]]
+
+      <dt>[=pull-into descriptor/buffer byte length=]
+      <dd>|autoAllocateChunkSize|
+
+      <dt>[=pull-into descriptor/byte offset=]
+      <dd>0
+
+      <dt>[=pull-into descriptor/byte length=]
+      <dd>|autoAllocateChunkSize|
+
+      <dt>[=pull-into descriptor/bytes filled=]
+      <dd>0
+
+      <dt>[=pull-into descriptor/minimum fill=]
+      <dd>1
+
+      <dt>[=pull-into descriptor/element size=]
+      <dd>1
+
+      <dt>[=pull-into descriptor/view constructor=]
+      <dd>{{%Uint8Array%}}
+
+      <dt>[=pull-into descriptor/reader type=]
+      <dd>"`default`"
+     </dl>
   1. [=list/Append=] |pullIntoDescriptor| to
      [=this=].[=ReadableByteStreamController/[[pendingPullIntos]]=].
  1. Perform ! [$ReadableStreamAddReadRequest$](|stream|, |readRequest|).
@@ -2548,7 +2605,7 @@ create them does not matter.
    : [=read-into request/error steps=]
    ::
     1. Set |reading| to false.
-  1. Perform ! [$ReadableStreamBYOBReaderRead$](|reader|, |view|, |readIntoRequest|).
+  1. Perform ! [$ReadableStreamBYOBReaderRead$](|reader|, |view|, 1, |readIntoRequest|).
  1. Let |pull1Algorithm| be the following steps:
   1. If |reading| is true,
    1. Set |readAgainForBranch1| to true.
@@ -2848,7 +2905,7 @@ The following abstract operations support the implementation and manipulation of
 
 <div algorithm>
  <dfn abstract-op lt="ReadableStreamBYOBReaderRead"
- id="readable-stream-byob-reader-read">ReadableStreamBYOBReaderRead(|reader|, |view|,
+ id="readable-stream-byob-reader-read">ReadableStreamBYOBReaderRead(|reader|, |view|, |min|,
  |readIntoRequest|)</dfn> performs the following steps:
 
  1. Let |stream| be |reader|.[=ReadableStreamGenericReader/[[stream]]=].
@@ -2857,7 +2914,7 @@ The following abstract operations support the implementation and manipulation of
  1. If |stream|.[=ReadableStream/[[state]]=] is "`errored`", perform |readIntoRequest|'s [=read-into
     request/error steps=] given |stream|.[=ReadableStream/[[storedError]]=].
  1. Otherwise, perform ! [$ReadableByteStreamControllerPullInto$](|stream|.[=ReadableStream/[[controller]]=],
-    |view|, |readIntoRequest|).
+    |view|, |min|, |readIntoRequest|).
 </div>
 
 <div algorithm>
@@ -3205,7 +3262,8 @@ The following abstract operations support the implementation of the
  1. If |controller|.[=ReadableByteStreamController/[[pendingPullIntos]]=] is not empty,
   1. Let |firstPendingPullInto| be
      |controller|.[=ReadableByteStreamController/[[pendingPullIntos]]=][0].
-  1. If |firstPendingPullInto|'s [=pull-into descriptor/bytes filled=] > 0,
+  1. If |firstPendingPullInto|'s [=pull-into descriptor/bytes filled=]
+     mod |firstPendingPullInto|'s [=pull-into descriptor/element size=] is not 0,
    1. Let |e| be a new {{TypeError}} exception.
    1. Perform ! [$ReadableByteStreamControllerError$](|controller|, |e|).
    1. Throw |e|.
@@ -3222,7 +3280,8 @@ The following abstract operations support the implementation of the
  1. Assert: |pullIntoDescriptor|.[=pull-into descriptor/reader type=] is not "`none`".
  1. Let |done| be false.
  1. If |stream|.[=ReadableStream/[[state]]=] is "`closed`",
-  1. Assert: |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] is 0.
+  1. Assert: |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=]
+     mod |pullIntoDescriptor|'s [=pull-into descriptor/element size=] is 0.
   1. Set |done| to true.
  1. Let |filledView| be !
     [$ReadableByteStreamControllerConvertPullIntoDescriptor$](|pullIntoDescriptor|).
@@ -3371,21 +3430,24 @@ The following abstract operations support the implementation of the
  id="readable-byte-stream-controller-fill-pull-into-descriptor-from-queue">ReadableByteStreamControllerFillPullIntoDescriptorFromQueue(|controller|,
  |pullIntoDescriptor|)</dfn> performs the following steps:
 
- 1. Let |elementSize| be |pullIntoDescriptor|.\[[elementSize]].
- 1. Let |currentAlignedBytes| be |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] −
-    (|pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] mod |elementSize|).
  1. Let |maxBytesToCopy| be min(|controller|.[=ReadableByteStreamController/[[queueTotalSize]]=],
     |pullIntoDescriptor|'s [=pull-into descriptor/byte length=] − |pullIntoDescriptor|'s [=pull-into
     descriptor/bytes filled=]).
  1. Let |maxBytesFilled| be |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] +
     |maxBytesToCopy|.
- 1. Let |maxAlignedBytes| be |maxBytesFilled| − (|maxBytesFilled| mod |elementSize|).
  1. Let |totalBytesToCopyRemaining| be |maxBytesToCopy|.
  1. Let |ready| be false.
- 1. If |maxAlignedBytes| > |currentAlignedBytes|,
+ 1. Assert: |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] < |pullIntoDescriptor|'s
+    [=pull-into descriptor/minimum fill=].
+ 1. Let |maxAlignedBytes| be |maxBytesFilled| − (|maxBytesFilled| mod |pullIntoDescriptor|'s
+    [=pull-into descriptor/element size=]).
+ 1. If |maxAlignedBytes| ≥ |pullIntoDescriptor|'s [=pull-into descriptor/minimum fill=],
   1. Set |totalBytesToCopyRemaining| to |maxAlignedBytes| − |pullIntoDescriptor|'s [=pull-into
      descriptor/bytes filled=].
   1. Set |ready| to true.
+     <p class="note">A descriptor for a {{ReadableStreamBYOBReader/read()}} request
+     that is not yet filled up to its minimum length will stay at the head of the queue, so the
+     [=underlying source=] can keep filling it.
  1. Let |queue| be |controller|.[=ReadableByteStreamController/[[queue]]=].
  1. [=While=] |totalBytesToCopyRemaining| > 0,
   1. Let |headOfQueue| be |queue|[0].
@@ -3413,7 +3475,7 @@ The following abstract operations support the implementation of the
   1. Assert: |controller|.[=ReadableByteStreamController/[[queueTotalSize]]=] is 0.
   1. Assert: |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] > 0.
   1. Assert: |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] &lt;
-     |pullIntoDescriptor|'s [=pull-into descriptor/element size=].
+     |pullIntoDescriptor|'s [=pull-into descriptor/minimum fill=].
  1. Return |ready|.
 </div>
 
@@ -3532,7 +3594,7 @@ The following abstract operations support the implementation of the
 <div algorithm>
  <dfn abstract-op lt="ReadableByteStreamControllerPullInto"
  id="readable-byte-stream-controller-pull-into">ReadableByteStreamControllerPullInto(|controller|,
- |view|, |readIntoRequest|)</dfn> performs the following steps:
+ |view|, |min|, |readIntoRequest|)</dfn> performs the following steps:
 
  1. Let |stream| be |controller|.[=ReadableByteStreamController/[[stream]]=].
  1. Let |elementSize| be 1.
@@ -3542,19 +3604,45 @@ The following abstract operations support the implementation of the
      |view|.\[[TypedArrayName]].
   1. Set |ctor| to the constructor specified in [=the typed array constructors table=] for
      |view|.\[[TypedArrayName]].
+ 1. Let |minimumFill| be |min| &times; |elementSize|.
+ 1. Assert: |minimumFill| ≥ 0 and |minimumFill| ≤ |view|.\[[ByteLength]].
+ 1. Assert: |minimumFill| mod |elementSize| is 0.
  1. Let |byteOffset| be |view|.\[[ByteOffset]].
  1. Let |byteLength| be |view|.\[[ByteLength]].
  1. Let |bufferResult| be [$TransferArrayBuffer$](|view|.\[[ViewedArrayBuffer]]).
  1. If |bufferResult| is an abrupt completion,
   1. Perform |readIntoRequest|'s [=read-into request/error steps=], given |bufferResult|.\[[Value]].
   1. Return.
  1. Let |buffer| be |bufferResult|.\[[Value]].
- 1. Let |pullIntoDescriptor| be a new [=pull-into descriptor=] with [=pull-into descriptor/buffer=]
-    |buffer|, [=pull-into descriptor/buffer byte length=] |buffer|.\[[ArrayBufferByteLength]],
-    [=pull-into descriptor/byte offset=] |byteOffset|, [=pull-into descriptor/byte length=]
-    |byteLength|, [=pull-into descriptor/bytes filled=] 0, [=pull-into descriptor/element size=]
-    |elementSize|, [=pull-into descriptor/view constructor=] |ctor|, and [=pull-into
-    descriptor/reader type=] "`byob`".
+ 1. Let |pullIntoDescriptor| be a new [=pull-into descriptor=] with
+    <dl class="props">
+     <dt>[=pull-into descriptor/buffer=]
+     <dd>|buffer|
+
+     <dt>[=pull-into descriptor/buffer byte length=]
+     <dd>|buffer|.\[[ArrayBufferByteLength]]
+
+     <dt>[=pull-into descriptor/byte offset=]
+     <dd>|byteOffset|
+
+     <dt>[=pull-into descriptor/byte length=]
+     <dd>|byteLength|
+
+     <dt>[=pull-into descriptor/bytes filled=]
+     <dd>0
+
+     <dt>[=pull-into descriptor/minimum fill=]
+     <dd>|minimumFill|
+
+     <dt>[=pull-into descriptor/element size=]
+     <dd>|elementSize|
+
+     <dt>[=pull-into descriptor/view constructor=]
+     <dd>|ctor|
+
+     <dt>[=pull-into descriptor/reader type=]
+     <dd>"`byob`"
+    </dl>
  1. If |controller|.[=ReadableByteStreamController/[[pendingPullIntos]]=] is not empty,
   1. [=list/Append=] |pullIntoDescriptor| to
      |controller|.[=ReadableByteStreamController/[[pendingPullIntos]]=].
@@ -3610,7 +3698,8 @@ The following abstract operations support the implementation of the
  id="readable-byte-stream-controller-respond-in-closed-state">ReadableByteStreamControllerRespondInClosedState(|controller|,
  |firstDescriptor|)</dfn> performs the following steps:
 
- 1. Assert: |firstDescriptor|'s [=pull-into descriptor/bytes filled=] is 0.
+ 1. Assert: |firstDescriptor|'s [=pull-into descriptor/bytes filled=] mod |firstDescriptor|'s
+    [=pull-into descriptor/element size=] is 0.
  1. If |firstDescriptor|'s [=pull-into descriptor/reader type=] is "`none`",
     perform ! [$ReadableByteStreamControllerShiftPendingPullInto$](|controller|).
  1. Let |stream| be |controller|.[=ReadableByteStreamController/[[stream]]=].
@@ -3637,7 +3726,10 @@ The following abstract operations support the implementation of the
   1. Perform ! [$ReadableByteStreamControllerProcessPullIntoDescriptorsUsingQueue$](|controller|).
   1. Return.
  1. If |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] &lt; |pullIntoDescriptor|'s
-    [=pull-into descriptor/element size=], return.
+    [=pull-into descriptor/minimum fill=], return.
+    <p class="note">A descriptor for a {{ReadableStreamBYOBReader/read()}} request
+    that is not yet filled up to its minimum length will stay at the head of the queue, so the
+    [=underlying source=] can keep filling it.
  1. Perform ! [$ReadableByteStreamControllerShiftPendingPullInto$](|controller|).
  1. Let |remainderSize| be |pullIntoDescriptor|'s [=pull-into descriptor/bytes filled=] mod
     |pullIntoDescriptor|'s [=pull-into descriptor/element size=].

reference-implementation/lib/ReadableByteStreamController-impl.js

@@ -87,6 +87,7 @@ exports.implementation = class ReadableByteStreamControllerImpl {
         byteOffset: 0,
         byteLength: autoAllocateChunkSize,
         bytesFilled: 0,
+        minimumFill: 1,
         elementSize: 1,
         viewConstructor: Uint8Array,
         readerType: 'default'