fs: deprecate never throw behaviour in fs.existsSync

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.

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;
   }
 

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')));