readable.unshift(chunk[, encoding])

• chunk <Buffer> | <TypedArray> | <DataView> | <string> | <null> | <any> 要取消转移到读取队列的数据块。对于不在对象模式下运行的流，chunk 必须是 <string>、<Buffer>、<TypedArray>、<DataView> 或 null。对于对象模式流，chunk 可以是任何 JavaScript 值。

  ¥chunk <Buffer> | <TypedArray> | <DataView> | <string> | <null> | <any> Chunk of data to unshift onto the read queue. For streams not operating in object mode, chunk must be a <string>, <Buffer>, <TypedArray>, <DataView> or null. For object mode streams, chunk may be any JavaScript value.

• encoding <string> 字符串块的编码。必须是有效的 Buffer 编码，例如 'utf8' 或 'ascii'。

  ¥encoding <string> Encoding of string chunks. Must be a valid Buffer encoding, such as 'utf8' or 'ascii'.

将 chunk 作为 null 传递表示流结束 (EOF)，其行为与 readable.push(null) 相同，之后无法写入更多数据。EOF 信号放在缓冲区的末尾，任何缓冲的数据仍将被刷新。

¥Passing chunk as null signals the end of the stream (EOF) and behaves the same as readable.push(null), after which no more data can be written. The EOF signal is put at the end of the buffer and any buffered data will still be flushed.

readable.unshift() 方法将一大块数据推回内部缓冲区。这在某些情况下很有用，在这种情况下，流正在被需要 "un-consume" 乐观地从源中提取的一些数据的代码使用，以便可以将数据传递给其他方。

¥The readable.unshift() method pushes a chunk of data back into the internal buffer. This is useful in certain situations where a stream is being consumed by code that needs to "un-consume" some amount of data that it has optimistically pulled out of the source, so that the data can be passed on to some other party.

在触发 'end' 事件后不能调用 stream.unshift(chunk) 方法，否则将抛出运行时错误。

¥The stream.unshift(chunk) method cannot be called after the 'end' event has been emitted or a runtime error will be thrown.

经常使用 stream.unshift() 的开发者应该考虑改用 Transform 流。有关详细信息，请参阅 流实现者的 API 部分。

¥Developers using stream.unshift() often should consider switching to use of a Transform stream instead. See the API for stream implementers section for more information.

// Pull off a header delimited by \n\n.
// Use unshift() if we get too much.
// Call the callback with (error, header, stream).
const { StringDecoder } = require('node:string_decoder');
function parseHeader(stream, callback) {
  stream.on('error', callback);
  stream.on('readable', onReadable);
  const decoder = new StringDecoder('utf8');
  let header = '';
  function onReadable() {
    let chunk;
    while (null !== (chunk = stream.read())) {
      const str = decoder.write(chunk);
      if (str.includes('\n\n')) {
        // Found the header boundary.
        const split = str.split(/\n\n/);
        header += split.shift();
        const remaining = split.join('\n\n');
        const buf = Buffer.from(remaining, 'utf8');
        stream.removeListener('error', callback);
        // Remove the 'readable' listener before unshifting.
        stream.removeListener('readable', onReadable);
        if (buf.length)
          stream.unshift(buf);
        // Now the body of the message can be read from the stream.
        callback(null, header, stream);
        return;
      }
      // Still reading the header.
      header += str;
    }
  }
} 拷贝

与 stream.push(chunk) 不同，stream.unshift(chunk) 不会通过重置流的内部读取状态来结束读取过程。如果在读取期间调用 readable.unshift()（即从自定义流上的 stream._read() 实现中调用），这可能会导致意外结果。在调用 readable.unshift() 后立即调用 stream.push('') 将适当地重置读取状态，但是最好避免在执行读取过程中调用 readable.unshift()。

¥Unlike stream.push(chunk), stream.unshift(chunk) will not end the reading process by resetting the internal reading state of the stream. This can cause unexpected results if readable.unshift() is called during a read (i.e. from within a stream._read() implementation on a custom stream). Following the call to readable.unshift() with an immediate stream.push('') will reset the reading state appropriately, however it is best to simply avoid calling readable.unshift() while in the process of performing a read.