fs: deprecate passing invalid types in fs.existsSync

PR-URL: nodejs#55753 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Matteo Collina <[email protected]>
zys-contrib · Jan 10, 2025 · 529b56e · 529b56e
1 parent a627a99
commit 529b56e
Show file tree

Hide file tree

Showing 3 changed files with 13 additions and 7 deletions.
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -3779,14 +3779,17 @@ It is recommended to use the `new` qualifier instead. This applies to all REPL c
 
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/55753
+    description: Runtime deprecation.
   - version:
     - v23.4.0
     - v22.13.0
     pr-url: https://github.com/nodejs/node/pull/55892
     description: Documentation-only.
 -->
 
-Type: Documentation-only
+Type: Runtime
 
 Passing non-supported argument types is deprecated and, instead of returning `false`,
 will throw an error in a future version.

diff --git a/lib/fs.js b/lib/fs.js
@@ -273,12 +273,7 @@ ObjectDefineProperty(exists, kCustomPromisifiedSymbol, {
   },
 });
 
-// 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
+let showExistsDeprecation = true;
 /**
  * Synchronously tests whether or not the given path exists.
  * @param {string | Buffer | URL} path
@@ -288,6 +283,12 @@ function existsSync(path) {
   try {
     path = getValidatedPath(path);
   } catch {
+    if (showExistsDeprecation) {
+      process.emitWarning(
+        'Passing invalid argument types to fs.existsSync is deprecated', 'DeprecationWarning', 'DEP0187',
+      );
+      showExistsDeprecation = false;
+    }
     return false;
   }
 

diff --git a/test/parallel/test-fs-exists.js b/test/parallel/test-fs-exists.js
@@ -51,6 +51,8 @@ assert(fs.existsSync(f));
 assert(!fs.existsSync(`${f}-NO`));
 
 // fs.existsSync() never throws
+const msg = 'Passing invalid argument types to fs.existsSync is deprecated';
+common.expectWarning('DeprecationWarning', msg, 'DEP0187');
 assert(!fs.existsSync());
 assert(!fs.existsSync({}));
 assert(!fs.existsSync(new URL('https://foo')));