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()。