fs: add mkstemp()

Add fs.mkstemp(), fs.mkstempSync() and fsPromises.mkstemp(), which
create and open a unique temporary file in one operation. They expose
uv_fs_mkstemp(), the file counterpart of the function behind
fs.mkdtemp().

The callback and sync versions return the path and a file descriptor,
the promise version returns the path and a FileHandle.

libuv clears the path of the request when mkstemp() fails, so the
template is saved in the request and used for the path of the error.

The functions are also supported on mounted virtual file systems.

Refs: #33549
Refs: #33890
Refs: #5332
Signed-off-by: marcopiraccini <marco.piraccini@gmail.com>
PR-URL: #66484
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>

Author: marcopiraccini

doc/api/fs.md

@@ -1732,6 +1732,58 @@ For detailed information, see the documentation of [`fsPromises.mkdtemp()`][].
 The optional `options` argument can be a string specifying an encoding, or an
 object with an `encoding` property specifying the character encoding to use.
 
+### `fsPromises.mkstemp(prefix[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `prefix` {string|Buffer|URL}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'` (or `'buffer'` if `prefix` is a `Buffer`)
+* Returns: {Promise} Fulfills with an {Object}:
+  * `path` {string|Buffer} The path of the created file.
+  * `handle` {FileHandle} The created file, opened for reading and writing.
+
+Creates and opens a unique temporary file. A unique file name is generated by
+appending six random characters to the end of the provided `prefix`. Due to
+platform 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 file is created and opened in a single operation, so another process cannot
+create a file with the same name in between. On POSIX systems, the file is only
+readable and writable by its owner.
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use for
+the returned `path`.
+
+```mjs
+import { mkstemp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const { path, handle } = await mkstemp(join(tmpdir(), 'foo-'));
+try {
+  await handle.writeFile('some data');
+  console.log(path);
+  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
+} finally {
+  await handle.close();
+}
+```
+
+The file is not removed automatically. It is the caller's responsibility to
+close the {FileHandle} and to remove the file when it is no longer needed.
+
+As with [`fsPromises.mkdtemp()`][], the random characters are appended directly
+to `prefix`. To create a file _within_ a directory, `prefix` must end with a
+trailing platform-specific path separator (`require('node:path').sep`) or
+include the beginning of the file name.
+
 ### `fsPromises.open(path, flags[, mode])`
 
 <!-- YAML
@@ -4099,6 +4151,66 @@ mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
 });
 ```
 
+### `fs.mkstemp(prefix[, options], callback)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `prefix` {string|Buffer|URL}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'` (or `'buffer'` if `prefix` is a `Buffer`)
+* `callback` {Function}
+  * `err` {Error}
+  * `file` {Object}
+    * `path` {string|Buffer} The path of the created file.
+    * `fd` {integer} A file descriptor for the created file, opened for
+      reading and writing.
+
+Creates and opens a unique temporary file.
+
+Generates six random characters to be appended behind a required `prefix` to
+create a unique temporary file. Due to platform 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 file is created and opened in a single operation, so another process cannot
+create a file with the same name in between. On POSIX systems, the file is only
+readable and writable by its owner.
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use for
+the `path` passed to the callback.
+
+```mjs
+import { mkstemp, write, close } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+mkstemp(join(tmpdir(), 'foo-'), (err, file) => {
+  if (err) throw err;
+  console.log(file.path);
+  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
+  write(file.fd, 'some data', (err) => {
+    if (err) throw err;
+    close(file.fd, (err) => {
+      if (err) throw err;
+    });
+  });
+});
+```
+
+The file is not removed automatically. It is the caller's responsibility to
+close the file descriptor and to remove the file when it is no longer needed.
+
+As with [`fs.mkdtemp()`][], the random characters are appended directly to
+`prefix`. To create a file _within_ a directory, `prefix` must end with a
+trailing platform-specific path separator (`require('node:path').sep`) or
+include the beginning of the file name.
+
 ### `fs.open(path[, flags[, mode]], callback)`
 
 <!-- YAML
@@ -6583,6 +6695,31 @@ with the [`using`][] syntax.
 The optional `options` argument can be a string specifying an encoding, or an
 object with an `encoding` property specifying the character encoding to use.
 
