Document highWaterMark option of events.on()

[ehmicky]

What is the problem this feature will solve?

#41276 added the highWaterMark option to events.on() in Node 20.0.0.

node/lib/events.js

Line 1067 in 1abff07

const highWatermark = options.highWatermark ?? NumberMAX_SAFE_INTEGER;

That option is quite useful when using on(stream, 'data'). on() uses an internal buffer. If too many events happen at once, this buffer can potentially consume lots of memory. When the highWaterMark option is used, the stream is temporarily paused when this happens. Once the buffer is empty, the stream is resumed. Basically, this makes on() stream-friendly.

What is the feature you are proposing to solve the problem?

Document the highWaterMark option of stream.on().

What alternatives have you considered?

An alternative would be, if a Readable or Duplex is passed to on(), to set the highWaterMark option to stream.readableHighWaterMark. This would enable the above streaming behavior by default, when a stream is used.

In many cases, users will just want to enable this feature and use the same highWaterMark as the stream. So enabling this by default for stream might remove the need to expose the option.