Skip to content

Document highWaterMark option of events.on() #52078

Closed
@ehmicky

Description

@ehmicky

What is the problem this feature will solve?

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

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    eventsIssues and PRs related to the events subsystem / EventEmitter.feature requestIssues that request new features to be added to Node.js.streamIssues and PRs related to the stream subsystem.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions