readable.push(chunk[, encoding])


  • chunk <Buffer> | <Uint8Array> | <string> | <null> | <any> 要推入读取队列的数据块。  对于非对象模式的流, chunk 必须是字符串、 BufferUint8Array。  对于对象模式的流, chunk 可以是任何 JavaScript 值。
  • encoding <string> 字符串数据块的字符编码。 必须是有效的 Buffer 字符编码,例如 'utf8' 或 'ascii'
  • 返回: <boolean> 如果还有数据块可以继续推入,则返回 true,否则返回 false

chunkBufferUint8Array 或字符串时, chunk 的数据会被添加到内部队列中供流消费。 在没有数据可写入后,给 chunk 传入 null 表示流的结束(EOF)。

当可读流处在暂停模式时,使用 readable.push() 添加的数据可以在触发 'readable' 事件时通过调用 readable.read() 读取。

当可读流处于流动模式时,使用 readable.push() 添加的数据可以通过触发 'data' 事件读取。

readable.push() 方法被设计得尽可能的灵活。 例如,当需要封装一个带有'暂停/继续'机制与数据回调的底层数据源时,该底层数据源可以使用自定义的可读流实例封装:

// `source` 是一个有 `readStop()` 和 `readStart()` 方法的对象,
// 当有数据时会调用 `ondata` 方法,
// 当数据结束时会调用 `onend` 方法。

class SourceWrapper extends Readable {
  constructor(options) {
    super(options);

    this._source = getLowlevelSourceObject();

    // 每当有数据时,将其推入内部缓冲。
    this._source.ondata = (chunk) => {
      // 如果 push() 返回 `false`,则停止读取。
      if (!this.push(chunk))
        this._source.readStop();
    };

    // 当读取到尽头时,推入 `null` 表示流的结束。
    this._source.onend = () => {
      this.push(null);
    };
  }
  // 当流想推送更多数据时, `_read` 会被调用。
  _read(size) {
    this._source.readStart();
  }
}

readable.push() 只能被可读流的实现调用,且只能在 readable._read() 方法中调用。

对于非对象模式的流,如果 readable.push()chunk 参数为 undefined,则它会被当成空字符串或 buffer。 详见 readable.push('')

  • chunk <Buffer> | <Uint8Array> | <string> | <null> | <any> Chunk of data to push into the read queue. For streams not operating in object mode, chunk must be a string, Buffer or Uint8Array. For object mode streams, chunk may be any JavaScript value.
  • encoding <string> Encoding of string chunks. Must be a valid Buffer encoding, such as 'utf8' or 'ascii'.
  • Returns: <boolean> true if additional chunks of data may continue to be pushed; false otherwise.

When chunk is a Buffer, Uint8Array or string, the chunk of data will be added to the internal queue for users of the stream to consume. Passing chunk as null signals the end of the stream (EOF), after which no more data can be written.

When the Readable is operating in paused mode, the data added with readable.push() can be read out by calling the readable.read() method when the 'readable' event is emitted.

When the Readable is operating in flowing mode, the data added with readable.push() will be delivered by emitting a 'data' event.

The readable.push() method is designed to be as flexible as possible. For example, when wrapping a lower-level source that provides some form of pause/resume mechanism, and a data callback, the low-level source can be wrapped by the custom Readable instance:

// source is an object with readStop() and readStart() methods,
// and an `ondata` member that gets called when it has data, and
// an `onend` member that gets called when the data is over.

class SourceWrapper extends Readable {
  constructor(options) {
    super(options);

    this._source = getLowlevelSourceObject();

    // Every time there's data, push it into the internal buffer.
    this._source.ondata = (chunk) => {
      // if push() returns false, then stop reading from source
      if (!this.push(chunk))
        this._source.readStop();
    };

    // When the source ends, push the EOF-signaling `null` chunk
    this._source.onend = () => {
      this.push(null);
    };
  }
  // _read will be called when the stream wants to pull more data in
  // the advisory size argument is ignored in this case.
  _read(size) {
    this._source.readStart();
  }
}

The readable.push() method is intended be called only by Readable implementers, and only from within the readable._read() method.

For streams not operating in object mode, if the chunk parameter of readable.push() is undefined, it will be treated as empty string or buffer. See readable.push('') for more information.