Problem
The current backpressure documentation contains examples that may be confusing or technically inaccurate.
Specifically:
The compression example uses the zip command in a way that does not clearly demonstrate the role of Node.js stream backpressure.
It implies that using a command-line compression utility loads the entire file into memory, which is generally not true and depends on the implementation.
The example focuses on comparing archive outputs rather than illustrating the memory and throughput implications of buffering versus streaming.
See discussion: https://stackoverflow.com/questions/79821132/node-js-back-pressure-documentation-whats-the-relevance-of-their-example
Proposed Solution
Update the examples to use Node.js APIs directly:
Replace the current zip example with fs.readFileSync() + zlib.gzipSync() examples (CommonJS and ESM variants) to demonstrate a buffering approach.
Add a corresponding streaming example using Node.js streams and zlib.createGzip().
Include an explicit example showing a stream implementation that ignores backpressure and explain why it can lead to excessive memory consumption or out-of-memory conditions.
Remove the note about comparing the resulting archives, as it does not help explain backpressure behavior.
Motivation
The primary goal of the backpressure documentation should be to help readers understand how streams regulate data flow and memory usage. Using examples based entirely on Node.js APIs makes the comparison clearer
#90
Problem
The current backpressure documentation contains examples that may be confusing or technically inaccurate.
Specifically:
The compression example uses the zip command in a way that does not clearly demonstrate the role of Node.js stream backpressure.
It implies that using a command-line compression utility loads the entire file into memory, which is generally not true and depends on the implementation.
The example focuses on comparing archive outputs rather than illustrating the memory and throughput implications of buffering versus streaming.
See discussion: https://stackoverflow.com/questions/79821132/node-js-back-pressure-documentation-whats-the-relevance-of-their-example
Proposed Solution
Update the examples to use Node.js APIs directly:
Replace the current zip example with fs.readFileSync() + zlib.gzipSync() examples (CommonJS and ESM variants) to demonstrate a buffering approach.
Add a corresponding streaming example using Node.js streams and zlib.createGzip().
Include an explicit example showing a stream implementation that ignores backpressure and explain why it can lead to excessive memory consumption or out-of-memory conditions.
Remove the note about comparing the resulting archives, as it does not help explain backpressure behavior.
Motivation
The primary goal of the backpressure documentation should be to help readers understand how streams regulate data flow and memory usage. Using examples based entirely on Node.js APIs makes the comparison clearer
#90