🤖 Merge PR DefinitelyTyped#74817 Fix JSDoc for overloaded Node stream APIs by @pimterry

Author: pimterry

types/node/net.d.ts

@@ -116,9 +116,14 @@ declare module "node:net" {
          * See `Writable` stream `write()` method for more
          * information.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          */
         write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean;
+        /**
+         * Sends data on the socket, with an explicit encoding for string data.
+         * @see {@link Socket.write} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         */
         write(str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
         /**
          * Initiate a connection on a given socket.
@@ -358,12 +363,26 @@ declare module "node:net" {
          *
          * See `writable.end()` for further details.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          * @param callback Optional callback for when the socket is finished.
          * @return The socket itself.
          */
         end(callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(buffer: Uint8Array | string, callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(str: Uint8Array | string, encoding?: BufferEncoding, callback?: () => void): this;
         // #region InternalEventEmitter
         addListener<E extends keyof SocketEventMap>(eventName: E, listener: (...args: SocketEventMap[E]) => void): this;

types/node/stream.d.ts

@@ -899,11 +899,20 @@ declare module "node:stream" {
              * @since v0.9.4
              * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
              * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
-             * @param [encoding='utf8'] The encoding, if `chunk` is a string.
              * @param callback Callback for when this chunk of data is flushed.
              * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
              */
             write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean;
+            /**
+             * Writes data to the stream, with an explicit encoding for string data.
+             * @see {@link Writable.write} for full details.
+             * @since v0.9.4
+             * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
+             * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
+             * @param encoding The encoding, if `chunk` is a string.
+             * @param callback Callback for when this chunk of data is flushed.
+             * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
+             */
             write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean;
             /**
              * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream.
@@ -928,13 +937,27 @@ declare module "node:stream" {
              * // Writing more now is not allowed!
              * ```
              * @since v0.9.4
+             * @param cb Callback for when the stream is finished.
+             */
+            end(cb?: () => void): this;
+            /**
+             * Signals that no more data will be written, with one final chunk of data.
+             * @see {@link Writable.end} for full details.
+             * @since v0.9.4
              * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
              * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
-             * @param encoding The encoding if `chunk` is a string
-             * @param callback Callback for when the stream is finished.
+             * @param cb Callback for when the stream is finished.
              */
-            end(cb?: () => void): this;
             end(chunk: any, cb?: () => void): this;
+            /**
+             * Signals that no more data will be written, with one final chunk of data.
+             * @see {@link Writable.end} for full details.
+             * @since v0.9.4
+             * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
+             * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
+             * @param encoding The encoding if `chunk` is a string
+             * @param cb Callback for when the stream is finished.
+             */
             end(chunk: any, encoding: BufferEncoding, cb?: () => void): this;
             /**
              * The `writable.cork()` method forces all written data to be buffered in memory.

types/node/v20/net.d.ts

@@ -111,9 +111,14 @@ declare module "net" {
          * See `Writable` stream `write()` method for more
          * information.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          */
         write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean;
+        /**
+         * Sends data on the socket, with an explicit encoding for string data.
+         * @see {@link Socket.write} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         */
         write(str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
         /**
          * Initiate a connection on a given socket.
@@ -353,12 +358,26 @@ declare module "net" {
          *
          * See `writable.end()` for further details.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          * @param callback Optional callback for when the socket is finished.
          * @return The socket itself.
          */
         end(callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(buffer: Uint8Array | string, callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(str: Uint8Array | string, encoding?: BufferEncoding, callback?: () => void): this;
         /**
          * events.EventEmitter

types/node/v20/stream.d.ts

@@ -865,11 +865,20 @@ declare module "stream" {
              * @since v0.9.4
              * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
              * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
-             * @param [encoding='utf8'] The encoding, if `chunk` is a string.
              * @param callback Callback for when this chunk of data is flushed.
              * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
              */
             write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean;
+            /**
+             * Writes data to the stream, with an explicit encoding for string data.
+             * @see {@link Writable.write} for full details.
+             * @since v0.9.4
+             * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
+             * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
+             * @param encoding The encoding, if `chunk` is a string.
+             * @param callback Callback for when this chunk of data is flushed.
+             * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
+             */
             write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean;
             /**
              * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream.
@@ -894,13 +903,27 @@ declare module "stream" {
              * // Writing more now is not allowed!
              * ```
              * @since v0.9.4
+             * @param cb Callback for when the stream is finished.
+             */
+            end(cb?: () => void): this;
+            /**
+             * Signals that no more data will be written, with one final chunk of data.
+             * @see {@link Writable.end} for full details.
+             * @since v0.9.4
              * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
              * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
-             * @param encoding The encoding if `chunk` is a string
-             * @param callback Callback for when the stream is finished.
+             * @param cb Callback for when the stream is finished.
              */
-            end(cb?: () => void): this;
             end(chunk: any, cb?: () => void): this;
+            /**
+             * Signals that no more data will be written, with one final chunk of data.
+             * @see {@link Writable.end} for full details.
+             * @since v0.9.4
+             * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
+             * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
+             * @param encoding The encoding if `chunk` is a string
+             * @param cb Callback for when the stream is finished.
+             */
             end(chunk: any, encoding: BufferEncoding, cb?: () => void): this;
             /**
              * The `writable.cork()` method forces all written data to be buffered in memory.

types/node/v22/net.d.ts

@@ -108,9 +108,14 @@ declare module "net" {
          * See `Writable` stream `write()` method for more
          * information.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          */
         write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean;
+        /**
+         * Sends data on the socket, with an explicit encoding for string data.
+         * @see {@link Socket.write} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         */
         write(str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
         /**
          * Initiate a connection on a given socket.
@@ -350,12 +355,26 @@ declare module "net" {
          *
          * See `writable.end()` for further details.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          * @param callback Optional callback for when the socket is finished.
          * @return The socket itself.
          */
         end(callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(buffer: Uint8Array | string, callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(str: Uint8Array | string, encoding?: BufferEncoding, callback?: () => void): this;
         /**
          * events.EventEmitter

types/node/v22/stream.d.ts

@@ -858,11 +858,20 @@ declare module "stream" {
              * @since v0.9.4
              * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
              * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
-             * @param [encoding='utf8'] The encoding, if `chunk` is a string.
              * @param callback Callback for when this chunk of data is flushed.
              * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
              */
             write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean;
+            /**
+             * Writes data to the stream, with an explicit encoding for string data.
+             * @see {@link Writable.write} for full details.
+             * @since v0.9.4
+             * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
+             * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
+             * @param encoding The encoding, if `chunk` is a string.
+             * @param callback Callback for when this chunk of data is flushed.
+             * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
+             */
             write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean;
             /**
              * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream.
@@ -887,13 +896,27 @@ declare module "stream" {
              * // Writing more now is not allowed!
              * ```
              * @since v0.9.4
+             * @param cb Callback for when the stream is finished.
+             */
+            end(cb?: () => void): this;
+            /**
+             * Signals that no more data will be written, with one final chunk of data.
+             * @see {@link Writable.end} for full details.
+             * @since v0.9.4
              * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
              * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
-             * @param encoding The encoding if `chunk` is a string
-             * @param callback Callback for when the stream is finished.
+             * @param cb Callback for when the stream is finished.
              */
-            end(cb?: () => void): this;
             end(chunk: any, cb?: () => void): this;
+            /**
+             * Signals that no more data will be written, with one final chunk of data.
+             * @see {@link Writable.end} for full details.
+             * @since v0.9.4
+             * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
+             * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
+             * @param encoding The encoding if `chunk` is a string
+             * @param cb Callback for when the stream is finished.
+             */
             end(chunk: any, encoding: BufferEncoding, cb?: () => void): this;
             /**
              * The `writable.cork()` method forces all written data to be buffered in memory.

types/node/v24/net.d.ts

@@ -105,9 +105,14 @@ declare module "net" {
          * See `Writable` stream `write()` method for more
          * information.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          */
         write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean;
+        /**
+         * Sends data on the socket, with an explicit encoding for string data.
+         * @see {@link Socket.write} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         */
         write(str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
         /**
          * Initiate a connection on a given socket.
@@ -347,12 +352,26 @@ declare module "net" {
          *
          * See `writable.end()` for further details.
          * @since v0.1.90
-         * @param [encoding='utf8'] Only used when data is `string`.
          * @param callback Optional callback for when the socket is finished.
          * @return The socket itself.
          */
         end(callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(buffer: Uint8Array | string, callback?: () => void): this;
+        /**
+         * Half-closes the socket, with one final chunk of data.
+         * @see {@link Socket.end} for full details.
+         * @since v0.1.90
+         * @param [encoding='utf8'] Only used when data is `string`.
+         * @param callback Optional callback for when the socket is finished.
+         * @return The socket itself.
+         */
         end(str: Uint8Array | string, encoding?: BufferEncoding, callback?: () => void): this;
         /**
          * events.EventEmitter