Skip to main content
Module

std/node/stream.ts>Readable

Deno standard library
Go to Latest
class Readable
implements ReadableStream
extends Stream
Re-export
import { Readable } from "https://deno.land/std@0.177.0/node/stream.ts";

Constructors

new
Readable(opts?: ReadableOptions)

Properties

destroyed: boolean

Is true after readable.destroy() has been called.

readable: boolean

Is true if it is safe to call readable.read(), which means the stream has not been destroyed or emitted 'error' or 'end'.

readonly
readableAborted: boolean

Returns whether the stream was destroyed or errored before emitting 'end'.

readonly
readableDidRead: boolean

Returns whether 'data' has been emitted.

readonly
readableEncoding: BufferEncoding | null

Getter for the property encoding of a given Readable stream. The encodingproperty can be set using the readable.setEncoding() method.

readonly
readableEnded: boolean

Becomes true when 'end' event is emitted.

readonly
readableFlowing: boolean | null

This property reflects the current state of a Readable stream as described in the Three states section.

readonly
readableHighWaterMark: number

Returns the value of highWaterMark passed when creating this Readable.

readonly
readableLength: number

This property contains the number of bytes (or objects) in the queue ready to be read. The value provides introspection data regarding the status of the highWaterMark.

readonly
readableObjectMode: boolean

Getter for the property objectMode of a given Readable stream.

Methods

optional
_construct(callback: (error?: Error | null) => void): void
_destroy(error: Error | null, callback: (error?: Error | null) => void): void
_read(size: number): void
_undestroy(): void
addListener(event: "close", listener: () => void): this

Event emitter The defined events on documents including:

  1. close
  2. data
  3. end
  4. error
  5. pause
  6. readable
  7. resume
addListener(event: "data", listener: (chunk: any) => void): this
addListener(event: "end", listener: () => void): this
addListener(event: "error", listener: (err: Error) => void): this
addListener(event: "pause", listener: () => void): this
addListener(event: "readable", listener: () => void): this
addListener(event: "resume", listener: () => void): this
addListener(event: string | symbol, listener: (...args: any[]) => void): this
destroy(error?: Error): void

Destroy the stream. Optionally emit an 'error' event, and emit a 'close'event (unless emitClose is set to false). After this call, the readable stream will release any internal resources and subsequent calls to push()will be ignored.

Once destroy() has been called any further calls will be a no-op and no further errors except from _destroy() may be emitted as 'error'.

Implementors should not override this method, but instead implement readable._destroy().

emit(event: "close"): boolean
emit(event: "data", chunk: any): boolean
emit(event: "end"): boolean
emit(event: "error", err: Error): boolean
emit(event: "pause"): boolean
emit(event: "readable"): boolean
emit(event: "resume"): boolean
emit(event: string | symbol, ...args: any[]): boolean
isPaused(): boolean

The readable.isPaused() method returns the current operating state of theReadable. This is used primarily by the mechanism that underlies thereadable.pipe() method. In most typical cases, there will be no reason to use this method directly.

const readable = new stream.Readable();

readable.isPaused(); // === false
readable.pause();
readable.isPaused(); // === true
readable.resume();
readable.isPaused(); // === false
on(event: "close", listener: () => void): this
on(event: "data", listener: (chunk: any) => void): this
on(event: "end", listener: () => void): this
on(event: "error", listener: (err: Error) => void): this
on(event: "pause", listener: () => void): this
on(event: "readable", listener: () => void): this
on(event: "resume", listener: () => void): this
on(event: string | symbol, listener: (...args: any[]) => void): this
once(event: "close", listener: () => void): this
once(event: "data", listener: (chunk: any) => void): this
once(event: "end", listener: () => void): this
once(event: "error", listener: (err: Error) => void): this
once(event: "pause", listener: () => void): this
once(event: "readable", listener: () => void): this
once(event: "resume", listener: () => void): this
once(event: string | symbol, listener: (...args: any[]) => void): this
pause(): this

The readable.pause() method will cause a stream in flowing mode to stop emitting 'data' events, switching out of flowing mode. Any data that becomes available will remain in the internal buffer.

const readable = getReadableStreamSomehow();
readable.on('data', (chunk) => {
  console.log(`Received ${chunk.length} bytes of data.`);
  readable.pause();
  console.log('There will be no additional data for 1 second.');
  setTimeout(() => {
    console.log('Now data will start flowing again.');
    readable.resume();
  }, 1000);
});

The readable.pause() method has no effect if there is a 'readable'event listener.

prependListener(event: "close", listener: () => void): this
prependListener(event: "data", listener: (chunk: any) => void): this
prependListener(event: "end", listener: () => void): this
prependListener(event: "error", listener: (err: Error) => void): this
prependListener(event: "pause", listener: () => void): this
prependListener(event: "readable", listener: () => void): this
prependListener(event: "resume", listener: () => void): this
prependListener(event: string | symbol, listener: (...args: any[]) => void): this
prependOnceListener(event: "close", listener: () => void): this
prependOnceListener(event: "data", listener: (chunk: any) => void): this
prependOnceListener(event: "end", listener: () => void): this
prependOnceListener(event: "error", listener: (err: Error) => void): this
prependOnceListener(event: "pause", listener: () => void): this
prependOnceListener(event: "readable", listener: () => void): this
prependOnceListener(event: "resume", listener: () => void): this
prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this
push(chunk: any, encoding?: BufferEncoding): boolean
read(size?: number): any

The readable.read() method pulls some data out of the internal buffer and returns it. If no data available to be read, null is returned. By default, the data will be returned as a Buffer object unless an encoding has been specified using the readable.setEncoding() method or the stream is operating in object mode.

The optional size argument specifies a specific number of bytes to read. Ifsize bytes are not available to be read, null will be returned _unless_the stream has ended, in which case all of the data remaining in the internal buffer will be returned.

If the size argument is not specified, all of the data contained in the internal buffer will be returned.

The size argument must be less than or equal to 1 GiB.

The readable.read() method should only be called on Readable streams operating in paused mode. In flowing mode, readable.read() is called automatically until the internal buffer is fully drained.

const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});

Each call to readable.read() returns a chunk of data, or null. The chunks are not concatenated. A while loop is necessary to consume all data currently in the buffer. When reading a large file .read() may return null, having consumed all buffered content so far, but there is still more data to come not yet buffered. In this case a new 'readable' event will be emitted when there is more data in the buffer. Finally the 'end' event will be emitted when there is no more data to come.

Therefore to read a file's whole contents from a readable, it is necessary to collect chunks across multiple 'readable' events:

const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});

A Readable stream in object mode will always return a single item from a call to readable.read(size), regardless of the value of thesize argument.

If the readable.read() method returns a chunk of data, a 'data' event will also be emitted.

Calling read after the 'end' event has been emitted will return null. No runtime error will be raised.

removeListener(event: "close", listener: () => void): this
removeListener(event: "data", listener: (chunk: any) => void): this
removeListener(event: "end", listener: () => void): this
removeListener(event: "error", listener: (err: Error) => void): this
removeListener(event: "pause", listener: () => void): this