From 2a9feac2f1cb70416aa4f9d5f5eda715839ebce0 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Mon, 18 May 2026 11:57:52 +0200 Subject: [PATCH 1/2] doc: fix promise nomenclature in `stream_iter.md` Signed-off-by: Antoine du Hamel --- doc/api/stream_iter.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/doc/api/stream_iter.md b/doc/api/stream_iter.md index 611f1bf88c7c02..ab4915cc76b247 100644 --- a/doc/api/stream_iter.md +++ b/doc/api/stream_iter.md @@ -220,7 +220,7 @@ that closes when the bucket is full: * **Pending writes (the hose)** -- writes waiting for slot space. After the consumer drains, pending writes are promoted into the now-empty - slots and their promises resolve. + slots and their promises settle. How each policy uses these buffers: @@ -430,7 +430,7 @@ The value is always non-negative. * `options` {Object} * `signal` {AbortSignal} Cancel just this operation. The signal cancels only the pending `end()` call; it does not fail the writer itself. -* Returns: {Promise\} Total bytes written. +* Returns: {Promise} Fulfills with the total number of bytes written. Signal that no more data will be written. @@ -463,9 +463,9 @@ transition with no async work to perform. * `options` {Object} * `signal` {AbortSignal} Cancel just this write operation. The signal cancels only the pending `write()` call; it does not fail the writer itself. -* Returns: {Promise\} +* Returns: {Promise} Fulfills with `undefined` when buffer space is available. -Write a chunk. The promise resolves when buffer space is available. +Write a chunk. #### `writer.writeSync(chunk)` @@ -481,7 +481,7 @@ Synchronous write. Does not block; returns `false` if backpressure is active. * `options` {Object} * `signal` {AbortSignal} Cancel just this write operation. The signal cancels only the pending `writev()` call; it does not fail the writer itself. -* Returns: {Promise\} +* Returns: {Promise} Write multiple chunks as a single batch. @@ -606,7 +606,7 @@ added: the source ends. **Default:** `false`. * `preventFail` {boolean} If `true`, do not call `writer.fail()` on error. **Default:** `false`. -* Returns: {Promise\} Total bytes written. +* Returns: {Promise} Fulfills with the total number of bytes written. Pipe a source through transforms into a writer. If the writer has a `writev(chunks)` method, entire batches are passed in a single call (enabling @@ -912,7 +912,7 @@ added: * `signal` {AbortSignal} * `limit` {number} Maximum number of bytes to consume. If the total bytes collected exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown -* Returns: {Promise\} +* Returns: {Promise} Fulfills with an array of `Uint8Array` objects. Collect all chunks as an array of `Uint8Array` values (without concatenating). @@ -928,7 +928,7 @@ added: * `signal` {AbortSignal} * `limit` {number} Maximum number of bytes to consume. If the total bytes collected exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown -* Returns: {Promise\} +* Returns: {Promise} Fulfills with an `ArrayBuffer` object. Collect all bytes into an `ArrayBuffer`. @@ -974,7 +974,7 @@ added: * `signal` {AbortSignal} * `limit` {number} Maximum number of bytes to consume. If the total bytes collected exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown -* Returns: {Promise\} +* Returns: {Promise} Fulfills with an `Uint8Array` object. Collect all bytes from a stream into a single `Uint8Array`. @@ -1024,7 +1024,7 @@ added: * `signal` {AbortSignal} * `limit` {number} Maximum number of bytes to consume. If the total bytes collected exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown -* Returns: {Promise\} +* Returns: {Promise} Fulfills with a `string`. Collect all bytes and decode as text. @@ -1070,11 +1070,11 @@ added: --> * `drainable` {Object} An object implementing the drainable protocol. -* Returns: {Promise\|null} +* Returns: {Promise|null} -Wait for a drainable writer's backpressure to clear. Returns a promise that -resolves to `true` when the writer can accept more data, or `null` if the -object does not implement the drainable protocol. +Wait for a drainable writer's backpressure to clear. Returns `null` if +the object does not implement the drainable protocol, or a promise that +fulfills with `true` when the writer can accept more data. ```mjs import { push, ondrain, text } from 'node:stream/iter'; @@ -1794,8 +1794,8 @@ text(consumer).then(console.log); // 'hello' * Value: `Symbol.for('Stream.drainableProtocol')` Implement to make a writer compatible with `ondrain()`. The method should -return a promise that resolves when backpressure clears, or `null` if no -backpressure. +return `null` if no backpressure, or a promise that fulfills with a truthy value +when backpressure clears. ```mjs import { ondrain } from 'node:stream/iter'; @@ -2001,8 +2001,8 @@ console.log(textSync(consumer)); // 'hello' The value must be a function that converts the object into a streamable value. When the object is encountered anywhere in the streaming pipeline (as a source passed to `from()`, or as a value returned from a transform), this method is -called to produce the actual data. It may return (or resolve to) any streamable -value: a string, `Uint8Array`, `AsyncIterable`, `Iterable`, or another streamable +called to produce the actual data. It may return any value that resolves to: +a string, `Uint8Array`, `AsyncIterable`, `Iterable`, or another streamable object. ```mjs From 2498b475e983e7d93546d308eff2b03744cee4f0 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Mon, 18 May 2026 19:26:13 +0200 Subject: [PATCH 2/2] fixup! doc: fix promise nomenclature in `stream_iter.md` --- doc/api/fs.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index c5e908aaa39f6c..170238d07e8107 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1034,16 +1034,16 @@ added: Set this to match the reader's `chunkSize` for optimal `pipeTo()` performance. **Default:** `131072` (128 KB). * Returns: {Object} - * `write(chunk[, options])` {Function} Returns {Promise\}. + * `write(chunk[, options])` {Function} Returns {Promise}. Accepts `Uint8Array`, `Buffer`, or string (UTF-8 encoded). * `chunk` {Buffer|TypedArray|DataView|string} * `options` {Object} * `signal` {AbortSignal} If the signal is already aborted, the write rejects with `AbortError` without performing I/O. - * `writev(chunks[, options])` {Function} Returns {Promise\}. Uses + * `writev(chunks[, options])` {Function} Returns {Promise}. Uses scatter/gather I/O via a single `writev()` syscall. Accepts mixed `Uint8Array`/string arrays. - * `chunks` {Array\} + * `chunks` {Buffer\[]|TypedArray\[]|DataView\[]|string\[]} * `options` {Object} * `signal` {AbortSignal} If the signal is already aborted, the write rejects with `AbortError` without performing I/O. @@ -1055,10 +1055,10 @@ added: * `chunk` {Buffer|TypedArray|DataView|string} * `writevSync(chunks)` {Function} Returns {boolean}. Synchronous batch write. Same fallback semantics as `writeSync()`. - * `chunks` {Array\} - * `end([options])` {Function} Returns {Promise\} total bytes - written. Idempotent: returns `totalBytesWritten` if already closed, - returns the pending promise if already closing. Rejects if the writer + * `chunks` {Buffer\[]|TypedArray\[]|DataView\[]|string\[]} + * `end([options])` {Function} Returns {Promise}, fulfills with the total + number of bytes written. Idempotent: returns `totalBytesWritten` if already + closed, returns the pending promise if already closing. Rejects if the writer is in an errored state. * `options` {Object} * `signal` {AbortSignal} If the signal is already aborted, `end()` @@ -2815,7 +2815,7 @@ changes: * `filter` {Function} Function to filter copied files/directories. Return `true` to copy the item, `false` to ignore it. When ignoring a directory, all of its contents will be skipped as well. Can also return a `Promise` - that resolves to `true` or `false` **Default:** `undefined`. + that fulfills with `true` or `false`. **Default:** `undefined`. * `src` {string} source path to copy. * `dest` {string} destination path to copy to. * Returns: {boolean|Promise} A value that is coercible to `boolean` or