fs: introduce dirent.parentPath

aduh95 · richardlau · commit 26e8f7793e7a · 2024-03-18T16:55:24.000Z
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: #50976 Backport-PR-URL: #51021 Reviewed-By: Ethan Arrowood <ethan@arrowood.dev> Reviewed-By: LiviaMedeiros <livia@cirno.name>
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -6437,6 +6437,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
diff --git a/lib/internal/fs/dir.js b/lib/internal/fs/dir.js
@@ -152,9 +152,10 @@ class Dir {
       ArrayPrototypePush(
         this[kDirBufferedEntries],
         getDirent(
-          pathModule.join(path, result[i]),
+          path,
           result[i],
           result[i + 1],
+          true, // Quirk to not introduce a breaking change.
         ),
       );
     }
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
@@ -161,9 +161,10 @@ function assertEncoding(encoding) {
 }
 
 class Dirent {
-  constructor(name, type, path) {
+  constructor(name, type, path, filepath = path && join(path, name)) {
     this.name = name;
-    this.path = path;
+    this.parentPath = path;
+    this.path = filepath;
     this[kType] = type;
   }
 
@@ -197,8 +198,8 @@ class Dirent {
 }
 
 class DirentFromStats extends Dirent {
-  constructor(name, stats, path) {
-    super(name, null, path);
+  constructor(name, stats, path, filepath) {
+    super(name, null, path, filepath);
     this[kStats] = stats;
   }
 }
@@ -233,7 +234,7 @@ function join(path, name) {
   }
 
   if (typeof path === 'string' && typeof name === 'string') {
-    return pathModule.basename(path) === name ? path : pathModule.join(path, name);
+    return pathModule.join(path, name);
   }
 
   if (isUint8Array(path) && isUint8Array(name)) {
@@ -268,7 +269,7 @@ function getDirents(path, { 0: names, 1: types }, callback) {
             callback(err);
             return;
           }
-          names[idx] = new DirentFromStats(name, stats, path);
+          names[idx] = new DirentFromStats(name, stats, path, filepath);
           if (--toFinish === 0) {
             callback(null, names);
           }
@@ -304,17 +305,21 @@ function getDirent(path, name, type, callback) {
           callback(err);
           return;
         }
-        callback(null, new DirentFromStats(name, stats, filepath));
+        callback(null, new DirentFromStats(name, stats, path, filepath));
       });
     } else {
       callback(null, new Dirent(name, type, path));
     }
   } else if (type === UV_DIRENT_UNKNOWN) {
     const filepath = join(path, name);
     const stats = lazyLoadFs().lstatSync(filepath);
-    return new DirentFromStats(name, stats, path);
-  } else {
+    // callback === true: Quirk to not introduce a breaking change.
+    return new DirentFromStats(name, stats, path, callback === true ? filepath : path);
+  } else if (callback === true) {
+    // callback === true: Quirk to not introduce a breaking change.
     return new Dirent(name, type, path);
+  } else {
+    return new Dirent(name, type, path, path);
   }
 }
 
diff --git 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), files.map((name) => path.join(testDir, name)));
+  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);

Original file line number	Diff line number	Diff line change
`@@ -161,9 +161,10 @@ function assertEncoding(encoding) {`
`161`	`161`	`}`
`162`	`162`
`163`	`163`	`class Dirent {`
`164`		`- constructor(name, type, path) {`
	`164`	`+ constructor(name, type, path, filepath = path && join(path, name)) {`
`165`	`165`	`this.name = name;`
`166`		`- this.path = path;`
	`166`	`+ this.parentPath = path;`
	`167`	`+ this.path = filepath;`
`167`	`168`	`this[kType] = type;`
`168`	`169`	`}`
`169`	`170`
`@@ -197,8 +198,8 @@ class Dirent {`
`197`	`198`	`}`
`198`	`199`
`199`	`200`	`class DirentFromStats extends Dirent {`
`200`		`- constructor(name, stats, path) {`
`201`		`- super(name, null, path);`
	`201`	`+ constructor(name, stats, path, filepath) {`
	`202`	`+ super(name, null, path, filepath);`
`202`	`203`	`this[kStats] = stats;`
`203`	`204`	`}`
`204`	`205`	`}`
`@@ -233,7 +234,7 @@ function join(path, name) {`
`233`	`234`	`}`
`234`	`235`
`235`	`236`	`if (typeof path === 'string' && typeof name === 'string') {`
`236`		`- return pathModule.basename(path) === name ? path : pathModule.join(path, name);`
	`237`	`+ return pathModule.join(path, name);`
`237`	`238`	`}`
`238`	`239`
`239`	`240`	`if (isUint8Array(path) && isUint8Array(name)) {`
`@@ -268,7 +269,7 @@ function getDirents(path, { 0: names, 1: types }, callback) {`
`268`	`269`	`callback(err);`
`269`	`270`	`return;`
`270`	`271`	`}`
`271`		`- names[idx] = new DirentFromStats(name, stats, path);`
	`272`	`+ names[idx] = new DirentFromStats(name, stats, path, filepath);`
`272`	`273`	`if (--toFinish === 0) {`
`273`	`274`	`callback(null, names);`
`274`	`275`	`}`
`@@ -304,17 +305,21 @@ function getDirent(path, name, type, callback) {`
`304`	`305`	`callback(err);`
`305`	`306`	`return;`
`306`	`307`	`}`
`307`		`- callback(null, new DirentFromStats(name, stats, filepath));`
	`308`	`+ callback(null, new DirentFromStats(name, stats, path, filepath));`
`308`	`309`	`});`
`309`	`310`	`} else {`
`310`	`311`	`callback(null, new Dirent(name, type, path));`
`311`	`312`	`}`
`312`	`313`	`} else if (type === UV_DIRENT_UNKNOWN) {`
`313`	`314`	`const filepath = join(path, name);`
`314`	`315`	`const stats = lazyLoadFs().lstatSync(filepath);`
`315`		`- return new DirentFromStats(name, stats, path);`
`316`		`- } else {`
	`316`	`+ // callback === true: Quirk to not introduce a breaking change.`
	`317`	`+ return new DirentFromStats(name, stats, path, callback === true ? filepath : path);`
	`318`	`+ } else if (callback === true) {`
	`319`	`+ // callback === true: Quirk to not introduce a breaking change.`
`317`	`320`	`return new Dirent(name, type, path);`
	`321`	`+ } else {`
	`322`	`+ return new Dirent(name, type, path, path);`
`318`	`323`	`}`
`319`	`324`	`}`
`320`	`325`