ReadableStreamDefaultReader: cancel() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨January 2020⁩.

Note: This feature is available inWeb Workers.

Thecancel() method of theReadableStreamDefaultReader interface returns aPromise that resolves when the stream is canceled. Calling this method signals a loss of interest in the stream by a consumer.

Cancel is used when you've completely finished with the stream and don't need any moredata from it, even if there are chunks enqueued waiting to be read. That data is lostafter cancel is called, and the stream is not readable any more. To read those chunksstill and not completely get rid of the stream, you'd useReadableStreamDefaultController.close().

Note:If the reader is active, thecancel() method behaves the same as that for the associated stream(ReadableStream.cancel()).

Syntax

cancel()cancel(reason)

Parameters

reasonOptional: A human-readable reason for the cancellation. This value may or may not be used.

Return value

APromise, which fulfills with the value given in thereasonparameter.

Exceptions

TypeError: The source object is not aReadableStreamDefaultReader, or the streamhas no owner.

Examples

In the following simple example, a previously-created customReadableStream is read using aReadableStreamDefaultReadercreated usinggetReader(). (this code is based on ourSimple random stream example). Each chunk is read sequentially and output to the UI, until thestream has finished being read, at which point we return out of the recursive functionand print the entire stream to another part of the UI.

When the stream is done (if (done)), we runreader.cancel()to cancel the stream, signalling that we don't need to use it any more.

function fetchStream() {  const reader = stream.getReader();  let charsReceived = 0;  // read() returns a promise that resolves  // when a value has been received  reader.read().then(function processText({ done, value }) {    // Result objects contain two properties:    // done  - true if the stream has already given you all its data.    // value - some data. Always undefined when done is true.    if (done) {      console.log("Stream complete");      reader.cancel();      para.textContent = result;      return;    }    // value for fetch streams is a Uint8Array    charsReceived += value.length;    const chunk = value;    let listItem = document.createElement("li");    listItem.textContent = `Received ${charsReceived} characters so far. Current chunk = ${chunk}`;    list2.appendChild(listItem);    result += chunk;    // Read some more, and call this function again    return reader.read().then(processText);  });}