Skip to content
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.

Sign up for GitHub

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

fs: implement fsp.exists #39968

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

fs: implement fsp.exists #39968

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
74a44f7
fs: implement `fsp.exists`
Ayase-252 Sep 1, 2021
b13b686
fixup!: validate args
Ayase-252 Sep 1, 2021
e9df79e
fixup!: remove extra line
Ayase-252 Sep 1, 2021
bf9a481
fixup!: support buffer and URL
Ayase-252 Sep 1, 2021
abe5717
fixup: rethrow the error if error is other than ENOENT
Ayase-252 Sep 2, 2021
51aeba6
fixup
Ayase-252 Sep 2, 2021
cfaf771
fixup: add warning section in doc
Ayase-252 Sep 6, 2021
10717fb
fixup: lint
Ayase-252 Sep 6, 2021
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
11 changes: 11 additions & 0 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
aduh95 marked this conversation as resolved.
Show resolved Hide resolved
-->

* `path` {string}
Ayase-252 marked this conversation as resolved.
Show resolved Hide resolved
* 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?


### `fsPromises.lchmod(path, mode)`
<!-- YAML
deprecated: v10.0.0
Expand Down
11 changes: 11 additions & 0 deletions lib/internal/fs/promises.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -808,11 +808,22 @@ async function readFile(path, options) {
return handleFdClose(readFileHandle(fd, options), fd.close);
}

async function exists(path) {
validateString(path, 'path');
Copy link
Contributor

Choose a reason for hiding this comment

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

I think access() has already validated the path.

Copy link
Member

Choose a reason for hiding this comment

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

Yes, but access() is called in the try block.

Copy link
Contributor

Choose a reason for hiding this comment

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

So the problem is, if we got a wrong path, should exists() return false or throw an error.

Copy link
Contributor

Choose a reason for hiding this comment

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

node/lib/fs.js

Lines 291 to 295 in 73d5f8a

try {
path = getValidatedPath(path);
} catch {
return false;
}

fs.existsSync() returns false if path validation failed.

Copy link
Member

Choose a reason for hiding this comment

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

According to

node/lib/fs.js

Lines 279 to 284 in 73d5f8a

// fs.existsSync never throws, it only returns true or false.
// Since fs.existsSync never throws, users have established
// the expectation that passing invalid arguments to it, even like
// fs.existsSync(), would only get a false in return, so we cannot signal
// validation errors to users properly out of compatibility concerns.
// TODO(joyeecheung): deprecate the never-throw-on-invalid-arguments behavior
, I think we should not make the same mistake with fsPromises.exists.
Maybe we should even go further and also throw if the error is not ENOENT. For example a permission error now ends up in returning false but we actually don't know if the file exists or not.

Copy link
Member Author

Choose a reason for hiding this comment

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

Currently, fs.existsSync(path) returns false when path validation failed, even path is not a string. e.g.

> const fs = require('fs')
undefined
> fs.existsSync({})
false

I would think it is a bug(?), since docs says it only allows path of type <string> | <Buffer> | <URL>.

Copy link
Contributor

@XadillaX XadillaX Sep 1, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

According to

node/lib/fs.js

Lines 279 to 284 in 73d5f8a

// fs.existsSync never throws, it only returns true or false.
// Since fs.existsSync never throws, users have established
// the expectation that passing invalid arguments to it, even like
// fs.existsSync(), would only get a false in return, so we cannot signal
// validation errors to users properly out of compatibility concerns.
// TODO(joyeecheung): deprecate the never-throw-on-invalid-arguments behavior

, I think we should not make the same mistake with fsPromises.exists.
Maybe we should even go further and also throw if the error is not ENOENT. For example a permission error now ends up in returning false but we actually don't know if the file exists or not.

If we throws, the behaivor of 3 APIs are very different:

  • fs.exists(): wrong callback signature;
  • fs.existsSync(): eats errors;
  • fsPromise.exists(): throws errors.

And actually they just do the same thing in different async ways. I think we shouldn't make the behaivor more chaotic.

I think there're 2 ways to choose:

  1. fsPromise.exists(): never throws;
  2. Delete fs.existsSync()'s TODO and make it throws.

Copy link
Contributor

Choose a reason for hiding this comment

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

If you want to make fs.existsSync throw, we should probably make the error swallowing go through a complete deprecation first to make sure this won't break the ecosystem.

Ayase-252 marked this conversation as resolved.
Show resolved Hide resolved
try {
await access(path, F_OK);
return true;
} catch {
return false;
}
}

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
View file
Open in desktop
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