+### `fs.mkstempSync(prefix[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `prefix` {string|Buffer|URL}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'` (or `'buffer'` if `prefix` is a `Buffer`)
+* Returns: {Object}
+  * `path` {string|Buffer} The path of the created file.
+  * `fd` {integer} A file descriptor for the created file, opened for reading
+    and writing.
+
+Synchronously creates and opens a unique temporary file.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.mkstemp()`][].
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use for
+the returned `path`.
+
 ### `fs.openAsBlobSync(path[, options])`
 
 <!-- YAML
@@ -9610,6 +9747,7 @@ the file contents.
 [`fs.lutimes()`]: #fslutimespath-atime-mtime-callback
 [`fs.mkdir()`]: #fsmkdirpath-options-callback
 [`fs.mkdtemp()`]: #fsmkdtempprefix-options-callback
+[`fs.mkstemp()`]: #fsmkstempprefix-options-callback
 [`fs.open()`]: #fsopenpath-flags-mode-callback
 [`fs.openAsBlob()`]: #fsopenasblobpath-options
 [`fs.opendir()`]: #fsopendirpath-options-callback

doc/api/vfs.md

@@ -376,6 +376,7 @@ signatures as their [`node:fs`][] counterparts:
 * `utimesSync(path, atime, mtime)`
 * `lutimesSync(path, atime, mtime)`
 * `mkdtempSync(prefix)`
+* `mkstempSync(prefix)`
 * `opendirSync(path[, options])`
 * `openAsBlob(path[, options])`
 * File-descriptor ops: `openSync`, `closeSync`, `readSync`, `writeSync`,
@@ -387,8 +388,8 @@ signatures as their [`node:fs`][] counterparts:
 
 `readFile`, `writeFile`, `stat`, `lstat`, `readdir`, `realpath`, `readlink`,
 `access`, `open`, `close`, `read`, `write`, `rm`, `fstat`, `truncate`,
-`ftruncate`, `link`, `mkdtemp`, `opendir`. Each takes a Node.js-style
-callback `(err, ...result) => {}`.
+`ftruncate`, `link`, `mkdtemp`, `mkstemp`, `opendir`. Each takes a
+Node.js-style callback `(err, ...result) => {}`.
 
 #### Promise API
 
@@ -409,8 +410,8 @@ example();
 The promise namespace mirrors `fs.promises` and includes `readFile`,
 `writeFile`, `appendFile`, `stat`, `lstat`, `readdir`, `mkdir`, `rmdir`,
 `unlink`, `rename`, `copyFile`, `realpath`, `readlink`, `symlink`,
-`access`, `rm`, `truncate`, `link`, `mkdtemp`, `chmod`, `chown`, `lchown`,
-`utimes`, `lutimes`, `open`, `lchmod`, and `watch`.
+`access`, `rm`, `truncate`, `link`, `mkdtemp`, `mkstemp`, `chmod`, `chown`,
+`lchown`, `utimes`, `lutimes`, `open`, `lchmod`, and `watch`.
 
 ## The reserved root directory
 

lib/fs.js

@@ -3773,6 +3773,58 @@ function mkdtempDisposableSync(prefix, options) {
   };
 }
 
+/**
+ * Creates and opens a unique temporary file.
+ * @param {string | Buffer | URL} prefix
+ * @param {string | { encoding?: string; }} [options]
+ * @param {(err?: Error, file?: { path: string | Buffer, fd: number }) => any} callback
+ * @returns {void}
+ */
+function mkstemp(prefix, options, callback) {
+  callback = makeCallback(typeof options === 'function' ? options : callback);
+
+  options = getOptions(options);
+  if (BufferIsBuffer(prefix)) {
+    options = { ...options, encoding: 'buffer' };
+  }
+  prefix = getValidatedPath(prefix, 'prefix');
+  warnOnNonPortableTemplate(prefix);
+
+  const h = vfsState.handlers;
+  if (h !== null && vfsResult(h.mkstemp(prefix, options), callback)) return;
+
+  const req = new FSReqCallback();
+  req.oncomplete = (err, result) => {
+    if (err) return callback(err);
+    callback(null, { path: result[0], fd: result[1] });
+  };
+  binding.mkstemp(prefix, options.encoding, req);
+}
+
+/**
+ * Synchronously creates and opens a unique temporary file.
+ * @param {string | Buffer | URL} prefix
+ * @param {string | { encoding?: string; }} [options]
+ * @returns {{ path: string | Buffer, fd: number }}
+ */
+function mkstempSync(prefix, options) {
+  options = getOptions(options);
+  if (BufferIsBuffer(prefix)) {
+    options = { ...options, encoding: 'buffer' };
+  }
+  prefix = getValidatedPath(prefix, 'prefix');
+  warnOnNonPortableTemplate(prefix);
+
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.mkstempSync(prefix, options);
+    if (result !== undefined) return result;
+  }
+
+  const result = binding.mkstemp(prefix, options.encoding);
+  return { path: result[0], fd: result[1] };
+}
+
 /**
  * Asynchronously copies `src` to `dest`. By
  * default, `dest` is overwritten if it already exists.
@@ -3997,6 +4049,8 @@ module.exports = fs = {
   mkdtemp,
   mkdtempSync,
   mkdtempDisposableSync,
+  mkstemp,
+  mkstempSync,
   open,
   openSync,
   openAsBlob,

lib/internal/fs/promises.js

@@ -2136,6 +2136,28 @@ async function mkdtemp(prefix, options) {
   );
 }
 
+async function mkstemp(prefix, options) {
+  options = getOptions(options);
+  if (BufferIsBuffer(prefix)) {
+    options = { ...options, encoding: 'buffer' };
+  }
+  prefix = getValidatedPath(prefix, 'prefix');
+  warnOnNonPortableTemplate(prefix);
+
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const promise = h.promisesMkstemp(prefix, options);
+    if (promise !== undefined) return await promise;
+  }
+
+  const result = await PromisePrototypeThen(
+    binding.mkstemp(prefix, options.encoding, kUsePromises),
+    undefined,
+    handleErrorFromBinding,
+  );
+  return { __proto__: null, path: result[0], handle: new FileHandle(result[1]) };
+}
+
 async function mkdtempDisposable(prefix, options) {
   options = getOptions(options);
   if (BufferIsBuffer(prefix)) {
@@ -2389,6 +2411,7 @@ module.exports = {
     realpath,
     mkdtemp,
     mkdtempDisposable,
+    mkstemp,
     writeFile,
     appendFile,
     readFile,

lib/internal/fs/utils.js

@@ -965,12 +965,14 @@ const validateBufferArray = hideStackFrames((buffers, propName = 'buffers') => {
 let nonPortableTemplateWarn = true;
 
 function warnOnNonPortableTemplate(template) {
-  // Template strings passed to the mkdtemp() family of functions should not
-  // end with 'X' because they are handled inconsistently across platforms.
+  // Template strings passed to the mkdtemp() and mkstemp() families of
+  // functions should not end with 'X' because they are handled inconsistently
+  // across platforms.
   if (nonPortableTemplateWarn &&
     ((typeof template === 'string' && StringPrototypeEndsWith(template, 'X')) ||
     (typeof template !== 'string' && TypedArrayPrototypeAt(template, -1) === 0x58))) {
-    process.emitWarning('mkdtemp() templates ending with X are not portable. ' +
+    process.emitWarning('mkdtemp() and mkstemp() templates ending with X are ' +
+                        'not portable. ' +
                         'For details see: https://nodejs.org/api/fs.html');
     nonPortableTemplateWarn = false;
   }

lib/internal/vfs/file_system.js

@@ -614,8 +614,19 @@ class VirtualFileSystem {
   }
 
   /**
-   * Converts a mkdtemp prefix to a provider-relative one, keeping a
-   * trailing separator.
+   * Creates and opens a unique temporary file synchronously.
+   * @param {string} prefix The prefix for the temp file
+   * @returns {{ path: string, fd: number }} The full path and a file descriptor
+   */
+  mkstempSync(prefix) {
+    const filePath = this.#toProviderPrefix(prefix) + randomSuffix();
+    const handle = this[kProvider].openSync(filePath, 'wx+', 0o600);
+    return { path: this.#toMountedPath(filePath), fd: openVirtualFd(handle) };
+  }
+
+  /**
+   * Converts a mkdtemp or mkstemp prefix to a provider-relative one, keeping
+   * a trailing separator.
    * @param {string} prefix The mounted prefix
    * @returns {string}
    */
@@ -1057,6 +1068,25 @@ class VirtualFileSystem {
     }
   }
 
+  /**
+   * Creates and opens a unique temporary file asynchronously.
+   * @param {string} prefix The prefix for the temp file
+   * @param {object|Function} [options] Options or callback
+   * @param {Function} [callback] Callback (err, { path, fd })
+   */
+  mkstemp(prefix, options, callback) {
+    if (typeof options === 'function') {
+      callback = options;
+      options = undefined;
+    }
+    try {
+      const file = this.mkstempSync(prefix);
+      process.nextTick(callback, null, file);
+    } catch (err) {
+      process.nextTick(callback, err);
+    }
+  }
+
   /**
    * Opens a directory asynchronously.
    * @param {string} dirPath The directory path
@@ -1308,6 +1338,16 @@ class VirtualFileSystem {
         return toMountedPath(dirPath);
       },
 
+      async mkstemp(prefix) {
+        const filePath = toProviderPrefix(prefix) + randomSuffix();
+        const handle = provider.openSync(filePath, 'wx+', 0o600);
+        return {
+          __proto__: null,
+          path: toMountedPath(filePath),
+          fd: openVirtualFd(handle),
+        };
+      },
+
       async chmod(filePath, mode) {
         const providerPath = toProviderPath(filePath);
         provider.chmodSync(providerPath, mode);