Skip to content

fs: implement fsp.exists #39968

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -775,6 +775,28 @@ 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't really check if the file exists, which is why the name is misleading, see #39960 (comment).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. It makes sense. Do you have a better name suggestion? Or like os.path.exists on Python, is a sepecial note sufficient?

It throws when check is impossible, such as encountering permission issue.

Using `fsPromises.exists` only proves that whether the given file
path existed at some time between calling and resolving `exists`
due to the nature of asynchronous operation.

It is not recommended to use `fsPromises.exists` to check accessibility of
a file before opening/reading/writing it. Doing so introduces a race condition,
since other process may change the states of the file between two call.
Instead, user code should open/read/write it directly and handle the error
raise if the file is not accessible.

### `fsPromises.lchmod(path, mode)`
<!-- YAML
deprecated: v10.0.0
Expand Down
16 changes: 16 additions & 0 deletions lib/internal/fs/promises.js
Original file line number Diff line number Diff line change
Expand Up @@ -808,11 +808,27 @@ 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 (err) {
if (err.code === 'ENOENT') {
return false;
}
// We are unable to determine if the file exists or not,
// like encountering a permission error.
throw err;
Comment on lines +817 to +822
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should always (including the fact that this is a permission error) return false in this catch block, and should never throw an error to mimic existsSync API.

}
}

module.exports = {
exports: {
access,
copyFile,
cp,
exists,
open,
opendir: promisify(opendir),
rename,
Expand Down
22 changes: 22 additions & 0 deletions test/parallel/test-fs-promises.js
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ const {
chmod,
chown,
copyFile,
exists,
lchown,
link,
lchmod,
Expand Down Expand Up @@ -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());
Expand Down