index.bs

<pre class="metadata">
Title: Streams Standard
Group: WHATWG
H1: Streams
Shortname: streams
Repository: whatwg/streams
Inline Github Issues: title
Status: LS
Boilerplate: omit conformance, omit feedback-header
No Editor: true
Abstract: This specification provides APIs for creating, composing, and consuming streams of data.
Abstract: These streams are designed to map efficiently to low-level I/O primitives, and allow easy
Abstract: composition with built-in backpressure and queuing. On top of streams, the web platform can
Abstract: build higher-level abstractions, such as filesystem or socket APIs, while at the same time
Abstract: users can use the supplied tools to build their own streams which integrate well with those
Abstract: of the web platform.
Logo: https://resources.whatwg.org/logo-streams.svg
!Participate: <a href="https://github.com/whatwg/streams">GitHub whatwg/streams</a> (<a href="https://github.com/whatwg/streams/issues/new">new issue</a>, <a href="https://github.com/whatwg/streams/issues">open issues</a>)
!Participate: <a href="https://wiki.whatwg.org/wiki/IRC">IRC: #whatwg on Freenode</a>
!Commits: <a href="https://github.com/whatwg/streams/commits">GitHub whatwg/streams/commits</a>
!Commits: [SNAPSHOT-LINK]
!Commits: <a href="https://twitter.com/streamsstandard">@streamsstandard</a>
!Translation (non-normative): <a href="https://triple-underscore.github.io/Streams-ja.html" rel="alternate" title="Japanese" hreflang="ja" lang="ja">日本語</a>
Opaque Elements: emu-alg
Ignored Vars: e
</pre>

<pre class="anchors">
urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
    text: %Uint8Array%; url: #sec-typedarray-objects; type: constructor
    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
    text: Uint8Array; url: #sec-typedarray-objects; type: interface
    text: typed array; url: #sec-typedarray-objects; type: dfn
    text: the typed array constructors table; url: #table-49; type: dfn
    text: TypeError; url: #sec-native-error-types-used-in-this-standard-typeerror; type: exception
    text: Invoke; url: #sec-invoke; type: abstract-op
</pre>

<style>
  .note + .example, .note + .note { margin-top: 1em; }

  emu-val { font-weight: bold; }
  emu-alg > ol, emu-alg > ol ol ol ol { list-style-type: decimal; }
  emu-alg > ol ol, emu-alg > ol ol ol ol ol { list-style-type: lower-alpha; }
  emu-alg > ol ol ol, emu-alg > ol ol ol ol ol ol { list-style-type: lower-roman; }
  emu-alg li { margin: 0; }

  .heading .annotation {
    background-color: beige;
    border: 1px solid black;
    border-radius: 3px;
    cursor: help;
    display: inline-block;
    font-size: 70%;
    font-weight: normal;
    padding: 1px 2px;
  }
</style>
<script src="https://resources.whatwg.org/file-issue.js" async></script>
<script src="https://resources.whatwg.org/commit-snapshot-shortcut-key.js" async></script>
<script src="https://resources.whatwg.org/dfn.js" defer></script>

<h2 id="intro">Introduction</h2>

<em>This section is non-normative.</em>

Large swathes of the web platform are built on streaming data: that is, data that is created, processed, and consumed
in an incremental fashion, without ever reading all of it into memory. The Streams Standard provides a common set of
APIs for creating and interfacing with such streaming data, embodied in <a>readable streams</a>,
<a>writable streams</a>, and <a>transform streams</a>.

This standard provides the base stream primitives which other parts of the web platform can use to expose their
streaming data. For example, [[FETCH]] could expose request bodies as a writable stream, or response bodies as a
readable stream. More generally, the platform is full of streaming abstractions waiting to be expressed as streams:
multimedia streams, file streams, interprocess communication, and more benefit from being able to process data
incrementally instead of buffering it all into memory and processing it in one go. By providing the foundation for
these streams to be exposed to developers, the Streams Standard enables use cases like:

<ul>
  <li> Video effects: piping a readable video stream through a transform stream that applies effects in real time.
  <li> Decompression: piping a file stream through a transform stream that selectively decompresses files from a
    <kbd>.tgz</kbd> archive, turning them into <code>img</code> elements as the user scrolls through an image gallery.
  <li> Image decoding: piping an HTTP response stream through a transform stream that decodes bytes into bitmap data,
    and then through another transform that translates bitmaps into PNGs. If installed inside the <code>fetch</code>
    hook of a service worker [[SERVICE-WORKERS]], this would allow developers to transparently polyfill new image
    formats.
</ul>

The APIs described here provide unifying abstraction for all such streams, encouraging an ecosystem to grow around
these shared and composable interfaces. At the same time, they have been carefully designed to map efficiently to
low-level I/O concerns, and to encapsulate the trickier issues (such as <a>backpressure</a>) that come along for the
ride.

<h2 id="model">Model</h2>

A <dfn>chunk</dfn> is a single piece of data that is written to or read from a stream. It can be of any type; streams
can even contain chunks of different types. A chunk will often not be the most atomic unit of data for a given stream;
for example a byte stream might contain chunks consisting of 16 KiB {{Uint8Array}}s, instead of single
bytes.

<h3 id="rs-model">Readable Streams</h3>

A <dfn>readable stream</dfn> represents a source of data, from which you can read. In other words, data comes
<em>out</em> of a readable stream.

Although a readable stream can be created with arbitrary behavior, most readable streams wrap a lower-level I/O source,
called the <dfn>underlying source</dfn>. There are two types of underlying source: push sources and pull sources.

<dfn lt="push source">Push sources</dfn> push data at you, whether or not you are listening for it. They may also
provide a mechanism for pausing and resuming the flow of data. An example push source is a TCP socket, where data is
constantly being pushed from the OS level, at a rate that can be controlled by changing the TCP window size.

<dfn lt="pull source">Pull sources</dfn> require you to request data from them. The data may be available
synchronously, e.g. if it is held by the operating system's in-memory buffers, or asynchronously, e.g. if it has to be
read from disk. An example pull source is a file handle, where you seek to specific locations and read specific amounts.

Readable streams are designed to wrap both types of sources behind a single, unified interface.

<a>Chunks</a> are enqueued into the stream by the stream's <a>underlying source</a>. They can then be read one at a
time via the stream's public interface.

Code that reads from a readable stream using its public interface is known as a <dfn>consumer</dfn>.

Consumers also have the ability to <dfn lt="cancel a readable stream">cancel</dfn> a readable stream. This indicates
that the consumer has lost interest in the stream, and will immediately close the stream, throw away any queued
<a>chunks</a>, and execute any cancellation mechanism of the <a>underlying source</a>.

Consumers can also <dfn lt="tee a readable stream">tee</dfn> a readable stream. This will
<a lt="locked to a reader">lock</a> the stream, making it no longer directly usable; however, it will create two new
streams, called <dfn lt="branches of a readable stream tee">branches</dfn>, which can be consumed independently.

For streams representing bytes, an extended version of the <a>readable stream</a> is provided to handle bytes
efficiently, in particular by minimizing copies. The <a>underlying source</a> for such a readable stream is called
a <dfn>underlying byte source</dfn>. A readable stream whose underlying source is an underlying byte source is sometimes
called a <dfn>readable byte stream</dfn>.

<h3 id="ws-model">Writable Streams</h3>

A <dfn>writable stream</dfn> represents a destination for data, into which you can write. In other words, data goes
<em>in</em> to a writable stream.

Analogously to readable streams, most writable streams wrap a lower-level I/O sink, called the
<dfn>underlying sink</dfn>. Writable streams work to abstract away some of the complexity of the underlying sink, by
queuing subsequent writes and only delivering them to the underlying sink one by one.

<a>Chunks</a> are written to the stream via its public interface, and are passed one at a time to the stream's
<a>underlying sink</a>.

Code that writes into a writable stream using its public interface is known as a <dfn>producer</dfn>.

Producers also have the ability to <dfn lt="abort a writable stream">abort</dfn> a writable stream. This indicates that
the producer believes something has gone wrong, and that future writes should be discontinued. It puts the stream in an
errored state, even without a signal from the <a>underlying sink</a>.

<h3 id="ts-model">Transform Streams</h3>

A <dfn>transform stream</dfn> consists of a pair of streams: a writable stream, and a readable stream.
In a manner specific to the transform stream in question, writes to the writable side result in new data being made
available for reading from the readable side.

Some examples of transform streams include:

<ul>
  <li>A GZIP compressor, to which uncompressed bytes are written and from which compressed bytes are read;</li>
  <li>A video decoder, to which encoded bytes are written and from which uncompressed video frames are read;</li>
  <li>A text decoder, to which bytes are written and from which strings are read;</li>
  <li>A CSV-to-JSON converter, to which strings representing lines of a CSV file are written and from which
    corresponding JavaScript objects are read.
</ul>

<h3 id="pipe-chains">Pipe Chains and Backpressure</h3>

Streams are primarily used by <dfn>piping</dfn> them to each other. A readable stream can be piped directly to a
writable stream, or it can be piped through one or more transform streams first.

A set of streams piped together in this way is referred to as a <dfn>pipe chain</dfn>. In a pipe chain, the
<dfn>original source</dfn> is the <a>underlying source</a> of the first readable stream in the chain; the
<dfn>ultimate sink</dfn> is the <a>underlying sink</a> of the final writable stream in the chain.

Once a pipe chain is constructed, it can be used to propagate signals regarding how fast <a>chunks</a> should flow
through it. If any step in the chain cannot yet accept chunks, it propagates a signal backwards through the pipe chain,
until eventually the original source is told to stop producing chunks so fast. This process of normalizing flow from
the original source according to how fast the chain can process chunks is called <dfn>backpressure</dfn>.

When <a lt="tee a readable stream">teeing</a> a readable stream, the <a>backpressure</a> signals from its two
<a lt="branches of a readable stream tee">branches</a> will aggregate, such that if neither branch is read from, a
backpressure signal will be sent to the <a>underlying source</a> of the original stream.

<!-- TODO when we have writable stream writers
Piping a readable stream <a href="locked to a reader">locks</a> the readable stream, preventing it from being accessed
-->

<h3 id="queuing-strategies">Internal Queues and Queuing Strategies</h3>

Both readable and writable streams maintain <dfn>internal queues</dfn>, which they use for similar purposes. In the
case of a readable stream, the internal queue contains <a>chunks</a> that have been enqueued by the <a>underlying
source</a>, but not yet read by the consumer. In the case of a writable stream, the internal queue contains
<a>chunks</a> which have been written to the stream by the producer, but not yet processed and acknowledged by the
<a>underlying sink</a>.

A <dfn>queuing strategy</dfn> is an object that determines how a stream should signal <a>backpressure</a> based on
the state of its <a>internal queue</a>. The queuing strategy assigns a size to each <a>chunk</a>, and compares the
total size of all chunks in the queue to a specified number, known as the <dfn>high water mark</dfn>. The resulting
difference, high water mark minus total size, is used to determine the
<dfn lt="desired size to fill a stream's internal queue">desired size to fill the stream's queue</dfn>.

For readable streams, an underlying source can use this desired size as a backpressure signal, slowing down chunk
generation so as to try to keep the desired size above or at zero. For writable streams, a producer can behave
similarly, avoiding writes that would cause the desired size to go negative.

<div class="example" id="example-simple-queuing-strategy">
  A simple example of a queuing strategy would be one that assigns a size of one to each chunk, and has a high water
  mark of three. This would mean that up to three chunks could be enqueued in a readable stream, or three chunks
  written to a writable stream, before the streams are considered to be applying backpressure.
</div>

<h3 id="locking">Locking</h3>

A <dfn>readable stream reader</dfn>, or simply reader, is an object that allows direct reading of <a>chunks</a> from a
<a>readable stream</a>. Without a reader, a <a>consumer</a> can only perform high-level operations on the readable
stream: <a lt="cancel a readable stream">canceling</a> the stream, or <a>piping</a> the readable stream to a writable
stream.

Similarly, a <dfn>writable stream writer</dfn>, or simply writer, is an object that allows direct writing of
<a>chunks</a> to a <a>writable stream</a>. Without a writer, a <a>producer</a> can only perform the high-level
operations of <a lt="abort a writable stream">aborting</a> the stream or <a>piping</a> a readable stream to the writable
stream.

(Under the covers, these high-level operations actually use a reader or writer themselves.)

A given readable or writable stream only has at most one reader or writer at a time. We say in this case the stream is
<dfn lt="locked to a reader|locked to a writer">locked</dfn>, and that the reader or writer is <dfn
lt="active|active reader|active writer">active</dfn>.

A reader or writer also has the capability to <dfn lt="release a lock|release a read lock|release a write lock">release
its lock</dfn>, which makes it no longer active, and allows further readers or writers to be acquired.

A <a>readable byte stream</a> has the ability to vend two types of readers: <dfn>default readers</dfn> and <dfn>BYOB
readers</dfn>. BYOB ("bring your own buffer") readers allow reading into a developer-supplied buffer, thus minimizing
copies.

<h2 id="rs">Readable Streams</h2>

<h3 id="rs-intro">Using Readable Streams</h3>

<div class="example" id="example-basic-pipe-to">
  The simplest way to consume a readable stream is to simply <a lt="piping">pipe</a> it to a <a>writable stream</a>.
  This ensures that <a>backpressure</a> is respected, and any errors (either writing or reading) are propagated through
  the chain:

  <pre><code class="lang-javascript">
    readableStream.pipeTo(writableStream)
      .then(() => console.log("All data successfully written!"))
      .catch(e => console.error("Something went wrong!", e));
  </code></pre>
</div>

<div class="example" id="example-pipe-as-chunks-receiver">
  If you simply want to be alerted of each new chunk from a readable stream, you can <a lt="piping">pipe</a> it to a
  new <a>writable stream</a> that you custom-create for that purpose:

  <pre><code class="lang-javascript">
    readableStream.pipeTo(new WritableStream({
      write(chunk) {
        console.log("Chunk received", chunk);
      },
      close() {
        console.log("All data successfully read!");
      },
      abort(e) {
        console.error("Something went wrong!", e);
      }
    }));
  </code></pre>

  By returning promises from your <code>write</code> implementation, you can signal <a>backpressure</a> to the readable
  stream.
</div>

<div class="example" id="example-manual-read">
  Although readable streams will usually be used by piping them to a writable stream, you can also read them directly
  by acquiring a <a lt="readable stream reader">reader</a> and using its <code>read()</code> method to get successive
  chunks. For example, this code logs the next <a>chunk</a> in the stream, if available:

  <pre><code class="lang-javascript">
    const reader = readableStream.getReader();

    reader.read().then(
      ({ value, done }) => {
        if (done) {
          console.log("The stream was already closed!");
        } else {
          console.log(value);
        }
      },
      e => console.error("The stream became errored and cannot be read from!", e)
    );
  </code></pre>

  This more manual method of reading a stream is mainly useful for library authors building new high-level operations
  on streams, beyond the provided ones of <a>piping</a> and <a lt="tee a readable stream">teeing</a>.
</div>

<div class="example" id="example-manual-read-bytes">
  The above example showed using the readable stream's <a>default reader</a>. If the stream is a <a>readable byte
  stream</a>, you can also acquire a <a>BYOB reader</a> for it, which allows more precise control over buffer
  allocation in order to avoid copies. For example, this code reads the first 1024 bytes from the stream into a single
  memory buffer:

  <pre><code class="lang-javascript">
    const reader = readableStream.getReader({ mode: "byob" });

    let startingAB = new ArrayBuffer(1024);
    readInto(startingAB)
      .then(buffer => console.log("The first 1024 bytes:", buffer))
      .catch(e => console.error("Something went wrong!", e));

    function readInto(buffer, offset = 0) {
      if (offset === buffer.byteLength) {
        return Promise.resolve(buffer);
      }

      const view = new Uint8Array(buffer, offset, buffer.byteLength - offset);
      return reader.read(view).then(newView => {
        return readInto(newView.buffer, offset + newView.byteLength);
      });
    }
  </code></pre>

  An important thing to note here is that the final <code>buffer</code> value is different from the
  <code>startingAB</code>, but it (and all intermediate buffers) shares the same backing memory allocation. At each
  step, the buffer is <a abstract-op lt="Transfer">transferred</a> to a new {{ArrayBuffer}} object. The
  <code>newView</code> is a 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.
</div>

<h3 id="rs-class" interface lt="ReadableStream">Class <code>ReadableStream</code></h3>

The {{ReadableStream}} class is a concrete instance of the general <a>readable stream</a> concept. It is
adaptable to any <a>chunk</a> type, and maintains an internal queue to keep track of data supplied by the <a>underlying
source</a> but not yet read by any consumer.

<h4 id="rs-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{ReadableStream}} class in something close to the syntax of [[!ECMASCRIPT]], it would look
like

<pre><code class="lang-javascript">
  class ReadableStream {
    constructor(underlyingSource = {}, { size, highWaterMark } = {})

    get locked()

    cancel(reason)
    getReader()
    pipeThrough({ writable, readable }, options)
    pipeTo(dest, { preventClose, preventAbort, preventCancel } = {})
    tee()
  }
</code></pre>

<h4 id="rs-internal-slots">Internal Slots</h4>

Instances of {{ReadableStream}} 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>\[[disturbed]]
    <td>A boolean flag set to <emu-val>true</emu-val> when the stream has been read from or canceled
  </tr>
  <tr>
    <td>\[[readableStreamController]]
    <td>A {{ReadableStreamDefaultController}} or {{ReadableByteStreamController}} created with the ability to control
    the state and queue of this stream; also used for the IsReadableStream brand check
  </tr>
  <tr>
    <td>\[[reader]]
    <td>A {{ReadableStreamDefaultReader}} or {{ReadableStreamBYOBReader}} instance, if the stream is <a>locked to a
      reader</a>, or <emu-val>undefined</emu-val> if it is not
  </tr>
  <tr>
    <td>\[[state]]
    <td>A string containing the stream's current state, used internally; one of <code>"readable"</code>,
      <code>"closed"</code>, or <code>"errored"</code>
  </tr>
  <tr>
    <td>\[[storedError]]
    <td>A value indicating how the stream failed, to be given as a failure reason or exception when trying to operate
      on an errored stream
  </tr>
</table>

<h4 id="rs-constructor" constructor for="ReadableStream" lt="ReadableStream(underlyingSource, queuingStrategy)">new
ReadableStream(<var>underlyingSource</var> = {}, { <var>size</var>, <var>highWaterMark</var> } = {})</h4>

