From 71b94e1ff7e7fa6a1047300773a0efb2eb69bf75 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 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes: https://github.com/nodejs/node/issues/28592 Signed-off-by: James M Snell PR-URL: https://github.com/nodejs/node/pull/36715 Reviewed-By: Matteo Collina Reviewed-By: Rich Trott Reviewed-By: Robert Nagy Reviewed-By: Michaël Zasso --- 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 baa72e565e8774..8d67462c1a2c41 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -65,8 +65,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` @@ -110,6 +109,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