nodejs / nodejs/learn

Revise backpressure examples in streams documentation

Open
#94 0 comments 0 reactions 0 assignees View on GitHub

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

https://github.com/nodejs/learn/pull/90

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.