Revise backpressure examples in streams documentation
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29
- Forks
- 165
- Avg merge
- 1d 18h
- Merged PRs (30d)
- 2
Description
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the current streams backpressure documentation and its compression example, then inspect the discussion and referenced pull request 90 for context. Done means the documentation contrasts Node.js buffering and streaming APIs, includes CommonJS and ESM examples, explains ignored backpressure and memory consequences, and removes the archive-comparison note.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100