From 9a2651352b8a6d1f687e3808d6d5e4615a40eb7b Mon Sep 17 00:00:00 2001 From: Voltrex <62040526+VoltrexMaster@users.noreply.github.com> Date: Tue, 20 Apr 2021 10:32:24 +0430 Subject: [PATCH] typings: add JSDoc typings for fs Added JSDoc typings for the `fs` lib module. PR-URL: https://github.com/nodejs/node/pull/38306 Reviewed-By: James M Snell Reviewed-By: Benjamin Gruenbaum Reviewed-By: Michael Dawson Reviewed-By: Rich Trott --- lib/fs.js | 797 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 771 insertions(+), 26 deletions(-) diff --git a/lib/fs.js b/lib/fs.js index e6cf8527e8720d..409ce83d628c6c 100644 --- a/lib/fs.js +++ b/lib/fs.js @@ -207,6 +207,14 @@ function isFileType(stats, fileType) { return (mode & S_IFMT) === fileType; } +/** + * Tests a user's permissions for the file or directory + * specified by `path`. + * @param {string | Buffer | URL} path + * @param {number} [mode] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function access(path, mode, callback) { if (typeof mode === 'function') { callback = mode; @@ -222,6 +230,13 @@ function access(path, mode, callback) { binding.access(pathModule.toNamespacedPath(path), mode, req); } +/** + * Synchronously tests a user's permissions for the file or + * directory specified by `path`. + * @param {string | Buffer | URL} path + * @param {number} [mode] + * @returns {void | never} + */ function accessSync(path, mode) { path = getValidatedPath(path); mode = getValidMode(mode, 'access'); @@ -231,6 +246,12 @@ function accessSync(path, mode) { handleErrorFromBinding(ctx); } +/** + * Tests whether or not the given path exists. + * @param {string | Buffer | URL} path + * @param {(exists?: boolean) => any} callback + * @returns {void} + */ function exists(path, callback) { maybeCallback(callback); @@ -257,6 +278,11 @@ ObjectDefineProperty(exists, internalUtil.promisify.custom, { // 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 +/** + * Synchronously tests whether or not the given path exists. + * @param {string | Buffer | URL} path + * @returns {boolean} + */ function existsSync(path) { try { path = getValidatedPath(path); @@ -326,6 +352,20 @@ function checkAborted(signal, callback) { return false; } +/** + * Asynchronously reads the entire contents of a file. + * @param {string | Buffer | URL | number} path + * @param {{ + * encoding?: string | null; + * flag?: string; + * signal?: AbortSignal; + * } | string} [options] + * @param {( + * err?: Error, + * data?: string | Buffer + * ) => any} callback + * @returns {void} + */ function readFile(path, options, callback) { callback = maybeCallback(callback || options); options = getOptions(options, { flag: 'r' }); @@ -396,6 +436,15 @@ function tryReadSync(fd, isUserFd, buffer, pos, len) { return bytesRead; } +/** + * Synchronously reads the entire contents of a file. + * @param {string | Buffer | URL | number} path + * @param {{ + * encoding?: string | null; + * flag?: string; + * }} [options] + * @returns {string | Buffer} + */ function readFileSync(path, options) { options = getOptions(options, { flag: 'r' }); const isUserFd = isFd(path); // File descriptor ownership @@ -451,6 +500,12 @@ function defaultCloseCallback(err) { if (err != null) throw err; } +/** + * Closes the file descriptor. + * @param {number} fd + * @param {(err?: Error) => any} [callback] + * @returns {void} + */ function close(fd, callback = defaultCloseCallback) { fd = getValidatedFd(fd); if (callback !== defaultCloseCallback) @@ -461,6 +516,11 @@ function close(fd, callback = defaultCloseCallback) { binding.close(fd, req); } +/** + * Synchronously closes the file descriptor. + * @param {number} fd + * @returns {void} + */ function closeSync(fd) { fd = getValidatedFd(fd); @@ -469,6 +529,17 @@ function closeSync(fd) { handleErrorFromBinding(ctx); } +/** + * Asynchronously opens a file. + * @param {string | Buffer | URL} path + * @param {string | number} [flags] + * @param {string | number} [mode] + * @param {( + * err?: Error, + * fd?: number + * ) => any} callback + * @returns {void} + */ function open(path, flags, mode, callback) { path = getValidatedPath(path); if (arguments.length < 3) { @@ -493,7 +564,13 @@ function open(path, flags, mode, callback) { req); } - +/** + * Synchronously opens a file. + * @param {string | Buffer | URL} path + * @param {string | number} [flags] + * @param {string | number} [mode] + * @returns {number} + */ function openSync(path, flags, mode) { path = getValidatedPath(path); const flagsNumber = stringToFlags(flags); @@ -507,10 +584,20 @@ function openSync(path, flags, mode) { return result; } -// usage: -// fs.read(fd, buffer, offset, length, position, callback); -// OR -// fs.read(fd, {}, callback) +/** + * Reads file from the specified `fd` (file descriptor). + * @param {number} fd + * @param {Buffer | TypedArray | DataView} buffer + * @param {number} offset + * @param {number} length + * @param {number | bigint} position + * @param {( + * err?: Error, + * bytesRead?: number, + * buffer?: Buffer + * ) => any} callback + * @returns {void} + */ function read(fd, buffer, offset, length, position, callback) { fd = getValidatedFd(fd); @@ -580,10 +667,18 @@ function read(fd, buffer, offset, length, position, callback) { ObjectDefineProperty(read, internalUtil.customPromisifyArgs, { value: ['bytesRead', 'buffer'], enumerable: false }); -// usage: -// fs.readSync(fd, buffer, offset, length, position); -// OR -// fs.readSync(fd, buffer, {}) or fs.readSync(fd, buffer) +/** + * Synchronously reads the file from the + * specified `fd` (file descriptor). + * @param {number} fd + * @param {Buffer | TypedArray | DataView} buffer + * @param {{ + * offset?: number; + * length?: number; + * position?: number | bigint; + * }} [offset] + * @returns {number} + */ function readSync(fd, buffer, offset, length, position) { fd = getValidatedFd(fd); @@ -627,6 +722,19 @@ function readSync(fd, buffer, offset, length, position) { return result; } +/** + * Reads file from the specified `fd` (file descriptor) + * and writes to an array of `ArrayBufferView`s. + * @param {number} fd + * @param {ArrayBufferView[]} buffers + * @param {number} [position] + * @param {( + * err?: Error, + * bytesRead?: number, + * buffers?: ArrayBufferView[]; + * ) => any} callback + * @returns {void} + */ function readv(fd, buffers, position, callback) { function wrapper(err, read) { callback(err, read || 0, buffers); @@ -648,6 +756,15 @@ function readv(fd, buffers, position, callback) { ObjectDefineProperty(readv, internalUtil.customPromisifyArgs, { value: ['bytesRead', 'buffers'], enumerable: false }); +/** + * Synchronously reads file from the + * specified `fd` (file descriptor) and writes to an array + * of `ArrayBufferView`s. + * @param {number} fd + * @param {ArrayBufferView[]} buffers + * @param {number} [position] + * @returns {number} + */ function readvSync(fd, buffers, position) { fd = getValidatedFd(fd); validateBufferArray(buffers); @@ -662,10 +779,20 @@ function readvSync(fd, buffers, position) { return result; } -// usage: -// fs.write(fd, buffer[, offset[, length[, position]]], callback); -// OR -// fs.write(fd, string[, position[, encoding]], callback); +/** + * Writes `buffer` to the specified `fd` (file descriptor). + * @param {number} fd + * @param {Buffer | TypedArray | DataView | string | Object} buffer + * @param {number} [offset] + * @param {number} [length] + * @param {number} [position] + * @param {( + * err?: Error, + * bytesWritten?: number; + * buffer?: Buffer | TypedArray | DataView + * ) => any} callback + * @returns {void} + */ function write(fd, buffer, offset, length, position, callback) { function wrapper(err, written) { // Retain a reference to buffer so that it can't be GC'ed too soon. @@ -716,10 +843,16 @@ function write(fd, buffer, offset, length, position, callback) { ObjectDefineProperty(write, internalUtil.customPromisifyArgs, { value: ['bytesWritten', 'buffer'], enumerable: false }); -// Usage: -// fs.writeSync(fd, buffer[, offset[, length[, position]]]); -// OR -// fs.writeSync(fd, string[, position[, encoding]]); +/** + * Synchronously writes `buffer` to the + * specified `fd` (file descriptor). + * @param {number} fd + * @param {Buffer | TypedArray | DataView | string | Object} buffer + * @param {number} [offset] + * @param {number} [length] + * @param {number} [position] + * @returns {number} + */ function writeSync(fd, buffer, offset, length, position) { fd = getValidatedFd(fd); const ctx = {}; @@ -750,8 +883,19 @@ function writeSync(fd, buffer, offset, length, position) { return result; } -// usage: -// fs.writev(fd, buffers[, position], callback); +/** + * Writes an array of `ArrayBufferView`s to the + * specified `fd` (file descriptor). + * @param {number} fd + * @param {ArrayBufferView[]} buffers + * @param {number} [position] + * @param {( + * err?: Error, + * bytesWritten?: number, + * buffers?: ArrayBufferView[] + * ) => any} callback + * @returns {void} + */ function writev(fd, buffers, position, callback) { function wrapper(err, written) { callback(err, written || 0, buffers); @@ -775,6 +919,14 @@ ObjectDefineProperty(writev, internalUtil.customPromisifyArgs, { enumerable: false }); +/** + * Synchronously writes an array of `ArrayBufferView`s + * to the specified `fd` (file descriptor). + * @param {number} fd + * @param {ArrayBufferView[]} buffers + * @param {number} [position] + * @returns {number} + */ function writevSync(fd, buffers, position) { fd = getValidatedFd(fd); validateBufferArray(buffers); @@ -790,6 +942,14 @@ function writevSync(fd, buffers, position) { return result; } +/** + * Asynchronously renames file at `oldPath` to + * the pathname provided as `newPath`. + * @param {string | Buffer | URL} oldPath + * @param {string | Buffer | URL} newPath + * @param {(err?: Error) => any} callback + * @returns {void} + */ function rename(oldPath, newPath, callback) { callback = makeCallback(callback); oldPath = getValidatedPath(oldPath, 'oldPath'); @@ -801,6 +961,14 @@ function rename(oldPath, newPath, callback) { req); } + +/** + * Synchronously renames file at `oldPath` to + * the pathname provided as `newPath`. + * @param {string | Buffer | URL} oldPath + * @param {string | Buffer | URL} newPath + * @returns {void} + */ function renameSync(oldPath, newPath) { oldPath = getValidatedPath(oldPath, 'oldPath'); newPath = getValidatedPath(newPath, 'newPath'); @@ -810,6 +978,13 @@ function renameSync(oldPath, newPath) { handleErrorFromBinding(ctx); } +/** + * Truncates the file. + * @param {string | Buffer | URL} path + * @param {number} [len] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function truncate(path, len, callback) { if (typeof path === 'number') { showTruncateDeprecation(); @@ -837,6 +1012,12 @@ function truncate(path, len, callback) { }); } +/** + * Synchronously truncates the file. + * @param {string | Buffer | URL} path + * @param {number} [len] + * @returns {void} + */ function truncateSync(path, len) { if (typeof path === 'number') { // legacy @@ -858,6 +1039,13 @@ function truncateSync(path, len) { return ret; } +/** + * Truncates the file descriptor. + * @param {number} fd + * @param {number} [len] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function ftruncate(fd, len = 0, callback) { if (typeof len === 'function') { callback = len; @@ -873,6 +1061,12 @@ function ftruncate(fd, len = 0, callback) { binding.ftruncate(fd, len, req); } +/** + * Synchronously truncates the file descriptor. + * @param {number} fd + * @param {number} [len] + * @returns {void} + */ function ftruncateSync(fd, len = 0) { fd = getValidatedFd(fd); validateInteger(len, 'len'); @@ -888,6 +1082,17 @@ function lazyLoadRimraf() { ({ rimraf, rimrafSync } = require('internal/fs/rimraf')); } +/** + * Asynchronously removes a directory. + * @param {string | Buffer | URL} path + * @param {{ + * maxRetries?: number; + * recursive?: boolean; + * retryDelay?: number; + * }} [options] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function rmdir(path, options, callback) { if (typeof options === 'function') { callback = options; @@ -924,6 +1129,16 @@ function rmdir(path, options, callback) { } } +/** + * Synchronously removes a directory. + * @param {string | Buffer | URL} path + * @param {{ + * maxRetries?: number; + * recursive?: boolean; + * retryDelay?: number; + * }} [options] + * @returns {void} + */ function rmdirSync(path, options) { path = getValidatedPath(path); @@ -943,6 +1158,19 @@ function rmdirSync(path, options) { return handleErrorFromBinding(ctx); } +/** + * Asynchronously removes files and + * directories (modeled on the standard POSIX `rm` utility). + * @param {string | Buffer | URL} path + * @param {{ + * force?: boolean; + * maxRetries?: number; + * recursive?: boolean; + * retryDelay?: number; + * }} [options] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function rm(path, options, callback) { if (typeof options === 'function') { callback = options; @@ -958,6 +1186,18 @@ function rm(path, options, callback) { }); } +/** + * Synchronously removes files and + * directories (modeled on the standard POSIX `rm` utility). + * @param {string | Buffer | URL} path + * @param {{ + * force?: boolean; + * maxRetries?: number; + * recursive?: boolean; + * retryDelay?: number; + * }} [options] + * @returns {void} + */ function rmSync(path, options) { options = validateRmOptionsSync(path, options, false); @@ -965,6 +1205,14 @@ function rmSync(path, options) { return rimrafSync(pathModule.toNamespacedPath(path), options); } +/** + * Forces all currently queued I/O operations associated + * with the file to the operating system's synchronized + * I/O completion state. + * @param {number} fd + * @param {(err?: Error) => any} callback + * @returns {void} + */ function fdatasync(fd, callback) { fd = getValidatedFd(fd); const req = new FSReqCallback(); @@ -972,6 +1220,13 @@ function fdatasync(fd, callback) { binding.fdatasync(fd, req); } +/** + * Synchronously forces all currently queued I/O operations + * associated with the file to the operating + * system's synchronized I/O completion state. + * @param {number} fd + * @returns {void} + */ function fdatasyncSync(fd) { fd = getValidatedFd(fd); const ctx = {}; @@ -979,6 +1234,13 @@ function fdatasyncSync(fd) { handleErrorFromBinding(ctx); } +/** + * Requests for all data for the open file descriptor + * to be flushed to the storage device. + * @param {number} fd + * @param {(err?: Error) => any} callback + * @returns {void} + */ function fsync(fd, callback) { fd = getValidatedFd(fd); const req = new FSReqCallback(); @@ -986,6 +1248,12 @@ function fsync(fd, callback) { binding.fsync(fd, req); } +/** + * Synchronously requests for all data for the open + * file descriptor to be flushed to the storage device. + * @param {number} fd + * @returns {void} + */ function fsyncSync(fd) { fd = getValidatedFd(fd); const ctx = {}; @@ -993,6 +1261,16 @@ function fsyncSync(fd) { handleErrorFromBinding(ctx); } +/** + * Asynchronously creates a directory. + * @param {string | Buffer | URL} path + * @param {{ + * recursive?: boolean; + * mode?: string | number; + * } | number} [options] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function mkdir(path, options, callback) { let mode = 0o777; let recursive = false; @@ -1017,6 +1295,15 @@ function mkdir(path, options, callback) { parseFileMode(mode, 'mode'), recursive, req); } +/** + * Synchronously creates a directory. + * @param {string | Buffer | URL} path + * @param {{ + * recursive?: boolean; + * mode?: string | number; + * } | number} [options] + * @returns {string | void} + */ function mkdirSync(path, options) { let mode = 0o777; let recursive = false; @@ -1041,6 +1328,19 @@ function mkdirSync(path, options) { } } +/** + * Reads the contents of a directory. + * @param {string | Buffer | URL} path + * @param {string | { + * encoding?: string; + * withFileTypes?: boolean; + * }} [options] + * @param {( + * err?: Error, + * files?: string[] | Buffer[] | Direct[]; + * ) => any} callback + * @returns {void} + */ function readdir(path, options, callback) { callback = makeCallback(typeof options === 'function' ? options : callback); options = getOptions(options, {}); @@ -1062,6 +1362,15 @@ function readdir(path, options, callback) { !!options.withFileTypes, req); } +/** + * Synchronously reads the contents of a directory. + * @param {string | Buffer | URL} path + * @param {string | { + * encoding?: string; + * withFileTypes?: boolean; + * }} [options] + * @returns {string | Buffer[] | Dirent[]} + */ function readdirSync(path, options) { options = getOptions(options, {}); path = getValidatedPath(path); @@ -1073,6 +1382,17 @@ function readdirSync(path, options) { return options.withFileTypes ? getDirents(path, result) : result; } +/** + * Invokes the callback with the `fs.Stats` + * for the file descriptor. + * @param {number} fd + * @param {{ bigint?: boolean; }} [options] + * @param {( + * err?: Error, + * stats?: Stats + * ) => any} callback + * @returns {void} + */ function fstat(fd, options = { bigint: false }, callback) { if (typeof options === 'function') { callback = options; @@ -1086,6 +1406,17 @@ function fstat(fd, options = { bigint: false }, callback) { binding.fstat(fd, options.bigint, req); } +/** + * Retrieves the `fs.Stats` for the symbolic link + * referred to by the `path`. + * @param {string | Buffer | URL} path + * @param {{ bigint?: boolean; }} [options] + * @param {( + * err?: Error, + * stats?: Stats + * ) => any} callback + * @returns {void} + */ function lstat(path, options = { bigint: false }, callback) { if (typeof options === 'function') { callback = options; @@ -1099,6 +1430,16 @@ function lstat(path, options = { bigint: false }, callback) { binding.lstat(pathModule.toNamespacedPath(path), options.bigint, req); } +/** + * Asynchronously gets the stats of a file. + * @param {string | Buffer | URL} path + * @param {{ bigint?: boolean; }} [options] + * @param {( + * err?: Error, + * stats?: Stats + * ) => any} callback + * @returns {void} + */ function stat(path, options = { bigint: false }, callback) { if (typeof options === 'function') { callback = options; @@ -1125,6 +1466,16 @@ function hasNoEntryError(ctx) { return false; } +/** + * Synchronously retrieves the `fs.Stats` for + * the file descriptor. + * @param {number} fd + * @param {{ + * bigint?: boolean; + * throwIfNoEntry?: boolean; + * }} [options] + * @returns {Stats} + */ function fstatSync(fd, options = { bigint: false, throwIfNoEntry: true }) { fd = getValidatedFd(fd); const ctx = { fd }; @@ -1133,6 +1484,16 @@ function fstatSync(fd, options = { bigint: false, throwIfNoEntry: true }) { return getStatsFromBinding(stats); } +/** + * Synchronously retrieves the `fs.Stats` for + * the symbolic link referred to by the `path`. + * @param {string | Buffer | URL} path + * @param {{ + * bigint?: boolean; + * throwIfNoEntry?: boolean; + * }} [options] + * @returns {Stats} + */ function lstatSync(path, options = { bigint: false, throwIfNoEntry: true }) { path = getValidatedPath(path); const ctx = { path }; @@ -1145,6 +1506,16 @@ function lstatSync(path, options = { bigint: false, throwIfNoEntry: true }) { return getStatsFromBinding(stats); } +/** + * Synchronously retrieves the `fs.Stats` + * for the `path`. + * @param {string | Buffer | URL} path + * @param {{ + * bigint?: boolean; + * throwIfNoEntry?: boolean; + * }} [options] + * @returns {Stats} + */ function statSync(path, options = { bigint: false, throwIfNoEntry: true }) { path = getValidatedPath(path); const ctx = { path }; @@ -1157,6 +1528,17 @@ function statSync(path, options = { bigint: false, throwIfNoEntry: true }) { return getStatsFromBinding(stats); } +/** + * Reads the contents of a symbolic link + * referred to by `path`. + * @param {string | Buffer | URL} path + * @param {{ encoding?: string; } | string} [options] + * @param {( + * err?: Error, + * linkString?: string | Buffer + * ) => any} callback + * @returns {void} + */ function readlink(path, options, callback) { callback = makeCallback(typeof options === 'function' ? options : callback); options = getOptions(options, {}); @@ -1166,6 +1548,13 @@ function readlink(path, options, callback) { binding.readlink(pathModule.toNamespacedPath(path), options.encoding, req); } +/** + * Synchronously reads the contents of a symbolic link + * referred to by `path`. + * @param {string | Buffer | URL} path + * @param {{ encoding?: string; } | string} [options] + * @returns {string | Buffer} + */ function readlinkSync(path, options) { options = getOptions(options, {}); path = getValidatedPath(path, 'oldPath'); @@ -1176,6 +1565,14 @@ function readlinkSync(path, options) { return result; } +/** + * Creates the link called `path` pointing to `target`. + * @param {string | Buffer | URL} target + * @param {string | Buffer | URL} path + * @param {string} [type_] + * @param {(err?: Error) => any} callback_ + * @returns {void} + */ function symlink(target, path, type_, callback_) { const type = (typeof type_ === 'string' ? type_ : null); const callback = makeCallback(arguments[arguments.length - 1]); @@ -1218,6 +1615,14 @@ function symlink(target, path, type_, callback_) { binding.symlink(destination, pathModule.toNamespacedPath(path), flags, req); } +/** + * Synchronously creates the link called `path` + * pointing to `target`. + * @param {string | Buffer | URL} target + * @param {string | Buffer | URL} path + * @param {string} [type] + * @returns {void} + */ function symlinkSync(target, path, type) { type = (typeof type === 'string' ? type : null); if (isWindows && type === null) { @@ -1237,6 +1642,14 @@ function symlinkSync(target, path, type) { handleErrorFromBinding(ctx); } +/** + * Creates a new link from the `existingPath` + * to the `newPath`. + * @param {string | Buffer | URL} existingPath + * @param {string | Buffer | URL} newPath + * @param {(err?: Error) => any} callback + * @returns {void} + */ function link(existingPath, newPath, callback) { callback = makeCallback(callback); @@ -1251,6 +1664,13 @@ function link(existingPath, newPath, callback) { req); } +/** + * Synchronously creates a new link from the `existingPath` + * to the `newPath`. + * @param {string | Buffer | URL} existingPath + * @param {string | Buffer | URL} newPath + * @returns {void} + */ function linkSync(existingPath, newPath) { existingPath = getValidatedPath(existingPath, 'existingPath'); newPath = getValidatedPath(newPath, 'newPath'); @@ -1263,6 +1683,12 @@ function linkSync(existingPath, newPath) { return result; } +/** + * Asynchronously removes a file or symbolic link. + * @param {string | Buffer | URL} path + * @param {(err?: Error) => any} callback + * @returns {void} + */ function unlink(path, callback) { callback = makeCallback(callback); path = getValidatedPath(path); @@ -1271,6 +1697,11 @@ function unlink(path, callback) { binding.unlink(pathModule.toNamespacedPath(path), req); } +/** + * Synchronously removes a file or symbolic link. + * @param {string | Buffer | URL} path + * @returns {void} + */ function unlinkSync(path) { path = getValidatedPath(path); const ctx = { path }; @@ -1278,6 +1709,13 @@ function unlinkSync(path) { handleErrorFromBinding(ctx); } +/** + * Sets the permissions on the file. + * @param {number} fd + * @param {string | number} mode + * @param {(err?: Error) => any} callback + * @returns {void} + */ function fchmod(fd, mode, callback) { fd = getValidatedFd(fd); mode = parseFileMode(mode, 'mode'); @@ -1288,6 +1726,12 @@ function fchmod(fd, mode, callback) { binding.fchmod(fd, mode, req); } +/** + * Synchronously sets the permissions on the file. + * @param {number} fd + * @param {string | number} mode + * @returns {void} + */ function fchmodSync(fd, mode) { fd = getValidatedFd(fd); mode = parseFileMode(mode, 'mode'); @@ -1296,6 +1740,13 @@ function fchmodSync(fd, mode) { handleErrorFromBinding(ctx); } +/** + * Changes the permissions on a symbolic link. + * @param {string | Buffer | URL} path + * @param {number} mode + * @param {(err?: Error) => any} callback + * @returns {void} + */ function lchmod(path, mode, callback) { callback = maybeCallback(callback); mode = parseFileMode(mode, 'mode'); @@ -1314,6 +1765,12 @@ function lchmod(path, mode, callback) { }); } +/** + * Synchronously changes the permissions on a symbolic link. + * @param {string | Buffer | URL} path + * @param {number} mode + * @returns {void} + */ function lchmodSync(path, mode) { const fd = fs.openSync(path, O_WRONLY | O_SYMLINK); @@ -1328,7 +1785,13 @@ function lchmodSync(path, mode) { return ret; } - +/** + * Asynchronously changes the permissions of a file. + * @param {string | Buffer | URL} path + * @param {string | number} mode + * @param {(err?: Error) => any} callback + * @returns {void} + */ function chmod(path, mode, callback) { path = getValidatedPath(path); mode = parseFileMode(mode, 'mode'); @@ -1339,6 +1802,12 @@ function chmod(path, mode, callback) { binding.chmod(pathModule.toNamespacedPath(path), mode, req); } +/** + * Synchronously changes the permissions of a file. + * @param {string | Buffer | URL} path + * @param {string | number} mode + * @returns {void} + */ function chmodSync(path, mode) { path = getValidatedPath(path); mode = parseFileMode(mode, 'mode'); @@ -1348,6 +1817,14 @@ function chmodSync(path, mode) { handleErrorFromBinding(ctx); } +/** + * Sets the owner of the symbolic link. + * @param {string | Buffer | URL} path + * @param {number} uid + * @param {number} gid + * @param {(err?: Error) => any} callback + * @returns {void} + */ function lchown(path, uid, gid, callback) { callback = makeCallback(callback); path = getValidatedPath(path); @@ -1358,6 +1835,13 @@ function lchown(path, uid, gid, callback) { binding.lchown(pathModule.toNamespacedPath(path), uid, gid, req); } +/** + * Synchronously sets the owner of the symbolic link. + * @param {string | Buffer | URL} path + * @param {number} uid + * @param {number} gid + * @returns {void} + */ function lchownSync(path, uid, gid) { path = getValidatedPath(path); validateInteger(uid, 'uid', -1, kMaxUserId); @@ -1367,6 +1851,14 @@ function lchownSync(path, uid, gid) { handleErrorFromBinding(ctx); } +/** + * Sets the owner of the file. + * @param {number} fd + * @param {number} uid + * @param {number} gid + * @param {(err?: Error) => any} callback + * @returns {void} + */ function fchown(fd, uid, gid, callback) { fd = getValidatedFd(fd); validateInteger(uid, 'uid', -1, kMaxUserId); @@ -1378,6 +1870,13 @@ function fchown(fd, uid, gid, callback) { binding.fchown(fd, uid, gid, req); } +/** + * Synchronously sets the owner of the file. + * @param {number} fd + * @param {number} uid + * @param {number} gid + * @returns {void} + */ function fchownSync(fd, uid, gid) { fd = getValidatedFd(fd); validateInteger(uid, 'uid', -1, kMaxUserId); @@ -1388,6 +1887,15 @@ function fchownSync(fd, uid, gid) { handleErrorFromBinding(ctx); } +/** + * Asynchronously changes the owner and group + * of a file. + * @param {string | Buffer | URL} path + * @param {number} uid + * @param {number} gid + * @param {(err?: Error) => any} callback + * @returns {void} + */ function chown(path, uid, gid, callback) { callback = makeCallback(callback); path = getValidatedPath(path); @@ -1399,6 +1907,14 @@ function chown(path, uid, gid, callback) { binding.chown(pathModule.toNamespacedPath(path), uid, gid, req); } +/** + * Synchronously changes the owner and group + * of a file. + * @param {string | Buffer | URL} path + * @param {number} uid + * @param {number} gid + * @returns {void} + */ function chownSync(path, uid, gid) { path = getValidatedPath(path); validateInteger(uid, 'uid', -1, kMaxUserId); @@ -1408,6 +1924,15 @@ function chownSync(path, uid, gid) { handleErrorFromBinding(ctx); } +/** + * Changes the file system timestamps of the object + * referenced by `path`. + * @param {string | Buffer | URL} path + * @param {number | string | Date} atime + * @param {number | string | Date} mtime + * @param {(err?: Error) => any} callback + * @returns {void} + */ function utimes(path, atime, mtime, callback) { callback = makeCallback(callback); path = getValidatedPath(path); @@ -1420,6 +1945,14 @@ function utimes(path, atime, mtime, callback) { req); } +/** + * Synchronously changes the file system timestamps + * of the object referenced by `path`. + * @param {string | Buffer | URL} path + * @param {number | string | Date} atime + * @param {number | string | Date} mtime + * @returns {void} + */ function utimesSync(path, atime, mtime) { path = getValidatedPath(path); const ctx = { path }; @@ -1429,6 +1962,15 @@ function utimesSync(path, atime, mtime) { handleErrorFromBinding(ctx); } +/** + * Changes the file system timestamps of the object + * referenced by the supplied `fd` (file descriptor). + * @param {number} fd + * @param {number | string | Date} atime + * @param {number | string | Date} mtime + * @param {(err?: Error) => any} callback + * @returns {void} + */ function futimes(fd, atime, mtime, callback) { fd = getValidatedFd(fd); atime = toUnixTimestamp(atime, 'atime'); @@ -1440,6 +1982,15 @@ function futimes(fd, atime, mtime, callback) { binding.futimes(fd, atime, mtime, req); } +/** + * Synchronously changes the file system timestamps + * of the object referenced by the + * supplied `fd` (file descriptor). + * @param {number} fd + * @param {number | string | Date} atime + * @param {number | string | Date} mtime + * @returns {void} + */ function futimesSync(fd, atime, mtime) { fd = getValidatedFd(fd); atime = toUnixTimestamp(atime, 'atime'); @@ -1449,6 +2000,15 @@ function futimesSync(fd, atime, mtime) { handleErrorFromBinding(ctx); } +/** + * Changes the access and modification times of + * a file in the same way as `fs.utimes()`. + * @param {string | Buffer | URL} path + * @param {number | string | Date} atime + * @param {number | string | Date} mtime + * @param {(err?: Error) => any} callback + * @returns {void} + */ function lutimes(path, atime, mtime, callback) { callback = makeCallback(callback); path = getValidatedPath(path); @@ -1461,6 +2021,14 @@ function lutimes(path, atime, mtime, callback) { req); } +/** + * Synchronously changes the access and modification + * times of a file in the same way as `fs.utimesSync()`. + * @param {string | Buffer | URL} path + * @param {number | string | Date} atime + * @param {number | string | Date} mtime + * @returns {void} + */ function lutimesSync(path, atime, mtime) { path = getValidatedPath(path); const ctx = { path }; @@ -1507,6 +2075,19 @@ function writeAll(fd, isUserFd, buffer, offset, length, signal, callback) { }); } +/** + * Asynchronously writes data to the file. + * @param {string | Buffer | URL | number} path + * @param {string | Buffer | TypedArray | DataView | Object} data + * @param {{ + * encoding?: string | null; + * mode?: number; + * flag?: string; + * signal?: AbortSignal; + * } | string} [options] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function writeFile(path, data, options, callback) { callback = maybeCallback(callback || options); options = getOptions(options, { encoding: 'utf8', mode: 0o666, flag: 'w' }); @@ -1538,6 +2119,17 @@ function writeFile(path, data, options, callback) { }); } +/** + * Synchronously writes data to the file. + * @param {string | Buffer | URL | number} path + * @param {string | Buffer | TypedArray | DataView | Object} data + * @param {{ + * encoding?: string | null; + * mode?: number; + * flag?: string; + * } | string} [options] + * @returns {void} + */ function writeFileSync(path, data, options) { options = getOptions(options, { encoding: 'utf8', mode: 0o666, flag: 'w' }); @@ -1564,6 +2156,18 @@ function writeFileSync(path, data, options) { } } +/** + * Asynchronously appends data to a file. + * @param {string | Buffer | URL | number} path + * @param {string | Buffer} data + * @param {{ + * encoding?: string | null; + * mode?: number; + * flag?: string; + * } | string} [options] + * @param {(err?: Error) => any} callback + * @returns {void} + */ function appendFile(path, data, options, callback) { callback = maybeCallback(callback || options); options = getOptions(options, { encoding: 'utf8', mode: 0o666, flag: 'a' }); @@ -1578,6 +2182,17 @@ function appendFile(path, data, options, callback) { fs.writeFile(path, data, options, callback); } +/** + * Synchronously appends data to a file. + * @param {string | Buffer | URL | number} path + * @param {string | Buffer} data + * @param {{ + * encoding?: string | null; + * mode?: number; + * flag?: string; + * } | string} [options] + * @returns {void} + */ function appendFileSync(path, data, options) { options = getOptions(options, { encoding: 'utf8', mode: 0o666, flag: 'a' }); @@ -1591,6 +2206,21 @@ function appendFileSync(path, data, options) { fs.writeFileSync(path, data, options); } +/** + * Watches for the changes on `filename`. + * @param {string | Buffer | URL} filename + * @param {string | { + * persistent?: boolean; + * recursive?: boolean; + * encoding?: string; + * signal?: AbortSignal; + * }} [options] + * @param {( + * eventType?: string, + * filename?: string | Buffer + * ) => any} [listener] + * @returns {watchers.FSWatcher} + */ function watch(filename, options, listener) { if (typeof options === 'function') { listener = options; @@ -1633,6 +2263,20 @@ function watch(filename, options, listener) { const statWatchers = new SafeMap(); +/** + * Watches for changes on `filename`. + * @param {string | Buffer | URL} filename + * @param {{ + * bigint?: boolean; + * persistent?: boolean; + * interval?: number; + * }} [options] + * @param {( + * current?: Stats, + * previous?: Stats + * ) => any} listener + * @returns {watchers.StatWatcher} + */ function watchFile(filename, options, listener) { filename = getValidatedPath(filename); filename = pathModule.resolve(filename); @@ -1671,6 +2315,12 @@ function watchFile(filename, options, listener) { return stat; } +/** + * Stops watching for changes on `filename`. + * @param {string | Buffer | URL} filename + * @param {() => any} [listener] + * @returns {void} + */ function unwatchFile(filename, listener) { filename = getValidatedPath(filename); filename = pathModule.resolve(filename); @@ -1743,6 +2393,13 @@ if (isWindows) { } const emptyObj = ObjectCreate(null); + +/** + * Returns the resolved pathname. + * @param {string | Buffer | URL} p + * @param {string | { encoding?: string | null; }} [options] + * @returns {string | Buffer} + */ function realpathSync(p, options) { options = getOptions(options, emptyObj); p = toPathIfFileURL(p); @@ -1874,7 +2531,12 @@ function realpathSync(p, options) { return encodeRealpathResult(p, options); } - +/** + * Returns the resolved pathname. + * @param {string | Buffer | URL} p + * @param {string | { encoding?: string; }} [options] + * @returns {string | Buffer} + */ realpathSync.native = (path, options) => { options = getOptions(options, {}); path = getValidatedPath(path); @@ -1884,7 +2546,17 @@ realpathSync.native = (path, options) => { return result; }; - +/** + * Asynchronously computes the canonical pathname by + * resolving `.`, `..` and symbolic links. + * @param {string | Buffer | URL} p + * @param {string | { encoding?: string; }} [options] + * @param {( + * err?: Error, + * resolvedPath?: string | Buffer + * ) => any} callback + * @returns {void} + */ function realpath(p, options, callback) { callback = typeof options === 'function' ? options : maybeCallback(callback); options = getOptions(options, {}); @@ -2012,7 +2684,17 @@ function realpath(p, options, callback) { } } - +/** + * Asynchronously computes the canonical pathname by + * resolving `.`, `..` and symbolic links. + * @param {string | Buffer | URL} p + * @param {string | { encoding?: string; }} [options] + * @param {( + * err?: Error, + * resolvedPath?: string | Buffer + * ) => any} callback + * @returns {void} + */ realpath.native = (path, options, callback) => { callback = makeCallback(callback || options); options = getOptions(options, {}); @@ -2022,6 +2704,16 @@ realpath.native = (path, options, callback) => { return binding.realpath(path, options.encoding, req); }; +/** + * Creates a unique temporary directory. + * @param {string} prefix + * @param {string | { encoding?: string; }} [options] + * @param {( + * err?: Error, + * directory?: string + * ) => any} callback + * @returns {void} + */ function mkdtemp(prefix, options, callback) { callback = makeCallback(typeof options === 'function' ? options : callback); options = getOptions(options, {}); @@ -2035,7 +2727,12 @@ function mkdtemp(prefix, options, callback) { binding.mkdtemp(`${prefix}XXXXXX`, options.encoding, req); } - +/** + * Synchronously creates a unique temporary directory. + * @param {string} prefix + * @param {string | { encoding?: string; }} [options] + * @returns {string} + */ function mkdtempSync(prefix, options) { options = getOptions(options, {}); if (!prefix || typeof prefix !== 'string') { @@ -2051,7 +2748,15 @@ function mkdtempSync(prefix, options) { return result; } - +/** + * Asynchronously copies `src` to `dest`. By + * default, `dest` is overwritten if it already exists. + * @param {string | Buffer | URL} src + * @param {string | Buffer | URL} dest + * @param {number} [mode] + * @param {() => any} callback + * @returns {void} + */ function copyFile(src, dest, mode, callback) { if (typeof mode === 'function') { callback = mode; @@ -2071,7 +2776,14 @@ function copyFile(src, dest, mode, callback) { binding.copyFile(src, dest, mode, req); } - +/** + * Synchronously copies `src` to `dest`. By + * default, `dest` is overwritten if it already exists. + * @param {string | Buffer | URL} src + * @param {string | Buffer | URL} dest + * @param {number} [mode] + * @returns {void} + */ function copyFileSync(src, dest, mode) { src = getValidatedPath(src, 'src'); dest = getValidatedPath(dest, 'dest'); @@ -2093,11 +2805,44 @@ function lazyLoadStreams() { } } +/** + * Creates a readable stream with a default `highWaterMark` + * of 64 kb. + * @param {string | Buffer | URL} path + * @param {string | { + * flags?: string; + * encoding?: string; + * fd?: number | FileHandle; + * mode?: number; + * autoClose?: boolean; + * emitClose?: boolean; + * start: number; + * end?: number; + * highWaterMark?: number; + * fs?: Object | null; + * }} [options] + * @returns {ReadStream} + */ function createReadStream(path, options) { lazyLoadStreams(); return new ReadStream(path, options); } +/** + * Creates a write stream. + * @param {string | Buffer | URL} path + * @param {string | { + * flags?: string; + * encoding?: string; + * fd?: number | FileHandle; + * mode?: number; + * autoClose?: boolean; + * emitClose?: boolean; + * start: number; + * fs?: Object | null; + * }} [options] + * @returns {WriteStream} + */ function createWriteStream(path, options) { lazyLoadStreams(); return new WriteStream(path, options);