fs: add disposable mkdtempSync

PR-URL: #58516
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: LiviaMedeiros <livia@cirno.name>

Author: bakkot

doc/api/fs.md

@@ -1314,6 +1314,37 @@ characters directly to the `prefix` string. For instance, given a directory
 `prefix` must end with a trailing platform-specific path separator
 (`require('node:path').sep`).
 
+### `fsPromises.mkdtempDisposable(prefix[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `prefix` {string|Buffer|URL}
+* `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.
+  * `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
+async `remove()` method which will perform the same task.
+
+Both this function and the disposal function on the resulting object are
+async, so it should be used with `await` + `await using` as in
+`await using dir = await fsPromises.mkdtempDisposable('prefix')`.
+
+<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
+
+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.open(path, flags[, mode])`
 
 <!-- YAML
@@ -5909,6 +5940,36 @@ this API: [`fs.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.
 
+### `fs.mkdtempDisposableSync(prefix[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `prefix` {string|Buffer|URL}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'`
+* Returns: {Object} A disposable object:
+  * `path` {string} 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.
+
+<!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
+
+For detailed information, see the documentation of [`fs.mkdtemp()`][].
+
+There is no callback-based version of this API because it is designed for use
+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.opendirSync(path[, options])`
 
 <!-- YAML
@@ -8502,6 +8563,7 @@ the file contents.
 [`fs.writev()`]: #fswritevfd-buffers-position-callback
 [`fsPromises.access()`]: #fspromisesaccesspath-mode
 [`fsPromises.copyFile()`]: #fspromisescopyfilesrc-dest-mode
+[`fsPromises.mkdtemp()`]: #fspromisesmkdtempprefix-options
 [`fsPromises.open()`]: #fspromisesopenpath-flags-mode
 [`fsPromises.opendir()`]: #fspromisesopendirpath-options
 [`fsPromises.rm()`]: #fspromisesrmpath-options

lib/fs.js

@@ -42,6 +42,7 @@ const {
   StringPrototypeCharCodeAt,
   StringPrototypeIndexOf,
   StringPrototypeSlice,
+  SymbolDispose,
   uncurryThis,
 } = primordials;
 
@@ -3033,6 +3034,36 @@ function mkdtempSync(prefix, options) {
   return binding.mkdtemp(prefix, options.encoding);
 }
 
+/**
+ * Synchronously creates a unique temporary directory.
+ * The returned value is a disposable object which removes the
+ * directory and its contents when disposed.
+ * @param {string | Buffer | URL} prefix
+ * @param {string | { encoding?: string; }} [options]
+ * @returns {object} A disposable object with a "path" property.
+ */
+function mkdtempDisposableSync(prefix, options) {
+  options = getOptions(options);
+
+  prefix = getValidatedPath(prefix, 'prefix');
+  warnOnNonPortableTemplate(prefix);
+
+  const path = binding.mkdtemp(prefix, options.encoding);
+  // Stash the full path in case of process.chdir()
+  const fullPath = pathModule.resolve(process.cwd(), path);
+
+  const remove = () => {
+    binding.rmSync(fullPath, 0 /* maxRetries */, true /* recursive */, 100 /* retryDelay */);
+  };
+  return {
+    path,
+    remove,
+    [SymbolDispose]() {
+      remove();
+    },
+  };
+}
+
 /**
  * Asynchronously copies `src` to `dest`. By
  * default, `dest` is overwritten if it already exists.
@@ -3238,6 +3269,7 @@ module.exports = fs = {
   mkdirSync,
   mkdtemp,
   mkdtempSync,
+  mkdtempDisposableSync,
   open,
   openSync,
   openAsBlob,

lib/internal/fs/promises.js

@@ -1188,6 +1188,39 @@ async function mkdtemp(prefix, options) {
   );
 }
 
+async function mkdtempDisposable(prefix, options) {
+  options = getOptions(options);
+
+  prefix = getValidatedPath(prefix, 'prefix');
+  warnOnNonPortableTemplate(prefix);
+
+  const cwd = process.cwd();
+  const path = await PromisePrototypeThen(
+    binding.mkdtemp(prefix, options.encoding, kUsePromises),
+    undefined,
+    handleErrorFromBinding,
+  );
+  // Stash the full path in case of process.chdir()
+  const fullPath = pathModule.resolve(cwd, path);
+
+  const remove = async () => {
+    const rmrf = lazyRimRaf();
+    await rmrf(fullPath, {
+      maxRetries: 0,
+      recursive: true,
+      retryDelay: 0,
+    });
+  };
+  return {
+    __proto__: null,
+    path,
+    remove,
+    async [SymbolAsyncDispose]() {
+      await remove();
+    },
+  };
+}
+
 async function writeFile(path, data, options) {
   options = getOptions(options, {
     encoding: 'utf8',
@@ -1300,6 +1333,7 @@ module.exports = {
     lutimes,
     realpath,
     mkdtemp,
+    mkdtempDisposable,
     writeFile,
     appendFile,
     readFile,

test/fixtures/permission/fs-write.js

@@ -199,6 +199,7 @@ const relativeProtectedFolder = process.env.RELATIVEBLOCKEDFOLDER;
   });
 }
 
+// fs.mkdtemp
 {
   assert.throws(() => {
     fs.mkdtempSync(path.join(blockedFolder, 'any-folder'));
@@ -212,6 +213,16 @@ const relativeProtectedFolder = process.env.RELATIVEBLOCKEDFOLDER;
   }));
 }
 
+// fs.mkdtempDisposableSync
+{
+  assert.throws(() => {
+    fs.mkdtempDisposableSync(path.join(blockedFolder, 'any-folder'));
+  },{
+    code: 'ERR_ACCESS_DENIED',
+    permission: 'FileSystemWrite',
+  });
+}
+
 // fs.rename
 {
   assert.throws(() => {

test/parallel/test-fs-mkdtempDisposableSync.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { isMainThread } = require('worker_threads');
+
+const tmpdir = require('../common/tmpdir');
+tmpdir.refresh();
+
+// Basic usage
+{
+  const result = fs.mkdtempDisposableSync(tmpdir.resolve('foo.'));
+
+  assert.strictEqual(path.basename(result.path).length, 'foo.XXXXXX'.length);
+  assert.strictEqual(path.dirname(result.path), tmpdir.path);
+  assert(fs.existsSync(result.path));
+
+  result.remove();
+
+  assert(!fs.existsSync(result.path));
+
+  // Second removal does not throw error
+  result.remove();
+}
+
+// Usage with [Symbol.dispose]()
+{
+  const result = fs.mkdtempDisposableSync(tmpdir.resolve('foo.'));
+
+  assert(fs.existsSync(result.path));
+
+  result[Symbol.dispose]();
+
+  assert(!fs.existsSync(result.path));
+
+  // Second removal does not throw error
+  result[Symbol.dispose]();
+}
+
+// `chdir`` does not affect removal
+// Can't use chdir in workers
+if (isMainThread) {
+  const originalCwd = process.cwd();
+
+  process.chdir(tmpdir.path);
+  const first = fs.mkdtempDisposableSync('first.');
+  const second = fs.mkdtempDisposableSync('second.');
+
+  const fullFirstPath = path.join(tmpdir.path, first.path);
+  const fullSecondPath = path.join(tmpdir.path, second.path);
+
+  assert(fs.existsSync(fullFirstPath));
+  assert(fs.existsSync(fullSecondPath));
+
+  process.chdir(fullFirstPath);
+  second.remove();
+
+  assert(!fs.existsSync(fullSecondPath));
+
+  process.chdir(tmpdir.path);
+  first.remove();
+  assert(!fs.existsSync(fullFirstPath));
+
+  process.chdir(originalCwd);
+}
+
+// Errors from cleanup are thrown
+// It is difficult to arrange for rmdir to fail on windows
+if (!common.isWindows) {
+  const base = fs.mkdtempDisposableSync(tmpdir.resolve('foo.'));
+
+  // On Unix we can prevent removal by making the parent directory read-only
+  const child = fs.mkdtempDisposableSync(path.join(base.path, 'bar.'));
+
+  const originalMode = fs.statSync(base.path).mode;
+  fs.chmodSync(base.path, 0o444);
+
+  assert.throws(() => {
+    child.remove();
+  }, /EACCES|EPERM/);
+
+  fs.chmodSync(base.path, originalMode);
+
+  // Removal works once permissions are reset
+  child.remove();
+  assert(!fs.existsSync(child.path));
+
+  base.remove();
+  assert(!fs.existsSync(base.path));
+}

