From dc2e838cbc151040ee10a3399f358a785f69a7b0 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Thu, 31 Dec 2020 15:02:48 -0800 Subject: [PATCH] doc: clarify undocumented stream properties Fixes: https://github.com/nodejs/node/issues/28592 Signed-off-by: James M Snell --- doc/api/stream.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index e0e1145dad1048..e3cc88c2e32c1f 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -75,8 +75,7 @@ object mode is not safe. Both [`Writable`][] and [`Readable`][] streams will store data in an internal -buffer that can be retrieved using `writable.writableBuffer` or -`readable.readableBuffer`, respectively. +buffer. The amount of data potentially buffered depends on the `highWaterMark` option passed into the stream's constructor. For normal streams, the `highWaterMark` @@ -120,6 +119,11 @@ writing data *to* the socket. Because data may be written to the socket at a faster or slower rate than data is received, each side should operate (and buffer) independently of the other. +The mechanics of the internal buffering are an internal implementation detail +and may be changed at any time. However, for certain advanced implementations, +the internal buffers can be retrieved using `writable.writableBuffer` or +`readable.readableBuffer`. Use of these undocumented properties is discouraged. + ## API for stream consumers