From 1f4ac06ce57ac3ae1fac16e6412b36ba227060b3 Mon Sep 17 00:00:00 2001
From: umuoy1 <burningdian@gmail.com>
Date: Mon, 20 Jul 2026 16:27:01 +0800
Subject: [PATCH] doc: correct default highWaterMark values

File write streams inherit the default byte-stream highWaterMark.
The fixed 16 KiB value became stale when that default changed.
Also document the Windows-specific byte-stream default.

Signed-off-by: umuoy1 <burningdian@gmail.com>
---
 doc/api/fs.md     | 13 +++++++++++--
 doc/api/stream.md | 10 ++++++----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 9cb84007b3b815..4e34c3265a082c 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -323,6 +323,9 @@ fd.createReadStream({ start: 90, end: 99 });
 <!-- YAML
 added: v16.11.0
 changes:
+  - version: v22.0.0
+    pr-url: https://github.com/nodejs/node/pull/52037
+    description: bump default highWaterMark.
   - version:
     - v21.0.0
     - v20.10.0
@@ -335,7 +338,8 @@ changes:
   * `autoClose` {boolean} **Default:** `true`
   * `emitClose` {boolean} **Default:** `true`
   * `start` {integer}
-  * `highWaterMark` {number} **Default:** `16384`
+  * `highWaterMark` {number} **Default:** See
+    [`stream.getDefaultHighWaterMark()`][].
   * `flush` {boolean} If `true`, the underlying file descriptor is flushed
     prior to closing it. **Default:** `false`.
 * Returns: {fs.WriteStream}
@@ -3057,6 +3061,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+  - version: v22.0.0
+    pr-url: https://github.com/nodejs/node/pull/52037
+    description: bump default highWaterMark.
   - version:
     - v21.0.0
     - v20.10.0
@@ -3114,7 +3121,8 @@ changes:
   * `start` {integer}
   * `fs` {Object|null} **Default:** `null`
   * `signal` {AbortSignal|null} **Default:** `null`
-  * `highWaterMark` {number} **Default:** `16384`
+  * `highWaterMark` {number} **Default:** See
+    [`stream.getDefaultHighWaterMark()`][].
   * `flush` {boolean} If `true`, the underlying file descriptor is flushed
     prior to closing it. **Default:** `false`.
 * Returns: {fs.WriteStream}
@@ -9330,6 +9338,7 @@ the file contents.
 [`minimatch`]: https://github.com/isaacs/minimatch
 [`node:stream/iter`]: stream_iter.md
 [`statfs.bsize`]: #statfsbsize
+[`stream.getDefaultHighWaterMark()`]: stream.md#streamgetdefaulthighwatermarkobjectmode
 [`stream/iter pipeTo()`]: stream_iter.md#pipetosource-transforms-writer
 [`stream/iter pull()`]: stream_iter.md#pullsource-transforms-options
 [`stream/iter pullSync()`]: stream_iter.md#pullsyncsource-transforms
diff --git a/doc/api/stream.md b/doc/api/stream.md
index 2f7fd7961a7334..d1b83f851f38df 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -3637,8 +3637,9 @@ added:
 * `objectMode` {boolean}
 * Returns: {integer}
 
-Returns the default highWaterMark used by streams.
-Defaults to `65536` (64 KiB), or `16` for `objectMode`.
+Returns the default highWaterMark used by streams. Defaults to `16` for
+`objectMode`. For byte streams, it defaults to `65536` (64 KiB) on non-Windows
+platforms and `16384` (16 KiB) on Windows.
 
 ### `stream.setDefaultHighWaterMark(objectMode, value)`
 
@@ -3768,7 +3769,7 @@ changes:
 * `options` {Object}
   * `highWaterMark` {number} Buffer level when
     [`stream.write()`][stream-write] starts returning `false`. **Default:**
-    `65536` (64 KiB), or `16` for `objectMode` streams.
+    See [`stream.getDefaultHighWaterMark()`][].
   * `decodeStrings` {boolean} Whether to encode `string`s passed to
     [`stream.write()`][stream-write] to `Buffer`s (with the encoding
     specified in the [`stream.write()`][stream-write] call) before passing
@@ -4142,7 +4143,7 @@ changes:
 * `options` {Object}
   * `highWaterMark` {number} The maximum [number of bytes][hwm-gotcha] to store
     in the internal buffer before ceasing to read from the underlying resource.
-    **Default:** `65536` (64 KiB), or `16` for `objectMode` streams.
+    **Default:** See [`stream.getDefaultHighWaterMark()`][].
   * `encoding` {string} If specified, then buffers will be decoded to
     strings using the specified encoding. **Default:** `null`.
   * `objectMode` {boolean} Whether this stream should behave
@@ -5083,6 +5084,7 @@ contain multi-byte characters.
 [`stream.cork()`]: #writablecork
 [`stream.duplexPair()`]: #streamduplexpairoptions
 [`stream.finished()`]: #streamfinishedstream-options-callback
+[`stream.getDefaultHighWaterMark()`]: #streamgetdefaulthighwatermarkobjectmode
 [`stream.pipe()`]: #readablepipedestination-options
 [`stream.pipeline()`]: #streampipelinesource-transforms-destination-callback
 [`stream.uncork()`]: #writableuncork