Skip to content

Commit fd82844

Browse files
jasnelladdaleax
jasnell
authored and
addaleax
committed
path: deprecate internal _makeLong, replace
Replace the internal `path._makeLong()` with a public `path.toLongUNCPath()` method. Add documentation. PR-URL: nodejs/node#14956 Ref: standard-things/esm#66 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>
1 parent 404870a commit fd82844

File tree

7 files changed

+116
-83
lines changed

7 files changed

+116
-83
lines changed

‎doc/api/deprecations.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -710,6 +710,16 @@ function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][]
710710
instead. For backwards compatibility with Node.js prior to version 6.4.0, both
711711
may be specified.
712712
713+
<a id="DEP00XX"></a>
714+
### DEP00XX: path.\_makeLong()
715+
716+
Type: Documentation-only
717+
718+
The internal `path._makeLong()` was not intended for public use. However,
719+
userland modules have found it useful. The internal API has been deprecated
720+
and replaced with an identical, public `path.toNamespacedPath()` method.
721+
722+
713723
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
714724
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
715725
[`Buffer.from(buffer)`]: buffer.html#buffer_class_method_buffer_from_buffer

‎doc/api/path.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -543,6 +543,21 @@ On Windows:
543543
accepted as path segment separators; however, the `path` methods only add
544544
backward slashes (`\`).
545545

546+
## path.toNamespacedPath(path)
547+
<!-- YAML
548+
added: REPLACEME
549+
-->
550+
551+
* `path` {string}
552+
* Returns: {string}
553+
554+
On Windows systems only, returns an equivalent [namespace-prefixed path][] for
555+
the given `path`. If `path` is not a string, `path` will be returned without
556+
modifications.
557+
558+
This method is meaningful only on Windows system. On posix systems, the
559+
method is non-operational and always returns `path` without modifications.
560+
546561
## path.win32
547562
<!-- YAML
548563
added: v0.11.15
@@ -559,3 +574,4 @@ of the `path` methods.
559574
[`path.sep`]: #path_path_sep
560575
[`path.win32`]: #path_path_win32
561576
[MSDN-Rel-Path]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247.aspx#fully_qualified_vs._relative_paths
577+
[namespace-prefixed path]: https://msdn.microsoft.com/library/windows/desktop/aa365247(v=vs.85).aspx#namespaces

‎lib/fs.js‎

Lines changed: 45 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -293,7 +293,7 @@ fs.access = function(path, mode, callback) {
293293
mode = mode | 0;
294294
var req = new FSReqWrap();
295295
req.oncomplete = makeCallback(callback);
296-
binding.access(pathModule._makeLong(path), mode, req);
296+
binding.access(pathModule.toNamespacedPath(path), mode, req);
297297
};
298298

299299
fs.accessSync = function(path, mode) {
@@ -305,7 +305,7 @@ fs.accessSync = function(path, mode) {
305305
else
306306
mode = mode | 0;
307307

308-
binding.access(pathModule._makeLong(path), mode);
308+
binding.access(pathModule.toNamespacedPath(path), mode);
309309
};
310310

311311
fs.exists = function(path, callback) {
@@ -314,7 +314,7 @@ fs.exists = function(path, callback) {
314314
if (!nullCheck(path, cb)) return;
315315
var req = new FSReqWrap();
316316
req.oncomplete = cb;
317-
binding.stat(pathModule._makeLong(path), req);
317+
binding.stat(pathModule.toNamespacedPath(path), req);
318318
function cb(err) {
319319
if (callback) callback(err ? false : true);
320320
}
@@ -333,7 +333,7 @@ fs.existsSync = function(path) {
333333
try {
334334
handleError((path = getPathFromURL(path)));
335335
nullCheck(path);
336-
binding.stat(pathModule._makeLong(path));
336+
binding.stat(pathModule.toNamespacedPath(path));
337337
return true;
338338
} catch (e) {
339339
return false;
@@ -362,7 +362,7 @@ fs.readFile = function(path, options, callback) {
362362
return;
363363
}
364364

365-
binding.open(pathModule._makeLong(path),
365+
binding.open(pathModule.toNamespacedPath(path),
366366
stringToFlags(options.flag || 'r'),
367367
0o666,
368368
req);
@@ -646,7 +646,7 @@ fs.open = function(path, flags, mode, callback_) {
646646
var req = new FSReqWrap();
647647
req.oncomplete = callback;
648648

649-
binding.open(pathModule._makeLong(path),
649+
binding.open(pathModule.toNamespacedPath(path),
650650
stringToFlags(flags),
651651
mode,
652652
req);
@@ -656,7 +656,8 @@ fs.openSync = function(path, flags, mode) {
656656
mode = modeNum(mode, 0o666);
657657
handleError((path = getPathFromURL(path)));
658658
nullCheck(path);
659-
return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
659+
return binding.open(pathModule.toNamespacedPath(path),
660+
stringToFlags(flags), mode);
660661
};
661662

662663
fs.read = function(fd, buffer, offset, length, position, callback) {
@@ -766,8 +767,8 @@ fs.rename = function(oldPath, newPath, callback) {
766767
if (!nullCheck(newPath, callback)) return;
767768
var req = new FSReqWrap();
768769
req.oncomplete = callback;
769-
binding.rename(pathModule._makeLong(oldPath),
770-
pathModule._makeLong(newPath),
770+
binding.rename(pathModule.toNamespacedPath(oldPath),
771+
pathModule.toNamespacedPath(newPath),
771772
req);
772773
};
773774

@@ -776,8 +777,8 @@ fs.renameSync = function(oldPath, newPath) {
776777
handleError((newPath = getPathFromURL(newPath)));
777778
nullCheck(oldPath);
778779
nullCheck(newPath);
779-
return binding.rename(pathModule._makeLong(oldPath),
780-
pathModule._makeLong(newPath));
780+
return binding.rename(pathModule.toNamespacedPath(oldPath),
781+
pathModule.toNamespacedPath(newPath));
781782
};
782783

783784
fs.truncate = function(path, len, callback) {
@@ -850,13 +851,13 @@ fs.rmdir = function(path, callback) {
850851
if (!nullCheck(path, callback)) return;
851852
var req = new FSReqWrap();
852853
req.oncomplete = callback;
853-
binding.rmdir(pathModule._makeLong(path), req);
854+
binding.rmdir(pathModule.toNamespacedPath(path), req);
854855
};
855856

856857
fs.rmdirSync = function(path) {
857858
handleError((path = getPathFromURL(path)));
858859
nullCheck(path);
859-
return binding.rmdir(pathModule._makeLong(path));
860+
return binding.rmdir(pathModule.toNamespacedPath(path));
860861
};
861862

862863
fs.fdatasync = function(fd, callback) {
@@ -887,15 +888,15 @@ fs.mkdir = function(path, mode, callback) {
887888
if (!nullCheck(path, callback)) return;
888889
var req = new FSReqWrap();
889890
req.oncomplete = callback;
890-
binding.mkdir(pathModule._makeLong(path),
891+
binding.mkdir(pathModule.toNamespacedPath(path),
891892
modeNum(mode, 0o777),
892893
req);
893894
};
894895

895896
fs.mkdirSync = function(path, mode) {
896897
handleError((path = getPathFromURL(path)));
897898
nullCheck(path);
898-
return binding.mkdir(pathModule._makeLong(path),
899+
return binding.mkdir(pathModule.toNamespacedPath(path),
899900
modeNum(mode, 0o777));
900901
};
901902

@@ -907,14 +908,14 @@ fs.readdir = function(path, options, callback) {
907908
if (!nullCheck(path, callback)) return;
908909
var req = new FSReqWrap();
909910
req.oncomplete = callback;
910-
binding.readdir(pathModule._makeLong(path), options.encoding, req);
911+
binding.readdir(pathModule.toNamespacedPath(path), options.encoding, req);
911912
};
912913

913914
fs.readdirSync = function(path, options) {
914915
options = getOptions(options, {});
915916
handleError((path = getPathFromURL(path)));
916917
nullCheck(path);
917-
return binding.readdir(pathModule._makeLong(path), options.encoding);
918+
return binding.readdir(pathModule.toNamespacedPath(path), options.encoding);
918919
};
919920

920921
fs.fstat = function(fd, callback) {
@@ -930,7 +931,7 @@ fs.lstat = function(path, callback) {
930931
if (!nullCheck(path, callback)) return;
931932
var req = new FSReqWrap();
932933
req.oncomplete = callback;
933-
binding.lstat(pathModule._makeLong(path), req);
934+
binding.lstat(pathModule.toNamespacedPath(path), req);
934935
};
935936

936937
fs.stat = function(path, callback) {
@@ -940,7 +941,7 @@ fs.stat = function(path, callback) {
940941
if (!nullCheck(path, callback)) return;
941942
var req = new FSReqWrap();
942943
req.oncomplete = callback;
943-
binding.stat(pathModule._makeLong(path), req);
944+
binding.stat(pathModule.toNamespacedPath(path), req);
944945
};
945946

946947
fs.fstatSync = function(fd) {
@@ -951,14 +952,14 @@ fs.fstatSync = function(fd) {
951952
fs.lstatSync = function(path) {
952953
handleError((path = getPathFromURL(path)));
953954
nullCheck(path);
954-
binding.lstat(pathModule._makeLong(path));
955+
binding.lstat(pathModule.toNamespacedPath(path));
955956
return statsFromValues();
956957
};
957958

958959
fs.statSync = function(path) {
959960
handleError((path = getPathFromURL(path)));
960961
nullCheck(path);
961-
binding.stat(pathModule._makeLong(path));
962+
binding.stat(pathModule.toNamespacedPath(path));
962963
return statsFromValues();
963964
};
964965

@@ -970,14 +971,14 @@ fs.readlink = function(path, options, callback) {
970971
if (!nullCheck(path, callback)) return;
971972
var req = new FSReqWrap();
972973
req.oncomplete = callback;
973-
binding.readlink(pathModule._makeLong(path), options.encoding, req);
974+
binding.readlink(pathModule.toNamespacedPath(path), options.encoding, req);
974975
};
975976

976977
fs.readlinkSync = function(path, options) {
977978
options = getOptions(options, {});
978979
handleError((path = getPathFromURL(path)));
979980
nullCheck(path);
980-
return binding.readlink(pathModule._makeLong(path), options.encoding);
981+
return binding.readlink(pathModule.toNamespacedPath(path), options.encoding);
981982
};
982983

983984
function preprocessSymlinkDestination(path, type, linkPath) {
@@ -988,7 +989,7 @@ function preprocessSymlinkDestination(path, type, linkPath) {
988989
// Junctions paths need to be absolute and \\?\-prefixed.
989990
// A relative target is relative to the link's parent directory.
990991
path = pathModule.resolve(linkPath, '..', path);
991-
return pathModule._makeLong(path);
992+
return pathModule.toNamespacedPath(path);
992993
} else {
993994
// Windows symlinks don't tolerate forward slashes.
994995
return ('' + path).replace(/\//g, '\\');
@@ -1012,7 +1013,7 @@ fs.symlink = function(target, path, type_, callback_) {
10121013
req.oncomplete = callback;
10131014

10141015
binding.symlink(preprocessSymlinkDestination(target, type, path),
1015-
pathModule._makeLong(path),
1016+
pathModule.toNamespacedPath(path),
10161017
type,
10171018
req);
10181019
};
@@ -1025,7 +1026,7 @@ fs.symlinkSync = function(target, path, type) {
10251026
nullCheck(path);
10261027

10271028
return binding.symlink(preprocessSymlinkDestination(target, type, path),
1028-
pathModule._makeLong(path),
1029+
pathModule.toNamespacedPath(path),
10291030
type);
10301031
};
10311032

@@ -1044,8 +1045,8 @@ fs.link = function(existingPath, newPath, callback) {
10441045
var req = new FSReqWrap();
10451046
req.oncomplete = callback;
10461047

1047-
binding.link(pathModule._makeLong(existingPath),
1048-
pathModule._makeLong(newPath),
1048+
binding.link(pathModule.toNamespacedPath(existingPath),
1049+
pathModule.toNamespacedPath(newPath),
10491050
req);
10501051
};
10511052

@@ -1054,8 +1055,8 @@ fs.linkSync = function(existingPath, newPath) {
10541055
handleError((newPath = getPathFromURL(newPath)));
10551056
nullCheck(existingPath);
10561057
nullCheck(newPath);
1057-
return binding.link(pathModule._makeLong(existingPath),
1058-
pathModule._makeLong(newPath));
1058+
return binding.link(pathModule.toNamespacedPath(existingPath),
1059+
pathModule.toNamespacedPath(newPath));
10591060
};
10601061

10611062
fs.unlink = function(path, callback) {
@@ -1065,13 +1066,13 @@ fs.unlink = function(path, callback) {
10651066
if (!nullCheck(path, callback)) return;
10661067
var req = new FSReqWrap();
10671068
req.oncomplete = callback;
1068-
binding.unlink(pathModule._makeLong(path), req);
1069+
binding.unlink(pathModule.toNamespacedPath(path), req);
10691070
};
10701071

10711072
fs.unlinkSync = function(path) {
10721073
handleError((path = getPathFromURL(path)));
10731074
nullCheck(path);
1074-
return binding.unlink(pathModule._makeLong(path));
1075+
return binding.unlink(pathModule.toNamespacedPath(path));
10751076
};
10761077

10771078
fs.fchmod = function(fd, mode, callback) {
@@ -1129,15 +1130,15 @@ fs.chmod = function(path, mode, callback) {
11291130
if (!nullCheck(path, callback)) return;
11301131
var req = new FSReqWrap();
11311132
req.oncomplete = callback;
1132-
binding.chmod(pathModule._makeLong(path),
1133+
binding.chmod(pathModule.toNamespacedPath(path),
11331134
modeNum(mode),
11341135
req);
11351136
};
11361137

11371138
fs.chmodSync = function(path, mode) {
11381139
handleError((path = getPathFromURL(path)));
11391140
nullCheck(path);
1140-
return binding.chmod(pathModule._makeLong(path), modeNum(mode));
1141+
return binding.chmod(pathModule.toNamespacedPath(path), modeNum(mode));
11411142
};
11421143

11431144
if (constants.O_SYMLINK !== undefined) {
@@ -1175,13 +1176,13 @@ fs.chown = function(path, uid, gid, callback) {
11751176
if (!nullCheck(path, callback)) return;
11761177
var req = new FSReqWrap();
11771178
req.oncomplete = callback;
1178-
binding.chown(pathModule._makeLong(path), uid, gid, req);
1179+
binding.chown(pathModule.toNamespacedPath(path), uid, gid, req);
11791180
};
11801181

11811182
fs.chownSync = function(path, uid, gid) {
11821183
handleError((path = getPathFromURL(path)));
11831184
nullCheck(path);
1184-
return binding.chown(pathModule._makeLong(path), uid, gid);
1185+
return binding.chown(pathModule.toNamespacedPath(path), uid, gid);
11851186
};
11861187

11871188
// converts Date or number to a fractional UNIX timestamp
@@ -1216,7 +1217,7 @@ fs.utimes = function(path, atime, mtime, callback) {
12161217
if (!nullCheck(path, callback)) return;
12171218
var req = new FSReqWrap();
12181219
req.oncomplete = callback;
1219-
binding.utimes(pathModule._makeLong(path),
1220+
binding.utimes(pathModule.toNamespacedPath(path),
12201221
toUnixTimestamp(atime),
12211222
toUnixTimestamp(mtime),
12221223
req);
@@ -1227,7 +1228,7 @@ fs.utimesSync = function(path, atime, mtime) {
12271228
nullCheck(path);
12281229
atime = toUnixTimestamp(atime);
12291230
mtime = toUnixTimestamp(mtime);
1230-
binding.utimes(pathModule._makeLong(path), atime, mtime);
1231+
binding.utimes(pathModule.toNamespacedPath(path), atime, mtime);
12311232
};
12321233

12331234
fs.futimes = function(fd, atime, mtime, callback) {
@@ -1383,7 +1384,7 @@ FSWatcher.prototype.start = function(filename,
13831384
encoding) {
13841385
handleError((filename = getPathFromURL(filename)));
13851386
nullCheck(filename);
1386-
var err = this._handle.start(pathModule._makeLong(filename),
1387+
var err = this._handle.start(pathModule.toNamespacedPath(filename),
13871388
persistent,
13881389
recursive,
13891390
encoding);
@@ -1472,7 +1473,8 @@ util.inherits(StatWatcher, EventEmitter);
14721473
StatWatcher.prototype.start = function(filename, persistent, interval) {
14731474
handleError((filename = getPathFromURL(filename)));
14741475
nullCheck(filename);
1475-
this._handle.start(pathModule._makeLong(filename), persistent, interval);
1476+
this._handle.start(pathModule.toNamespacedPath(filename),
1477+
persistent, interval);
14761478
};
14771479

14781480

@@ -1627,7 +1629,7 @@ fs.realpathSync = function realpathSync(p, options) {
16271629

16281630
// On windows, check that the root exists. On unix there is no need.
16291631
if (isWindows && !knownHard[base]) {
1630-
binding.lstat(pathModule._makeLong(base));
1632+
binding.lstat(pathModule.toNamespacedPath(base));
16311633
knownHard[base] = true;
16321634
}
16331635

@@ -1666,7 +1668,7 @@ fs.realpathSync = function realpathSync(p, options) {
16661668
// Use stats array directly to avoid creating an fs.Stats instance just
16671669
// for our internal use.
16681670

1669-
var baseLong = pathModule._makeLong(base);
1671+
var baseLong = pathModule.toNamespacedPath(base);
16701672
binding.lstat(baseLong);
16711673

16721674
if ((statValues[1/*mode*/] & S_IFMT) !== S_IFLNK) {
@@ -1706,7 +1708,7 @@ fs.realpathSync = function realpathSync(p, options) {
17061708

17071709
// On windows, check that the root exists. On unix there is no need.
17081710
if (isWindows && !knownHard[base]) {
1709-
binding.lstat(pathModule._makeLong(base));
1711+
binding.lstat(pathModule.toNamespacedPath(base));
17101712
knownHard[base] = true;
17111713
}
17121714
}

0 commit comments

Comments
 (0)