From 529b56ef9d2a0b3402dee5a812a1d88983b09a80 Mon Sep 17 00:00:00 2001
From: Carlos Espa <43477095+Ceres6@users.noreply.github.com>
Date: Fri, 10 Jan 2025 13:04:14 +0100
Subject: [PATCH] fs: deprecate passing invalid types in `fs.existsSync`

PR-URL: https://github.com/nodejs/node/pull/55753
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
---
 doc/api/deprecations.md         |  5 ++++-
 lib/fs.js                       | 13 +++++++------
 test/parallel/test-fs-exists.js |  2 ++
 3 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 8912015bb14..ba0676f1b84 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -3779,6 +3779,9 @@ 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
@@ -3786,7 +3789,7 @@ changes:
     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
index af72ac36144..e2996ba9ca4 100644
--- 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
index 857f3f26174..3be2197660c 100644
--- 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')));