ReadableStream locked property
The `locked` property is a boolean value that indicates if the readable stream is locked to a reader.
Cloudflare Workers · Runtime APIs · all subjects
streams
49 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
ReadableStream getReader method
The `getReader(optionsObject)` method gets an instance of `ReadableStreamDefaultReader` and locks the `ReadableStream` to that reader instance. The method accepts an object argument with an optional `mode` property that can be set to 'byob' to create a `ReadableStreamBYOBReader` instead.
ReadableStream getReader with byob mode example
To create a `ReadableStreamBYOBReader` from a readable stream, call `getReader` with `mode` set to `'byob'`: let reader = readable.getReader({ mode: 'byob' });
PipeToOptions preventClose
The `preventClose` option (boolean) in PipeToOptions: when set to `true`, closure of the source `ReadableStream` will not cause the destination `WritableStream` to be closed.
PipeToOptions preventAbort
The `preventAbort` option (boolean) in PipeToOptions: when set to `true`, errors in the source `ReadableStream` will no longer abort the destination `WritableStream`. The `pipeTo` method will return a rejected promise with the error from the source or any error that occurred while aborting the destination.
ReadableStream returned by TransformStream
A `ReadableStream` is returned by the `readable` property inside `TransformStream`.
ReadableStream pipeTo method
The `pipeTo(destinationWritableStream, optionsPipeToOptions)` method pipes the readable stream to a given writable stream destination and returns a Promise<void>. The promise is fulfilled when the write operation succeeds or rejects if the operation fails.
ReadableStreamDefaultReader.releaseLock() method
The releaseLock() method releases the lock on the readable stream and returns void. A lock cannot be released if the reader has pending read operations. If releaseLock() is called while read operations are pending, a TypeError is thrown and the reader remains locked.
ReadableStreamDefaultReader overview
A ReadableStreamDefaultReader is used to read chunks from a ReadableStream rather than piping its output to a WritableStream. It is not instantiated via its constructor but is retrieved from a ReadableStream by calling the getReader() method.
How to create a ReadableStreamDefaultReader
Call the getReader() method on a ReadableStream to obtain a ReadableStreamDefaultReader. Example: const { readable, writable } = new TransformStream(); const reader = readable.getReader();
ReadableStreamDefaultReader.read() method
The read() method returns a Promise that resolves with the next available chunk of data being passed through the reader queue.
ReadableStreamDefaultReader.cancel() method
The cancel() method cancels the stream and returns void. It accepts an optional reason parameter as a human-readable string indicating the reason for cancellation. The reason is passed to the underlying source's cancel algorithm. If this readable stream is one side of a TransformStream, the cancel algorithm causes the transform's writable side to become errored with the reason. Any data not yet read is lost when cancel is called.
ReadableStreamBYOBReader read method
The read(bufferArrayBufferView) method returns a Promise<ReadableStreamBYOBReadResult> containing the next available chunk of data read into a passed-in buffer. This method provides no control over the minimum number of bytes read; the kernel may fulfill the read with as little as a single byte even if a larger buffer is allocated.
ReadableStreamBYOBReader overview
ReadableStreamBYOBReader is a BYOB (bring your own buffer) reader that allows reading into a developer-supplied buffer to minimize copies. It is functionally identical to ReadableStreamDefaultReader except for the read method. It is not instantiated via constructor but retrieved from a ReadableStream using getReader({ mode: 'byob' }).
ReadableStreamBYOBReader readAtLeast method
The readAtLeast(minElements, bufferArrayBufferView) method returns a Promise<ReadableStreamBYOBReadResult> containing the next available chunk of data read into a passed-in buffer. It will not resolve until at least minElements elements have been read, where element size is determined by the bufferArrayBufferView type (for example 4 bytes per element for Uint32Array). Fewer than minElements elements may be returned if the end of the stream is reached or the underlying stream is closed. If minElements or more elements are available, it resolves with { value: <buffer view sized to bytes read>, done: false }. If the stream ends after some data but fewer than minElements elements, it resolves with partial data: { value: <buffer view sized to bytes actually read>, done: false }. If the stream ends with zero bytes available (at EOF), it resolves with { value: <zero-length view>, done: true }. If the stream errors, the promise rejects. minElements must be at least 1, and minElements * elementSize must not exceed the byte length of bufferArrayBufferView, or the promise rejects with TypeError. For Uint8Array, element size is 1, so minElements is effectively a byte count.
ReadableStreamBYOBReader instantiation
A ReadableStreamBYOBReader is obtained from a ReadableStream by calling getReader({ mode: 'byob' }), not via direct constructor.
read method buffer efficiency pitfall
The read method typically fills only about 1% of a provided buffer. Even if you allocate a 1 MiB buffer, the kernel may fulfill the read with a single byte. For better control over the minimum amount of data read, use readAtLeast instead.
readAtLeast is non-standard extension
readAtLeast is a non-standard extension to the Streams API that allows specifying a minimum number of elements to read before resolving. This differs from the standard Streams API and is specific to the Workers runtime.
FixedLengthStream constructor example
Example: `let { readable, writable } = new FixedLengthStream(1000);` creates a fixed-length stream with a 1000 byte limit.
TransformStream constructor creates identity transform stream
TransformStream() returns a new identity transform stream with readable and writable properties. The destructuring syntax `let { readable, writable } = new TransformStream();` extracts both stream sides.
Identity transform stream behavior
An identity transform stream forwards all chunks written to its writable side to its readable side without any changes. Workers currently only implements this type of transform stream.
IdentityTransformStream constructor
IdentityTransformStream() returns a new identity transform stream with readable and writable properties. It implements behavior identical to the current TransformStream class.
IdentityTransformStream forwards byte data chunks
IdentityTransformStream forwards all chunks of byte data in the form of TypedArrays written to its writable side to its readable side without any changes. The readable side supports bring your own buffer (BYOB) reads.
IdentityTransformStream readable property
The readable property of IdentityTransformStream is an instance of ReadableStream.
IdentityTransformStream writable property
The writable property of IdentityTransformStream is an instance of WritableStream.
FixedLengthStream limits passthrough bytes
FixedLengthStream is a specialization of IdentityTransformStream that limits the total number of bytes that the stream will passthrough. An error will occur if too many or too few bytes are written through the stream.
FixedLengthStream sets Content-Length header
When using FixedLengthStream to produce a Response or Request, the fixed length of the stream is used as the Content-Length header value instead of chunked encoding.
FixedLengthStream constructor syntax
FixedLengthStream(length) returns a new identity transform stream with a fixed length constraint. The length parameter may be a number or bigint with a maximum value of 2^53 - 1.
FixedLengthStream readable property
The readable property of FixedLengthStream is an instance of ReadableStream.
FixedLengthStream writable property
The writable property of FixedLengthStream is an instance of WritableStream.
TransformStream future spec compliance planned
The current implementation of TransformStream in the Workers platform is not fully compliant with the Streams Standard and will be changed to conform with the specification. IdentityTransformStream was introduced to preserve current behavior during this transition.
IdentityTransformStream constructor example
Example: `let { readable, writable } = new IdentityTransformStream();` creates a new identity transform stream.
WritableStream cannot be directly constructed
On the Workers platform, WritableStream cannot be directly created using the WritableStream constructor. Instead, WritableStream is the writable property of a TransformStream.
Writing to WritableStream via pipeTo
A typical way to write to a WritableStream is to pipe a ReadableStream to it using the pipeTo() method. This returns a promise that fulfills when all data is successfully written, or rejects if an error occurs during writing.
WritableStream.pipeTo example code
readableStream .pipeTo(writableStream) .then(() => console.log('All data successfully written!')) .catch(e => console.error('Something went wrong!', e));
Writing to WritableStream directly with writer
To write to a WritableStream directly, you must get a writer instance using getWriter(), then call write(data) on the writer.
WritableStream.getWriter example code
const writer = writableStream.getWriter(); writer.write(data);
WritableStream.locked property
The locked property is a boolean value that indicates if the writable stream is locked to a writer. It returns true when the stream is locked, false otherwise.
WritableStream.getWriter method
The getWriter() method returns an instance of WritableStreamDefaultWriter and locks the WritableStream to that writer instance.
WritableStreamDefaultWriter write and pipe example
Example showing how to write a preamble to a writable stream and then pipe additional data from another source: let writer = writable.getWriter(); writer.write(new TextEncoder().encode('foo bar')); writer.releaseLock(); await someResponse.body.pipeTo(writable);
WritableStreamDefaultWriter forEach write example
Example showing how to write an array of items to a stream: function writeArrayToStream(array, writableStream) { const writer = writableStream.getWriter(); array.forEach(chunk => writer.write(chunk).catch(() => {})); return writer.close(); } writeArrayToStream([1, 2, 3, 4, 5], writableStream).then(() => console.log('All done!')).catch(e => console.error('Error with the stream: ' + e));
WritableStreamDefaultWriter.desiredSize property
The desiredSize property returns an integer indicating the size needed to fill the stream's internal queue. It always returns 1, 0 (if the stream is closed), or null (if the stream has errors).
WritableStreamDefaultWriter.closed property
The closed property is a Promise<void> that indicates if the writer is closed. The promise is fulfilled when the writer stream is closed and rejected if there is an error in the stream.
WritableStreamDefaultWriter.abort() method
The abort(reason) method aborts the stream and returns a Promise<void>. The reason parameter is optional and should be a human-readable string indicating the reason for cancellation. The reason is passed to the underlying sink's abort algorithm. If this writable stream is one side of a TransformStream, the abort algorithm causes the transform's readable side to become errored with the reason. Any data not yet written is lost upon abort.
WritableStreamDefaultWriter.close() method
The close() method attempts to close the writer and returns a Promise<void>. Remaining writes finish processing before the writer is closed. The promise is fulfilled with undefined if the writer successfully closes and processes the remaining writes, or rejected on any error.
WritableStreamDefaultWriter.releaseLock() method
The releaseLock() method releases the writer's lock on the stream and returns void. Once released, the writer is no longer active. You can call this method before all pending write(chunk) calls are resolved. This allows you to queue a write operation, release the lock, and begin piping into the writable stream from another source.
WritableStreamDefaultWriter.write() method
The write(chunk) method writes a chunk of data to the writer and returns a Promise<void> that resolves if the operation succeeds. The chunk parameter is of type any. The underlying stream may accept fewer kinds of type than any, and will throw an exception when encountering an unexpected type.
WritableStreamDefaultWriter usage pattern
A writer is used when you want to write directly to a WritableStream, rather than piping data to it from a ReadableStream. Use writableStream.getWriter() to obtain a writer instance.
CompressionStream and DecompressionStream support deflate, deflate-raw, and gzip
The CompressionStream and DecompressionStream classes are available and support the deflate, deflate-raw, and gzip compression methods.