fs: implement fsp.exists

doc/api/fs.md

@@ -775,6 +775,17 @@ including subdirectories and files.
 When copying a directory to another directory, globs are not supported and
 behavior is similar to `cp dir1/ dir2/`.
 
+### `fsPromises.exists(path)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string|Buffer|URL}
+* Returns: {Promise} Resolved as `true` if the given path exists, otherwise,
+  resolved as `false`.
+
+Test whether or not the given path exists by checking with the file system.
+
 ### `fsPromises.lchmod(path, mode)`
 <!-- YAML
 deprecated: v10.0.0

lib/internal/fs/promises.js

@@ -808,11 +808,22 @@ async function readFile(path, options) {
   return handleFdClose(readFileHandle(fd, options), fd.close);
 }
 
+async function exists(path) {
+  path = getValidatedPath(path, 'path');
+  try {
+    await access(path, F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 module.exports = {
   exports: {
     access,
     copyFile,
     cp,
+    exists,
     open,
     opendir: promisify(opendir),
     rename,

test/parallel/test-fs-promises.js

@@ -12,6 +12,7 @@ const {
   chmod,
   chown,
   copyFile,
+  exists,
   lchown,
   link,
   lchmod,
@@ -471,6 +472,27 @@ async function executeOnHandle(dest, func) {
         });
       });
     }
+
+    {
+      const newFile = path.resolve(tmpDir, 'foo');
+      await writeFile(newFile, '');
+      const fileExists = await exists(newFile);
+      assert.strictEqual(fileExists, true);
+      await unlink(newFile);
+    }
+
+    {
+      const nonExistFile = path.resolve(tmpDir, 'non-exist-file');
+      const fileExists = await exists(nonExistFile);
+      assert.strictEqual(fileExists, false);
+    }
+
+    {
+      await assert.rejects(() => exists({}), {
+        code: 'ERR_INVALID_ARG_TYPE',
+        name: 'TypeError'
+      });
+    }
   }
 
   doTest().then(common.mustCall());