Node.js stream.Readable.unshift(chunk[, encoding])用法及代码示例

readable.unshift(chunk[, encoding])

参数

• chunk <Buffer> | <Uint8Array> | <string> | <null> | <any> 要取消转移到读取队列的数据块。对于不在对象模式下运行的流，chunk 必须是字符串、Buffer、Uint8Array 或 null。对于对象模式流，chunk 可以是任何 JavaScript 值。
• encoding <string> 字符串块的编码。必须是有效的 Buffer 编码，例如 'utf8' 或 'ascii' 。

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

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

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

使用stream.unshift() 的开发人员通常应该考虑改用 Transform 流。有关详细信息，请参阅API for stream implementers 部分。

// 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() 实现中)，这可能会导致意外结果。在使用立即 stream.push('') 调用 readable.unshift() 之后将适当地重置读取状态，但是最好在执行读取的过程中简单地避免调用 readable.unshift()。