From d87476ec015de90dca4f423a023bd4d362f2f854 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Wed, 2 Sep 2026 13:49:14 +0200 Subject: [PATCH 1/2] doc: clarify return type of `fs.mkdtemp*` Signed-off-by: Antoine du Hamel Co-authored-by: Hamid Reza Ghavami --- doc/api/fs.md | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 1ad902ad5fb6..3c119d10a565 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1652,8 +1652,10 @@ changes: * `prefix` {string|Buffer|URL} * `options` {string|Object} * `encoding` {string} **Default:** `'utf8'` -* Returns: {Promise} Fulfills with a string containing the file system path - of the newly created temporary directory. +* Returns: {Promise} Fulfills with the created directory path. + If `encoding` is `'buffer'`, then the resulting directory + path is returned as a {Buffer}. Otherwise, the path is returned as a + {string} using the specified encoding. Creates a unique temporary directory. A unique directory name is generated by appending six random characters to the end of the provided `prefix`. Due to @@ -1692,14 +1694,15 @@ added: v24.4.0 * `options` {string|Object} * `encoding` {string} **Default:** `'utf8'` * Returns: {Promise} Fulfills with a Promise for an async-disposable Object: - * `path` {string} The path of the created directory. + * `path` {string|Buffer} The path of the created directory. * `remove` {AsyncFunction} A function which removes the created directory. * `[Symbol.asyncDispose]` {AsyncFunction} The same as `remove`. The resulting Promise holds an async-disposable object whose `path` property -holds the created directory path. When the object is disposed, the directory -and its contents will be removed asynchronously if it still exists. If the -directory cannot be deleted, disposal will throw an error. The object has an +holds the created directory path. If `encoding` is `'buffer'`, the `path` will +also be a {Buffer}, otherwise a {string}. When the object is disposed, the +directory and its contents will be removed asynchronously if it still exists. If +the directory cannot be deleted, disposal will throw an error. The object has an async `remove()` method which will perform the same task. Both this function and the disposal function on the resulting object are @@ -4008,7 +4011,7 @@ changes: * `encoding` {string} **Default:** `'utf8'` * `callback` {Function} * `err` {Error} - * `directory` {string} + * `directory` {string|Buffer} Creates a unique temporary directory. @@ -4018,12 +4021,15 @@ inconsistencies, avoid trailing `X` characters in `prefix`. Some platforms, notably the BSDs, can return more than six random characters, and replace trailing `X` characters in `prefix` with random characters. -The created directory path is passed as a string to the callback's second -parameter. - The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use. +The created directory path is passed to the callback's second parameter. If +`encoding` is `'buffer'`, then the resulting directory path is passed as a +{Buffer}. Otherwise, the path is passed as a {string} using the specified +encoding. + + ```mjs import { mkdtemp } from 'node:fs'; import { join } from 'node:path'; @@ -6500,9 +6506,11 @@ changes: * `prefix` {string|Buffer|URL} * `options` {string|Object} * `encoding` {string} **Default:** `'utf8'` -* Returns: {string} +* Returns: {string|Buffer} -Returns the created directory path. +Returns the created directory path. If `encoding` is `'buffer'`, then the +resulting directory path is returned as a {Buffer}. Otherwise, the path +is returned as a {string} using the specified encoding. For detailed information, see the documentation of the asynchronous version of this API: [`fs.mkdtemp()`][]. @@ -6520,15 +6528,15 @@ added: v24.4.0 * `options` {string|Object} * `encoding` {string} **Default:** `'utf8'` * Returns: {Object} A disposable object: - * `path` {string} The path of the created directory. + * `path` {string|Buffer} The path of the created directory. * `remove` {Function} A function which removes the created directory. * `[Symbol.dispose]` {Function} The same as `remove`. Returns a disposable object whose `path` property holds the created directory -path. When the object is disposed, the directory and its contents will be -removed if it still exists. If the directory cannot be deleted, disposal will -throw an error. The object has a `remove()` method which will perform the same -task. +path. If `encoding` is `'buffer'`, the `path` will be a {Buffer}. When the +object is disposed, the directory and its contents will be removed if it still +exists. If the directory cannot be deleted, disposal will throw an error. The +object has a `remove()` method which will perform the same task. See the [MDN documentation on `using` statements][`using`] for more information about explicit resource management. From e94cf7ba26f73b8ce4996e9742d981eb5fe2c15f Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Wed, 2 Sep 2026 13:59:12 +0200 Subject: [PATCH 2/2] fixup! doc: clarify return type of `fs.mkdtemp*` --- doc/api/fs.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 3c119d10a565..9be67ded1f50 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -4029,7 +4029,6 @@ The created directory path is passed to the callback's second parameter. If {Buffer}. Otherwise, the path is passed as a {string} using the specified encoding. - ```mjs import { mkdtemp } from 'node:fs'; import { join } from 'node:path';