<div class="note">
  The <code>underlyingSource</code> object passed to the constructor can implement any of the following methods to
  govern how the constructed stream instance behaves:

  <ul>
    <li> <code>start(controller)</code> is called immediately, and is typically used to adapt a <a>push
      source</a> by setting up relevant event listeners, or to acquire access to a <a>pull source</a>. If this process
      is asynchronous, it can return a promise to signal success or failure.
    <li> <code>pull(controller)</code> is called when the stream's <a>internal queue</a> of chunks is not full, and
      will be called repeatedly until the queue reaches its <a>high water mark</a>. If <code>pull</code> returns a
      promise, then <code>pull</code> will not be called again until that promise fulfills; if the promise rejects, the
      stream will become errored.
    <li> <code>cancel(reason)</code> is called when the consumer signals that they are no longer interested in the
      stream. It should perform any actions necessary to release access to the <a>underlying source</a>. If this
      process is asynchronous, it can return a promise to signal success or failure.
  </ul>

  Both <code>start</code> and <code>pull</code> are given the ability to manipulate the stream's internal queue and
  state via the passed <code>controller</code> object. This is an example of the
  <a href="https://blog.domenic.me/the-revealing-constructor-pattern/">revealing constructor pattern</a>.

  If the <code>underlyingSource</code> object contains a property <code>type</code> set to <code>"bytes"</code>, this
  <a>readable stream</a> is a <a>readable byte stream</a>, and can successfully vend <a>BYOB readers</a>. In that case,
  the passed <code>controller</code> object will be an instance of {{ReadableByteStreamController}}. Otherwise, it will
  be an instance of {{ReadableStreamDefaultController}}.

  For <a>readable byte streams</a>, <code>underlyingSource</code> can also contain a property
  <code>autoAllocateChunkSize</code>, which can be set to a positive integer to enable the auto-allocation feature for
  this stream. In that case, when a <a>consumer</a> uses a <a>default reader</a>, the stream implementation will
  automatically allocate an {{ArrayBuffer}} of the given size, and call the <a>underlying source</a> code
  as if the <a>consumer</a> was using a <a>BYOB reader</a>. This can cut down on the amount of code needed when writing
  the <a>underlying source</a> implementation, as can be seen by comparing [[#example-rbs-push]] without auto-allocation
  to [[#example-rbs-pull]] with auto-allocation.

  The constructor also accepts a second argument containing the <a>queuing strategy</a> object with
  two properties: a non-negative number <code>highWaterMark</code>, and a function <code>size(chunk)</code>. The
  supplied <code>strategy</code> could be an instance of the built-in {{CountQueuingStrategy}} or
  {{ByteLengthQueuingStrategy}} classes, or it could be custom. If no strategy is supplied, the default
  behavior will be the same as a {{CountQueuingStrategy}} with a <a>high water mark</a> of 1.
</div>

<emu-alg>
  1. Set *this*.[[state]] to `"readable"`.
  1. Set *this*.[[reader]] and *this*.[[storedError]] to *undefined*.
  1. Set *this*.[[disturbed]] to *false*.
  1. Set *this*.[[readableStreamController]] to *undefined*.
  1. Let _type_ be ? GetV(_underlyingSource_, `"type"`).
  1. Let _typeString_ be ? ToString(_type_).
  1. If _typeString_ is `"bytes"`,
    1. If _highWaterMark_ is *undefined*, let _highWaterMark_ be *0*.
    1. Set *this*.[[readableStreamController]] to ? Construct(`<a idl>ReadableByteStreamController</a>`, « *this*,
       _underlyingSource_, _highWaterMark_ »).
  1. Otherwise, if _type_ is *undefined*,
    1. If _highWaterMark_ is *undefined*, let _highWaterMark_ be *1*.
    1. Set *this*.[[readableStreamController]] to ? Construct(`<a idl>ReadableStreamDefaultController</a>`, « *this*,
       _underlyingSource_, _size_, _highWaterMark_ »).
  1. Otherwise, throw a *RangeError* exception.
</emu-alg>

<h4 id="rs-prototype">Properties of the {{ReadableStream}} Prototype</h4>

<h5 id="rs-locked" attribute for="ReadableStream" lt="locked">get locked</h5>

<div class="note">
  The <code>locked</code> getter returns whether or not the readable stream is <a>locked to a reader</a>.
</div>

<emu-alg>
  1. If ! IsReadableStream(*this*) is *false*, throw a *TypeError* exception.
  1. Return ! IsReadableStreamLocked(*this*).
</emu-alg>

<h5 id="rs-cancel" method for="ReadableStream">cancel(<var>reason</var>)</h5>

<div class="note">
  The <code>cancel</code> method <a lt="cancel a readable stream">cancels</a> the stream, signaling a loss of interest
  in the stream by a consumer. The supplied <code>reason</code> argument will be given to the underlying source, which
  may or may not use it.
</div>

<emu-alg>
  1. If ! IsReadableStream(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If ! IsReadableStreamLocked(*this*) is *true*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! ReadableStreamCancel(*this*, _reason_).
</emu-alg>

<h5 id="rs-get-reader" method for="ReadableStream">getReader({ <var>mode</var> } = {})</h5>

<div class="note">
  The <code>getReader</code> method creates a reader of the type specified by the <code>mode</code> option 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.

  When <code>mode</code> is <emu-val>undefined</emu-val>, the method creates a <a>default reader</a> (an instance of
  {{ReadableStreamDefaultReader}}). The reader provides the ability to directly read individual <a>chunks</a> from the
  stream via the reader's {{ReadableStreamDefaultReader/read()}} method.

  When <code>mode</code> is <code>"byob"</code>, the <code>getReader</code> method creates a <a>BYOB reader</a> (an
  instance of {{ReadableStreamBYOBReader}}). This feature only works on <a>readable byte streams</a>, i.e. streams which
  were constructed specifically with the ability to handle "bring your own buffer" reading. The reader provides the
  ability to directly read individual <a>chunks</a> from the stream via the reader's {{ReadableStreamBYOBReader/read()}}
  method, into developer-supplied buffers, allowing more precise control over allocation.
</div>

<emu-alg>
  1. If ! IsReadableStream(*this*) is *false*, throw a *TypeError* exception.
  1. If _mode_ is `"byob"`, return ? AcquireReadableStreamBYOBReader(*this*).
  1. If _mode_ is *undefined*, return ? AcquireReadableStreamDefaultReader(*this*).
  1. Throw a *RangeError* exception.
</emu-alg>

<div class="example" id="example-read-all-chunks">
  An example of an abstraction that might benefit from using a reader is a function like the following, which is
  designed to read an entire readable stream into memory as an array of <a>chunks</a>.

  <pre><code class="lang-javascript">
    function readAllChunks(readableStream) {
      const reader = readableStream.getReader();
      const chunks = [];

      return pump();

      function pump() {
        return reader.read().then(({ value, done }) => {
          if (done) {
            return chunks;
          }

          chunks.push(value);
          return pump();
        });
      }
    }
  </code></pre>

  Note how the first thing it does is obtain a reader, and from then on it uses the reader exclusively. This ensures
  that no other consumer can interfere with the stream, either by reading chunks or by
  <a lt="cancel a readable stream">canceling</a> the stream.
</div>

<h5 id="rs-pipe-through" method for="ReadableStream" lt="pipeThrough(transform, options)">pipeThrough({
<var>writable</var>, <var>readable</var> }, <var>options</var>)</h5>

<div class="note">
  The <code>pipeThrough</code> method provides a convenient, chainable way of <a>piping</a> this <a>readable stream</a>
  through a <a>transform stream</a> (or any other <code>{ writable, readable }</code> pair). It simply pipes the stream
  into the writable side of the supplied pair, and returns the readable side for further use.

  Piping a stream will generally <a lt="locked to a reader">lock</a> it for the duration of the pipe, preventing any
  other consumer from acquiring a reader.

  This method is intentionally generic; it does not require that its <emu-val>this</emu-val> value be a
  {{ReadableStream}} object. It also does not require that its <code>writable</code> argument be a {{WritableStream}}
  instance, or that its <code>readable</code> argument be a {{ReadableStream}} instance.
</div>

<emu-alg>
  1. Let _promise_ be ? Invoke(*this*, `"pipeTo"`, « _writable_, _options_ »).
  1. If Type(_promise_) is Object and _promise_ has a [[PromiseIsHandled]] internal slot, set
     _promise_.[[PromiseIsHandled]] to *true*.
  1. Return _readable_.
</emu-alg>

<div class="example" id="example-pipe-chain">
  A typical example of constructing <a>pipe chain</a> using {{ReadableStream/pipeThrough(transform, options)}} would
  look like

  <pre><code class="lang-javascript">
    httpResponseBody
      .pipeThrough(decompressorTransform)
      .pipeThrough(ignoreNonImageFilesTransform)
      .pipeTo(mediaGallery);
  </code></pre>
</div>

<h5 id="rs-pipe-to" method for="ReadableStream" lt="pipeTo(dest, options)">pipeTo(<var>dest</var>, {
<var>preventClose</var>, <var>preventAbort</var>, <var>preventCancel</var> } = {})</h5>

<div class="note">
  The <code>pipeTo</code> method <a lt="piping">pipes</a> this <a>readable stream</a> to a given <a>writable
  stream</a>. The way in which the piping process behaves under various error conditions can be customized with a
  number of passed options. It returns a promise that fulfills when the piping process completes successfully, or
  rejects if any errors were encountered.

  Piping a stream will <a lt="locked to a reader">lock</a> it for the duration of the pipe, preventing any other
  consumer from acquiring a reader.

  Errors and closures of the source and destination streams propagate as follows:

  <ul>
    <li><p>An error in the source <a>readable stream</a> will <a lt="abort a writable stream">abort</a> the destination
    <a>writable stream</a>, unless <code>preventAbort</code> is truthy. The returned promise will be rejected with the
    source's error, or with any error that occurs during aborting the destination.</p></li>

    <li><p>An error in the destination <a>writable stream</a> will <a lt="cancel a readable stream">cancel</a> the
    source <a>readable stream</a>, unless <code>preventCancel</code> is truthy. The returned promise will be rejected
    with the destination's error, or with any error that occurs during canceling the source.</p></li>

    <li><p>When the source <a>readable stream</a> closes, the destination <a>writable stream</a> will be closed, unless
    <code>preventClose</code> is true. The returned promise will be fulfilled once this process completes, unless an
    error is encountered while closing the destination, in which case it will be rejected with that error.</p></li>

    <li><p>If the destination <a>writable stream</a> starts out closed or closing, the source <a>readable stream</a>
    will be <a lt="cancel a readable stream">canceled</a>, unless <code>preventCancel</code> is true. The returned
    promise will be rejected with an error indicating piping to a closed stream failed, or with any error that occurs
    during canceling the source.</p></li>
  </ul>
</div>

<emu-alg>
  1. If ! IsReadableStream(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If ! IsWritableStream(_dest_) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Set _preventClose_ to ! ToBoolean(_preventClose_), set _preventAbort_ to ! ToBoolean(_preventAbort_), and set
     _preventCancel_ to ! ToBoolean(_preventCancel_).
  1. If ! IsReadableStreamLocked(*this*) is *true*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If ! IsWritableStreamLocked(_dest_) is *true*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If ! IsReadableByteStreamController(*this*.[[readableStreamController]]) is *true*, let _reader_ be either !
     AcquireReadableStreamBYOBReader(*this*) or ! AcquireReadableStreamDefaultReader(*this*), at the user agent's
     discretion.
  1. Otherwise, let _reader_ be ! AcquireReadableStreamDefaultReader(*this*).
  1. Let _writer_ be ! AcquireWritableStreamDefaultWriter(_dest_).
  1. Let _shuttingDown_ be *false*.
  1. Let _promise_ be <a>a new promise</a>.
  1. <a>In parallel</a>, using _reader_ and _writer_, read all <a>chunks</a> from *this* and write them to _dest_. Due
     to the locking provided by the reader and writer, the exact manner in which this happens is not observable to
     author code, and so there is flexibility in how this is done. The following constraints apply regardless of the
     exact algorithm used:
     * <strong>Public API must not be used:</strong> while reading or writing, or performing any of the operations
       below, the JavaScript-modifiable reader, writer, and stream APIs (i.e. methods on the appropriate prototypes)
       must not be used. Instead, the streams must be manipulated directly.
     * <strong>Backpressure must be enforced:</strong>
       * While WritableStreamDefaultWriterGetDesiredSize(_writer_) is ≤ *0* or is *null*, the user agent must not read
         from _reader_.
       * If _reader_ is a <a>BYOB reader</a>, WritableStreamDefaultWriterGetDesiredSize(_writer_) should be used to
         determine the size of the chunks read from _reader_.
       * Otherwise, WritableStreamDefaultWriterGetDesiredSize(_writer_) may be used to determine the flow rate
         heuristically, e.g. by delaying reads while it is judged to be "low" compared to the size of chunks that have
         been typically read.
     * <strong>Shutdown must stop all activity:</strong> if _shuttingDown_ becomes *true*, the user agent must not
       initiate further reads from _reader_ or writes to _writer_. (Ongoing reads and writes may finish.) In particular,
       the user agent must check the below conditions on *this*.[[state]] and _dest_.[[state]] before performing any
       reads or writes, since they might lead to immediate shutdown.
     * <strong>Errors must be propagated forward:</strong> if *this*.[[state]] is or becomes `"errored"`, then
       1. If _preventAbort_ is *false*, <a href="#rs-pipeTo-shutdown-with-action">shutdown with an action</a> of !
          WritableStreamAbort(_dest_, *this*.[[storedError]]) and with *this*.[[storedError]].
       1. Otherwise, <a href="#rs-pipeTo-shutdown">shutdown</a> with *this*.[[storedError]].
     * <strong>Errors must be propagated backward:</strong> if _dest_.[[state]] is or becomes `"errored"`, then
       1. If _preventCancel_ is *false*, <a href="#rs-pipeTo-shutdown-with-action">shutdown with an action</a> of !
          ReadableStreamCancel(*this*, _dest_.[[storedError]]) and with _dest_.[[storedError]].
       1. Otherwise, <a href="#rs-pipeTo-shutdown">shutdown</a> with _dest_.[[storedError]].
     * <strong>Closing must be propagated forward:</strong> if *this*.[[state]] is or becomes `"closed"`, then
       1. If _preventClose_ is *false*, <a href="#rs-pipeTo-shutdown-with-action">shutdown with an action</a> of !
          WritableStreamDefaultWriterCloseWithErrorPropagation(_writer_).
       1. Otherwise, <a href="#rs-pipeTo-shutdown">shutdown</a>.
     * <strong>Closing must be propagated backward:</strong> if ! WritableStreamCloseQueuedOrInFlight(_dest_) is *true*
       or _dest_.[[state]] is `"closed"`, then
       1. Let _destClosed_ be a new *TypeError*.
       1. If _preventCancel_ is *false*, <a href="#rs-pipeTo-shutdown-with-action">shutdown with an action</a> of !
          ReadableStreamCancel(*this*, _destClosed_) and with _destClosed_.
       1. Otherwise, <a href="#rs-pipeTo-shutdown">shutdown</a> with _destClosed_.
     * <i id="rs-pipeTo-shutdown-with-action">Shutdown with an action</i>: if any of the above requirements ask to
       shutdown with an action _action_, optionally with an error _originalError_, then:
       1. If _shuttingDown_ is *true*, abort these substeps.
       1. Set _shuttingDown_ to *true*.
       1. Wait until any ongoing write finishes (i.e. the corresponding promises settle).
       1. Let _p_ be the result of performing _action_.
       1. <a>Upon fulfillment</a> of _p_, <a href="#rs-pipeTo-finalize">finalize</a>, passing along _originalError_ if
          it was given.
       1. <a>Upon rejection</a> of _p_ with reason _newError_, <a href="#rs-pipeTo-finalize">finalize</a> with
          _newError_.
     * <i id="rs-pipeTo-shutdown">Shutdown</i>: if any of the above requirements or steps ask to shutdown, optionally
       with an error _error_, then:
       1. If _shuttingDown_ is *true*, abort these substeps.
       1. Set _shuttingDown_ to *true*.
       1. Wait until any ongoing write finishes (i.e. the corresponding promises settle).
       1. <a href="#rs-pipeTo-finalize">Finalize</a>, passing along _error_ if it was given.
     * <i id="rs-pipeTo-finalize">Finalize</i>: both forms of shutdown will eventually ask to finalize, optionally with
       an error _error_, which means to perform the following steps:
       1. Perform ! WritableStreamDefaultWriterRelease(_writer_).
       1. Perform ! ReadableStreamReaderGenericRelease(_reader_).
       1. If _error_ was given, <a>reject</a> _promise_ with _error_.
       1. Otherwise, <a>resolve</a> _promise_ with *undefined*.
  1. Return _promise_.
</emu-alg>

<h5 id="rs-tee" method for="ReadableStream">tee()</h5>

<div class="note">
  The <code>tee</code> method <a lt="tee a readable stream">tees</a> this readable stream, returning a two-element
  array containing the two resulting branches as new {{ReadableStream}} instances.

  Teeing a stream will <a lt="locked to a reader">lock</a> it, preventing any other consumer from acquiring a reader.
  To <a lt="cancel a readable stream">cancel</a> the stream, cancel both of the resulting branches; a composite
  cancellation reason will then be propagated to the stream's <a>underlying source</a>.

  Note that the <a>chunks</a> seen in each branch will be the same object. If the chunks are not immutable, this could
  allow interference between the two branches. (<a href="https://github.com/whatwg/streams/issues/new">Let us know</a>
  if you think we should add an option to <code>tee</code> that creates <a abstract-op lt="StructuredClone">structured
  clones</a> of the chunks for each branch.)
</div>

<emu-alg>
  1. If ! IsReadableStream(*this*) is *false*, throw a *TypeError* exception.
  1. Let _branches_ be ? ReadableStreamTee(*this*, *false*).
  1. Return ! CreateArrayFromList(_branches_).
</emu-alg>

<div class="example" id="example-tee-and-pipe">
  Teeing a stream is most useful when you wish to let two independent consumers read from the stream in parallel,
  perhaps even at different speeds. For example, given a writable stream <code>cacheEntry</code> representing an
  on-disk file, and another writable stream <code>httpRequestBody</code> representing an upload to a remote server,
  you could pipe the same readable stream to both destinations at once:

  <pre><code class="lang-javascript">
    const [forLocal, forRemote] = readableStream.tee();

    Promise.all([
      forLocal.pipeTo(cacheEntry),
      forRemote.pipeTo(httpRequestBody)
    ])
    .then(() => console.log("Saved the stream to the cache and also uploaded it!"))
    .catch(e => console.error("Either caching or uploading failed: ", e));
  </code></pre>
</div>

<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
specifications, instead of just being part of the implementation of this spec's classes.

<h4 id="acquire-readable-stream-byob-reader" aoid="AcquireReadableStreamBYOBReader"
throws>AcquireReadableStreamBYOBReader ( <var>stream</var> )</h4>

This abstract operation is meant to be called from other specifications that may wish to acquire a <a>BYOB reader</a>
for a given stream.

<emu-alg>
  1. Return ? Construct(`<a idl>ReadableStreamBYOBReader</a>`, « _stream_ »).
</emu-alg>

<h4 id="acquire-readable-stream-reader" aoid="AcquireReadableStreamDefaultReader" throws
export>AcquireReadableStreamDefaultReader ( <var>stream</var> )</h4>

This abstract operation is meant to be called from other specifications that may wish to acquire a <a>default
reader</a> for a given stream.

<emu-alg>
  1. Return ? Construct(`<a idl>ReadableStreamDefaultReader</a>`, « _stream_ »).
</emu-alg>

<h4 id="is-readable-stream" aoid="IsReadableStream" nothrow>IsReadableStream ( <var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have a [[readableStreamController]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="is-readable-stream-disturbed" aoid="IsReadableStreamDisturbed" nothrow export>IsReadableStreamDisturbed (
<var>stream</var> )</h4>

This abstract operation is meant to be called from other specifications that may wish to query whether or not a
readable stream has ever been read from or canceled.

<emu-alg>
  1. Assert: ! IsReadableStream(_stream_) is *true*.
  1. Return _stream_.[[disturbed]].
</emu-alg>

<h4 id="is-readable-stream-locked" aoid="IsReadableStreamLocked" nothrow export>IsReadableStreamLocked (
<var>stream</var> )</h4>

This abstract operation is meant to be called from other specifications that may wish to query whether or not a
readable stream is <a>locked to a reader</a>.

<emu-alg>
  1. Assert: ! IsReadableStream(_stream_) is *true*.
  1. If _stream_.[[reader]] is *undefined*, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="readable-stream-tee" aoid="ReadableStreamTee" throws export>ReadableStreamTee ( <var>stream</var>,
<var>cloneForBranch2</var> )</h4>

This abstract operation is meant to be called from other specifications that may wish to <a lt="tee a readable
stream">tee</a> a given readable stream.

The second argument, <var>cloneForBranch2</var>, governs whether or not the data from the original stream will be <a
abstract-op lt="StructuredClone">structured cloned</a> before appearing in the second of the returned branches. This is
useful for scenarios where both branches are to be consumed in such a way that they might otherwise interfere with each
other, such as by <a abstract-op lt="Transfer">transfering</a> their <a>chunks</a>. However, it does introduce a
noticable asymmetry between the two branches. [[!HTML]]

<emu-alg>
  1. Assert: ! IsReadableStream(_stream_) is *true*.
  1. Assert: Type(_cloneForBranch2_) is Boolean.
  1. Let _reader_ be ? AcquireReadableStreamDefaultReader(_stream_).
  1. Let _teeState_ be Record {[[closedOrErrored]]: *false*, [[canceled1]]: *false*, [[canceled2]]: *false*,
     [[reason1]]: *undefined*, [[reason2]]: *undefined*, [[promise]]: <a>a new promise</a>}.
  1. Let _pull_ be a new <a>ReadableStreamTee pull function</a>.
  1. Set _pull_.[[reader]] to _reader_, _pull_.[[teeState]] to _teeState_, and _pull_.[[cloneForBranch2]] to
     _cloneForBranch2_.
  1. Let _cancel1_ be a new <a>ReadableStreamTee branch 1 cancel function</a>.
  1. Set _cancel1_.[[stream]] to _stream_ and _cancel1_.[[teeState]] to _teeState_.
  1. Let _cancel2_ be a new <a>ReadableStreamTee branch 2 cancel function</a>.
  1. Set _cancel2_.[[stream]] to _stream_ and _cancel2_.[[teeState]] to _teeState_.
  1. Let _underlyingSource1_ be ! ObjectCreate(%ObjectPrototype%).
  1. Perform ! CreateDataProperty(_underlyingSource1_, `"pull"`, _pull_).
  1. Perform ! CreateDataProperty(_underlyingSource1_, `"cancel"`, _cancel1_).
  1. Let _branch1Stream_ be ! Construct(`<a idl>ReadableStream</a>`, _underlyingSource1_).
  1. Let _underlyingSource2_ be ! ObjectCreate(%ObjectPrototype%).
  1. Perform ! CreateDataProperty(_underlyingSource2_, `"pull"`, _pull_).
  1. Perform ! CreateDataProperty(_underlyingSource2_, `"cancel"`, _cancel2_).
  1. Let _branch2Stream_ be ! Construct(`<a idl>ReadableStream</a>`, _underlyingSource2_).
  1. Set _pull_.[[branch1]] to _branch1Stream_.[[readableStreamController]].
  1. Set _pull_.[[branch2]] to _branch2Stream_.[[readableStreamController]].
  1. <a>Upon rejection</a> of _reader_.[[closedPromise]] with reason _r_,
    1. If _teeState_.[[closedOrErrored]] is *false*, then:
      1. Perform ! ReadableStreamDefaultControllerError(_pull_.[[branch1]], _r_).
      1. Perform ! ReadableStreamDefaultControllerError(_pull_.[[branch2]], _r_).
      1. Set _teeState_.[[closedOrErrored]] to *true*.
  1. Return « _branch1Stream_, _branch2Stream_ ».
</emu-alg>

A <dfn>ReadableStreamTee pull function</dfn> is an anonymous built-in function that pulls data from a given <a>readable
stream reader</a> and enqueues it into two other streams ("branches" of the associated tee). Each ReadableStreamTee
pull function has \[[reader]], \[[branch1]], \[[branch2]], \[[teeState]], and \[[cloneForBranch2]] internal slots. When
a ReadableStreamTee pull function <var>F</var> is called, it performs the following steps:

<emu-alg>
  1. Let _reader_ be _F_.[[reader]], _branch1_ be _F_.[[branch1]], _branch2_ be _F_.[[branch2]], _teeState_ be
     _F_.[[teeState]], and _cloneForBranch2_ be _F_.[[cloneForBranch2]].
  1. Return the result of <a>transforming</a> ! ReadableStreamDefaultReaderRead(_reader_) with a fulfillment handler
     which takes the argument _result_ and performs the following steps:
    1. Assert: Type(_result_) is Object.
    1. Let _value_ be ? Get(_result_, `"value"`).
    1. Let _done_ be ? Get(_result_, `"done"`).
    1. Assert: Type(_done_) is Boolean.
    1. If _done_ is *true* and _teeState_.[[closedOrErrored]] is *false*,
      1. If _teeState_.[[canceled1]] is *false*,
        1. Perform ! ReadableStreamDefaultControllerClose(_branch1_).
      1. If _teeState_.[[canceled2]] is *false*,
        1. Perform ! ReadableStreamDefaultControllerClose(_branch2_).
      1. Set _teeState_.[[closedOrErrored]] to *true*.
    1. If _teeState_.[[closedOrErrored]] is *true*, return.
    1. Let _value1_ and _value2_ be _value_.
    1. If _teeState_.[[canceled2]] is *false* and _cloneForBranch2_ is *true*, set _value2_ to ? <a
       abstract-op>StructuredClone</a>(_value2_).
    1. If _teeState_.[[canceled1]] is *false*, perform ? ReadableStreamDefaultControllerEnqueue(_branch1_, _value1_).
    1. If _teeState_.[[canceled2]] is *false*, perform ? ReadableStreamDefaultControllerEnqueue(_branch2_, _value2_).
</emu-alg>

A <dfn>ReadableStreamTee branch 1 cancel function</dfn> is an anonymous built-in function that reacts to the
cancellation of the first of the two branches of the associated tee. Each ReadableStreamTee branch 1 cancel function
has \[[stream]] and \[[teeState]] internal slots. When a ReadableStreamTee branch 1 cancel function <var>F</var> is
called with argument <var>reason</var>, it performs the following steps:

<emu-alg>
  1. Let _stream_ be _F_.[[stream]] and _teeState_ be _F_.[[teeState]].
  1. Set _teeState_.[[canceled1]] to *true*.
  1. Set _teeState_.[[reason1]] to _reason_.
  1. If _teeState_.[[canceled2]] is *true*,
    1. Let _compositeReason_ be ! CreateArrayFromList(« _teeState_.[[reason1]], _teeState_.[[reason2]] »).
    1. Let _cancelResult_ be ! ReadableStreamCancel(_stream_, _compositeReason_).
    1. <a>Resolve</a> _teeState_.[[promise]] with _cancelResult_.
  1. Return _teeState_.[[promise]].
</emu-alg>

A <dfn>ReadableStreamTee branch 2 cancel function</dfn> is an anonymous built-in function that reacts to the
cancellation of the second of the two branches of the associated tee. Each ReadableStreamTee branch 2 cancel function
has \[[stream]] and \[[teeState]] internal slots. When a ReadableStreamTee branch 2 cancel function <var>F</var> is
called with argument <var>reason</var>, it performs the following steps:

<emu-alg>
  1. Let _stream_ be _F_.[[stream]] and _teeState_ be _F_.[[teeState]].
  1. Set _teeState_.[[canceled2]] to *true*.
  1. Set _teeState_.[[reason2]] to _reason_.
  1. If _teeState_.[[canceled1]] is *true*,
    1. Let _compositeReason_ be ! CreateArrayFromList(« _teeState_.[[reason1]], _teeState_.[[reason2]] »).
    1. Let _cancelResult_ be ! ReadableStreamCancel(_stream_, _compositeReason_).
    1. <a>Resolve</a> _teeState_.[[promise]] with _cancelResult_.
  1. Return _teeState_.[[promise]].
</emu-alg>

<div class="note">
  The algorithm given here is written such that three new function objects are created for each call to to
  ReadableStreamTee. This is just a simplification, and is not actually necessary, since it is unobservable to
  developer code. For example, a self-hosted implementation could optimize by creating a class whose prototype contains
  methods for these functions, with the state stored as instance variables.
</div>

<h3 id="rs-abstract-ops-used-by-controllers">Readable Stream Abstract Operations Used by Controllers</h3>

In terms of specification factoring, the way that the {{ReadableStream}} class encapsulates the behavior of
both simple readable streams and <a>readable byte streams</a> into a single class is by centralizing most of the
potentially-varying logic inside the two controller classes, {{ReadableStreamDefaultController}} and
{{ReadableByteStreamController}}. Those classes define most of the stateful internal slots and abstract
operations for how a stream's <a>internal queue</a> is managed and how it interfaces with its <a>underlying source</a>
or <a>underlying byte source</a>.

The abstract operations in this section are interfaces that are used by the controller implementations to affect their
associated {{ReadableStream}} object, translating those internal state changes into developer-facing results
visible through the {{ReadableStream}}'s public API.

<h4 id="readable-stream-add-read-into-request" aoid="ReadableStreamAddReadIntoRequest"
nothrow>ReadableStreamAddReadIntoRequest ( <var>stream</var> )</h4>

<emu-alg>
  1. Assert: ! IsReadableStreamBYOBReader(_stream_.[[reader]]) is *true*.
  1. Assert: _stream_.[[state]] is `"readable"` or `"closed"`.
  1. Let _promise_ be <a>a new promise</a>.
  1. Let _readIntoRequest_ be Record {[[promise]]: _promise_}.
  1. Append _readIntoRequest_ as the last element of _stream_.[[reader]].[[readIntoRequests]].
  1. Return _promise_.
</emu-alg>

<h4 id="readable-stream-add-read-request" aoid="ReadableStreamAddReadRequest" nothrow>ReadableStreamAddReadRequest (
<var>stream</var> )</h4>

<emu-alg>
  1. Assert: ! IsReadableStreamDefaultReader(_stream_.[[reader]]) is *true*.
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Let _promise_ be <a>a new promise</a>.
  1. Let _readRequest_ be Record {[[promise]]: _promise_}.
  1. Append _readRequest_ as the last element of _stream_.[[reader]].[[readRequests]].
  1. Return _promise_.
</emu-alg>

<h4 id="readable-stream-cancel" aoid="ReadableStreamCancel" nothrow export>ReadableStreamCancel ( <var>stream</var>,
<var>reason</var> )</h4>

<emu-alg>
  1. Set _stream_.[[disturbed]] to *true*.
  1. If _stream_.[[state]] is `"closed"`, return <a>a promise resolved with</a> *undefined*.
  1. If _stream_.[[state]] is `"errored"`, return <a>a promise rejected with</a> _stream_.[[storedError]].
  1. Perform ! ReadableStreamClose(_stream_).
  1. Let _sourceCancelPromise_ be ! _stream_.[[readableStreamController]].[[CancelSteps]](_reason_).
  1. Return the result of <a>transforming</a> _sourceCancelPromise_ with a fulfillment handler that returns *undefined*.
</emu-alg>

<h4 id="readable-stream-close" aoid="ReadableStreamClose" nothrow>ReadableStreamClose ( <var>stream</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Set _stream_.[[state]] to `"closed"`.
  1. Let _reader_ be _stream_.[[reader]].
  1. If _reader_ is *undefined*, return.
  1. If ! IsReadableStreamDefaultReader(_reader_) is *true*,
    1. Repeat for each _readRequest_ that is an element of _reader_.[[readRequests]],
      1. <a>Resolve</a> _readRequest_.[[promise]] with ! CreateIterResultObject(*undefined*, *true*).
    1. Set _reader_.[[readRequests]] to an empty List.
  1. <a>Resolve</a> _reader_.[[closedPromise]] with *undefined*.
</emu-alg>

<div class="note">
  The case where <var>stream</var>.\[[state]] is <code>"closed"</code>, but <var>stream</var>.\[[closeRequested]] is
  <emu-val>false</emu-val>, will happen if the stream was closed without its controller's close method ever being
  called: i.e., if the stream was closed by a call to {{ReadableStream/cancel(reason)}}. In this case we allow the
  controller's <code>close</code> method to be called and silently do nothing, since the cancelation was outside the
  control of the underlying source.
</div>

<h4 id="readable-stream-error" aoid="ReadableStreamError" nothrow>ReadableStreamError ( <var>stream</var>, <var>e</var>
)</h4>

<emu-alg>
  1. Assert: ! IsReadableStream(_stream_) is *true*.
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Set _stream_.[[state]] to `"errored"`.
  1. Set _stream_.[[storedError]] to _e_.
  1. Let _reader_ be _stream_.[[reader]].
  1. If _reader_ is *undefined*, return.
  1. If ! IsReadableStreamDefaultReader(_reader_) is *true*,
    1. Repeat for each _readRequest_ that is an element of _reader_.[[readRequests]],
      1. <a>Reject</a> _readRequest_.[[promise]] with _e_.
    1. Set _reader_.[[readRequests]] to a new empty List.
  1. Otherwise,
    1. Assert: ! IsReadableStreamBYOBReader(_reader_).
    1. Repeat for each _readIntoRequest_ that is an element of _reader_.[[readIntoRequests]],
      1. <a>Reject</a> _readIntoRequest_.[[promise]] with _e_.
    1. Set _reader_.[[readIntoRequests]] to a new empty List.
  1. <a>Reject</a> _reader_.[[closedPromise]] with _e_.
  1. Set _reader_.[[closedPromise]].[[PromiseIsHandled]] to *true*.
</emu-alg>

<h4 id="readable-stream-fulfill-read-into-request" aoid="ReadableStreamFulfillReadIntoRequest"
nothrow>ReadableStreamFulfillReadIntoRequest ( <var>stream</var>, <var>chunk</var>, <var>done</var> )</h4>

<emu-alg>
  1. Let _reader_ be _stream_.[[reader]].
  1. Let _readIntoRequest_ be the first element of _reader_.[[readIntoRequests]].
  1. Remove _readIntoRequest_ from _reader_.[[readIntoRequests]], shifting all other elements downward (so that the
     second becomes the first, and so on).
  1. <a>Resolve</a> _readIntoRequest_.[[promise]] with ! CreateIterResultObject(_chunk_, _done_).
</emu-alg>

<h4 id="readable-stream-fulfill-read-request" aoid="ReadableStreamFulfillReadRequest"
nothrow>ReadableStreamFulfillReadRequest ( <var>stream</var>, <var>chunk</var>, <var>done</var> )</h4>

<emu-alg>
  1. Let _reader_ be _stream_.[[reader]].
  1. Let _readRequest_ be the first element of _reader_.[[readRequests]].
  1. Remove _readRequest_ from _reader_.[[readRequests]], shifting all other elements downward (so that the second
     becomes the first, and so on).
  1. <a>Resolve</a> _readRequest_.[[promise]] with ! CreateIterResultObject(_chunk_, _done_).
</emu-alg>

<h4 id="readable-stream-get-num-read-into-requests" aoid="ReadableStreamGetNumReadIntoRequests"
nothrow>ReadableStreamGetNumReadIntoRequests ( <var>stream</var> )</h4>

<emu-alg>
  1. Return the number of elements in _stream_.[[reader]].[[readIntoRequests]].
</emu-alg>

<h4 id="readable-stream-get-num-read-requests" aoid="ReadableStreamGetNumReadRequests"
nothrow>ReadableStreamGetNumReadRequests ( <var>stream</var> )</h4>

<emu-alg>
  1. Return the number of elements in _stream_.[[reader]].[[readRequests]].
</emu-alg>

<h4 id="readable-stream-has-byob-reader" aoid="ReadableStreamHasBYOBReader" nothrow>ReadableStreamHasBYOBReader (
<var>stream</var> )</h4>

<emu-alg>
  1. Let _reader_ be _stream_.[[reader]].
  1. If _reader_ is *undefined*, return *false*.
  1. If ! IsReadableStreamBYOBReader(_reader_) is *false*, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="readable-stream-has-default-reader" aoid="ReadableStreamHasDefaultReader" nothrow>ReadableStreamHasDefaultReader (
<var>stream</var> )</h4>

<emu-alg>
  1. Let _reader_ be _stream_.[[reader]].
  1. If _reader_ is *undefined*, return *false*.
  1. If ! IsReadableStreamDefaultReader(_reader_) is *false*, return *false*.
  1. Return *true*.
</emu-alg>

<h3 id="default-reader-class" interface lt="ReadableStreamDefaultReader">Class
<code>ReadableStreamDefaultReader</code></h3>

The {{ReadableStreamDefaultReader}} class represents a <a>default reader</a> designed to be vended by a
{{ReadableStream}} instance.

<h4 id="default-reader-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{ReadableStreamDefaultReader}} class in something close to the syntax of [[!ECMASCRIPT]], it
would look like

<pre><code class="lang-javascript">
  class ReadableStreamDefaultReader {
    constructor(stream)

    get closed()

    cancel(reason)
    read()
    releaseLock()
  }
</code></pre>

<h4 id="default-reader-internal-slots">Internal Slots</h4>

Instances of {{ReadableStreamDefaultReader}} 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>\[[closedPromise]]
    <td>A promise returned by the reader's {{ReadableStreamDefaultReader/closed}} getter
  </tr>
  <tr>
    <td>\[[ownerReadableStream]]
    <td>A {{ReadableStream}} instance that owns this reader
  </tr>
  <tr>
    <td>\[[readRequests]]
    <td>A List of promises returned by calls to the reader's {{ReadableStreamDefaultReader/read()}} method that have
      not yet been resolved, due to the <a>consumer</a> requesting <a>chunks</a> sooner than they are available; also
      used for the <a href="#is-readable-stream-default-reader">IsReadableStreamDefaultReader</a> brand check
  </tr>
</table>

<h4 id="default-reader-constructor" constructor for="ReadableStreamDefaultReader"
lt="ReadableStreamDefaultReader(stream)">new ReadableStreamDefaultReader(<var>stream</var>)</h4>

<div class="note">
  The <code>ReadableStreamDefaultReader</code> constructor is generally not meant to be used directly; instead, a
  stream's {{ReadableStream/getReader()}} method should be used.
</div>

<emu-alg>
  1. If ! IsReadableStream(_stream_) is *false*, throw a *TypeError* exception.
  1. If ! IsReadableStreamLocked(_stream_) is *true*, throw a *TypeError* exception.
  1. Perform ! ReadableStreamReaderGenericInitialize(*this*, _stream_).
  1. Set *this*.[[readRequests]] to a new empty List.
</emu-alg>

<h4 id="default-reader-prototype">Properties of the {{ReadableStreamDefaultReader}} Prototype</h4>

<h5 id="default-reader-closed" attribute for="ReadableStreamDefaultReader" lt="closed">get closed</h5>

<div class="note">
  The <code>closed</code> getter returns a promise that will be fulfilled when the stream becomes closed or the
  reader's lock is <a lt="release a read lock">released</a>, or rejected if the stream ever errors.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultReader(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return *this*.[[closedPromise]].
</emu-alg>

<h5 id="default-reader-cancel" method for="ReadableStreamDefaultReader">cancel(<var>reason</var>)</h5>

<div class="note">
  If the reader is <a lt="active reader">active</a>, the <code>cancel</code> method behaves the same as that for the
  associated stream.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultReader(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If *this*.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! ReadableStreamReaderGenericCancel(*this*, _reason_).
</emu-alg>

<h5 id="default-reader-read" method for="ReadableStreamDefaultReader">read()</h5>

<div class="note">
  The <code>read</code> method will return a promise that allows access to the next <a>chunk</a> from the stream's
  internal queue, if available.

  <ul>
    <li> If the chunk does become available, the promise will be fulfilled with an object of the form
      <code>{ value: theChunk, done: false }</code>.
    <li> If the stream becomes closed, the promise will be fulfilled with an object of the form
      <code>{ value: undefined, done: true }</code>.
    <li> If the stream becomes errored, the promise will be rejected with the relevant error.
  </ul>

  If reading a chunk causes the queue to become empty, more data will be pulled from the <a>underlying source</a>.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultReader(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If *this*.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! ReadableStreamDefaultReaderRead(*this*).
</emu-alg>

<h5 id="default-reader-release-lock" method for="ReadableStreamDefaultReader">releaseLock()</h5>

<div class="note">
  The <code>releaseLock</code> method <a lt="release a read lock">releases the reader's lock</a> on the corresponding
  stream. After the lock is released, the reader is no longer <a lt="active reader">active</a>. If the associated
  stream is errored when the lock is released, the reader will appear errored in the same way from now on; otherwise,
  the reader will appear closed.

  A reader's lock cannot be released while it still has a pending read request, i.e., if a promise returned by the
  reader's {{ReadableStreamDefaultReader/read()}} method has not yet been settled. Attempting to do so will throw
  a <emu-val>TypeError</emu-val> and leave the reader locked to the stream.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultReader(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[ownerReadableStream]] is *undefined*, return.
  1. If *this*.[[readRequests]] is not empty, throw a *TypeError* exception.
  1. Perform ! ReadableStreamReaderGenericRelease(*this*).
</emu-alg>

<h3 id="byob-reader-class" interface lt="ReadableStreamBYOBReader">Class <code>ReadableStreamBYOBReader</code></h3>

The {{ReadableStreamBYOBReader}} class represents a <a>BYOB reader</a> designed to be vended by a {{ReadableStream}}
instance.

<h4 id="byob-reader-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{ReadableStreamBYOBReader}} class in something close to the syntax of [[!ECMASCRIPT]], it
would look like

<pre><code class="lang-javascript">
  class ReadableStreamBYOBReader {
    constructor(stream)

    get closed()

    cancel(reason)
    read(view)
    releaseLock()
  }
</code></pre>

<h4 id="byob-reader-internal-slots">Internal Slots</h4>

Instances of {{ReadableStreamBYOBReader}} 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>\[[closedPromise]]
    <td>A promise returned by the reader's {{ReadableStreamBYOBReader/closed}} getter
  </tr>
  <tr>
    <td>\[[ownerReadableStream]]
    <td>A {{ReadableStream}} instance that owns this reader
  </tr>
  <tr>
    <td>\[[readIntoRequests]]
    <td>A List of promises returned by calls to the reader's {{ReadableStreamBYOBReader/read(view)}} method that have
      not yet been resolved, due to the <a>consumer</a> requesting <a>chunks</a> sooner than they are available; also
      used for the <a href="#is-readable-stream-byob-reader">IsReadableStreamBYOBReader</a> brand check
  </tr>
</table>

<h4 id="byob-reader-constructor" constructor for="ReadableStreamBYOBReader" lt="ReadableStreamBYOBReader(stream)">new
ReadableStreamBYOBReader(<var>stream</var>)</h4>

<div class="note">
  The <code>ReadableStreamBYOBReader</code> constructor is generally not meant to be used directly; instead, a stream's
  {{ReadableStream/getReader()}} method should be used.
</div>

<emu-alg>
  1. If ! IsReadableStream(_stream_) is *false*, throw a *TypeError* exception.
  1. If ! IsReadableByteStreamController(_stream_.[[readableStreamController]]) is *false*, throw a *TypeError* exception.
  1. If ! IsReadableStreamLocked(_stream_) is *true*, throw a *TypeError* exception.
  1. Perform ! ReadableStreamReaderGenericInitialize(*this*, _stream_).
  1. Set *this*.[[readIntoRequests]] to a new empty List.
</emu-alg>

<h4 id="byob-reader-prototype">Properties of the {{ReadableStreamBYOBReader}} Prototype</h4>

<h5 id="byob-reader-closed" attribute for="ReadableStreamBYOBReader" lt="closed">get closed</h5>

<div class="note">
  The <code>closed</code> getter returns a promise that will be fulfilled when the stream becomes closed or the
  reader's lock is <a lt="release a read lock">released</a>, or rejected if the stream ever errors.
</div>

<emu-alg>
  1. If ! IsReadableStreamBYOBReader(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return *this*.[[closedPromise]].
</emu-alg>

<h5 id="byob-reader-cancel" method for="ReadableStreamBYOBReader">cancel(<var>reason</var>)</h5>

<div class="note">
  If the reader is <a lt="active reader">active</a>, the <code>cancel</code> method behaves the same as that for the
  associated stream.
</div>

<emu-alg>
  1. If ! IsReadableStreamBYOBReader(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If *this*.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! ReadableStreamReaderGenericCancel(*this*, _reason_).
</emu-alg>

<h5 id="byob-reader-read" method for="ReadableStreamBYOBReader">read(<var>view</var>)</h5>

<div class="note">
  The <code>read</code> method will write read bytes into <code>view</code> and return <a>a promise resolved with</a> a
  possibly transferred buffer as described below.

  <ul>
    <li> If the chunk does become available, the promise will be fulfilled with an object of the form
      <code>{ value: theChunk, done: false }</code>.
    <li> If the stream becomes closed, the promise will be fulfilled with an object of the form
      <code>{ value: undefined, done: true }</code>.
    <li> If the stream becomes errored, the promise will be rejected with the relevant error.
  </ul>

  If reading a chunk causes the queue to become empty, more data will be pulled from the <a>underlying byte source</a>.
</div>

<emu-alg>
  1. If ! IsReadableStreamBYOBReader(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If *this*.[[ownerReadableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If Type(_view_) is not Object, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If _view_ does not have a [[ViewedArrayBuffer]] internal slot, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If _view_.[[ByteLength]] is *0*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! ReadableStreamBYOBReaderRead(*this*, _view_).
</emu-alg>

<h5 id="byob-reader-release-lock" method for="ReadableStreamBYOBReader">releaseLock()</h5>

<div class="note">
  The <code>releaseLock</code> method <a lt="release a read lock">releases the reader's lock</a> on the corresponding
  stream. After the lock is released, the reader is no longer <a lt="active reader">active</a>. If the associated
  stream is errored when the lock is released, the reader will appear errored in the same way from now on; otherwise,
  the reader will appear closed.

  A reader's lock cannot be released while it still has a pending read request, i.e., if a promise returned by the
  reader's {{ReadableStreamBYOBReader/read()}} method has not yet been settled. Attempting to do so will throw
  a <emu-val>TypeError</emu-val> and leave the reader locked to the stream.
</div>

<emu-alg>
  1. If ! IsReadableStreamBYOBReader(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[ownerReadableStream]] is *undefined*, return.
  1. If *this*.[[readIntoRequests]] is not empty, throw a *TypeError* exception.
  1. Perform ! ReadableStreamReaderGenericRelease(*this*).
</emu-alg>

<h3 id="rs-reader-abstract-ops">Readable Stream Reader Abstract Operations</h3>

<h4 id="is-readable-stream-default-reader" aoid="IsReadableStreamDefaultReader" nothrow>IsReadableStreamDefaultReader (
<var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have a [[readRequests]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="is-readable-stream-byob-reader" aoid="IsReadableStreamBYOBReader" nothrow>IsReadableStreamBYOBReader (
<var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have a [[readIntoRequests]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="readable-stream-reader-generic-cancel" aoid="ReadableStreamReaderGenericCancel"
nothrow>ReadableStreamReaderGenericCancel ( <var>reader</var>, <var>reason</var> )</h4>

<emu-alg>
  1. Let _stream_ be _reader_.[[ownerReadableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Return ! ReadableStreamCancel(_stream_, _reason_).
</emu-alg>

<h4 id="readable-stream-reader-generic-initialize" aoid="ReadableStreamReaderGenericInitialize"
nothrow>ReadableStreamReaderGenericInitialize ( <var>reader</var>, <var>stream</var> )</h4>

<emu-alg>
  1. Set _reader_.[[ownerReadableStream]] to _stream_.
  1. Set _stream_.[[reader]] to _reader_.
  1. If _stream_.[[state]] is `"readable"`,
    1. Set _reader_.[[closedPromise]] to <a>a new promise</a>.
  1. Otherwise, if _stream_.[[state]] is `"closed"`,
    1. Set _reader_.[[closedPromise]] to <a>a promise resolved with</a> *undefined*.
  1. Otherwise,
    1. Assert: _stream_.[[state]] is `"errored"`.
    1. Set _reader_.[[closedPromise]] to <a>a promise rejected with</a> _stream_.[[storedError]].
    1. Set _reader_.[[closedPromise]].[[PromiseIsHandled]] to *true*.
</emu-alg>

<h4 id="readable-stream-reader-generic-release" aoid="ReadableStreamReaderGenericRelease"
nothrow>ReadableStreamReaderGenericRelease ( <var>reader</var> )</h4>

<emu-alg>
  1. Assert: _reader_.[[ownerReadableStream]] is not *undefined*.
  1. Assert: _reader_.[[ownerReadableStream]].[[reader]] is _reader_.
  1. If _reader_.[[ownerReadableStream]].[[state]] is `"readable"`, <a>reject</a> _reader_.[[closedPromise]] with a *TypeError*
     exception.
  1. Otherwise, set _reader_.[[closedPromise]] to <a>a promise rejected with</a> a *TypeError* exception.
  1. Set _reader_.[[closedPromise]].[[PromiseIsHandled]] to *true*.
  1. Set _reader_.[[ownerReadableStream]].[[reader]] to *undefined*.
  1. Set _reader_.[[ownerReadableStream]] to *undefined*.
</emu-alg>

<h4 id="readable-stream-byob-reader-read" aoid="ReadableStreamBYOBReaderRead" nothrow>ReadableStreamBYOBReaderRead
( <var>reader</var>, <var>view</var> )</h4>

<emu-alg>
  1. Let _stream_ be _reader_.[[ownerReadableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Set _stream_.[[disturbed]] to *true*.
  1. If _stream_.[[state]] is `"errored"`, return <a>a promise rejected with</a> _stream_.[[storedError]].
  1. Return ! ReadableByteStreamControllerPullInto(_stream_.[[readableStreamController]], _view_).
</emu-alg>

<h4 id="readable-stream-default-reader-read" aoid="ReadableStreamDefaultReaderRead" nothrow
export>ReadableStreamDefaultReaderRead ( <var>reader</var> )</h4>

<emu-alg>
  1. Let _stream_ be _reader_.[[ownerReadableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Set _stream_.[[disturbed]] to *true*.
  1. If _stream_.[[state]] is `"closed"`, return <a>a promise resolved with</a> ! CreateIterResultObject(*undefined*,
     *true*).
  1. If _stream_.[[state]] is `"errored"`, return <a>a promise rejected with</a> _stream_.[[storedError]].
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Return ! _stream_.[[readableStreamController]].[[PullSteps]]().
</emu-alg>

<h3 id="rs-default-controller-class" interface lt="ReadableStreamDefaultController">Class
<code>ReadableStreamDefaultController</code></h3>

The {{ReadableStreamDefaultController}} class has methods that allow control of a {{ReadableStream}}'s state and
<a>internal queue</a>. When constructing a {{ReadableStream}} that is not a <a>readable byte stream</a>, the
<a>underlying source</a> is given a corresponding {{ReadableStreamDefaultController}} instance to manipulate.

<h4 id="rs-default-controller-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{ReadableStreamDefaultController}} class in something close to the syntax of [[!ECMASCRIPT]],
it would look like

<pre><code class="lang-javascript">
  class ReadableStreamDefaultController {
    constructor(stream, underlyingSource, size, highWaterMark)

    get desiredSize()

    close()
    enqueue(chunk)
    error(e)
  }
</code></pre>

<h4 id="rs-default-controller-internal-slots">Internal Slots</h4>

Instances of {{ReadableStreamDefaultController}} 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>\[[closeRequested]]
    <td>A boolean flag indicating whether the stream has been closed by its <a>underlying source</a>, but still has
      <a>chunks</a> in its internal queue that have not yet been read
  </tr>
  <tr>
    <td>\[[controlledReadableStream]]
    <td>The {{ReadableStream}} instance controlled
  </tr>
  <tr>
    <td>\[[pullAgain]]
    <td>A boolean flag set to <emu-val>true</emu-val> if the stream's mechanisms requested a call to the underlying
      source's <code>pull</code> method to pull more data, but the pull could not yet be done since a previous call is
      still executing
  </tr>
  <tr>
    <td>\[[pulling]]
    <td>A boolean flag set to <emu-val>true</emu-val> while the <a>underlying source</a>'s <code>pull</code> method is
      executing and has not yet fulfilled, used to prevent reentrant calls
  </tr>
  <tr>
    <td>\[[queue]]
    <td>A List representing the stream's internal queue of <a>chunks</a>
  </tr>
  <tr>
    <td>\[[queueTotalSize]]
    <td>The total size of all the chunks stored in \[[queue]] (see [[#queue-with-sizes]])
  </tr>
  <tr>
    <td>\[[started]]
    <td>A boolean flag indicating whether the <a>underlying source</a> has finished starting
  </tr>
  <tr>
    <td>\[[strategyHWM]]
    <td>A number supplied to the constructor as part of the stream's <a>queuing strategy</a>, indicating the point at
      which the stream will apply <a>backpressure</a> to its <a>underlying source</a>
  </tr>
  <tr>
    <td>\[[strategySize]]
    <td>A function supplied to the constructor as part of the stream's <a>queuing strategy</a>, designed to calculate
      the size of enqueued <a>chunks</a>; can be <emu-val>undefined</emu-val> for the default behavior
  </tr>
  <tr>
    <td>\[[underlyingSource]]
    <td>An object representation of the stream's <a>underlying source</a>; also
      used for the <a href="#is-readable-stream-default-controller">IsReadableStreamDefaultController</a> brand check
  </tr>
</table>

<h4 id="rs-default-controller-constructor" constructor for="ReadableStreamDefaultController"
lt="ReadableStreamDefaultController(stream, underlyingSource, size, highWaterMark)">new
ReadableStreamDefaultController(<var>stream</var>, <var>underlyingSource</var>, <var>size</var>,
<var>highWaterMark</var>)</h4>

<div class="note">
  The <code>ReadableStreamDefaultController</code> constructor cannot be used directly; it only works on a
  {{ReadableStream}} that is in the middle of being constructed.
</div>

<emu-alg>
  1. If ! IsReadableStream(_stream_) is *false*, throw a *TypeError* exception.
  1. If _stream_.[[readableStreamController]] is not *undefined*, throw a *TypeError* exception.
  1. Set *this*.[[controlledReadableStream]] to _stream_.
  1. Set *this*.[[underlyingSource]] to _underlyingSource_.
  1. Perform ! ResetQueue(*this*).
  1. Set *this*.[[started]], *this*.[[closeRequested]], *this*.[[pullAgain]], and *this*.[[pulling]] to *false*.
  1. Let _normalizedStrategy_ be ? ValidateAndNormalizeQueuingStrategy(_size_, _highWaterMark_).
  1. Set *this*.[[strategySize]] to _normalizedStrategy_.[[size]] and *this*.[[strategyHWM]] to
     _normalizedStrategy_.[[highWaterMark]].
  1. Let _controller_ be *this*.
  1. Let _startResult_ be ? InvokeOrNoop(_underlyingSource_, `"start"`, « *this* »).
  1. Let _startPromise_ be <a>a promise resolved with</a> _startResult_:
    1. <a>Upon fulfillment</a>  of _startPromise_,
      1. Set _controller_.[[started]] to *true*.
      1. Assert: _controller_.[[pulling]] is *false*.
      1. Assert: _controller_.[[pullAgain]] is *false*.
      1. Perform ! ReadableStreamDefaultControllerCallPullIfNeeded(_controller_).
    1. <a>Upon rejection</a> of _startPromise_ with reason _r_,
      1. Perform ! ReadableStreamDefaultControllerErrorIfNeeded(_controller_, _r_).
</emu-alg>

<h4 id="rs-default-controller-prototype">Properties of the {{ReadableStreamDefaultController}} Prototype</h4>

<h5 id="rs-default-controller-desired-size" attribute for="ReadableStreamDefaultController" lt="desiredSize">get
desiredSize</h5>

<div class="note">
  The <code>desiredSize</code> getter returns the <a lt="desired size to fill a stream's internal queue">desired size
  to fill the controlled stream's internal queue</a>. It can be negative, if the queue is over-full. An <a>underlying
  source</a> should use this information to determine when and how to apply <a>backpressure</a>.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultController(*this*) is *false*, throw a *TypeError* exception.
  1. Return ! ReadableStreamDefaultControllerGetDesiredSize(*this*).
</emu-alg>

<h5 id="rs-default-controller-close" method for="ReadableStreamDefaultController">close()</h5>

<div class="note">
  The <code>close</code> method will close the controlled readable stream. <a>Consumers</a> will still be able to read
  any previously-enqueued <a>chunks</a> from the stream, but once those are read, the stream will become closed.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultController(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[closeRequested]] is *true*, throw a *TypeError* exception.
  1. If *this*.[[controlledReadableStream]].[[state]] is not `"readable"`, throw a *TypeError* exception.
  1. Perform ! ReadableStreamDefaultControllerClose(*this*).
</emu-alg>

<h5 id="rs-default-controller-enqueue" method for="ReadableStreamDefaultController">enqueue(<var>chunk</var>)</h5>

<div class="note">
  The <code>enqueue</code> method will enqueue a given <a>chunk</a> in the controlled readable stream.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultController(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[closeRequested]] is *true*, throw a *TypeError* exception.
  1. If *this*.[[controlledReadableStream]].[[state]] is not `"readable"`, throw a *TypeError* exception.
  1. Return ? ReadableStreamDefaultControllerEnqueue(*this*, _chunk_).
</emu-alg>

<h5 id="rs-default-controller-error" method for="ReadableStreamDefaultController">error(<var>e</var>)</h5>

<div class="note">
  The <code>error</code> method will error the readable stream, making all future interactions with it fail with the
  given error <code>e</code>.
</div>

<emu-alg>
  1. If ! IsReadableStreamDefaultController(*this*) is *false*, throw a *TypeError* exception.
  1. Let _stream_ be *this*.[[controlledReadableStream]].
  1. If _stream_.[[state]] is not `"readable"`, throw a *TypeError* exception.
  1. Perform ! ReadableStreamDefaultControllerError(*this*, _e_).
</emu-alg>

<h4 id="rs-default-controller-internal-methods">Readable Stream Default Controller Internal Methods</h4>

The following are additional internal methods implemented by each {{ReadableStreamDefaultController}} instance. The
readable stream implementation will polymorphically call to either these or their counterparts for BYOB controllers.

<h5 id="rs-default-controller-private-cancel">\[[CancelSteps]](<var>reason</var>)</h5>

<emu-alg>
  1. Perform ! ResetQueue(*this*).
  1. Return ! PromiseInvokeOrNoop(*this*.[[underlyingSource]], `"cancel"`, « _reason_ »)
</emu-alg>

<h5 id="rs-default-controller-private-pull">\[[PullSteps]]()</h5>

<emu-alg>
  1. Let _stream_ be *this*.[[controlledReadableStream]].
  1. If *this*.[[queue]] is not empty,
    1. Let _chunk_ be ! DequeueValue(*this*).
    1. If *this*.[[closeRequested]] is *true* and *this*.[[queue]] is empty, perform ! ReadableStreamClose(_stream_).
    1. Otherwise, perform ! ReadableStreamDefaultControllerCallPullIfNeeded(*this*).
    1. Return <a>a promise resolved with</a> ! CreateIterResultObject(_chunk_, *false*).
  1. Let _pendingPromise_ be ! ReadableStreamAddReadRequest(_stream_).
  1. Perform ! ReadableStreamDefaultControllerCallPullIfNeeded(*this*).
  1. Return _pendingPromise_.
</emu-alg>

<h3 id="rs-default-controller-abstract-ops">Readable Stream Default Controller Abstract Operations</h3>

<h4 id="is-readable-stream-default-controller" aoid="IsReadableStreamDefaultController"
nothrow>IsReadableStreamDefaultController ( <var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have an [[underlyingSource]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="readable-stream-default-controller-call-pull-if-needed" aoid="ReadableStreamDefaultControllerCallPullIfNeeded"
nothrow>ReadableStreamDefaultControllerCallPullIfNeeded ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _shouldPull_ be ! ReadableStreamDefaultControllerShouldCallPull(_controller_).
  1. If _shouldPull_ is *false*, return.
  1. If _controller_.[[pulling]] is *true*,
    1. Set _controller_.[[pullAgain]] to *true*.
    1. Return.
  1. Assert: _controller_.[[pullAgain]] is *false*.
  1. Set _controller_.[[pulling]] to *true*.
  1. Let _pullPromise_ be ! PromiseInvokeOrNoop(_controller_.[[underlyingSource]], `"pull"`, « _controller_ »).
  1. <a>Upon fulfillment</a> of _pullPromise_,
    1. Set _controller_.[[pulling]] to *false*.
    1. If _controller_.[[pullAgain]] is *true*,
      1. Set _controller_.[[pullAgain]] to *false*.
      1. Perform ! ReadableStreamDefaultControllerCallPullIfNeeded(_controller_).
  1. <a>Upon rejection</a> of _pullPromise_ with reason _e_,
    1. Perform ! ReadableStreamDefaultControllerErrorIfNeeded(_controller_, _e_).
</emu-alg>

<h4 id="readable-stream-default-controller-should-call-pull" aoid="ReadableStreamDefaultControllerShouldCallPull"
nothrow>ReadableStreamDefaultControllerShouldCallPull ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. If _stream_.[[state]] is `"closed"` or _stream_.[[state]] is `"errored"`, return *false*.
  1. If _controller_.[[closeRequested]] is *true*, return *false*.
  1. If _controller_.[[started]] is *false*, return *false*.
  1. If ! IsReadableStreamLocked(_stream_) is *true* and ! ReadableStreamGetNumReadRequests(_stream_) > *0*, return
     *true*.
  1. Let _desiredSize_ be ReadableStreamDefaultControllerGetDesiredSize(_controller_).
  1. If _desiredSize_ > *0*, return *true*.
  1. Return *false*.
</emu-alg>

<h4 id="readable-stream-default-controller-close" aoid="ReadableStreamDefaultControllerClose" nothrow
export>ReadableStreamDefaultControllerClose ( <var>controller</var> )</h4>

This abstract operation can be called by other specifications that wish to close a readable stream, in the same way
a developer-created stream would be closed by its associated controller object. Specifications should <em>not</em> do
this to streams they did not create, and must ensure they have obeyed the preconditions (listed here as asserts).

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Assert: _controller_.[[closeRequested]] is *false*.
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Set _controller_.[[closeRequested]] to *true*.
  1. If _controller_.[[queue]] is empty, perform ! ReadableStreamClose(_stream_).
</emu-alg>

<h4 id="readable-stream-default-controller-enqueue" aoid="ReadableStreamDefaultControllerEnqueue" throws
export>ReadableStreamDefaultControllerEnqueue ( <var>controller</var>, <var>chunk</var> )</h4>

This abstract operation can be called by other specifications that wish to enqueue <a>chunks</a> in a readable stream,
in the same way a developer would enqueue chunks using the stream's associated controller object. Specifications should
<em>not</em> do this to streams they did not create, and must ensure they have obeyed the preconditions (listed here as
asserts).

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Assert: _controller_.[[closeRequested]] is *false*.
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. If ! IsReadableStreamLocked(_stream_) is *true* and ! ReadableStreamGetNumReadRequests(_stream_) > *0*, perform
     ! ReadableStreamFulfillReadRequest(_stream_, _chunk_, *false*).
  1. Otherwise,
    1. Let _chunkSize_ be *1*.
    1. If _controller_.[[strategySize]] is not *undefined*,
      1. Set _chunkSize_ to Call(_controller_.[[strategySize]], *undefined*, « _chunk_ »).
      1. If _chunkSize_ is an abrupt completion,
        1. Perform ! ReadableStreamDefaultControllerErrorIfNeeded(_controller_, _chunkSize_.[[Value]]).
        1. Return _chunkSize_.
      1. Let _chunkSize_ be _chunkSize_.[[Value]].
    1. Let _enqueueResult_ be ! EnqueueValueWithSize(_controller_, _chunk_, _chunkSize_).
    1. If _enqueueResult_ is an abrupt completion,
      1. Perform ! ReadableStreamDefaultControllerErrorIfNeeded(_controller_, _enqueueResult_.[[Value]]).
      1. Return _enqueueResult_.
  1. Perform ! ReadableStreamDefaultControllerCallPullIfNeeded(_controller_).
</emu-alg>

<div class="note">
  The case where <var>stream</var>.\[[state]] is <code>"closed"</code>, but <var>stream</var>.\[[closeRequested]]
  is <emu-val>false</emu-val>, will happen if the stream was closed without its controller's close method ever being
  called: i.e., if the stream was closed by a call to {{ReadableStream/cancel(reason)}}. In this case we allow the
  controller's <code>enqueue</code> method to be called and silently do nothing, since the cancelation was outside the
  control of the underlying source.
</div>

<h4 id="readable-stream-default-controller-error" aoid="ReadableStreamDefaultControllerError" nothrow
export>ReadableStreamDefaultControllerError ( <var>controller</var>, <var>e</var> )</h4>

This abstract operation can be called by other specifications that wish to move a readable stream to an errored state,
in the same way a developer would error a stream using its associated controller object. Specifications should
<em>not</em> do this to streams they did not create, and must ensure they have obeyed the precondition (listed here as
an assert).

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Perform ! ResetQueue(_controller_).
  1. Perform ! ReadableStreamError(_stream_, _e_).
</emu-alg>

<h4 id="readable-stream-default-controller-error-if-needed" aoid="ReadableStreamDefaultControllerErrorIfNeeded"
nothrow>ReadableStreamDefaultControllerErrorIfNeeded ( <var>controller</var>, <var>e</var> )</h4>

<emu-alg>
  1. If _controller_.[[controlledReadableStream]].[[state]] is `"readable"`, perform !
     ReadableStreamDefaultControllerError(_controller_, _e_).
</emu-alg>

<h4 id="readable-stream-default-controller-get-desired-size" aoid="ReadableStreamDefaultControllerGetDesiredSize"
nothrow export>ReadableStreamDefaultControllerGetDesiredSize ( <var>controller</var> )</h4>

This abstract operation can be called by other specifications that wish to determine the <a lt="desired size to fill a
stream's internal queue">desired size to fill this stream's internal queue</a>, similar to how a developer would consult
the {{ReadableStreamDefaultController/desiredSize}} property of the stream's associated controller object.
Specifications should <em>not</em> use this on streams they did not create.

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"errored"`, return *null*.
  1. If _state_ is `"closed"`, return *0*.
  1. Return _controller_.[[strategyHWM]] − _controller_.[[queueTotalSize]].
</emu-alg>

<h3 id="rbs-controller-class" interface lt="ReadableByteStreamController">Class
<code>ReadableByteStreamController</code></h3>

The {{ReadableByteStreamController}} class has methods that allow control of a {{ReadableStream}}'s state and
<a>internal queue</a>. When constructing a {{ReadableStream}}, the <a>underlying byte source</a> is given a
corresponding {{ReadableByteStreamController}} instance to manipulate.

<h4 id="rbs-controller-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{ReadableByteStreamController}} class in something close to the syntax of [[!ECMASCRIPT]], it
would look like

<pre><code class="lang-javascript">
  class ReadableByteStreamController {
    constructor(stream, underlyingByteSource, highWaterMark)

    get byobRequest()
    get desiredSize()

    close()
    enqueue(chunk)
    error(e)
  }
</code></pre>

<h4 id="rbs-controller-internal-slots">Internal Slots</h4>

Instances of {{ReadableByteStreamController}} 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>\[[autoAllocateChunkSize]]
    <td>A positive integer, when the automatic buffer allocation feature is enabled. In that case, this value
      specifies the size of buffer to allocate. It is <emu-val>undefined</emu-val> otherwise.
  </tr>
  <tr>
    <td>\[[closeRequested]]
    <td>A boolean flag indicating whether the stream has been closed by its <a>underlying byte source</a>, but still has
      <a>chunks</a> in its internal queue that have not yet been read
  </tr>
  <tr>
    <td>\[[controlledReadableStream]]
    <td>The {{ReadableStream}} instance controlled
  </tr>
  <tr>
    <td>\[[pullAgain]]
    <td>A boolean flag set to <emu-val>true</emu-val> if the stream's mechanisms requested a call to the
      <a>underlying byte source</a>'s <code>pull</code> method to pull more data, but the pull could not yet be done
      since a previous call is still executing
  </tr>
  <tr>
    <td>\[[pulling]]
    <td>A boolean flag set to <emu-val>true</emu-val> while the <a>underlying byte source</a>'s <code>pull</code>
      method is executing and has not yet fulfilled, used to prevent reentrant calls
  </tr>
  <tr>
    <td>\[[byobRequest]]
    <td>A {{ReadableStreamBYOBRequest}} instance representing the current BYOB pull request
  </tr>
  <tr>
    <td>\[[pendingPullIntos]]
    <td>A List of descriptors representing pending BYOB pull requests
  </tr>
  <tr>
    <td>\[[queue]]
    <td>A List representing the stream's internal queue of <a>chunks</a>
  </tr>
  <tr>
    <td>\[[queueTotalSize]]
    <td>The total size (in bytes) of all the chunks stored in \[[queue]]
  </tr>
  <tr>
    <td>\[[started]]
    <td>A boolean flag indicating whether the <a>underlying source</a> has finished starting
  </tr>
  <tr>
    <td>\[[strategyHWM]]
    <td>A number supplied to the constructor as part of the stream's <a>queuing strategy</a>, indicating the point at
      which the stream will apply <a>backpressure</a> to its <a>underlying byte source</a>
  </tr>
  <tr>
    <td>\[[underlyingByteSource]]
    <td>An object representation of the stream's <a>underlying byte source</a>;
      also used for the <a href="#is-readable-byte-stream-controller">IsReadableByteStreamController</a> brand check
  </tr>
</table>

<div class="note">
  <p>Although {{ReadableByteStreamController}} instances have \[[queue]] and \[[queueTotalSize]] slots, we do not use
  most of the abstract operations in [[#queue-with-sizes]] on them, as the way in which we manipulate this queue is
  rather different than the others in the spec. Instead, we update the two slots together manually.</p>

  <p>This might be cleaned up in a future spec refactoring.</p>
</div>

<h4 id="rbs-controller-constructor" constructor for="ReadableByteStreamController"
lt="ReadableByteStreamController(stream, underlyingByteSource, highWaterMark)">new
ReadableByteStreamController(<var>stream</var>, <var>underlyingByteSource</var>, <var>highWaterMark</var>)</h4>

<div class="note">
  The <code>ReadableByteStreamController</code> constructor cannot be used directly; it only works on a
  {{ReadableStream}} that is in the middle of being constructed.
</div>

<emu-alg>
  1. If ! IsReadableStream(_stream_) is *false*, throw a *TypeError* exception.
  1. If _stream_.[[readableStreamController]] is not *undefined*, throw a *TypeError* exception.
  1. Set *this*.[[controlledReadableStream]] to _stream_.
  1. Set *this*.[[underlyingByteSource]] to _underlyingByteSource_.
  1. Set *this*.[[pullAgain]], and *this*.[[pulling]] to *false*.
  1. Perform ! ReadableByteStreamControllerClearPendingPullIntos(*this*).
  1. Perform ! ResetQueue(*this*).
  1. Set *this*.[[started]] and *this*.[[closeRequested]] to *false*.
  1. Set *this*.[[strategyHWM]] to ? ValidateAndNormalizeHighWaterMark(_highWaterMark_).
  1. Let _autoAllocateChunkSize_ be ? GetV(_underlyingByteSource_, `"autoAllocateChunkSize"`).
  1. If _autoAllocateChunkSize_ is not *undefined*,
    1. If ! IsInteger(_autoAllocateChunkSize_) is *false*, or if _autoAllocateChunkSize_ ≤ *0*, throw a *RangeError* exception.
  1. Set *this*.[[autoAllocateChunkSize]] to _autoAllocateChunkSize_.
  1. Set *this*.[[pendingPullIntos]] to a new empty List.
  1. Let _controller_ be *this*.
  1. Let _startResult_ be ? InvokeOrNoop(_underlyingByteSource_, `"start"`, « *this* »).
  1. Let _startPromise_ be <a>a promise resolved with</a> _startResult_:
    1. <a>Upon fulfillment</a>  of _startPromise_,
      1. Set _controller_.[[started]] to *true*.
      1. Assert: _controller_.[[pulling]] is *false*.
      1. Assert: _controller_.[[pullAgain]] is *false*.
      1. Perform ! ReadableByteStreamControllerCallPullIfNeeded(_controller_).
    1. <a>Upon rejection</a> of _startPromise_ with reason _r_,
      1. If _stream_.[[state]] is `"readable"`, perform ! ReadableByteStreamControllerError(_controller_, _r_).
</emu-alg>

<h4 id="rbs-controller-prototype">Properties of the {{ReadableByteStreamController}} Prototype</h4>

<h5 id="rbs-controller-byob-request" attribute for="ReadableByteStreamController" lt="byobRequest">get byobRequest</h5>

<div class="note">
  The <code>byobRequest</code> getter returns the current BYOB pull request.
</div>

<emu-alg>
  1. If IsReadableByteStreamController(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[byobRequest]] is *undefined* and *this*.[[pendingPullIntos]] is not empty,
    1. Let _firstDescriptor_ be the first element of *this*.[[pendingPullIntos]].
    1. Let _view_ be ! Construct(<a idl>%Uint8Array%</a>, « _firstDescriptor_.[[buffer]],
       _firstDescriptor_.[[byteOffset]] + _firstDescriptor_.[[bytesFilled]], _firstDescriptor_.[[byteLength]] −
       _firstDescriptor_.[[bytesFilled]] »).
    1. Set *this*.[[byobRequest]] to ! Construct(`<a idl>ReadableStreamBYOBRequest</a>`, « *this*, _view_ »).
  1. Return *this*.[[byobRequest]].
</emu-alg>

<h5 id="rbs-controller-desired-size" attribute for="ReadableByteStreamController" lt="desiredSize">get desiredSize</h5>

<div class="note">
  The <code>desiredSize</code> getter returns the <a lt="desired size to fill a stream's internal queue">desired size
  to fill the controlled stream's internal queue</a>. It can be negative, if the queue is over-full. An <a>underlying
  source</a> should use this information to determine when and how to apply <a>backpressure</a>.
</div>

<emu-alg>
  1. If ! IsReadableByteStreamController(*this*) is *false*, throw a *TypeError* exception.
  1. Return ! ReadableByteStreamControllerGetDesiredSize(*this*).
</emu-alg>

<h5 id="rbs-controller-close" method for="ReadableByteStreamController">close()</h5>

<div class="note">
  The <code>close</code> method will close the controlled readable stream. <a>Consumers</a> will still be able to read
  any previously-enqueued <a>chunks</a> from the stream, but once those are read, the stream will become closed.
</div>

<emu-alg>
  1. If ! IsReadableByteStreamController(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[closeRequested]] is *true*, throw a *TypeError* exception.
  1. If *this*.[[controlledReadableStream]].[[state]] is not `"readable"`, throw a *TypeError* exception.
  1. Perform ? ReadableByteStreamControllerClose(*this*).
</emu-alg>

<h5 id="rbs-controller-enqueue" method for="ReadableByteStreamController">enqueue(<var>chunk</var>)</h5>

<div class="note">
  The <code>enqueue</code> method will enqueue a given <a>chunk</a> in the controlled readable stream.
</div>

<emu-alg>
  1. If ! IsReadableByteStreamController(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[closeRequested]] is *true*, throw a *TypeError* exception.
  1. If *this*.[[controlledReadableStream]].[[state]] is not `"readable"`, throw a *TypeError* exception.
  1. If Type(_chunk_) is not Object, throw a *TypeError* exception.
  1. If _chunk_ does not have a [[ViewedArrayBuffer]] internal slot, throw a *TypeError* exception.
  1. Return ! ReadableByteStreamControllerEnqueue(*this*, _chunk_).
</emu-alg>

<h5 id="rbs-controller-error" method for="ReadableByteStreamController">error(<var>e</var>)</h5>

<div class="note">
  The <code>error</code> method will error the readable stream, making all future interactions with it fail with the
  given error <code>e</code>.
</div>

<emu-alg>
  1. If ! IsReadableByteStreamController(*this*) is *false*, throw a *TypeError* exception.
  1. Let _stream_ be *this*.[[controlledReadableStream]].
  1. If _stream_.[[state]] is not `"readable"`, throw a *TypeError* exception.
  1. Perform ! ReadableByteStreamControllerError(*this*, _e_).
</emu-alg>

<h4 id="rbs-controller-internal-methods">Readable Stream BYOB Controller Internal Methods</h4>

The following are additional internal methods implemented by each {{ReadableByteStreamController}} instance. The
readable stream implementation will polymorphically call to either these or their counterparts for default controllers.

<h5 id="rbs-controller-private-cancel">\[[CancelSteps]](<var>reason</var>)</h5>

<emu-alg>
  1. If *this*.[[pendingPullIntos]] is not empty,
    1. Let _firstDescriptor_ be the first element of *this*.[[pendingPullIntos]].
    1. Set _firstDescriptor_.[[bytesFilled]] to *0*.
  1. Perform ! ResetQueue(*this*).
  1. Return ! PromiseInvokeOrNoop(*this*.[[underlyingByteSource]], `"cancel"`, « _reason_ »)
</emu-alg>

<h5 id="rbs-controller-private-pull">\[[PullSteps]]()</h5>

<emu-alg>
  1. Let _stream_ be *this*.[[controlledReadableStream]].
  1. Assert: ! ReadableStreamHasDefaultReader(_stream_) is *true*.
  1. If *this*.[[queueTotalSize]] > *0*,
    1. Assert: ! ReadableStreamGetNumReadRequests(_stream_) is *0*.
    1. Let _entry_ be the first element of *this*.[[queue]].
    1. Remove _entry_ from *this*.[[queue]], shifting all other elements downward (so that the second becomes the
       first, and so on).
    1. Set *this*.[[queueTotalSize]] to *this*.[[queueTotalSize]] − _entry_.[[byteLength]].
    1. Perform ! ReadableByteStreamControllerHandleQueueDrain(*this*).
    1. Let _view_ be ! Construct(<a idl>%Uint8Array%</a>, « _entry_.[[buffer]], _entry_.[[byteOffset]],
       _entry_.[[byteLength]] »).
    1. Return <a>a promise resolved with</a> ! CreateIterResultObject(_view_, *false*).
  1. Let _autoAllocateChunkSize_ be *this*.[[autoAllocateChunkSize]].
  1. If _autoAllocateChunkSize_ is not *undefined*,
    1. Let _buffer_ be Construct(%ArrayBuffer%, « _autoAllocateChunkSize_ »).
    1. If _buffer_ is an abrupt completion, return <a>a promise rejected with</a> _buffer_.[[Value]].
    1. Let _pullIntoDescriptor_ be Record {[[buffer]]: _buffer_.[[Value]], [[byteOffset]]: *0*, [[byteLength]]:
       _autoAllocateChunkSize_, [[bytesFilled]]: *0*, [[elementSize]]: *1*, [[ctor]]: <a idl>%Uint8Array%</a>,
       [[readerType]]: `"default"`}.
    1. Append _pullIntoDescriptor_ as the last element of *this*.[[pendingPullIntos]].
  1. Let _promise_ be ! ReadableStreamAddReadRequest(_stream_).
  1. Perform ! ReadableByteStreamControllerCallPullIfNeeded(*this*).
  1. Return _promise_.
</emu-alg>

<h3 id="rs-byob-request-class" interface lt="ReadableStreamBYOBRequest">Class
<code>ReadableStreamBYOBRequest</code></h3>

The {{ReadableStreamBYOBRequest}} class represents a pull into request in a {{ReadableByteStreamController}}.

<h4 id="rs-byob-request-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{ReadableStreamBYOBRequest}} class in something close to the syntax of [[!ECMASCRIPT]], it
would look like

<pre><code class="lang-javascript">
  class ReadableStreamBYOBRequest {
    constructor(controller, view)

    get view()

    respond(bytesWritten)
    respondWithNewView(view)
  }
</code></pre>

<h4 id="rs-byob-request-internal-slots">Internal Slots</h4>

Instances of {{ReadableStreamBYOBRequest}} 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>\[[associatedReadableByteStreamController]]
    <td>The parent {{ReadableByteStreamController}} instance
  </tr>
  <tr>
    <td>\[[view]]
    <td>A <a>typed array</a> representing the destination region to which the controller may write generated data
  </tr>
</table>

<h4 id="rs-byob-request-constructor" constructor for="ReadableStreamBYOBRequest"
lt="ReadableStreamBYOBRequest(controller, view)">new
ReadableStreamBYOBRequest(<var>controller</var>, <var>view</var>)</h4>

<emu-alg>
  1. Set *this*.[[associatedReadableByteStreamController]] to _controller_.
  1. Set *this*.[[view]] to _view_.
</emu-alg>

<h4 id="rs-byob-request-prototype">Properties of the {{ReadableStreamBYOBRequest}} Prototype</h4>

<h5 id="rs-byob-request-view" attribute for="ReadableStreamBYOBRequest" lt="view">get view</h5>

<emu-alg>
  1. If ! IsReadableStreamBYOBRequest(*this*) is *false*, throw a *TypeError* exception.
  1. Return *this*.[[view]].
</emu-alg>

<h5 id="rs-byob-request-respond" method for="ReadableStreamBYOBRequest">respond(<var>bytesWritten</var>)</h5>

<emu-alg>
  1. If ! IsReadableStreamBYOBRequest(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[associatedReadableByteStreamController]] is *undefined*, throw a *TypeError* exception.
  1. Return ? ReadableByteStreamControllerRespond(*this*.[[associatedReadableByteStreamController]], _bytesWritten_).
</emu-alg>

<h5 id="rs-byob-request-respond-with-new-view" method
for="ReadableStreamBYOBRequest">respondWithNewView(<var>view</var>)</h5>

<emu-alg>
  1. If ! IsReadableStreamBYOBRequest(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[associatedReadableByteStreamController]] is *undefined*, throw a *TypeError* exception.
  1. If Type(_view_) is not Object, throw a *TypeError* exception.
  1. If _view_ does not have a [[ViewedArrayBuffer]] internal slot, throw a *TypeError* exception.
  1. Return ? ReadableByteStreamControllerRespondWithNewView(*this*.[[associatedReadableByteStreamController]], _view_).
</emu-alg>

<h3 id="rbs-controller-abstract-ops">Readable Stream BYOB Controller Abstract Operations</h3>

<h4 id="is-readable-stream-byob-request" aoid="IsReadableStreamBYOBRequest" nothrow>IsReadableStreamBYOBRequest (
<var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have an [[associatedReadableByteStreamController]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>


<h4 id="is-readable-byte-stream-controller" aoid="IsReadableByteStreamController" nothrow>IsReadableByteStreamController
( <var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have an [[underlyingByteSource]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="readable-byte-stream-controller-call-pull-if-needed" aoid="ReadableByteStreamControllerCallPullIfNeeded"
nothrow>ReadableByteStreamControllerCallPullIfNeeded ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _shouldPull_ be ! ReadableByteStreamControllerShouldCallPull(_controller_).
  1. If _shouldPull_ is *false*, return.
  1. If _controller_.[[pulling]] is *true*,
    1. Set _controller_.[[pullAgain]] to *true*.
    1. Return.
  1. Assert: _controller_.[[pullAgain]] is *false*.
  1. Set _controller_.[[pulling]] to *true*.
  1. Let _pullPromise_ be ! PromiseInvokeOrNoop(_controller_.[[underlyingByteSource]], `"pull"`, « _controller_ »).
  1. <a>Upon fulfillment</a> of _pullPromise_,
    1. Set _controller_.[[pulling]] to *false*.
    1. If _controller_.[[pullAgain]] is *true*,
      1. Set _controller_.[[pullAgain]] to *false*.
      1. Perform ! ReadableByteStreamControllerCallPullIfNeeded(_controller_).
  1. <a>Upon rejection</a> of _pullPromise_ with reason _e_,
    1. If _controller_.[[controlledReadableStream]].[[state]] is `"readable"`, perform
       ! ReadableByteStreamControllerError(_controller_, _e_).
</emu-alg>

<h4 id="readable-byte-stream-controller-clear-pending-pull-intos"
aoid="ReadableByteStreamControllerClearPendingPullIntos" nothrow>ReadableByteStreamControllerClearPendingPullIntos (
<var>controller</var> )</h4>

<emu-alg>
  1. Perform ! ReadableByteStreamControllerInvalidateBYOBRequest(_controller_).
  1. Set _controller_.[[pendingPullIntos]] to a new empty List.
</emu-alg>

<h4 id="readable-byte-stream-controller-close" aoid="ReadableByteStreamControllerClose"
throws>ReadableByteStreamControllerClose ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Assert: _controller_.[[closeRequested]] is *false*.
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. If _controller_.[[queueTotalSize]] > *0*,
    1. Set _controller_.[[closeRequested]] to *true*.
    1. Return.
  1. If _controller_.[[pendingPullIntos]] is not empty,
    1. Let _firstPendingPullInto_ be the first element of _controller_.[[pendingPullIntos]].
    1. If _firstPendingPullInto_.[[bytesFilled]] > *0*,
      1. Let _e_ be a new *TypeError* exception.
      1. Perform ! ReadableByteStreamControllerError(_controller_, _e_).
      1. Throw _e_.
  1. Perform ! ReadableStreamClose(_stream_).
</emu-alg>

<h4 id="readable-byte-stream-controller-commit-pull-into-descriptor"
aoid="ReadableByteStreamControllerCommitPullIntoDescriptor" nothrow>ReadableByteStreamControllerCommitPullIntoDescriptor
( <var>stream</var>, <var>pullIntoDescriptor</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[state]] is not `"errored"`.
  1. Let _done_ be *false*.
  1. If _stream_.[[state]] is `"closed"`,
    1. Assert: _pullIntoDescriptor_.[[bytesFilled]] is *0*.
    1. Set _done_ to *true*.
  1. Let _filledView_ be ! ReadableByteStreamControllerConvertPullIntoDescriptor(_pullIntoDescriptor_).
  1. If _pullIntoDescriptor_.[[readerType]] is `"default"`,
    1. Perform ! ReadableStreamFulfillReadRequest(_stream_, _filledView_, _done_).
  1. Otherwise,
    1. Assert: _pullIntoDescriptor_.[[readerType]] is `"byob"`.
    1. Perform ! ReadableStreamFulfillReadIntoRequest(_stream_, _filledView_, _done_).
</emu-alg>

<h4 id="readable-byte-stream-controller-convert-pull-into-descriptor"
aoid="ReadableByteStreamControllerConvertPullIntoDescriptor"
nothrow>ReadableByteStreamControllerConvertPullIntoDescriptor ( <var>pullIntoDescriptor</var> )</h4>

<emu-alg>
  1. Let _bytesFilled_ be _pullIntoDescriptor_.[[bytesFilled]].
  1. Let _elementSize_ be _pullIntoDescriptor_.[[elementSize]].
  1. Assert: _bytesFilled_ ≤ _pullIntoDescriptor_.[[byteLength]].
  1. Assert: _bytesFilled_ mod _elementSize_ is *0*.
  1. Return ! Construct(_pullIntoDescriptor_.[[ctor]], « _pullIntoDescriptor_.[[buffer]],
     _pullIntoDescriptor_.[[byteOffset]], _bytesFilled_ ÷ _elementSize_ »).
</emu-alg>

<h4 id="readable-byte-stream-controller-enqueue" aoid="ReadableByteStreamControllerEnqueue"
nothrow>ReadableByteStreamControllerEnqueue ( <var>controller</var>, <var>chunk</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Assert: _controller_.[[closeRequested]] is *false*.
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Let _buffer_ be _chunk_.[[ViewedArrayBuffer]].
  1. Let _byteOffset_ be _chunk_.[[ByteOffset]].
  1. Let _byteLength_ be _chunk_.[[ByteLength]].
  1. Let _transferredBuffer_ be ! <a abstract-op>Transfer</a>(_buffer_, the current Realm Record).
  1. If ! ReadableStreamHasDefaultReader(_stream_) is *true*
    1. If ! ReadableStreamGetNumReadRequests(_stream_) is *0*,
      1. Perform ! ReadableByteStreamControllerEnqueueChunkToQueue(_controller_, _transferredBuffer_, _byteOffset_,
         _byteLength_).
    1. Otherwise,
      1. Assert: _controller_.[[queue]] is empty.
      1. Let _transferredView_ be ! Construct(<a idl>%Uint8Array%</a>, « _transferredBuffer_, _byteOffset_,
         _byteLength_ »).
      1. Perform ! ReadableStreamFulfillReadRequest(_stream_, _transferredView_, *false*).
  1. Otherwise, if ! ReadableStreamHasBYOBReader(_stream_) is *true*,
    1. Perform ! ReadableByteStreamControllerEnqueueChunkToQueue(_controller_, _transferredBuffer_, _byteOffset_,
       _byteLength_).
    1. Perform ! ReadableByteStreamControllerProcessPullIntoDescriptorsUsingQueue(_controller_).
  1. Otherwise,
    1. Assert: ! IsReadableStreamLocked(_stream_) is *false*.
    1. Perform ! ReadableByteStreamControllerEnqueueChunkToQueue(_controller_, _transferredBuffer_, _byteOffset_,
       _byteLength_).
</emu-alg>

<h4 id="readable-byte-stream-controller-enqueue-chunk-to-queue" aoid="ReadableByteStreamControllerEnqueueChunkToQueue"
nothrow>ReadableByteStreamControllerEnqueueChunkToQueue ( <var>controller</var>, <var>buffer</var>,
<var>byteOffset</var>, <var>byteLength</var> )</h4>

<emu-alg>
  1. Append Record {[[buffer]]: _buffer_, [[byteOffset]]: _byteOffset_, [[byteLength]]: _byteLength_} as the last
     element of _controller_.[[queue]].
  1. Add _byteLength_ to _controller_.[[queueTotalSize]].
</emu-alg>

<h4 id="readable-byte-stream-controller-error" aoid="ReadableByteStreamControllerError"
nothrow>ReadableByteStreamControllerError ( <var>controller</var>, <var>e</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Assert: _stream_.[[state]] is `"readable"`.
  1. Perform ! ReadableByteStreamControllerClearPendingPullIntos(_controller_).
  1. Perform ! ResetQueue(_controller_).
  1. Perform ! ReadableStreamError(_stream_, _e_).
</emu-alg>

<h4 id="readable-byte-stream-controller-fill-head-pull-into-descriptor"
aoid="ReadableByteStreamControllerFillHeadPullIntoDescriptor"
nothrow>ReadableByteStreamControllerFillHeadPullIntoDescriptor ( <var>controller</var>, <var>size</var>,
<var>pullIntoDescriptor</var> )</h4>

<emu-alg>
  1. Assert: either _controller_.[[pendingPullIntos]] is empty, or the first element of
     _controller_.[[pendingPullIntos]] is _pullIntoDescriptor_.
  1. Perform ! ReadableByteStreamControllerInvalidateBYOBRequest(_controller_).
  1. Set _pullIntoDescriptor_.[[bytesFilled]] to _pullIntoDescriptor_.[[bytesFilled]] + _size_.
</emu-alg>

<h4 id="readable-byte-stream-controller-fill-pull-into-descriptor-from-queue"
aoid="ReadableByteStreamControllerFillPullIntoDescriptorFromQueue"
nothrow>ReadableByteStreamControllerFillPullIntoDescriptorFromQueue ( <var>controller</var>,
<var>pullIntoDescriptor</var> )</h4>

<emu-alg>
  1. Let _elementSize_ be _pullIntoDescriptor_.[[elementSize]].
  1. Let _currentAlignedBytes_ be _pullIntoDescriptor_.[[bytesFilled]] − (_pullIntoDescriptor_.[[bytesFilled]] mod
     _elementSize_).
  1. Let _maxBytesToCopy_ be min(_controller_.[[queueTotalSize]], _pullIntoDescriptor_.[[byteLength]] −
     _pullIntoDescriptor_.[[bytesFilled]]).
  1. Let _maxBytesFilled_ be _pullIntoDescriptor_.[[bytesFilled]] + _maxBytesToCopy_.
  1. Let _maxAlignedBytes_ be _maxBytesFilled_ − (_maxBytesFilled_ mod _elementSize_).
  1. Let _totalBytesToCopyRemaining_ be _maxBytesToCopy_.
  1. Let _ready_ be *false*.
  1. If _maxAlignedBytes_ > _currentAlignedBytes_,
    1. Set _totalBytesToCopyRemaining_ to _maxAlignedBytes_ − _pullIntoDescriptor_.[[bytesFilled]].
    1. Set _ready_ to *true*.
  1. Let _queue_ be _controller_.[[queue]].
  1. Repeat the following steps while _totalBytesToCopyRemaining_ > *0*,
    1. Let _headOfQueue_ be the first element of _queue_.
    1. Let _bytesToCopy_ be min(_totalBytesToCopyRemaining_, _headOfQueue_.[[byteLength]]).
    1. Let _destStart_ be _pullIntoDescriptor_.[[byteOffset]] + _pullIntoDescriptor_.[[bytesFilled]].
    1. Perform ! CopyDataBlockBytes(_headOfQueue_.[[buffer]].[[ArrayBufferData]], _headOfQueue_.[[byteOffset]],
       _pullIntoDescriptor_.[[buffer]].[[ArrayBufferData]], _destStart_, _bytesToCopy_).
    1. If _headOfQueue_.[[byteLength]] is _bytesToCopy_,
      1. Remove the first element of _queue_, shifting all other elements downward (so that the second becomes the
         first, and so on).
    1. Otherwise,
      1. Set _headOfQueue_.[[byteOffset]] to _headOfQueue_.[[byteOffset]] + _bytesToCopy_.
      1. Set _headOfQueue_.[[byteLength]] to _headOfQueue_.[[byteLength]] − _bytesToCopy_.
    1. Set _controller_.[[queueTotalSize]] to _controller_.[[queueTotalSize]] − _bytesToCopy_.
    1. Perform ! ReadableByteStreamControllerFillHeadPullIntoDescriptor(_controller_, _bytesToCopy_,
       _pullIntoDescriptor_).
    1. Set _totalBytesToCopyRemaining_ to _totalBytesToCopyRemaining_ − _bytesToCopy_.
  1. If _ready_ is *false*,
    1. Assert: _controller_.[[queueTotalSize]] is *0*.
    1. Assert: _pullIntoDescriptor_.[[bytesFilled]] > *0*.
    1. Assert: _pullIntoDescriptor_.[[bytesFilled]] < _pullIntoDescriptor_.[[elementSize]].
  1. Return _ready_.
</emu-alg>

<h4 id="readable-byte-stream-controller-get-desired-size" aoid="ReadableByteStreamControllerGetDesiredSize"
nothrow>ReadableByteStreamControllerGetDesiredSize ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"errored"`, return *null*.
  1. If _state_ is `"closed"`, return *0*.
  1. Return _controller_.[[strategyHWM]] − _controller_.[[queueTotalSize]].
</emu-alg>

<h4 id="readable-byte-stream-controller-handle-queue-drain" aoid="ReadableByteStreamControllerHandleQueueDrain"
nothrow>ReadableByteStreamControllerHandleQueueDrain ( <var>controller</var> )</h4>

<emu-alg>
  1. Assert: _controller_.[[controlledReadableStream]].[[state]] is `"readable"`.
  1. If _controller_.[[queueTotalSize]] is *0* and _controller_.[[closeRequested]] is *true*,
    1. Perform ! ReadableStreamClose(_controller_.[[controlledReadableStream]]).
  1. Otherwise,
    1. Perform ! ReadableByteStreamControllerCallPullIfNeeded(_controller_).
</emu-alg>

<h4 id="readable-byte-stream-controller-invalidate-byob-request"
aoid="ReadableByteStreamControllerInvalidateBYOBRequest" nothrow>ReadableByteStreamControllerInvalidateBYOBRequest (
<var>controller</var> )</h4>

<emu-alg>
  1. If _controller_.[[byobRequest]] is *undefined*, return.
  1. Set _controller_.[[byobRequest]].[[associatedReadableByteStreamController]] to *undefined*.
  1. Set _controller_.[[byobRequest]].[[view]] to *undefined*.
  1. Set _controller_.[[byobRequest]] to *undefined*.
</emu-alg>

<h4 id="readable-byte-stream-controller-process-pull-into-descriptors-using-queue"
aoid="ReadableByteStreamControllerProcessPullIntoDescriptorsUsingQueue"
nothrow>ReadableByteStreamControllerProcessPullIntoDescriptorsUsingQueue ( <var>controller</var> )</h4>

<emu-alg>
  1. Assert: _controller_.[[closeRequested]] is *false*.
  1. Repeat the following steps while _controller_.[[pendingPullIntos]] is not empty,
    1. If _controller_.[[queueTotalSize]] is *0*, return.
    1. Let _pullIntoDescriptor_ be the first element of _controller_.[[pendingPullIntos]].
    1. If ! ReadableByteStreamControllerFillPullIntoDescriptorFromQueue(_controller_, _pullIntoDescriptor_) is *true*,
      1. Perform ! ReadableByteStreamControllerShiftPendingPullInto(_controller_).
      1. Perform ! ReadableByteStreamControllerCommitPullIntoDescriptor(_controller_.[[controlledReadableStream]],
         _pullIntoDescriptor_).
</emu-alg>

<h4 id="readable-byte-stream-controller-pull-into" aoid="ReadableByteStreamControllerPullInto"
nothrow>ReadableByteStreamControllerPullInto ( <var>controller</var>, <var>view</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Let _elementSize_ be 1.
  1. Let _ctor_ be %DataView%.
  1. If _view_ has a [[TypedArrayName]] internal slot (i.e., it is not a `<a idl>DataView</a>`),
    1. Set _elementSize_ to the element size specified in <a>the typed array constructors table</a> for
       _view_.[[TypedArrayName]].
    1. Set _ctor_ to the constructor specified in <a>the typed array constructors table</a> for
       _view_.[[TypedArrayName]].
  1. Let _pullIntoDescriptor_ be Record {[[buffer]]: _view_.[[ViewedArrayBuffer]], [[byteOffset]]:
     _view_.[[ByteOffset]], [[byteLength]]: _view_.[[ByteLength]], [[bytesFilled]]: *0*, [[elementSize]]: _elementSize_,
     [[ctor]]: _ctor_, [[readerType]]: `"byob"`}.
  1. If _controller_.[[pendingPullIntos]] is not empty,
    1. Set _pullIntoDescriptor_.[[buffer]] to ! <a abstract-op>Transfer</a>(_pullIntoDescriptor_.[[buffer]], the current
       Realm Record).
    1. Append _pullIntoDescriptor_ as the last element of _controller_.[[pendingPullIntos]].
    1. Return ! ReadableStreamAddReadIntoRequest(_stream_).
  1. If _stream_.[[state]] is `"closed"`,
    1. Let _emptyView_ be ! Construct(_ctor_, « _pullIntoDescriptor_.[[buffer]], _pullIntoDescriptor_.[[byteOffset]], *0* »).
    1. Return <a>a promise resolved with</a> ! CreateIterResultObject(_emptyView_, *true*).
  1. If _controller_.[[queueTotalSize]] > *0*,
    1. If ! ReadableByteStreamControllerFillPullIntoDescriptorFromQueue(_controller_, _pullIntoDescriptor_) is *true*,
      1. Let _filledView_ be ! ReadableByteStreamControllerConvertPullIntoDescriptor(_pullIntoDescriptor_).
      1. Perform ! ReadableByteStreamControllerHandleQueueDrain(_controller_).
      1. Return <a>a promise resolved with</a> ! CreateIterResultObject(_filledView_, *false*).
    1. If _controller_.[[closeRequested]] is *true*,
      1. Let _e_ be a *TypeError* exception.
      1. Perform ! ReadableByteStreamControllerError(_controller_, _e_).
      1. Return <a>a promise rejected with</a> _e_.
  1. Set _pullIntoDescriptor_.[[buffer]] to ! <a abstract-op>Transfer</a>(_pullIntoDescriptor_.[[buffer]], the current
     Realm Record).
  1. Append _pullIntoDescriptor_ as the last element of _controller_.[[pendingPullIntos]].
  1. Let _promise_ be ! ReadableStreamAddReadIntoRequest(_stream_).
  1. Perform ! ReadableByteStreamControllerCallPullIfNeeded(_controller_).
  1. Return _promise_.
</emu-alg>

<h4 id="readable-byte-stream-controller-respond" aoid="ReadableByteStreamControllerRespond"
throws>ReadableByteStreamControllerRespond ( <var>controller</var>, <var>bytesWritten</var> )</h4>

<emu-alg>
  1. Let _bytesWritten_ be ? ToNumber(_bytesWritten_).
  1. If ! IsFiniteNonNegativeNumber(_bytesWritten_) is *false*,
    1. Throw a *RangeError* exception.
  1. Assert: _controller_.[[pendingPullIntos]] is not empty.
  1. Perform ? ReadableByteStreamControllerRespondInternal(_controller_, _bytesWritten_).
</emu-alg>

<h4 id="readable-byte-stream-controller-respond-in-closed-state" aoid="ReadableByteStreamControllerRespondInClosedState"
nothrow>ReadableByteStreamControllerRespondInClosedState ( <var>controller</var>, <var>firstDescriptor</var> )</h4>

<emu-alg>
  1. Set _firstDescriptor_.[[buffer]] to ! <a abstract-op>Transfer</a>(_firstDescriptor_.[[buffer]], the current Realm
     Record).
  1. Assert: _firstDescriptor_.[[bytesFilled]] is *0*.
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. Repeat the following steps while ! ReadableStreamGetNumReadIntoRequests(_stream_) > *0*,
    1. Let _pullIntoDescriptor_ be ! ReadableByteStreamControllerShiftPendingPullInto(_controller_).
    1. Perform ! ReadableByteStreamControllerCommitPullIntoDescriptor(_stream_, _pullIntoDescriptor_).
</emu-alg>

<h4 id="readable-byte-stream-controller-respond-in-readable-state"
aoid="ReadableByteStreamControllerRespondInReadableState" throws>ReadableByteStreamControllerRespondInReadableState (
<var>controller</var>, <var>bytesWritten</var>, <var>pullIntoDescriptor</var> )</h4>

<emu-alg>
  1. If _pullIntoDescriptor_.[[bytesFilled]] + _bytesWritten_ > _pullIntoDescriptor_.[[byteLength]], throw a
     *RangeError* exception.
  1. Perform ! ReadableByteStreamControllerFillHeadPullIntoDescriptor(_controller_, _bytesWritten_,
     _pullIntoDescriptor_).
  1. If _pullIntoDescriptor_.[[bytesFilled]] < _pullIntoDescriptor_.[[elementSize]], return.
  1. Perform ! ReadableByteStreamControllerShiftPendingPullInto(_controller_).
  1. Let _remainderSize_ be _pullIntoDescriptor_.[[bytesFilled]] mod _pullIntoDescriptor_.[[elementSize]].
  1. If _remainderSize_ > *0*,
    1. Let _end_ be _pullIntoDescriptor_.[[byteOffset]] + _pullIntoDescriptor_.[[bytesFilled]].
    1. Let _remainder_ be ? CloneArrayBuffer(_pullIntoDescriptor_.[[buffer]], _end_ − _remainderSize_, _remainderSize_,
       %ArrayBuffer%).
    1. Perform ! ReadableByteStreamControllerEnqueueChunkToQueue(_controller_, _remainder_, *0*,
       _remainder_.[[ByteLength]]).
  1. Set _pullIntoDescriptor_.[[buffer]] to ! <a abstract-op>Transfer</a>(_pullIntoDescriptor_.[[buffer]], the current
     Realm Record).
  1. Set _pullIntoDescriptor_.[[bytesFilled]] to _pullIntoDescriptor_.[[bytesFilled]] − _remainderSize_.
  1. Perform ! ReadableByteStreamControllerCommitPullIntoDescriptor(_controller_.[[controlledReadableStream]],
     _pullIntoDescriptor_).
  1. Perform ! ReadableByteStreamControllerProcessPullIntoDescriptorsUsingQueue(_controller_).
</emu-alg>

<h4 id="readable-byte-stream-controller-respond-internal" aoid="ReadableByteStreamControllerRespondInternal"
throws>ReadableByteStreamControllerRespondInternal ( <var>controller</var>, <var>bytesWritten</var> )</h4>

<emu-alg>
  1. Let _firstDescriptor_ be the first element of _controller_.[[pendingPullIntos]].
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. If _stream_.[[state]] is `"closed"`,
    1. If _bytesWritten_ is not *0*, throw a *TypeError* exception.
    1. Perform ! ReadableByteStreamControllerRespondInClosedState(_controller_, _firstDescriptor_).
  1. Otherwise,
    1. Assert: _stream_.[[state]] is `"readable"`.
    1. Perform ? ReadableByteStreamControllerRespondInReadableState(_controller_, _bytesWritten_, _firstDescriptor_).
</emu-alg>

<h4 id="readable-byte-stream-controller-respond-with-new-view" aoid="ReadableByteStreamControllerRespondWithNewView"
throws>ReadableByteStreamControllerRespondWithNewView ( <var>controller</var>, <var>view</var> )</h4>

<emu-alg>
  1. Assert: _controller_.[[pendingPullIntos]] is not empty.
  1. Let _firstDescriptor_ be the first element of _controller_.[[pendingPullIntos]].
  1. If _firstDescriptor_.[[byteOffset]] + _firstDescriptor_.[[bytesFilled]] is not _view_.[[ByteOffset]], throw a
     *RangeError* exception.
  1. If _firstDescriptor_.[[byteLength]] is not _view_.[[ByteLength]], throw a *RangeError* exception.
  1. Set _firstDescriptor_.[[buffer]] to _view_.[[ViewedArrayBuffer]].
  1. Perform ? ReadableByteStreamControllerRespondInternal(_controller_, _view_.[[ByteLength]]).
</emu-alg>

<h4 id="readable-byte-stream-controller-shift-pending-pull-into" aoid="ReadableByteStreamControllerShiftPendingPullInto"
nothrow>ReadableByteStreamControllerShiftPendingPullInto ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _descriptor_ be the first element of _controller_.[[pendingPullIntos]].
  1. Remove _descriptor_ from _controller_.[[pendingPullIntos]], shifting all other elements downward (so that the
     second becomes the first, and so on).
  1. Perform ! ReadableByteStreamControllerInvalidateBYOBRequest(_controller_).
  1. Return _descriptor_.
</emu-alg>

<h4 id="readable-byte-stream-controller-should-call-pull" aoid="ReadableByteStreamControllerShouldCallPull"
nothrow>ReadableByteStreamControllerShouldCallPull ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledReadableStream]].
  1. If _stream_.[[state]] is not `"readable"`, return *false*.
  1. If _controller_.[[closeRequested]] is *true*, return *false*.
  1. If _controller_.[[started]] is *false*, return *false*.
  1. If ! ReadableStreamHasDefaultReader(_stream_) is *true* and ! ReadableStreamGetNumReadRequests(_stream_) > *0*,
     return *true*.
  1. If ! ReadableStreamHasBYOBReader(_stream_) is *true* and ! ReadableStreamGetNumReadIntoRequests(_stream_) > *0*,
     return *true*.
  1. If ! ReadableByteStreamControllerGetDesiredSize(_controller_) > *0*, return *true*.
  1. Return *false*.
</emu-alg>

<h2 id="ws">Writable Streams</h2>

<div class="warning" id="ws-not-ready-yet">
  The writable stream spec is still stabilizing, although it has recently improved a lot and is more aligned with our
  vision. Still, it is not quite yet ready to ship.
</div>

<h3 id="ws-intro">Using Writable Streams</h3>

<div class="example" id="example-basic-pipe-to-2">
  The usual way to write to a writable stream is to simply <a lt="piping">pipe</a> a <a>readable stream</a> to it.
  This ensures that <a>backpressure</a> is respected, so that if the writable stream's <a>underlying sink</a> is not
  able to accept data as fast as the readable stream can produce it, the readable stream is informed of this and has a
  chance to slow down its data production.

  <pre><code class="lang-javascript">
    readableStream.pipeTo(writableStream)
      .then(() => console.log("All data successfully written!"))
      .catch(e => console.error("Something went wrong!", e));
  </code></pre>
</div>

<div class="example" id="example-manual-write-batch">
  You can also write directly to writable streams by acquiring a <a lt="writable stream writer">writer</a> and using its
  {{WritableStreamDefaultWriter/write()}} and {{WritableStreamDefaultWriter/close()}} methods. Since writable streams
  queue any incoming writes, and take care internally to forward them to the <a>underlying sink</a> in sequence, you can
  indiscriminately write to a writable stream without much ceremony:

  <pre><code class="lang-javascript">
    function writeArrayToStream(array, writableStream) {
      const writer = writableStream.getWriter();
      array.forEach(chunk => writer.write(chunk));

      return writer.close();
    }

    writeArrayToStream([1, 2, 3, 4, 5], writableStream)
      .then(() => console.log("All done!"))
      .catch(e => console.error("Error with the stream: " + e));
  </code></pre>
</div>

<div class="example" id="example-manual-write-with-error-handling">
  In the previous example we only paid attention to the success or failure of the entire stream, by looking at the
  promise returned by its {{WritableStreamDefaultWriter/close()}} method. That promise (which can also be accessed using
  the {{WritableStreamDefaultWriter/closed}} getter) will reject if anything goes wrong with the stream—initializing it,
  writing to it, or closing it. And it will fulfill once the stream is successfully closed. Often this is all you care
  about.

  However, if you care about the success of writing a specific <a>chunk</a>, you can use the promise returned by the
  stream's {{WritableStreamDefaultWriter/write()}} method:

  <pre><code class="lang-javascript">
    writer.write("i am a chunk of data")
      .then(() => console.log("chunk successfully written!"))
      .catch(e => console.error(e));
  </code></pre>

  What "success" means is up to a given stream instance (or more precisely, its <a>underlying sink</a>) to decide. For
  example, for a file stream it could simply mean that the OS has accepted the write, and not necessarily that the
  chunk has been flushed to disk.
</div>

<div class="example" id="example-manual-write-with-backpressure">
  The {{WritableStreamDefaultWriter/desiredSize}} and {{WritableStreamDefaultWriter/ready}} properties of <a>writable
  stream writers</a> allow <a>producers</a> to more precisely respond to flow control signals from the stream, to keep
  memory usage below the stream's specified <a>high water mark</a>. The following example writes an infinite sequence of
  random bytes to a stream, using {{WritableStreamDefaultWriter/desiredSize}} to determine how many bytes to generate at
  a given time, and using {{WritableStreamDefaultWriter/ready}} to wait for the <a>backpressure</a> to subside.

  <pre><code class="lang-javascript">
  async function writeRandomBytesForever(writableStream) {
    const writer = writableStream.getWriter();

    while (true) {
      await writer.ready;

      const bytes = new Uint8Array(writer.desiredSize);
      window.crypto.getRandomValues(bytes);

      await writer.write(bytes);
    }
  }

  writeRandomBytesForever(myWritableStream).catch(e => console.error("Something broke", e));
  </code></pre>
</div>
<h3 id="ws-class" interface lt="WritableStream">Class <code>WritableStream</code></h3>

<h4 id="ws-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{WritableStream}} class in something close to the syntax of [[!ECMASCRIPT]], it would look
like

<pre><code class="lang-javascript">
  class WritableStream {
    constructor(underlyingSink = {}, { size, highWaterMark = 1 } = {})

    get locked()

    abort(reason)
    getWriter()
  }
</code></pre>

<h4 id="ws-internal-slots">Internal Slots</h4>

Instances of {{WritableStream}} 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>\[[backpressure]]
    <td>The backpressure signal set by the controller
  </tr>
  <tr>
    <td>\[[closeRequest]]
    <td>The promise returned from the writer {{WritableStreamDefaultWriter/close()}} method
  </tr>
  <tr>
    <td>\[[inFlightWriteRequest]]
    <td>A slot set to the promise for the current in-flight write operation while the <a>underlying sink</a>'s
      <code>write</code> method is executing and has not yet fulfilled, used to prevent reentrant calls
  </tr>
  <tr>
    <td>\[[inFlightCloseRequest]]
    <td>A slot set to the promise for the current in-flight close operation while the <a>underlying sink</a>'s
      <code>close</code> method is executing and has not yet fulfilled, used to prevent the
      {{WritableStreamDefaultWriter/abort()}} method from interrupting close
  </tr>
  <tr>
    <td>\[[pendingAbortRequest]]
    <td>The promise for a pending abort operation
  </tr>
  <tr>
    <td>\[[state]]
    <td>A string containing the stream's current state, used internally; one of <code>"writable"</code>,
    <code>"closed"</code>, or <code>"errored"</code>
  </tr>
  <tr>
    <td>\[[storedError]]
    <td>A value indicating how the stream failed, to be given as a failure reason or exception when trying to operate
      on the stream while in the <code>"errored"</code> state
  </tr>
  <tr>
    <td>\[[writableStreamController]]
    <td>A {{WritableStreamDefaultController}} created with the ability to control the state and queue of this stream;
    also used for the IsWritableStream brand check
  </tr>
  <tr>
    <td>\[[writer]]
    <td>A {{WritableStreamDefaultWriter}} instance, if the stream is <a>locked to a writer</a>, or
    <emu-val>undefined</emu-val> if it is not
  </tr>
  <tr>
    <td>\[[writeRequests]]
    <td>A List of promises representing the stream's internal queue of write requests not yet processed by the
      <a>underlying sink</a>.
  </tr>
</table>

<p class="note">
  The \[[inFlightCloseRequest]] slot and \[[closeRequest]] slot are mutually exclusive. Similarly, no element will be
  removed from \[[writeRequests]] while \[[inFlightWriteRequest]] is not <code>undefined</code>. Implementations can
  optimize storage for these slots based on these invariants.
</p>

<h4 id="ws-constructor" constructor for="WritableStream" lt="WritableStream(underlyingSink, queuingStrategy)">new
WritableStream(<var>underlyingSink</var> = {}, { <var>size</var>, <var>highWaterMark</var> = 1 } = {})</h4>

<div class="note">
  The <code>underlyingSink</code> object passed to the constructor can implement any of the following methods to govern
  how the constructed stream instance behaves:

  <ul>
    <li> <code>start(controller)</code> is called immediately, and should perform any actions necessary to acquire
      access to the <a>underlying sink</a>. If this process is asynchronous, it can return a promise to signal success
      or failure.
    <li> <code>write(chunk, controller)</code> is called when a new <a>chunk</a> of data is ready to be written to the
      <a>underlying sink</a>. It can return a promise to signal success or failure of the write operation. The stream
      implementation guarantees that this method will be called only after previous writes have succeeded, and never
      after <code>close</code> or <code>abort</code> is called.
    <li> <code>close(controller)</code> is called after the producer signals that they are done writing chunks to the
      stream, and all queued-up writes successfully complete. It should perform any actions necessary to finalize writes
      to the <a>underlying sink</a>, and release access to it. If this process is asynchronous, it can return a promise
      to signal success or failure. The stream implementation guarantees that this method will be called only after all
      queued-up writes have succeeded.
    <li> <code>abort(reason)</code> is called when the producer signals they wish to abruptly close the stream
      and put it in an errored state. It should clean up any held resources, much like <code>close</code>, but perhaps
      with some custom handling. Unlike <code>close</code>, <code>abort</code> will be called even if writes are queued
      up; those <a>chunks</a> will be thrown away. If this process is asynchronous, it can return a promise to signal
      success or failure.
  </ul>

  The <code>controller</code> object passed to <code>start</code>, <code>write</code> and <code>close</code> is an
  instance of {{WritableStreamDefaultController}}, and has the ability to error the stream.

  The constructor also accepts a second argument containing the <a>queuing strategy</a> object with
  two properties: a non-negative number <code>highWaterMark</code>, and a function <code>size(chunk)</code>. The
  supplied <code>strategy</code> could be an instance of the built-in {{CountQueuingStrategy}} or
  {{ByteLengthQueuingStrategy}} classes, or it could be custom. If no strategy is supplied, the default
  behavior will be the same as a {{CountQueuingStrategy}} with a <a>high water mark</a> of 1.
</div>

<emu-alg>
  1. Set *this*.[[state]] to `"writable"`.
  1. Set *this*.[[storedError]], *this*.[[writer]], *this*.[[writableStreamController]],
     *this*.[[inFlightWriteRequest]], *this*.[[closeRequest]], *this*.[[inFlightCloseRequest]] and
     *this*.[[pendingAbortRequest]] to *undefined*.
  1. Set *this*.[[writeRequests]] to a new empty List.
  1. Set *this*.[[backpressure]] to *false*.
  1. Let _type_ be ? GetV(_underlyingSink_, `"type"`).
  1. If _type_ is not *undefined*, throw a *RangeError* exception. <p class="note">This is to allow us to add new
     potential types in the future, without backward-compatibility concerns.</p>
  1. Set *this*.[[writableStreamController]] to ? Construct(`<a idl>WritableStreamDefaultController</a>`, « *this*,
     _underlyingSink_, _size_, _highWaterMark_ »).
  1. Perform ? *this*.[[writableStreamController]].[[StartSteps]]().
</emu-alg>

<h4 id="ws-prototype">Properties of the {{WritableStream}} Prototype</h4>

<h5 id="ws-locked" attribute for="WritableStream" lt="locked">get locked</h5>

<div class="note">
  The <code>locked</code> getter returns whether or not the writable stream is <a>locked to a writer</a>.
</div>

<emu-alg>
  1. If ! IsWritableStream(*this*) is *false*, throw a *TypeError* exception.
  1. Return ! IsWritableStreamLocked(*this*).
</emu-alg>

<h5 id="ws-abort" method for="WritableStream">abort(<var>reason</var>)</h5>

<div class="note">
  The <code>abort</code> method <a lt="abort a writable stream">aborts</a> the stream, signaling that the producer can
  no longer successfully write to the stream and it should be immediately moved to an errored state, with any queued-up
  writes discarded. This will also execute any abort mechanism of the <a>underlying sink</a>.
</div>

<emu-alg>
  1. If ! IsWritableStream(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If ! IsWritableStreamLocked(*this*) is *true*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! WritableStreamAbort(*this*, _reason_).
</emu-alg>

<h5 id="ws-get-writer" method for="WritableStream">getWriter()</h5>

<div class="note">
  The <code>getWriter</code> method creates a <a lt="writable stream writer">writer</a> (an instance of
  {{WritableStreamDefaultWriter}}) and <a lt="locked to a writer">locks</a> the stream to the new writer. While the
  stream is locked, no other writer can be acquired until this one is <a lt="release a write lock">released</a>.

  This functionality is especially useful for creating abstractions that desire the ability to write to a stream without
  interruption or interleaving. By getting a writer for the stream, you can ensure nobody else can write at the same
  time, which would cause the resulting written data to be unpredictable and probably useless.
</div>

<emu-alg>
  1. If ! IsWritableStream(*this*) is *false*, throw a *TypeError* exception.
  1. Return ? AcquireWritableStreamDefaultWriter(*this*).
</emu-alg>

<h3 id="ws-abstract-ops">General Writable Stream Abstract Operations</h3>

The following abstract operations, unlike most in this specification, are meant to be generally useful by other
specifications, instead of just being part of the implementation of this spec's classes.

<h4 id="acquire-writable-stream-default-writer" aoid="AcquireWritableStreamDefaultWriter"
throws>AcquireWritableStreamDefaultWriter ( <var>stream</var> )</h4>

<emu-alg>
  1. Return ? Construct(`<a idl>WritableStreamDefaultWriter</a>`, « _stream_ »).
</emu-alg>

<h4 id="is-writable-stream" aoid="IsWritableStream" nothrow>IsWritableStream ( <var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have a [[writableStreamController]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="is-writable-stream-locked" aoid="IsWritableStreamLocked" nothrow>IsWritableStreamLocked ( <var>stream</var>
)</h4>

This abstract operation is meant to be called from other specifications that may wish to query whether or not a
writable stream is <a>locked to a writer</a>.

<emu-alg>
  1. Assert: ! IsWritableStream(_stream_) is *true*.
  1. If _stream_.[[writer]] is *undefined*, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="writable-stream-abort" aoid="WritableStreamAbort" nothrow>WritableStreamAbort ( <var>stream</var>,
<var>reason</var> )</h4>

<emu-alg>
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"closed"`, return <a>a promise resolved with</a> *undefined*.
  1. If _state_ is `"errored"`, return <a>a promise rejected with</a> _stream_.[[storedError]].
  1. Assert: _state_ is `"writable"`.
  1. Let _error_ be a new *TypeError* indicating that the stream has been requested to abort.
  1. If _stream_.[[pendingAbortRequest]] is not *undefined*, return <a>a promise rejected with</a> _error_.
  1. Let _controller_ be _stream_.[[writableStreamController]].
  1. Assert: _controller_ is not *undefined*.
  1. If ! WritableStreamHasOperationMarkedInFlight(_stream_) is *false* and _controller_.[[started]] is *true*,
    1. Perform ! WritableStreamFinishAbort(_stream_).
    1. Return ! _controller_.[[AbortSteps]](_reason_).
  1. Let _writer_ be _stream_.[[writer]].
  1. If _writer_ is not *undefined*,
    1. Perform ! WritableStreamDefaultWriterEnsureReadyPromiseRejected(_writer_, _error_).
  1. Let _promise_ be <a>a new promise</a>.
  1. Set _stream_.[[pendingAbortRequest]] to Record {[[promise]]: _promise_, [[reason]]: _reason_}.
  1. Return _promise_.
</emu-alg>

<h4 id="writable-stream-error" aoid="WritableStreamError" nothrow>WritableStreamError ( <var>stream</var>,
<var>error</var> )</h4>

<emu-alg>
  1. Set _stream_.[[state]] to `"errored"`.
  1. Set _stream_.[[storedError]] to _error_.
  1. Perform ! _stream_.[[writableStreamController]].[[ErrorSteps]]().
  1. If _stream_.[[pendingAbortRequest]] is *undefined*,
    1. Let _writer_ be _stream_.[[writer]].
    1. If _writer_ is not *undefined*,
      1. Perform ! WritableStreamDefaultWriterEnsureReadyPromiseRejected(_writer_, _error_).
  1. If ! WritableStreamHasOperationMarkedInFlight(_stream_) is *false*, perform !
     WritableStreamRejectPromisesInReactionToError(_stream_).
</emu-alg>

<h4 id="writable-stream-finish-abort" aoid="WritableStreamFinishAbort" nothrow>WritableStreamFinishAbort (
<var>stream</var> )</h4>

<emu-alg>
  1. Let _error_ be a new *TypeError* indicating that the stream has been aborted.
  1. Perform ! WritableStreamRejectPromisesInReactionToError(_stream_).
</emu-alg>

<h3 id="ws-abstract-ops-used-by-controllers">Writable Stream Abstract Operations Used by Controllers</h3>

To allow future flexibility to add different writable stream behaviors (similar to the distinction between simple
readable streams and <a>readable byte streams</a>), much of the internal state of a <a>writable stream</a> is
encapsulated by the {{WritableStreamDefaultController}} class. At this point in time the division of work between the
stream and its controller may seems somewhat arbitrary, but centralizing much of the logic in the controller is a useful
structure for the future.

The abstract operations in this section are interfaces that are used by the controller implementation to affect its
associated {{WritableStream}} object, translating the controller's internal state changes into developer-facing results
visible through the {{WritableStream}}'s public API.

<h4 id="writable-stream-add-write-request" aoid="WritableStreamAddWriteRequest" nothrow>WritableStreamAddWriteRequest (
<var>stream</var> )</h4>

<emu-alg>
  1. Assert: ! IsWritableStreamLocked(_stream_) is *true*.
  1. Assert: _stream_.[[state]] is `"writable"`.
  1. Let _promise_ be <a>a new promise</a>.
  1. Append _promise_ as the last element of _stream_.[[writeRequests]].
  1. Return _promise_.
</emu-alg>

<h4 id="writable-stream-finish-in-flight-write" aoid="WritableStreamFinishInFlightWrite"
nothrow>WritableStreamFinishInFlightWrite ( <var>stream</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[inFlightWriteRequest]] is not *undefined*.
  1. <a>Resolve</a> _stream_.[[inFlightWriteRequest]] with *undefined*.
  1. Set _stream_.[[inFlightWriteRequest]] to *undefined*.
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"errored"`,
    1. Perform ! WritableStreamFinishInFlightWriteInErroredState(_stream_).
    1. Return.
  1. Assert: _state_ is `"writable"`.
  1. Perform ! WritableStreamHandleAbortRequestIfPending(_stream_).
</emu-alg>

<h4 id="writable-stream-finish-in-flight-write-in-errored-state" aoid="WritableStreamFinishInFlightWriteInErroredState"
nothrow>WritableStreamFinishInFlightWriteInErroredState ( <var>stream</var> )</h4>

<emu-alg>
  1. Perform ! WritableStreamRejectAbortRequestIfPending(_stream_).
  1. Perform ! WritableStreamRejectPromisesInReactionToError(_stream_).
</emu-alg>

<h4 id="writable-stream-finish-in-flight-write-with-error" aoid="WritableStreamFinishInFlightWriteWithError"
nothrow>WritableStreamFinishInFlightWriteWithError ( <var>stream</var>, <var>error</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[inFlightWriteRequest]] is not *undefined*.
  1. <a>Reject</a> _stream_.[[inFlightWriteRequest]] with _error_.
  1. Set _stream_.[[inFlightWriteRequest]] to *undefined*.
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"errored"`,
    1. Perform ! WritableStreamFinishInFlightWriteInErroredState(_stream_).
    1. Return.
  1. Assert: _state_ is `"writable"`.
  1. Perform ! WritableStreamError(_stream_, _error_).
  1. Perform ! WritableStreamRejectAbortRequestIfPending(_stream_).
</emu-alg>

<h4 id="writable-stream-finish-in-flight-close" aoid="WritableStreamFinishInFlightClose"
nothrow>WritableStreamFinishInFlightClose ( <var>stream</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[inFlightCloseRequest]] is not *undefined*.
  1. <a>Resolve</a> _stream_.[[inFlightCloseRequest]] with *undefined*.
  1. Set _stream_.[[inFlightCloseRequest]] to *undefined*.
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"errored"`,
    1. Perform ! WritableStreamFinishInFlightCloseInErroredState(_stream_).
    1. Return.
  1. Assert: _state_ is `"writable"`.
  1. Set _stream_.[[state]] to `"closed"`.
  1. Let _writer_ be _stream_.[[writer]].
  1. If _writer_ is not *undefined*, <a>resolve</a> _writer_.[[closedPromise]] with *undefined*.
  1. If _stream_.[[pendingAbortRequest]] is not *undefined*,
    1. <a>Resolve</a> _stream_.[[pendingAbortRequest]] with *undefined*.
    1. Set _stream_.[[pendingAbortRequest]] to *undefined*.
</emu-alg>

<h4 id="writable-stream-finish-in-flight-close-in-errored-state" aoid="WritableStreamFinishInFlightCloseInErroredState"
nothrow>WritableStreamFinishInFlightCloseInErroredState ( <var>stream</var> )</h4>

<emu-alg>
  1. Perform ! WritableStreamRejectAbortRequestIfPending(_stream_).
  1. Perform ! WritableStreamRejectClosedPromiseInReactionToError(_stream_).
</emu-alg>

<h4 id="writable-stream-finish-in-flight-close-with-error" aoid="WritableStreamFinishInFlightCloseWithError"
nothrow>WritableStreamFinishInFlightCloseWithError ( <var>stream</var>, <var>error</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[inFlightCloseRequest]] is not *undefined*.
  1. <a>Reject</a> _stream_.[[inFlightCloseRequest]] with _error_.
  1. Set _stream_.[[inFlightCloseRequest]] to *undefined*.
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"errored"`,
    1. Perform ! WritableStreamFinishInFlightCloseInErroredState(_stream_).
    1. Return.
  1. Assert: _state_ is `"writable"`.
  1. Perform ! WritableStreamError(_stream_, _error_).
  1. Perform ! WritableStreamRejectAbortRequestIfPending(_stream_).
</emu-alg>

<h4 id="writable-stream-close-queued-or-in-flight" aoid="WritableStreamCloseQueuedOrInFlight" nothrow>
WritableStreamCloseQueuedOrInFlight ( <var>stream</var> )</h4>

<emu-alg>
  1. If _stream_.[[closeRequest]] is *undefined* and _stream_.[[inFlightCloseRequest]] is *undefined*, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="writable-stream-handle-abort-request-if-pending" aoid="WritableStreamHandleAbortRequestIfPending"
nothrow>WritableStreamHandleAbortRequestIfPending ( <var>stream</var> )</h4>

<emu-alg>
  1. If _stream_.[[pendingAbortRequest]] is *undefined*, return.
  1. Perform ! WritableStreamFinishAbort(_stream_).
  1. Let _abortRequest_ be _stream_.[[pendingAbortRequest]].
  1. Set _stream_.[[pendingAbortRequest]] to *undefined*.
  1. Let _promise_ be ! _stream_.[[writableStreamController]].[[AbortSteps]](_abortRequest_.[[reason]]).
  1. <a>Upon fulfillment</a> of _promise_ with value _result_, <a>resolve</a> _abortRequest_.[[promise]] with _result_.
  1. <a>Upon rejection</a> of _promise_ with reason _reason_, <a>reject</a> _abortRequest_.[[promise]] with _reason_.
</emu-alg>

<h4 id="writable-stream-has-operation-marked-in-flight" aoid="WritableStreamHasOperationMarkedInFlight"
nothrow>WritableStreamHasOperationMarkedInFlight ( <var>stream</var> )</h4>

<emu-alg>
  1. If _stream_.[[inFlightWriteRequest]] is *undefined* and _controller_.[[inFlightCloseRequest]] is *undefined*, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="writable-stream-mark-close-request-in-flight" aoid="WritableStreamMarkCloseRequestInFlight"
nothrow>WritableStreamMarkCloseRequestInFlight ( <var>stream</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[inFlightCloseRequest]] is *undefined*.
  1. Assert: _stream_.[[closeRequest]] is not *undefined*.
  1. Set _stream_.[[inFlightCloseRequest]] to _stream_.[[closeRequest]].
  1. Set _stream_.[[closeRequest]] to *undefined*.
</emu-alg>

<h4 id="writable-stream-mark-first-write-request-in-flight" aoid="WritableStreamMarkFirstWriteRequestInFlight"
nothrow>WritableStreamMarkFirstWriteRequestInFlight ( <var>stream</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[inFlightWriteRequest]] is *undefined*.
  1. Assert: _stream_.[[writeRequests]] is not empty.
  1. Let _writeRequest_ be the first element of _stream_.[[writeRequests]].
  1. Remove _writeRequest_ from _stream_.[[writeRequests]], shifting all other elements downward (so that the second
     becomes the first, and so on).
  1. Set _stream_.[[inFlightWriteRequest]] to _writeRequest_.
</emu-alg>

<h4 id="writable-stream-reject-closed-promise-in-reaction-to-error"
aoid="WritableStreamRejectClosedPromiseInReactionToError" nothrow>WritableStreamRejectClosedPromiseInReactionToError (
<var>stream</var> )</h4>

<emu-alg>
  1. Let _writer_ be _stream_.[[writer]].
  1. If _writer_ is not *undefined*,
    1. <a>Reject</a> _writer_.[[closedPromise]] with _stream_.[[storedError]].
    1. Set _writer_.[[closedPromise]].[[PromiseIsHandled]] to *true*.
</emu-alg>

<h4 id="writable-stream-reject-abort-request-if-pending" aoid="WritableStreamRejectAbortRequestIfPending"
nothrow>WritableStreamRejectAbortRequestIfPending ( <var>stream</var> )</h4>

<emu-alg>
  1. If _stream_.[[pendingAbortRequest]] is not *undefined*,
    1. <a>Reject</a> _stream_.[[pendingAbortRequest]] with _stream_.[[storedError]].
    1. Set _stream_.[[pendingAbortRequest]] to *undefined*.
</emu-alg>

<h4 id="writable-stream-reject-promises-in-reaction-to-error" aoid="WritableStreamRejectPromisesInReactionToError"
nothrow>WritableStreamRejectPromisesInReactionToError ( <var>stream</var> )</h4>

<emu-alg>
  1. Let _storedError_ be _stream_.[[storedError]].
  1. Repeat for each _writeRequest_ that is an element of _stream_.[[writeRequests]],
    1. <a>Reject</a> _writeRequest_ with _storedError_.
  1. Set _stream_.[[writeRequests]] to an empty List.
  1. If _stream_.[[closeRequest]] is not *undefined*,
    1. Assert: _stream_.[[inFlightCloseRequest]] is *undefined*.
    1. <a>Reject</a> _stream_.[[closeRequest]] with _storedError_.
    1. Set _stream_.[[closeRequest]] to *undefined*.
  1. Perform ! WritableStreamRejectClosedPromiseInReactionToError(_stream_).
</emu-alg>

<h4 id="writable-stream-update-backpressure" aoid="WritableStreamUpdateBackpressure"
nothrow>WritableStreamUpdateBackpressure ( <var>stream</var>, <var>backpressure</var> )</h4>

<emu-alg>
  1. Assert: _stream_.[[state]] is `"writable"`.
  1. Assert: WritableStreamCloseQueuedOrInFlight(_stream_) is *false*.
  1. Let _writer_ be _stream_.[[writer]].
  1. If _writer_ is not *undefined* and _backpressure_ is not _stream_.[[backpressure]],
    1. If _backpressure_ is *true*, set _writer_.[[readyPromise]] to <a>a new promise</a>.
    1. Otherwise,
      1. Assert: _backpressure_ is *false*.
      1. <a>Resolve</a> _writer_.[[readyPromise]] with *undefined*.
  1. Set _stream_.[[backpressure]] to _backpressure_.
</emu-alg>

<h3 id="default-writer-class" interface lt="WritableStreamDefaultWriter">Class
<code>WritableStreamDefaultWriter</code></h3>

The {{WritableStreamDefaultWriter}} class represents a <a>writable stream writer</a> designed to be vended by a
{{WritableStream}} instance.

<h4 id="default-writer-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{WritableStreamDefaultWriter}} class in something close to the syntax of [[!ECMASCRIPT]], it
would look like

<pre><code class="lang-javascript">
  class WritableStreamDefaultWriter {
    constructor(stream)

    get closed()
    get desiredSize()
    get ready()

    abort(reason)
    close()
    releaseLock()
    write(chunk)
  }
</code></pre>

<h4 id="default-writer-internal-slots">Internal Slots</h4>

Instances of {{WritableStreamDefaultWriter}} 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>\[[closedPromise]]
    <td>A promise returned by the writer's {{WritableStreamDefaultWriter/closed}} getter
  </tr>
  <tr>
    <td>\[[ownerWritableStream]]
    <td>A {{WritableStream}} instance that owns this writer
  </tr>
  <tr>
    <td>\[[readyPromise]]
    <td>A promise returned by the writer's {{WritableStreamDefaultWriter/ready}} getter
  </tr>
</table>

<h4 id="default-writer-constructor" constructor for="WritableStreamDefaultWriter"
lt="WritableStreamDefaultWriter(stream)">new WritableStreamDefaultWriter(<var>stream</var>)</h4>

<div class="note">
  The <code>WritableStreamDefaultWriter</code> constructor is generally not meant to be used directly; instead, a
  stream's {{WritableStream/getWriter()}} method should be used.
</div>

<emu-alg>
  1. If ! IsWritableStream(_stream_) is *false*, throw a *TypeError* exception.
  1. If ! IsWritableStreamLocked(_stream_) is *true*, throw a *TypeError* exception.
  1. Set *this*.[[ownerWritableStream]] to _stream_.
  1. Set _stream_.[[writer]] to *this*.
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"writable"`,
    1. If _stream_.[[pendingAbortRequest]] is not *undefined*,
      1. Let _error_ be a new *TypeError* indicating that the stream has been requested to abort.
      1. Set *this*.[[readyPromise]] to <a>a promise rejected with</a> _error_.
      1. Set *this*.[[readyPromise]].[[PromiseIsHandled]] to *true*.
    1. Otherwise, if ! WritableStreamCloseQueuedOrInFlight(_stream_) is *false* and _stream_.[[backpressure]] is *true*,
       set *this*.[[readyPromise]] to <a>a new promise</a>.
    1. Otherwise, set *this*.[[readyPromise]] to <a>a promise resolved with</a> *undefined*.
    1. Set *this*.[[closedPromise]] to <a>a new promise</a>.
  1. Otherwise, if _state_ is `"closed"`,
    1. Set *this*.[[readyPromise]] to <a>a promise resolved with</a> *undefined*.
    1. Set *this*.[[closedPromise]] to <a>a promise resolved with</a> *undefined*.
  1. Otherwise,
    1. Assert: _state_ is `"errored"`.
    1. Let _storedError_ be _stream_.[[storedError]].
    1. Set *this*.[[readyPromise]] to <a>a promise rejected with</a> _storedError_.
    1. Set *this*.[[readyPromise]].[[PromiseIsHandled]] to *true*.
    1. Set *this*.[[closedPromise]] to <a>a promise rejected with</a> _storedError_.
    1. Set *this*.[[closedPromise]].[[PromiseIsHandled]] to *true*.
</emu-alg>

<h4 id="default-writer-prototype">Properties of the {{WritableStreamDefaultWriter}} Prototype</h4>

<h5 id="default-writer-closed" attribute for="WritableStreamDefaultWriter" lt="closed">get closed</h5>

<div class="note">
  The <code>closed</code> getter returns a promise that will be fulfilled when the stream becomes closed, or rejected if
  the stream ever errors or the writer's lock is <a lt="release a write lock">released</a> before the stream finishes
  closing.
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultWriter(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return *this*.[[closedPromise]].
</emu-alg>

<h5 id="default-writer-desiredSize" attribute for="WritableStreamDefaultWriter" lt="desiredSize">get desiredSize</h5>

<div class="note">
  The <code>desiredSize</code> getter returns the <a lt="desired size to fill a stream's internal queue">desired size to
  fill the stream's internal queue</a>. It can be negative, if the queue is over-full. A <a>producer</a> should use this
  information to determine the right amount of data to write.

  It will be <emu-val>null</emu-val> if the stream is errored, or zero if the stream is closed. The getter will throw an
  exception if invoked when the writer's lock is <a lt="release a write lock">released</a>.
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultWriter(*this*) is *false*, throw a *TypeError* exception.
  1. If *this*.[[ownerWritableStream]] is *undefined*, throw a *TypeError* exception.
  1. Return ! WritableStreamDefaultWriterGetDesiredSize(*this*).
</emu-alg>

<h5 id="default-writer-ready" attribute for="WritableStreamDefaultWriter" lt="ready">get ready</h5>

<div class="note">
  The <code>ready</code> getter returns a promise that will be fulfilled when the <a lt="desired size to fill a stream's
  internal queue">desired size to fill the stream's internal queue</a> transitions from nonpositive to positive,
  signaling that it is no longer applying <a>backpressure</a>. Once the <a lt="desired size to fill a stream's internal
  queue">desired size to fill the stream's internal queue</a> dips back to zero or below, the getter will return a new
  promise that stays pending until the next transition.

  If the stream becomes errored, or the writer's lock is <a lt="release a write lock">released</a>, is the returned
  promise will become rejected.
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultWriter(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return *this*.[[readyPromise]].
</emu-alg>

<h5 id="default-writer-abort" method for="WritableStreamDefaultWriter">abort(<var>reason</var>)</h5>

<div class="note">
  If the writer is <a lt="active writer">active</a>, the <code>abort</code> method behaves the same as that for the
  associated stream. (Otherwise, it returns a rejected promise.)
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultWriter(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If *this*.[[ownerWritableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! WritableStreamDefaultWriterAbort(*this*, _reason_).
</emu-alg>

<h5 id="default-writer-close" method for="WritableStreamDefaultWriter">close()</h5>

<div class="note">
  The <code>close</code> method will close the associated writable stream. The <a>underlying sink</a> will finish
  processing any previously-written <a>chunks</a>, before invoking its close behavior. During this time any further
  attempts to write will fail (without erroring the stream).

  The method returns a promise that is fulfilled with <emu-val>undefined</emu-val> if all remaining <a>chunks</a> are
  successfully written and the stream successfully closes, or rejects if an error is encountered during this process.
  (This is the same promise as is returned by {{WritableStreamDefaultWriter/closed}}.)
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultWriter(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Let _stream_ be *this*.[[ownerWritableStream]].
  1. If _stream_ is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If ! WritableStreamCloseQueuedOrInFlight(_stream_) is *true*, return <a>a promise rejected with</a> a *TypeError*
     exception.
  1. Return ! WritableStreamDefaultWriterClose(*this*).
</emu-alg>

<h5 id="default-writer-release-lock" method for="WritableStreamDefaultWriter">releaseLock()</h5>

<div class="note">
  The <code>releaseLock</code> method <a lt="release a write lock">releases the writer's lock</a> on the corresponding
  stream. After the lock is released, the writer is no longer <a lt="active writer">active</a>. If the associated
  stream is errored when the lock is released, the writer will appear errored in the same way from now on; otherwise,
  the writer will appear closed.

  Note that the lock can still be released even if some ongoing writes have not yet finished (i.e. even if the promises
  returned from previous calls to {{WritableStreamDefaultWriter/write()}} have not yet settled). It's not required to
  hold the lock on the writer for the duration of the write; the lock instead simply prevents other <a>producers</a>
  from writing in an interleaved manner.
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultWriter(*this*) is *false*, throw a *TypeError* exception.
  1. Let _stream_ be *this*.[[ownerWritableStream]].
  1. If _stream_ is *undefined*, return.
  1. Assert: _stream_.[[writer]] is not *undefined*.
  1. Perform ! WritableStreamDefaultWriterRelease(*this*).
</emu-alg>

<h5 id="default-writer-write" method for="WritableStreamDefaultWriter">write(<var>chunk</var>)</h5>

<div class="note">
  The <code>write</code> method writes the given <a>chunk</a> to the writable stream, by waiting until any previous
  writes have finished successfully, and then sending the <a>chunk</a> to the <a>underlying sink</a>. It will return a
  promise that fulfills with <emu-val>undefined</emu-val> upon a successful write, or rejects if the write fails or
  stream becomes errored before the writing process is initiated.

  Note that what "success" means is up to the <a>underlying sink</a>; it may indicate simply that the <a>chunk</a> has
  been accepted, and not necessarily that it is safely saved to its ultimate destination.
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultWriter(*this*) is *false*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If *this*.[[ownerWritableStream]] is *undefined*, return <a>a promise rejected with</a> a *TypeError* exception.
  1. Return ! WritableStreamDefaultWriterWrite(*this*, _chunk_).
</emu-alg>

<h3 id="rs-writer-abstract-ops">Writable Stream Writer Abstract Operations</h3>

<h4 id="is-writable-stream-default-writer" aoid="IsWritableStreamDefaultWriter" nothrow>IsWritableStreamDefaultWriter (
<var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have an [[ownerWritableStream]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="writable-stream-default-writer-abort" aoid="WritableStreamDefaultWriterAbort"
nothrow>WritableStreamDefaultWriterAbort ( <var>writer</var>, <var>reason</var> )</h4>

<emu-alg>
  1. Let _stream_ be _writer_.[[ownerWritableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Return ! WritableStreamAbort(_stream_, _reason_).
</emu-alg>

<h4 id="writable-stream-default-writer-close" aoid="WritableStreamDefaultWriterClose"
nothrow>WritableStreamDefaultWriterClose ( <var>writer</var> )</h4>

<emu-alg>
  1. Let _stream_ be _writer_.[[ownerWritableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"closed"` or `"errored"`, return <a>a promise rejected with</a> a *TypeError* exception.
  1. If _stream_.[[pendingAbortRequest]] is not *undefined*, return <a>a promise rejected with</a> a *TypeError*
     indicating that the stream has been requested to abort.
  1. Assert: _state_ is `"writable"`.
  1. Assert: ! WritableStreamCloseQueuedOrInFlight(_stream_) is *false*.
  1. Let _promise_ be <a>a new promise</a>.
  1. Set _stream_.[[closeRequest]] to _promise_.
  1. If _stream_.[[backpressure]] is *true*, <a>resolve</a> _writer_.[[readyPromise]] with *undefined*.
  1. Perform ! WritableStreamDefaultControllerClose(_stream_.[[writableStreamController]]).
  1. Return _promise_.
</emu-alg>

<h4 id="writable-stream-default-writer-close-with-error-propagation" aoid="WritableStreamDefaultWriterCloseWithErrorPropagation"
nothrow>WritableStreamDefaultWriterCloseWithErrorPropagation ( <var>writer</var> )</h4>

<p class="note">This abstract operation helps implement the error propagation semantics of
{{ReadableStream/pipeTo()}}.</p>

<emu-alg>
  1. Let _stream_ be _writer_.[[ownerWritableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Let _state_ be _stream_.[[state]].
  1. If ! WritableStreamCloseQueuedOrInFlight(_stream_) is *true* or _state_ is `"closed"`, return
     <a>a promise resolved with</a> *undefined*.
  1. If _state_ is `"errored"`, return <a>a promise rejected with</a> _stream_.[[storedError]].
  1. Assert: _state_ is `"writable"`.
  1. Return ! WritableStreamDefaultWriterClose(_writer_).
</emu-alg>

<h4 id="writable-stream-default-writer-ensure-ready-promise-rejected"
aoid="WritableStreamDefaultWriterEnsureReadyPromiseRejected"
nothrow>WritableStreamDefaultWriterEnsureReadyPromiseRejected( <var>writer</var>, <var>error</var> )</h4>

<emu-alg>
  1. If _writer_.[[readyPromise]].[[PromiseState]] is `"pending"`, <a>reject</a> _writer.[[readyPromise]] with _error_.
  1. Otherwise, set _writer_.[[readyPromise]] to <a>a promise rejected with</a> _error_.
  1. Set _writer_.[[readyPromise]].[[PromiseIsHandled]] to *true*.
</emu-alg>

<h4 id="writable-stream-default-writer-get-desired-size" aoid="WritableStreamDefaultWriterGetDesiredSize"
nothrow>WritableStreamDefaultWriterGetDesiredSize ( <var>writer</var> )</h4>

<emu-alg>
  1. Let _stream_ be _writer_.[[ownerWritableStream]].
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"errored"` or _stream_.[[pendingAbortRequest]] is not *undefined*, return *null*.
  1. If _state_ is `"closed"`, return *0*.
  1. Return ! WritableStreamDefaultControllerGetDesiredSize(_stream_.[[writableStreamController]]).
</emu-alg>

<h4 id="writable-stream-default-writer-release" aoid="WritableStreamDefaultWriterRelease"
nothrow>WritableStreamDefaultWriterRelease ( <var>writer</var> )</h4>

<emu-alg>
  1. Let _stream_ be _writer_.[[ownerWritableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Assert: _stream_.[[writer]] is _writer_.
  1. Let _releasedError_ be a new *TypeError*.
  1. Let _state_ be _stream_.[[state]].
  1. Perform ! WritableStreamDefaultWriterEnsureReadyPromiseRejected(_writer_, _releasedError_).
  1. If _state_ is `"writable"` or ! WritableStreamHasOperationMarkedInFlight(_stream_) is *true*,
     <a>reject</a> _writer_.[[closedPromise]] with _releasedError_.
  1. Otherwise, set _writer_.[[closedPromise]] to <a>a promise rejected with</a> _releasedError_.
  1. Set _writer_.[[closedPromise]].[[PromiseIsHandled]] to *true*.
  1. Set _stream_.[[writer]] to *undefined*.
  1. Set _writer_.[[ownerWritableStream]] to *undefined*.
</emu-alg>

<h4 id="writable-stream-default-writer-write" aoid="WritableStreamDefaultWriterWrite"
nothrow>WritableStreamDefaultWriterWrite ( <var>writer</var>, <var>chunk</var> )</h4>

<emu-alg>
  1. Let _stream_ be _writer_.[[ownerWritableStream]].
  1. Assert: _stream_ is not *undefined*.
  1. Let _controller_ be _stream_.[[writableStreamController]].
  1. Let _chunkSize_ be ! WritableStreamDefaultControllerGetChunkSize(_controller_, _chunk_).
  1. If _stream_ is not equal to _writer_.[[ownerWritableStream]], return <a>a promise rejected with</a> a *TypeError*
     exception.
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is not `"writable"` or ! WritableStreamCloseQueuedOrInFlight(_stream_) is *true*, return
     <a>a promise rejected with</a> a *TypeError* exception.
  1. If _stream_.[[pendingAbortRequest]] is not *undefined*, return <a>a promise rejected with</a> a *TypeError*
     indicating that the stream has been requested to abort.
  1. Let _promise_ be ! WritableStreamAddWriteRequest(_stream_).
  1. Perform ! WritableStreamDefaultControllerWrite(_controller_, _chunk_, _chunkSize_).
  1. Return _promise_.
</emu-alg>

<h3 id="ws-default-controller-class" interface lt="WritableStreamDefaultController">Class
<code>WritableStreamDefaultController</code></h3>

The {{WritableStreamDefaultController}} class has methods that allow control of a {{WritableStream}}'s state. When
constructing a {{WritableStream}}, the <a>underlying sink</a> is given a corresponding
{{WritableStreamDefaultController}} instance to manipulate.

<h4 id="ws-default-controller-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{WritableStreamDefaultController}} class in something close to the syntax of [[!ECMASCRIPT]],
it would look like

<pre><code class="lang-javascript">
  class WritableStreamDefaultController {
    constructor(stream, underlyingSink, size, highWaterMark)

    error(e)
  }
</code></pre>

<h4 id="ws-default-controller-internal-slots">Internal Slots</h4>

Instances of {{WritableStreamDefaultController}} 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>\[[controlledWritableStream]]
    <td>The {{WritableStream}} instance controlled
  </tr>
  <tr>
    <td>\[[queue]]
    <td>A List representing the stream's internal queue of <a>chunks</a>
  </tr>
  <tr>
    <td>\[[queueTotalSize]]
    <td>The total size of all the chunks stored in \[[queue]] (see [[#queue-with-sizes]])
  </tr>
  <tr>
    <td>\[[started]]
    <td>A boolean flag indicating whether the <a>underlying sink</a> has finished starting
  </tr>
  <tr>
    <td>\[[strategyHWM]]
    <td>A number supplied to the constructor as part of the stream's <a>queuing strategy</a>, indicating the point at
      which the stream will apply <a>backpressure</a> to its <a>underlying sink</a>
  </tr>
  <tr>
    <td>\[[strategySize]]
    <td>A function supplied to the constructor as part of the stream's <a>queuing strategy</a>, designed to calculate
      the size of enqueued <a>chunks</a>; can be <emu-val>undefined</emu-val> for the default behavior
  </tr>
  <tr>
    <td>\[[underlyingSink]]
    <td>An object representation of the stream's <a>underlying sink</a>; also
      used for the <a href="#is-writable-stream-default-controller">IsWritableStreamDefaultController</a> brand check
  </tr>
</table>

<h4 id="ws-default-controller-constructor" constructor for="WritableStreamDefaultController"
lt="WritableStreamDefaultController(stream, underlyingSink, size, highWaterMark)">new
WritableStreamDefaultController(<var>stream</var>, <var>underlyingSink</var>, <var>size</var>,
<var>highWaterMark</var>)</h4>

<div class="note">
  The <code>WritableStreamDefaultController</code> constructor cannot be used directly; it only works on a
  {{WritableStream}} that is in the middle of being constructed.
</div>

<emu-alg>
  1. If ! IsWritableStream(_stream_) is *false*, throw a *TypeError* exception.
  1. If _stream_.[[writableStreamController]] is not *undefined*, throw a *TypeError* exception.
  1. Set *this*.[[controlledWritableStream]] to _stream_.
  1. Set *this*.[[underlyingSink]] to _underlyingSink_.
  1. Perform ! ResetQueue(*this*).
  1. Set *this*.[[started]] to *false*.
  1. Let _normalizedStrategy_ be ? ValidateAndNormalizeQueuingStrategy(_size_, _highWaterMark_).
  1. Set *this*.[[strategySize]] to _normalizedStrategy_.[[size]] and *this*.[[strategyHWM]] to
     _normalizedStrategy_.[[highWaterMark]].
  1. Let _backpressure_ be ! WritableStreamDefaultControllerGetBackpressure(*this*).
  1. Perform ! WritableStreamUpdateBackpressure(_stream_, _backpressure_).
</emu-alg>

<h4 id="ws-default-controller-prototype">Properties of the {{WritableStreamDefaultController}} Prototype</h4>

<h5 id="ws-default-controller-error" method for="WritableStreamDefaultController">error(<var>e</var>)</h5>

<div class="note">
  The <code>error</code> method will error the writable stream, making all future interactions with it fail with the
  given error <code>e</code>.

  This method is rarely used, since usually it suffices to return a rejected promise from one of the <a>underlying
  sink</a>'s methods. However, it can be useful for suddenly shutting down a stream in response to an event outside the
  normal lifecycle of interactions with the <a>underlying sink</a>.
</div>

<emu-alg>
  1. If ! IsWritableStreamDefaultController(*this*) is *false*, throw a *TypeError* exception.
  1. Let _state_ be *this*.[[controlledWritableStream]].[[state]].
  1. If _state_ is `"closed"` or `"errored"`, throw a *TypeError* exception.
  1. Perform ! WritableStreamDefaultControllerError(*this*, _e_).
</emu-alg>

<h4 id="ws-default-controller-internal-methods">Writable Stream Default Controller Internal Methods</h4>

The following are additional internal methods implemented by each {{WritableStreamDefaultController}} instance. The
writable stream implementation will call into these.

<p class="note">The reason these are in method form, instead of as abstract operations, is to make it clear that the
writable stream implementation is decoupled from the controller implementation, and could in the future be expanded with
other controllers, as long as those controllers implemented such internal methods. A similar scenario is seen for
readable streams, where there actually are multiple controller types and as such the counterpart internal methods are
used polymorphically.

<h5 id="ws-default-controller-private-abort" oldids="writable-stream-default-controller-abort">\[[AbortSteps]]()</h5>

<emu-alg>
  1. Perform ! ResetQueue(*this*).
  1. Let _sinkAbortPromise_ be ! PromiseInvokeOrNoop(*this*.[[underlyingSink]], `"abort"`, « _reason_ »).
  1. Return the result of <a>transforming</a> _sinkAbortPromise_ with a fulfillment handler that returns
     *undefined*.
</emu-alg>

<h5 id="ws-default-controller-private-start" oldids="writable-stream-default-controller-start">\[[StartSteps]]()</h5>

<emu-alg>
  1. Let _startResult_ be ? InvokeOrNoop(*this*.[[underlyingSink]], `"start"`, « *this* »).
  1. Let _stream_ be *this*.[[controlledWritableStream]].
  1. Let _startPromise_ be <a>a promise resolved with</a> _startResult_:
    1. <a>Upon fulfillment</a>  of _startPromise_,
      1. Set *this*.[[started]] to *true*.
      1. If _stream_.[[state]] is `"errored"`, perform ! WritableStreamRejectAbortRequestIfPending(_stream_).
      1. Otherwise, perform ! WritableStreamHandleAbortRequestIfPending(_stream_).
      1. Perform ! WritableStreamDefaultControllerAdvanceQueueIfNeeded(*this*).
    1. <a>Upon rejection</a> of _startPromise_ with reason _r_,
      1. Assert: _stream_.[[state]] is `"writable"` or `"errored"`.
      1. Perform ! WritableStreamDefaultControllerErrorIfNeeded(*this*, _r_).
      1. Perform ! WritableStreamRejectAbortRequestIfPending(_stream_).
</emu-alg>

<h3 id="ws-default-controller-abstract-ops">Writable Stream Default Controller Abstract Operations</h3>

<h4 id="is-writable-stream-default-controller" aoid="IsWritableStreamDefaultController"
nothrow>IsWritableStreamDefaultController ( <var>x</var> )</h4>

<emu-alg>
  1. If Type(_x_) is not Object, return *false*.
  1. If _x_ does not have an [[underlyingSink]] internal slot, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="writable-stream-default-controller-close" aoid="WritableStreamDefaultControllerClose"
nothrow>WritableStreamDefaultControllerClose ( <var>controller</var> )</h4>

<emu-alg>
  1. Perform ! EnqueueValueWithSize(_controller_, `"close"`, *0*).
  1. Perform ! WritableStreamDefaultControllerAdvanceQueueIfNeeded(_controller_).
</emu-alg>

<h4 id="writable-stream-default-controller-get-chunk-size" aoid="WritableStreamDefaultControllerGetChunkSize"
nothrow>WritableStreamDefaultControllerGetChunkSize ( <var>controller</var>, <var>chunk</var> )</h4>

<emu-alg>
  1. Let _strategySize_ be _controller_.[[strategySize]].
  1. If _strategySize_ is *undefined*, return 1.
  1. Let _returnValue_ be Call(_strategySize_, *undefined*, « _chunk_ »).
  1. If _returnValue_ is an abrupt completion,
    1. Perform ! WritableStreamDefaultControllerErrorIfNeeded(_controller_, _returnValue_.[[Value]]).
    1. Return 1.
  1. Return _returnValue_.[[Value]].
</emu-alg>

<h4 id="writable-stream-default-controller-get-desired-size" aoid="WritableStreamDefaultControllerGetDesiredSize"
nothrow>WritableStreamDefaultControllerGetDesiredSize ( <var>controller</var> )</h4>

<emu-alg>
  1. Return _controller_.[[strategyHWM]] − _controller_.[[queueTotalSize]].
</emu-alg>

<h4 id="writable-stream-default-controller-write" aoid="WritableStreamDefaultControllerWrite"
nothrow>WritableStreamDefaultControllerWrite ( <var>controller</var>, <var>chunk</var>, <var>chunkSize</var> )</h4>

<emu-alg>
  1. Let _writeRecord_ be Record {[[chunk]]: _chunk_}.
  1. Let _enqueueResult_ be ! EnqueueValueWithSize(_controller_, _writeRecord_, _chunkSize_).
  1. If _enqueueResult_ is an abrupt completion,
    1. Perform ! WritableStreamDefaultControllerErrorIfNeeded(_controller_, _enqueueResult_.[[Value]]).
    1. Return.
  1. Let _stream_ be _controller_.[[controlledWritableStream]].
  1. If ! WritableStreamCloseQueuedOrInFlight(_stream_) is *false*,
    1. Let _backpressure_ be ! WritableStreamDefaultControllerGetBackpressure(_controller_).
    1. Perform ! WritableStreamUpdateBackpressure(_stream_, _backpressure_).
  1. Perform ! WritableStreamDefaultControllerAdvanceQueueIfNeeded(_controller_).
</emu-alg>

<h4 id="writable-stream-default-controller-advance-queue-if-needed"
aoid="WritableStreamDefaultControllerAdvanceQueueIfNeeded" nothrow>WritableStreamDefaultControllerAdvanceQueueIfNeeded (
<var>controller</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledWritableStream]].
  1. Let _state_ be _stream_.[[state]].
  1. If _state_ is `"closed"` or `"errored"`, return.
  1. If _controller_.[[started]] is *false*, return.
  1. If _stream_.[[inFlightWriteRequest]] is not *undefined*, return.
  1. If _controller_.[[queue]] is empty, return.
  1. Let _writeRecord_ be ! PeekQueueValue(_controller_).
  1. If _writeRecord_ is `"close"`, perform ! WritableStreamDefaultControllerProcessClose(_controller_).
  1. Otherwise, perform ! WritableStreamDefaultControllerProcessWrite(_controller_, _writeRecord_.[[chunk]]).
</emu-alg>

<h4 id="writable-stream-default-controller-error-if-needed" aoid="WritableStreamDefaultControllerErrorIfNeeded"
nothrow>WritableStreamDefaultControllerErrorIfNeeded ( <var>controller</var>, <var>error</var> )</h4>

<emu-alg>
  1. If _controller_.[[controlledWritableStream]].[[state]] is `"writable"`, perform !
     WritableStreamDefaultControllerError(_controller_, _error_).
</emu-alg>

<h4 id="writable-stream-default-controller-process-close" aoid="WritableStreamDefaultControllerProcessClose"
nothrow>WritableStreamDefaultControllerProcessClose ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledWritableStream]].
  1. Perform ! WritableStreamMarkCloseRequestInFlight(_stream_).
  1. Perform ! DequeueValue(_controller_).
  1. Assert: _controller_.[[queue]] is empty.
  1. Let _sinkClosePromise_ be ! PromiseInvokeOrNoop(_controller_.[[underlyingSink]], `"close"`, « _controller_ »).
  1. <a>Upon fulfillment</a> of _sinkClosePromise_,
    1. Perform ! WritableStreamFinishInFlightClose(_stream_).
  1. <a>Upon rejection</a> of _sinkClosePromise_ with reason _reason_,
    1. Perform ! WritableStreamFinishInFlightCloseWithError(_stream_, _reason_).
</emu-alg>

<h4 id="writable-stream-default-controller-process-write" aoid="WritableStreamDefaultControllerProcessWrite"
nothrow>WritableStreamDefaultControllerProcessWrite ( <var>controller</var>, <var>chunk</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controllerWritableStream]].
  1. Perform ! WritableStreamMarkFirstWriteRequestInFlight(_stream_).
  1. Let _sinkWritePromise_ be ! PromiseInvokeOrNoop(_controller_.[[underlyingSink]], `"write"`, « _chunk_,
     _controller_ »).
  1. <a>Upon fulfillment</a> of _sinkWritePromise_,
    1. Perform ! WritableStreamFinishInFlightWrite(_stream_).
    1. Let _state_ be _stream_.[[state]].
    1. If _state_ is `"errored"`, return.
    1. Assert: _state_ is `"writable"`.
    1. Perform ! DequeueValue(_controller_).
    1. If ! WritableStreamCloseQueuedOrInFlight(_stream_) is *false*,
      1. Let _backpressure_ be ! WritableStreamDefaultControllerGetBackpressure(_controller_).
      1. Perform ! WritableStreamUpdateBackpressure(_stream_, _backpressure_).
    1. Perform ! WritableStreamDefaultControllerAdvanceQueueIfNeeded(_controller_).
  1. <a>Upon rejection</a> of _sinkWritePromise_ with _reason_,
    1. Let _wasErrored_ be *false*.
    1. If _stream_.[[state]] is `"errored"`, set _wasErrored_ to *true*.
    1. Perform ! WritableStreamFinishInFlightWriteWithError(_stream_, _reason_).
    1. Assert: _stream_.[[state]] is `"errored"`.
    1. If _wasErrored_ is *false*, set _controller_.[[queue]] to an empty List.
</emu-alg>

<h4 id="writable-stream-default-controller-get-backpressure" aoid="WritableStreamDefaultControllerGetBackpressure"
nothrow>WritableStreamDefaultControllerGetBackpressure ( <var>controller</var> )</h4>

<emu-alg>
  1. Let _desiredSize_ be ! WritableStreamDefaultControllerGetDesiredSize(_controller_).
  1. Return _desiredSize_ ≤ *0*.
</emu-alg>

<h4 id="writable-stream-default-controller-error" aoid="WritableStreamDefaultControllerError"
nothrow>WritableStreamDefaultControllerError ( <var>controller</var>, <var>error</var> )</h4>

<emu-alg>
  1. Let _stream_ be _controller_.[[controlledWritableStream]].
  1. Assert: _stream_.[[state]] is `"writable"`.
  1. Perform ! WritableStreamError(_stream_, _error_).
</emu-alg>

<h2 id="ts">Transform Streams</h2>

Transform streams have been developed in the testable implementation, but not yet re-encoded in spec language.
We are waiting to validate their design before doing so. In the meantime, see <a
href="https://github.com/whatwg/streams/blob/master/reference-implementation/lib/transform-stream.js">reference-implementation/lib/transform-stream.js</a>.


<h2 id="other-stuff">Other Stream APIs and Operations</h2>

<h3 id="blqs-class" interface lt="ByteLengthQueuingStrategy">Class <code>ByteLengthQueuingStrategy</code></h3>

A common <a>queuing strategy</a> when dealing with bytes is to wait until the accumulated <code>byteLength</code>
properties of the incoming <a>chunks</a> reaches a specified high-water mark. As such, this is provided as a built-in
<a>queuing strategy</a> that can be used when constructing streams.

<div class="example" id="example-blqs">
  When creating a <a>readable stream</a> or <a>writable stream</a>, you can supply a byte-length queuing strategy
  directly:

  <pre><code class="lang-javascript">
    const stream = new ReadableStream(
      { ... },
      new ByteLengthQueuingStrategy({ highWaterMark: 16 * 1024 })
    );
  </code></pre>

  In this case, 16 KiB worth of <a>chunks</a> can be enqueued by the readable stream's <a>underlying source</a> before
  the readable stream implementation starts sending <a>backpressure</a> signals to the underlying source.

  <pre><code class="lang-javascript">
    const stream = new WritableStream(
      { ... },
      new ByteLengthQueuingStrategy({ highWaterMark: 32 * 1024 })
    );
  </code></pre>

  In this case, 32 KiB worth of <a>chunks</a> can be accumulated in the writable stream's internal queue, waiting for
  previous writes to the <a>underlying sink</a> to finish, before the writable stream starts sending
  <a>backpressure</a> signals to any <a>producers</a>.
</div>

<h4 id="blqs-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{ByteLengthQueuingStrategy}} class in something close to the syntax of [[!ECMASCRIPT]], it
would look like

<pre><code class="lang-javascript">
  class ByteLengthQueuingStrategy {
    constructor({ highWaterMark })
    size(chunk)
  }
</code></pre>

Each {{ByteLengthQueuingStrategy}} instance will additionally have an own data property
<code>highWaterMark</code> set by its constructor.

<h4 id="blqs-constructor" constructor for="ByteLengthQueuingStrategy" lt="ByteLengthQueuingStrategy(options)">new
ByteLengthQueuingStrategy({ <var>highWaterMark</var> })</h4>

<div class="note">
  The constructor takes a non-negative number for the high-water mark, and stores it on the object as a property.
</div>

<emu-alg>
  1. Perform ! CreateDataProperty(*this*, `"highWaterMark"`, _highWaterMark_).
</emu-alg>

<h4 id="blqs-prototype">Properties of the {{ByteLengthQueuingStrategy}} Prototype</h4>

<h5 id="blqs-size" method for="ByteLengthQueuingStrategy">size(<var>chunk</var>)</h5>

<div class="note">
  The <code>size</code> method returns the given chunk's <code>byteLength</code> property. (If the chunk doesn't have
  one, it will return <emu-val>undefined</emu-val>, causing the stream using this strategy to error.)

  This method is intentionally generic; it does not require that its <emu-val>this</emu-val> value be a
  <code>ByteLengthQueuingStrategy</code> object.
</div>

<emu-alg>
  1. Return ? GetV(_chunk_, `"byteLength"`).
</emu-alg>

<h3 id="cqs-class" interface lt="CountQueuingStrategy">Class <code>CountQueuingStrategy</code></h3>

A common <a>queuing strategy</a> when dealing with streams of generic objects is to simply count the number of chunks
that have been accumulated so far, waiting until this number reaches a specified high-water mark. As such, this
strategy is also provided out of the box.

<div class="example" id="example-cqs">
  When creating a <a>readable stream</a> or <a>writable stream</a>, you can supply a count queuing strategy directly:

  <pre><code class="lang-javascript">
    const stream = new ReadableStream(
      { ... },
      new CountQueuingStrategy({ highWaterMark: 10 })
    );
  </code></pre>

  In this case, 10 <a>chunks</a> (of any kind) can be enqueued by the readable stream's <a>underlying source</a> before
  the readable stream implementation starts sending <a>backpressure</a> signals to the underlying source.

  <pre><code class="lang-javascript">
    const stream = new WritableStream(
      { ... },
      new CountQueuingStrategy({ highWaterMark: 5 })
    );
  </code></pre>

  In this case, five <a>chunks</a> (of any kind) can be accumulated in the writable stream's internal queue, waiting
  for previous writes to the <a>underlying sink</a> to finish, before the writable stream starts sending
  <a>backpressure</a> signals to any <a>producers</a>.
</div>

<h4 id="cqs-class-definition">Class Definition</h4>

<em>This section is non-normative.</em>

If one were to write the {{CountQueuingStrategy}} class in something close to the syntax of [[!ECMASCRIPT]], it would
look like

<pre><code class="lang-javascript">
  class CountQueuingStrategy {
    constructor({ highWaterMark })
    size()
  }
</code></pre>

Each {{CountQueuingStrategy}} instance will additionally have an own data property <code>highWaterMark</code>
set by its constructor.

<h4 id="cqs-constructor" constructor for="CountQueuingStrategy" lt="CountQueuingStrategy(options)">new
CountQueuingStrategy({ <var>highWaterMark</var> })</h4>

<div class="note">
  The constructor takes a non-negative number for the high-water mark, and stores it on the object as a property.
</div>

<emu-alg>
  1. Perform ! CreateDataProperty(*this*, `"highWaterMark"`, _highWaterMark_).
</emu-alg>

<h4 id="cqs-prototype">Properties of the {{CountQueuingStrategy}} Prototype</h4>

<h5 id="cqs-size" method for="CountQueuingStrategy">size()</h5>

<div class="note">
  The <code>size</code> method returns one always, so that the total queue size is a count of the number of chunks in
  the queue.

  This method is intentionally generic; it does not require that its <emu-val>this</emu-val> value be a
  <code>CountQueuingStrategy</code> object.
</div>

<emu-alg>
  1. Return *1*.
</emu-alg>

<h3 id="queue-with-sizes">Queue-with-Sizes Operations</h3>

The streams in this specification use a "queue-with-sizes" data structure to store queued up values, along with their
determined sizes. Various specification objects contain a queue-with-sizes, represented by the object having two paired
internal slots, always named \[[queue]] and \[[queueTotalSize]]. \[[queue]] is a List of Records with \[[value]] and
\[[size]] fields, and \[[queueTotalSize]] is a JavaScript {{Number}}, i.e. a double-precision floating point number.

The following abstract operations are used when operating on objects that contain queues-with-sizes, in order to ensure
that the two internal slots stay synchronized.

<p class="warning">Due to the limited precision of floating-point arithmetic, the framework specified here, of keeping a
running total in the \[[queueTotalSize]] slot, is <em>not</em> equivalent to adding up the size of all <a>chunks</a> in
\[[queue]]. (However, this only makes a difference when there is a huge (~10<sup>15</sup>) variance in size between
chunks, or when trillions of chunks are enqueued.)</p>

<h4 id="dequeue-value" aoid="DequeueValue" nothrow>DequeueValue ( <var>container</var> )</h4>

<emu-alg>
  1. Assert: _container_ has [[queue]] and [[queueTotalSize]] internal slots.
  1. Assert: _container_.[[queue]] is not empty.
  1. Let _pair_ be the first element of _container_.[[queue]].
  1. Remove _pair_ from _container_.[[queue]], shifting all other elements downward (so that the second becomes the
     first, and so on).
  1. Set _container_.[[queueTotalSize]] to _container_.[[queueTotalSize]] − _pair_.[[size]].
  1. If _container_.[[queueTotalSize]] < *0*, set _container_.[[queueTotalSize]] to *0*. (This can occur due to
     rounding errors.)
  1. Return _pair_.[[value]].
</emu-alg>

<h4 id="enqueue-value-with-size" aoid="EnqueueValueWithSize" throws>EnqueueValueWithSize ( <var>container</var>,
<var>value</var>, <var>size</var> )</h4>

<emu-alg>
  1. Assert: _container_ has [[queue]] and [[queueTotalSize]] internal slots.
  1. Let _size_ be ? ToNumber(_size_).
  1. If ! IsFiniteNonNegativeNumber(_size_) is *false*, throw a *RangeError* exception.
  1. Append Record {[[value]]: _value_, [[size]]: _size_} as the last element of _container_.[[queue]].
  1. Set _container_.[[queueTotalSize]] to _container_.[[queueTotalSize]] + _size_.
</emu-alg>

<h4 id="peek-queue-value" aoid="PeekQueueValue" nothrow>PeekQueueValue ( <var>container</var> )</h4>

<emu-alg>
  1. Assert: _container_ has [[queue]] and [[queueTotalSize]] internal slots.
  1. Assert: _container_.[[queue]] is not empty.
  1. Let _pair_ be the first element of _container_.[[queue]].
  1. Return _pair_.[[value]].
</emu-alg>

<h4 id="reset-queue" aoid="ResetQueue" nothrow>ResetQueue ( <var>container</var> )</h4>

<emu-alg>
  1. Assert: _container_ has [[queue]] and [[queueTotalSize]] internal slots.
  1. Set _container_.[[queue]] to a new empty List.
  1. Set _container_.[[queueTotalSize]] to *0*.
</emu-alg>

<h3 id="misc-abstract-ops">Miscellaneous Operations</h3>

A few abstract operations are used in this specification for utility purposes. We define them here.

<h4 id="invoke-or-noop" aoid="InvokeOrNoop" throws>InvokeOrNoop ( <var>O</var>, <var>P</var>, <var>args</var> )</h4>

<div class="note">
  InvokeOrNoop is a slight modification of the [[!ECMASCRIPT]] <a abstract-op>Invoke</a> abstract operation to return
  <emu-val>undefined</emu-val> when the method is not present.
</div>

<emu-alg>
  1. Assert: _O_ is not *undefined*.
  1. Assert: ! IsPropertyKey(_P_) is *true*.
  1. Assert: _args_ is a List.
  1. Let _method_ be ? GetV(_O_, _P_).
  1. If _method_ is *undefined*, return *undefined*.
  1. Return ? Call(_method_, _O_, _args_).
</emu-alg>

<h4 id="is-finite-non-negative-number" aoid="IsFiniteNonNegativeNumber" nothrow>IsFiniteNonNegativeNumber ( <var>v</var>
)</h4>

<emu-alg>
  1. If _v_ is *NaN*, return *false*.
  1. If _v_ is *+∞*, return *false*.
  1. If _v_ < *0*, return *false*.
  1. Return *true*.
</emu-alg>

<h4 id="promise-invoke-or-noop" aoid="PromiseInvokeOrNoop" nothrow>PromiseInvokeOrNoop ( <var>O</var>, <var>P</var>,
<var>args</var> )</h4>

<div class="note">
  PromiseInvokeOrNoop is a specialized version of <a>promise-calling</a> that both works on methods and returns a
  promise for <emu-val>undefined</emu-val> when the method is not present.
</div>

<emu-alg>
  1. Assert: _O_ is not *undefined*.
  1. Assert: ! IsPropertyKey(_P_) is *true*.
  1. Assert: _args_ is a List.
  1. Let _returnValue_ be InvokeOrNoop(_O_, _P_, _args_).
  1. If _returnValue_ is an abrupt completion, return <a>a promise rejected with</a> _returnValue_.[[Value]].
  1. Otherwise, return <a>a promise resolved with</a> _returnValue_.[[Value]].
</emu-alg>

<h4 id="validate-and-normalize-high-water-mark" aoid="ValidateAndNormalizeHighWaterMark"
throws>ValidateAndNormalizeHighWaterMark ( <var>highWaterMark</var> )</h4>

<emu-alg>
  1. Set _highWaterMark_ to ? ToNumber(_highWaterMark_).
  1. If _highWaterMark_ is *NaN* or _highWaterMark_ < *0*, throw a *RangeError* exception.
     <p class="note">*+∞* is explicitly allowed as a valid <a>high water mark</a>. It causes <a>backpressure</a> to never be applied.</p>
  1. Return _highWaterMark_.
</emu-alg>

<h4 id="validate-and-normalize-queuing-strategy" aoid="ValidateAndNormalizeQueuingStrategy"
throws>ValidateAndNormalizeQueuingStrategy ( <var>size</var>, <var>highWaterMark</var> )</h4>

<emu-alg>
  1. If _size_ is not *undefined* and ! IsCallable(_size_) is *false*, throw a *TypeError* exception.
  1. Let _highWaterMark_ be ? ValidateAndNormalizeHighWaterMark(_highWaterMark_).
  1. Return Record {[[size]]: _size_, [[highWaterMark]]: _highWaterMark_}.
</emu-alg>

<h2 id="globals">Global Properties</h2>

The following constructors must be exposed on the global object as data properties of the same name:

<ul class="brief">
  <li> {{ReadableStream}}
  <li> {{WritableStream}}
  <li> {{ByteLengthQueuingStrategy}}
  <li> {{CountQueuingStrategy}}
</ul>

The attributes of these properties must be { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>,
\[[Configurable]]: <emu-val>true</emu-val> }.

<div class="note">
  The {{ReadableStreamDefaultReader}}, {{ReadableStreamBYOBReader}}, {{ReadableStreamDefaultController}},
  {{ReadableByteStreamController}}, {{WritableStreamDefaultWriter}}, and {{WritableStreamDefaultController}} classes are
  specifically not exposed, as they are not independently useful.
</div>

<h2 id="creating-examples">Examples of Creating Streams</h2>

<em>This section, and all its subsections, are non-normative.</em>

The previous examples throughout the standard have focused on how to use streams. Here we show how to create a stream,
using the {{ReadableStream}} or {{WritableStream}} constructors.

<h3 id="example-rs-push-no-backpressure">A readable stream with an underlying push source (no backpressure support)</h3>

The following function creates <a>readable streams</a> that wrap {{WebSocket}} instances [[HTML]], which are <a>push sources</a>
that do not support backpressure signals. It illustrates how, when adapting a push source, usually most of the work
happens in the <code>start</code> function.

<pre><code class="lang-javascript">
  function makeReadableWebSocketStream(url, protocols) {
    const ws = new WebSocket(url, protocols);
    ws.binaryType = "arraybuffer";

    return new ReadableStream({
      start(controller) {
        ws.onmessage = event => controller.enqueue(event.data);
        ws.onclose = () => controller.close();
        ws.onerror = () => controller.error(new Error("The WebSocket errored!"));
      },

      cancel() {
        ws.close();
      }
    });
  }
</code></pre>

We can then use this function to create readable streams for a web socket, and pipe that stream to an arbitrary
writable stream:

<pre><code class="lang-javascript">
  const webSocketStream = makeReadableWebSocketStream("wss://example.com:443/", "protocol");

  webSocketStream.pipeTo(writableStream)
    .then(() => console.log("All data successfully written!"))
    .catch(e => console.error("Something went wrong!", e));
</code></pre>

<h3 id="example-rs-push-backpressure">A readable stream with an underlying push source and backpressure support</h3>

The following function returns <a>readable streams</a> that wrap "backpressure sockets," which are hypothetical objects
that have the same API as web sockets, but also provide the ability to pause and resume the flow of data with their
<code>readStop</code> and <code>readStart</code> methods. In doing so, this example shows how to apply
<a>backpressure</a> to <a>underlying sources</a> that support it.

<pre><code class="lang-javascript">
  function makeReadableBackpressureSocketStream(host, port) {
    const socket = createBackpressureSocket(host, port);

    return new ReadableStream({
      start(controller) {
        socket.ondata = event => {
          controller.enqueue(event.data);

          if (controller.desiredSize <= 0) {
            // The internal queue is full, so propagate
            // the backpressure signal to the underlying source.
            socket.readStop();
          }
        };

        socket.onend = () => controller.close();
        socket.onerror = () => controller.error(new Error("The socket errored!"));
      },

      pull() {
        // This is called if the internal queue has been emptied, but the
        // stream's consumer still wants more data. In that case, restart
        // the flow of data if we have previously paused it.
        socket.readStart();
      },

      cancel() {
        socket.close();
      }
    });
  }
</code></pre>

We can then use this function to create readable streams for such "backpressure sockets" in the same way we do for web
sockets. This time, however, when we pipe to a destination that cannot accept data as fast as the socket is producing
it, or if we leave the stream alone without reading from it for some time, a backpressure signal will be sent to the
socket.

<h3 id="example-rbs-push">A readable byte stream with an underlying push source (no backpressure support)</h3>

The following function returns <a>readable byte streams</a> that wraps a hypothetical UDP socket API, including a
promise-returning <code>select2()</code> method that is meant to be evocative of the POSIX select(2) system call.

Since the UDP protocol does not have any built-in backpressure support, the backpressure signal given by
{{ReadableByteStreamController/desiredSize}} is ignored, and the stream ensures that when data is available from the
socket but not yet requested by the developer, it is enqueued in the stream's <a>internal queue</a>, to avoid overflow
of the kernel-space queue and a consequent loss of data.

This has some interesting consequences for how <a>consumers</a> interact with the stream. If the consumer does not read
data as fast as the socket produces it, the <a>chunks</a> will remain in the stream's <a>internal queue</a>
indefinitely. In this case, using a <a>BYOB reader</a> will cause an extra copy, to move the data from the stream's
internal queue to the developer-supplied buffer. However, if the consumer consumes the data quickly enough, a <a>BYOB
reader</a> will allow zero-copy reading directly into developer-supplied buffers.

(You can imagine a more complex version of this example which uses {{ReadableByteStreamController/desiredSize}} to
inform an out-of-band backpressure signaling mechanism, for example by sending a message down the socket to adjust the
rate of data being sent. That is left as an exercise for the reader.)

<pre><code class="lang-javascript">
  const DEFAULT_CHUNK_SIZE = 65536;

  function makeUDPSocketStream(host, port) {
    const socket = createUDPSocket(host, port);

    return new ReadableStream({
      type: "bytes",

      start(controller) {
        readRepeatedly().catch(e => controller.error(e));

        function readRepeatedly() {
          return socket.select2().then(() => {
            // Since the socket can become readable even when there’s
            // no pending BYOB requests, we need to handle both cases.
            let bytesRead;
            if (controller.byobRequest) {
              const v = controller.byobRequest.view;
              bytesRead = socket.readInto(v.buffer, v.byteOffset, v.byteLength);
              controller.byobRequest.respond(bytesRead);
            } else {
              const buffer = new ArrayBuffer(DEFAULT_CHUNK_SIZE);
              bytesRead = socket.readInto(buffer, 0, DEFAULT_CHUNK_SIZE);
              controller.enqueue(new Uint8Array(buffer, 0, bytesRead));
            }

            if (bytesRead === 0) {
              controller.close();
              return;
            }

            return readRepeatedly();
          });
        }
      },

      cancel() {
        socket.close();
      }
    });
  }
</code></pre>

{{ReadableStream}} instances returned from this function can now vend <a>BYOB readers</a>, with all of the
aforementioned benefits and caveats.

<h3 id="example-rs-pull">A readable stream with an underlying pull source</h3>

The following function returns <a>readable streams</a> that wrap portions of the
<a href="https://nodejs.org/api/fs.html">Node.js file system API</a> (which themselves map fairly directly to C's
<code>fopen</code>, <code>fread</code>, and <code>fclose</code> trio). Files are a typical example of <a>pull
sources</a>. Note how in contrast to the examples with push sources, most of the work here happens on-demand in the
<code>pull</code> function, and not at startup time in the <code>start</code> function.

<pre><code class="lang-javascript">
  const fs = require("pr/fs"); // https://github.com/jden/pr
  const CHUNK_SIZE = 1024;

  function makeReadableFileStream(filename) {
    let fd;
    let position = 0;

    return new ReadableStream({
      start() {
        return fs.open(filename, "r").then(result => {
          fd = result;
        });
      },

      pull(controller) {
        const buffer = new ArrayBuffer(CHUNK_SIZE);

        return fs.read(fd, buffer, 0, CHUNK_SIZE, position).then(bytesRead => {
          if (bytesRead === 0) {
            return fs.close(fd).then(() => controller.close());
          } else {
            position += bytesRead;
            controller.enqueue(new Uint8Array(buffer, 0, bytesRead));
          }
        });
      },

      cancel() {
        return fs.close(fd);
      }
    });
  }
</code></pre>

We can then create and use readable streams for files just as we could before for sockets.

<h3 id="example-rbs-pull">A readable byte stream with an underlying pull source</h3>

The following function returns <a>readable byte streams</a> that allow efficient zero-copy reading of files, again
using the <a href="https://nodejs.org/api/fs.html">Node.js file system API</a>. Instead of using a predetermined chunk
size of 1024, it attempts to fill the developer-supplied buffer, allowing full control.

<pre><code class="lang-javascript">
  const fs = require("pr/fs"); // https://github.com/jden/pr
  const DEFAULT_CHUNK_SIZE = 1024;

  function makeReadableByteFileStream(filename) {
    let fd;
    let position = 0;

    return new ReadableStream({
      type: "bytes",

      start() {
        return fs.open(filename, "r").then(result => {
          fd = result;
        });
      },

      pull(controller) {
        // Even when the consumer is using the default reader, the auto-allocation
        // feature allocates a buffer and passes it to us via byobRequest.
        const v = controller.byobRequest.view;

        return fs.read(fd, v.buffer, v.byteOffset, v.byteLength, position).then(bytesRead => {
          if (bytesRead === 0) {
            return fs.close(fd).then(() => controller.close());
          } else {
            position += bytesRead;
            controller.byobRequest.respond(bytesRead);
          }
        });
      },

      cancel() {
        return fs.close(fd);
      },

      autoAllocateChunkSize: DEFAULT_CHUNK_SIZE
    });
  }
</code></pre>

With this in hand, we can create and use <a>BYOB readers</a> for the returned {{ReadableStream}}. But we can
also create <a>default readers</a>, using them in the same simple and generic manner as usual. The adaptation between
the low-level byte tracking of the <a>underlying byte source</a> shown here, and the higher-level chunk-based
consumption of a <a>default reader</a>, is all taken care of automatically by the streams implementation. The
auto-allocation feature, via the <code>autoAllocateChunkSize</code> option, even allows us to write less code, compared
to the manual branching in [[#example-rbs-push]].

<h3 id="example-ws-no-backpressure">A writable stream with no backpressure or success signals</h3>

The following function returns a <a>writable stream</a> that wraps a {{WebSocket}} [[HTML]]. Web sockets do not provide
any way to tell when a given chunk of data has been successfully sent (without awkward polling of
{{WebSocket/bufferedAmount}}, which we leave as an exercise to the reader). As such, this writable stream has no ability
to communicate accurate <a>backpressure</a> signals or write success/failure to its <a>producers</a>. That is, the
promises returned by its <a lt="writable stream writer">writer</a>'s {{WritableStreamDefaultWriter/write()}} method and
{{WritableStreamDefaultWriter/ready}} getter will always fulfill immediately.

<pre><code class="lang-javascript">
  function makeWritableWebSocketStream(url, protocols) {
    const ws = new WebSocket(url, protocols);

    return new WritableStream({
      start(controller) {
        ws.onerror = () => controller.error(new Error("The WebSocket errored!"));
        return new Promise(resolve => ws.onopen = resolve);
      },

      write(chunk) {
        ws.send(chunk);
        // Return immediately, since the web socket gives us no easy way to tell
        // when the write completes.
      },

      close() {
        return new Promise((resolve, reject) => {
          ws.onclose = resolve;
          ws.close(1000);
        });
      },

      abort(reason) {
        return new Promise((resolve, reject) => {
          ws.onclose = resolve;
          ws.close(4000, reason && reason.message);
        });
      }
    });
  }
</code></pre>

We can then use this function to create writable streams for a web socket, and pipe an arbitrary readable stream to it:

<pre><code class="lang-javascript">
  const webSocketStream = makeWritableWebSocketStream("wss://example.com:443/", "protocol");

  readableStream.pipeTo(webSocketStream)
    .then(() => console.log("All data successfully written!"))
    .catch(e => console.error("Something went wrong!", e));
</code></pre>

<h3 id="example-ws-backpressure">A writable stream with backpressure and success signals</h3>

The following function returns <a>writable streams</a> that wrap portions of the <a
href="https://nodejs.org/api/fs.html">Node.js file system API</a> (which themselves map fairly directly to C's
<code>fopen</code>, <code>fwrite</code>, and <code>fclose</code> trio). Since the API we are wrapping provides a way to
tell when a given write succeeds, this stream will be able to communicate <a>backpressure</a> signals as well as whether
an individual write succeeded or failed.

<pre><code class="lang-javascript">
  const fs = require("pr/fs"); // https://github.com/jden/pr

  function makeWritableFileStream(filename) {
    let fd;

    return new WritableStream({
      start() {
        return fs.open(filename, "w").then(result => {
          fd = result;
        });
      },

      write(chunk) {
        return fs.write(fd, chunk, 0, chunk.length);
      },

      close() {
        return fs.close(fd);
      },

      abort() {
        return fs.close(fd);
      }
    });
  }
</code></pre>

We can then use this function to create a writable stream for a file, and write individual <a>chunks</a> of data to it:

<pre><code class="lang-javascript">
  const fileStream = makeWritableFileStream("/example/path/on/fs.txt");
  const writer = fileStream.getWriter();

  writer.write("To stream, or not to stream\n");
  writer.write("That is the question\n");

  writer.close()
    .then(() => console.log("chunks written and stream closed successfully!"))
    .catch(e => console.error(e));
</code></pre>

Note that if a particular call to <code>fs.write</code> takes a longer time, the returned promise will fulfill later.
In the meantime, additional writes can be queued up, which are stored in the stream's internal queue. The accumulation
of chunks in this queue can change the stream to return a pending promise from the {{WritableStreamDefaultWriter/ready}}
getter, which is a signal to <a>producers</a> that they should back off and stop writing if possible.

The way in which the writable stream queues up writes is especially important in this case, since as stated in
<a href="https://nodejs.org/api/fs.html#fs_fs_write_fd_data_position_encoding_callback">the documentation for
<code>fs.write</code></a>, "it is unsafe to use <code>fs.write</code> multiple times on the same file without waiting
for the [promise]." But we don't have to worry about that when writing the <code>makeWritableFileStream</code>
function, since the stream implementation guarantees that the <a>underlying sink</a>'s <code>write</code> method will
not be called until any promises returned by previous calls have fulfilled!

<h3 id="example-both">A { readable, writable } stream pair wrapping the same underlying resource</h3>

The following function returns an object of the form <code>{ readable, writable }</code>, with the
<code>readable</code> property containing a readable stream and the <code>writable</code> property containing a
writable stream, where both streams wrap the same underlying web socket resource. In essence, this combines
[[#example-rs-push-no-backpressure]] and [[#example-ws-no-backpressure]].

While doing so, it illustrates how you can use JavaScript classes to create reusable underlying sink and underlying
source abstractions.

<pre><code class="lang-javascript">
  function streamifyWebSocket(url, protocol) {
    const ws = new WebSocket(url, protocols);
    ws.binaryType = "arraybuffer";

    return {
      readable: new ReadableStream(new WebSocketSource(ws)),
      writable: new WritableStream(new WebSocketSink(ws))
    };
  }

  class WebSocketSource {
    constructor(ws) {
      this._ws = ws;
    }

    start(controller) {
      this._ws.onmessage = event => controller.enqueue(event.data);
      this._ws.onclose = () => controller.close();

      this._ws.addEventListener("error", () => {
        controller.error(new Error("The WebSocket errored!"));
      });
    }

    cancel() {
      this._ws.close();
    }
  }

  class WebSocketSink {
    constructor(ws) {
      this._ws = ws;
    }

    start(controller) {
      this._ws.addEventListener("error", () => {
        controller.error(new Error("The WebSocket errored!"));
      });

      return new Promise(resolve => this._ws.onopen = resolve);
    }

    write(chunk) {
      this._ws.send(chunk);
    }

    close() {
      return new Promise((resolve, reject) => {
        this._ws.onclose = resolve;
        this._ws.close();
      });
    }

    abort(reason) {
      return new Promise((resolve, reject) => {
        ws.onclose = resolve;
        ws.close(4000, reason && reason.message);
      });
    }
  }
</code></pre>

We can then use the objects created by this function to communicate with a remote web socket, using the standard stream
APIs:

<pre><code class="lang-javascript">
  const streamyWS = streamifyWebSocket("wss://example.com:443/", "protocol");
  const writer = streamyWS.writable.getWriter();
  const reader = streamyWS.readable.getReader();

  writer.write("Hello");
  writer.write("web socket!");

  reader.read().then(({ value, done }) => {
    console.log("The web socket says: ", value);
  });
</code></pre>

Note how in this setup canceling the <code>readable</code> side will implicitly close the <code>writable</code> side,
and similarly, closing or aborting the <code>writable</code> side will implicitly close the <code>readable</code> side.

<h2 id="conventions" class="no-num">Conventions</h2>

This specification uses algorithm conventions very similar to those of [[!ECMASCRIPT]]. However, it deviates in the
following ways, mostly for brevity. It is hoped (and vaguely planned) that eventually the conventions of ECMAScript
itself will evolve in these ways.

<ul>
  <li> We use destructuring notation in function and method declarations, and assume that the destructuring assignment
    procedure was performed before the algorithm starts.
  <li> We similarly use the default argument notation <code>= {}</code> in a couple of cases.
  <li> We use "<emu-val>this</emu-val>" instead of "<emu-val>this</emu-val> value".
  <li> We use the shorthand phrases from the [[!PROMISES-GUIDE]] to operate on promises at a higher level than the
    ECMAScript spec does.
</ul>

It's also worth noting that, as in [[!ECMASCRIPT]], all numbers are represented as double-precision floating point
values, and all arithmetic operations performed on them must be done in the standard way for such values.

<h2 id="acks" class="no-num">Acknowledgments</h2>

The editor would like to thank
Adam Rice,
Anne van Kesteren,
Ben Kelly,
Brian di Palma,
Calvin Metcalf,
Dominic Tarr,
Ed Hager,
Forbes Lindesay,
贺师俊 (hax),
isonmad,
Jake Archibald,
Jens Nockert,
Mangala Sadhu Sangeet Singh Khalsa,
Marcos Caceres,
Marvin Hagemeister,
Michael Mior,
Mihai Potra,
Simon Menke,
Stephen Sugden,
Tab Atkins,
Tanguy Krotoff,
Thorsten Lorenz,
Till Schneidereit,
Tim Caswell,
Trevor Norris,
tzik,
Youenn Fablet,
and
Xabier Rodríguez
for their contributions to this specification.

Special thanks to:
Bert Belder for bringing up <a href="https://github.com/whatwg/streams/issues/253">implementation concerns</a> that led
  to crucial API changes;
Forrest Norvell for his work on the initial reference implementation;
Gorgi Kosev for his breakthrough idea of separating piping into two methods, thus resolving
  <a href="https://github.com/whatwg/streams/issues/44">a major sticking point</a>;
Isaac Schlueter for his pioneering work on JavaScript streams in Node.js;
Jake Verbaten for his early involvement and support;
Janessa Det for the logo;
Will Chan for his help ensuring that the API allows high-performance network streaming;
and
平野裕 (Yutaka Hirano) for his help with the readable stream reader design.

This standard is written by <a href="https://domenic.me/">Domenic Denicola</a>
(<a href="https://google.com">Google</a>, <a href="mailto:d@domenic.me">d@domenic.me</a>) and
吉野剛史 (Takeshi Yoshino, <a href="https://google.com">Google</a>,
<a href="mailto:tyoshino@chromium.org">tyoshino@chromium.org</a>).

Per <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>, to the extent possible under law, the editor has waived all copyright and related or neighboring rights to this work.

<script>
"use strict";
if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register("/service-worker.js");
}
</script>