@@ -667,6 +667,19 @@ changes: |
667 | 667 | `false`. |
668 | 668 | * `fd` {number} If specified, wrap around an existing socket with |
669 | 669 | the given file descriptor, otherwise a new socket will be created. |
| 670 | + * `onread` {Object} If specified, incoming data is stored in a single `buffer` |
| 671 | + and passed to the supplied `callback` when data arrives on the socket. |
| 672 | + This will cause the streaming functionality to not provide any data. |
| 673 | + The socket will emit events like `'error'`, `'end'`, and `'close'` |
| 674 | + as usual. Methods like `pause()` and `resume()` will also behave as |
| 675 | + expected. |
| 676 | + * `buffer` {Buffer|Uint8Array|Function} Either a reusable chunk of memory to |
| 677 | + use for storing incoming data or a function that returns such. |
| 678 | + * `callback` {Function} This function is called for every chunk of incoming |
| 679 | + data. Two arguments are passed to it: the number of bytes written to |
| 680 | + `buffer` and a reference to `buffer`. Return `false` from this function to |
| 681 | + implicitly `pause()` the socket. This function will be executed in the |
| 682 | + global context. |
670 | 683 | * `readable` {boolean} Allow reads on the socket when an `fd` is passed, |
671 | 684 | otherwise ignored. **Default:** `false`. |
672 | 685 | * `signal` {AbortSignal} An Abort signal that may be used to destroy the |
@@ -1038,39 +1051,6 @@ For [IPC][] connections, available `options` are: |
1038 | 1051 | See [Identifying paths for IPC connections][]. If provided, the TCP-specific |
1039 | 1052 | options above are ignored. |
1040 | 1053 |
|
1041 | | -For both types, available `options` include: |
1042 | | - |
1043 | | -* `onread` {Object} If specified, incoming data is stored in a single `buffer` |
1044 | | - and passed to the supplied `callback` when data arrives on the socket. |
1045 | | - This will cause the streaming functionality to not provide any data. |
1046 | | - The socket will emit events like `'error'`, `'end'`, and `'close'` |
1047 | | - as usual. Methods like `pause()` and `resume()` will also behave as |
1048 | | - expected. |
1049 | | - * `buffer` {Buffer|Uint8Array|Function} Either a reusable chunk of memory to |
1050 | | - use for storing incoming data or a function that returns such. |
1051 | | - * `callback` {Function} This function is called for every chunk of incoming |
1052 | | - data. Two arguments are passed to it: the number of bytes written to |
1053 | | - `buffer` and a reference to `buffer`. Return `false` from this function to |
1054 | | - implicitly `pause()` the socket. This function will be executed in the |
1055 | | - global context. |
1056 | | - |
1057 | | -Following is an example of a client using the `onread` option: |
1058 | | - |
1059 | | -```js |
1060 | | -const net = require('node:net'); |
1061 | | -net.connect({ |
1062 | | - port: 80, |
1063 | | - onread: { |
1064 | | - // Reuses a 4KiB Buffer for every read from the socket. |
1065 | | - buffer: Buffer.alloc(4 * 1024), |
1066 | | - callback: function(nread, buf) { |
1067 | | - // Received data is available in `buf` from 0 to `nread`. |
1068 | | - console.log(buf.toString('utf8', 0, nread)); |
1069 | | - }, |
1070 | | - }, |
1071 | | -}); |
1072 | | -``` |
1073 | | - |
1074 | 1054 | #### `socket.connect(path[, connectListener])` |
1075 | 1055 |
|
1076 | 1056 | * `path` {string} Path the client should connect to. See |
@@ -1573,6 +1553,26 @@ To connect on the socket `/tmp/echo.sock`: |
1573 | 1553 | const client = net.createConnection({ path: '/tmp/echo.sock' }); |
1574 | 1554 | ``` |
1575 | 1555 |
|
| 1556 | +Following is an example of a client using the `port` and `onread` |
| 1557 | +option. In this case, the `onread` option will be only used to call |
| 1558 | +`new net.Socket([options])` and the `port` option will be used to |
| 1559 | +call `socket.connect(options[, connectListener])`. |
| 1560 | + |
| 1561 | +```js |
| 1562 | +const net = require('node:net'); |
| 1563 | +net.createConnection({ |
| 1564 | + port: 80, |
| 1565 | + onread: { |
| 1566 | + // Reuses a 4KiB Buffer for every read from the socket. |
| 1567 | + buffer: Buffer.alloc(4 * 1024), |
| 1568 | + callback: function(nread, buf) { |
| 1569 | + // Received data is available in `buf` from 0 to `nread`. |
| 1570 | + console.log(buf.toString('utf8', 0, nread)); |
| 1571 | + }, |
| 1572 | + }, |
| 1573 | +}); |
| 1574 | +``` |
| 1575 | + |
1576 | 1576 | ### `net.createConnection(path[, connectListener])` |
1577 | 1577 |
|
1578 | 1578 | <!-- YAML |
|