test/parallel/test-fs-promises-mkdtempDisposable.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const fsPromises = require('fs/promises');
+const path = require('path');
+const { isMainThread } = require('worker_threads');
+
+const tmpdir = require('../common/tmpdir');
+tmpdir.refresh();
+
+async function basicUsage() {
+  const result = await fsPromises.mkdtempDisposable(tmpdir.resolve('foo.'));
+
+  assert.strictEqual(path.basename(result.path).length, 'foo.XXXXXX'.length);
+  assert.strictEqual(path.dirname(result.path), tmpdir.path);
+  assert(fs.existsSync(result.path));
+
+  await result.remove();
+
+  assert(!fs.existsSync(result.path));
+
+  // Second removal does not throw error
+  result.remove();
+}
+
+async function symbolAsyncDispose() {
+  const result = await fsPromises.mkdtempDisposable(tmpdir.resolve('foo.'));
+
+  assert(fs.existsSync(result.path));
+
+  await result[Symbol.asyncDispose]();
+
+  assert(!fs.existsSync(result.path));
+
+  // Second removal does not throw error
+  await result[Symbol.asyncDispose]();
+}
+
+async function chdirDoesNotAffectRemoval() {
+  // Can't use chdir in workers
+  if (!isMainThread) return;
+
+  const originalCwd = process.cwd();
+
+  process.chdir(tmpdir.path);
+  const first = await fsPromises.mkdtempDisposable('first.');
+  const second = await fsPromises.mkdtempDisposable('second.');
+
+  const fullFirstPath = path.join(tmpdir.path, first.path);
+  const fullSecondPath = path.join(tmpdir.path, second.path);
+
+  assert(fs.existsSync(fullFirstPath));
+  assert(fs.existsSync(fullSecondPath));
+
+  process.chdir(fullFirstPath);
+  await second.remove();
+
+  assert(!fs.existsSync(fullSecondPath));
+
+  process.chdir(tmpdir.path);
+  await first.remove();
+  assert(!fs.existsSync(fullFirstPath));
+
+  process.chdir(originalCwd);
+}
+
+async function errorsAreReThrown() {
+  // It is difficult to arrange for rmdir to fail on windows
+  if (common.isWindows) return;
+  const base = await fsPromises.mkdtempDisposable(tmpdir.resolve('foo.'));
+
+  // On Unix we can prevent removal by making the parent directory read-only
+  const child = await fsPromises.mkdtempDisposable(path.join(base.path, 'bar.'));
+
+  const originalMode = fs.statSync(base.path).mode;
+  fs.chmodSync(base.path, 0o444);
+
+  await assert.rejects(child.remove(), /EACCES|EPERM/);
+
+  fs.chmodSync(base.path, originalMode);
+
+  // Removal works once permissions are reset
+  await child.remove();
+  assert(!fs.existsSync(child.path));
+
+  await base.remove();
+  assert(!fs.existsSync(base.path));
+}
+
+(async () => {
+  await basicUsage();
+  await symbolAsyncDispose();
+  await chdirDoesNotAffectRemoval();
+  await errorsAreReThrown();
+})().then(common.mustCall());