From 7cfa1bee418696c1c97c1f2466520ab4f4cc8791 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 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