From 2e458d973638d01fcb6a0d7d611e0120a94f4d35 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sat, 2 Dec 2023 23:49:21 +0100
Subject: [PATCH] fs: introduce `dirent.parentPath`

The goal is to replace `dirent.path` using a name that's less likely to
create confusion.
`dirent.path` value has not been stable, moving it to a different
property name should avoid breaking some upgrading user expectations.

PR-URL: https://github.com/nodejs/node/pull/50976
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: LiviaMedeiros <livia@cirno.name>
---
 doc/api/fs.md                    | 15 ++++++++++++++-
 lib/fs.js                        |  2 +-
 lib/internal/fs/dir.js           |  2 +-
 lib/internal/fs/utils.js         |  1 +
 test/parallel/test-fs-opendir.js |  8 +++++---
 5 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index be9acd7dad7a35..17ff809f328bfb 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -6638,6 +6638,19 @@ The file name that this {fs.Dirent} object refers to. The type of this
 value is determined by the `options.encoding` passed to [`fs.readdir()`][] or
 [`fs.readdirSync()`][].
 
+#### `dirent.parentPath`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1 – Experimental
+
+* {string}
+
+The path to the parent directory of the file this {fs.Dirent} object refers to.
+
 #### `dirent.path`
 
 <!-- YAML
@@ -6648,7 +6661,7 @@ added:
 
 * {string}
 
-The base path that this {fs.Dirent} object refers to.
+Alias for `dirent.parentPath`.
 
 ### Class: `fs.FSWatcher`
 
diff --git a/lib/fs.js b/lib/fs.js
index 8761ab4f9f00a2..037d947a111ff9 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -1426,7 +1426,7 @@ function readdirSyncRecursive(basePath, options) {
         const dirent = getDirent(path, readdirResult[0][i], readdirResult[1][i]);
         ArrayPrototypePush(readdirResults, dirent);
         if (dirent.isDirectory()) {
-          ArrayPrototypePush(pathsQueue, pathModule.join(dirent.path, dirent.name));
+          ArrayPrototypePush(pathsQueue, pathModule.join(dirent.parentPath, dirent.name));
         }
       }
     } else {
diff --git a/lib/internal/fs/dir.js b/lib/internal/fs/dir.js
index 1118ff5f674915..82c6c1bd780fba 100644
--- a/lib/internal/fs/dir.js
+++ b/lib/internal/fs/dir.js
@@ -161,7 +161,7 @@ class Dir {
   }
 
   readSyncRecursive(dirent) {
-    const path = pathModule.join(dirent.path, dirent.name);
+    const path = pathModule.join(dirent.parentPath, dirent.name);
     const ctx = { path };
     const handle = dirBinding.opendir(
       pathModule.toNamespacedPath(path),
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 6e2ae69555130d..fa2851a244b5ee 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -165,6 +165,7 @@ function assertEncoding(encoding) {
 class Dirent {
   constructor(name, type, path) {
     this.name = name;
+    this.parentPath = path;
     this.path = path;
     this[kType] = type;
   }
diff --git a/test/parallel/test-fs-opendir.js b/test/parallel/test-fs-opendir.js
index 82ee8e20da31cd..8b8fc161eee661 100644
--- a/test/parallel/test-fs-opendir.js
+++ b/test/parallel/test-fs-opendir.js
@@ -48,9 +48,11 @@ const invalidCallbackObj = {
   const entries = files.map(() => {
     const dirent = dir.readSync();
     assertDirent(dirent);
-    return dirent.name;
-  });
-  assert.deepStrictEqual(files, entries.sort());
+    return { name: dirent.name, path: dirent.path, parentPath: dirent.parentPath, toString() { return dirent.name; } };
+  }).sort();
+  assert.deepStrictEqual(entries.map((d) => d.name), files);
+  assert.deepStrictEqual(entries.map((d) => d.path), Array(entries.length).fill(testDir));
+  assert.deepStrictEqual(entries.map((d) => d.parentPath), Array(entries.length).fill(testDir));
 
   // dir.read should return null when no more entries exist
   assert.strictEqual(dir.readSync(), null);