Skip to content

Commit

Permalink
typings: add JSDoc types to lib/path
Browse files Browse the repository at this point in the history
PR-URL: #38186
Reviewed-By: Bradley Farias <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
  • Loading branch information
Skn0tt authored and targos committed May 1, 2021
1 parent 08a6d9e commit e2c2f2b
Showing 1 changed file with 105 additions and 6 deletions.
111 changes: 105 additions & 6 deletions lib/path.js
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,17 @@ function normalizeString(path, allowAboveRoot, separator, isPathSeparator) {
return res;
}

/**
* @param {string} sep
* @param {{
* dir?: string;
* root?: string;
* base?: string;
* name?: string;
* ext?: string;
* }} pathObject
* @returns {string}
*/
function _format(sep, pathObject) {
if (pathObject === null || typeof pathObject !== 'object') {
throw new ERR_INVALID_ARG_TYPE('pathObject', 'Object', pathObject);
Expand All @@ -126,7 +137,11 @@ function _format(sep, pathObject) {
}

const win32 = {
// path.resolve([from ...], to)
/**
* path.resolve([from ...], to)
* @param {...string} args
* @returns {string}
*/
resolve(...args) {
let resolvedDevice = '';
let resolvedTail = '';
Expand Down Expand Up @@ -262,6 +277,10 @@ const win32 = {
`${resolvedDevice}${resolvedTail}` || '.';
},

/**
* @param {string} path
* @returns {string}
*/
normalize(path) {
validateString(path, 'path');
const len = path.length;
Expand Down Expand Up @@ -349,6 +368,10 @@ const win32 = {
return isAbsolute ? `${device}\\${tail}` : `${device}${tail}`;
},

/**
* @param {string} path
* @returns {boolean}
*/
isAbsolute(path) {
validateString(path, 'path');
const len = path.length;
Expand All @@ -364,6 +387,10 @@ const win32 = {
isPathSeparator(path.charCodeAt(2)));
},

/**
* @param {...string} args
* @returns {string}
*/
join(...args) {
if (args.length === 0)
return '.';
Expand Down Expand Up @@ -429,10 +456,15 @@ const win32 = {
return win32.normalize(joined);
},

// It will solve the relative path from `from` to `to`, for instance:
// from = 'C:\\orandea\\test\\aaa'
// to = 'C:\\orandea\\impl\\bbb'
// The output of the function should be: '..\\..\\impl\\bbb'
/**
* It will solve the relative path from `from` to `to`, for instancee
* from = 'C:\\orandea\\test\\aaa'
* to = 'C:\\orandea\\impl\\bbb'
* The output of the function should be: '..\\..\\impl\\bbb'
* @param {string} from
* @param {string} to
* @returns {string}
*/
relative(from, to) {
validateString(from, 'from');
validateString(to, 'to');
Expand Down Expand Up @@ -579,6 +611,10 @@ const win32 = {
return path;
},

/**
* @param {string} path
* @returns {string}
*/
dirname(path) {
validateString(path, 'path');
const len = path.length;
Expand Down Expand Up @@ -665,6 +701,11 @@ const win32 = {
return path.slice(0, end);
},

/**
* @param {string} path
* @param {string} [ext]
* @returns {string}
*/
basename(path, ext) {
if (ext !== undefined)
validateString(ext, 'ext');
Expand Down Expand Up @@ -748,6 +789,10 @@ const win32 = {
return path.slice(start, end);
},

/**
* @param {string} path
* @returns {string}
*/
extname(path) {
validateString(path, 'path');
let start = 0;
Expand Down Expand Up @@ -814,6 +859,16 @@ const win32 = {

format: _format.bind(null, '\\'),

/**
* @param {string} path
* @returns {{
* dir: string;
* root: string;
* base: string;
* name: string;
* ext: string;
* }}
*/
parse(path) {
validateString(path, 'path');

Expand Down Expand Up @@ -969,7 +1024,11 @@ const win32 = {
};

const posix = {
// path.resolve([from ...], to)
/**
* path.resolve([from ...], to)
* @param {...string} args
* @returns {string}
*/
resolve(...args) {
let resolvedPath = '';
let resolvedAbsolute = false;
Expand Down Expand Up @@ -1001,6 +1060,10 @@ const posix = {
return resolvedPath.length > 0 ? resolvedPath : '.';
},

/**
* @param {string} path
* @returns {string}
*/
normalize(path) {
validateString(path, 'path');

Expand All @@ -1025,11 +1088,19 @@ const posix = {
return isAbsolute ? `/${path}` : path;
},

/**
* @param {string} path
* @returns {boolean}
*/
isAbsolute(path) {
validateString(path, 'path');
return path.length > 0 && path.charCodeAt(0) === CHAR_FORWARD_SLASH;
},

/**
* @param {...string} args
* @returns {string}
*/
join(...args) {
if (args.length === 0)
return '.';
Expand All @@ -1049,6 +1120,11 @@ const posix = {
return posix.normalize(joined);
},

/**
* @param {string} from
* @param {string} to
* @returns {string}
*/
relative(from, to) {
validateString(from, 'from');
validateString(to, 'to');
Expand Down Expand Up @@ -1124,6 +1200,10 @@ const posix = {
return path;
},

/**
* @param {string} path
* @returns {string}
*/
dirname(path) {
validateString(path, 'path');
if (path.length === 0)
Expand All @@ -1150,6 +1230,11 @@ const posix = {
return path.slice(0, end);
},

/**
* @param {string} path
* @param {string} [ext]
* @returns {string}
*/
basename(path, ext) {
if (ext !== undefined)
validateString(ext, 'ext');
Expand Down Expand Up @@ -1225,6 +1310,10 @@ const posix = {
return path.slice(start, end);
},

/**
* @param {string} path
* @returns {string}
*/
extname(path) {
validateString(path, 'path');
let startDot = -1;
Expand Down Expand Up @@ -1279,6 +1368,16 @@ const posix = {

format: _format.bind(null, '/'),

/**
* @param {string} path
* @returns {{
* dir: string;
* root: string;
* base: string;
* name: string;
* ext: string;
* }}
*/
parse(path) {
validateString(path, 'path');

Expand Down

0 comments on commit e2c2f2b

Please sign in to comment.