RoadmapShopEvents
Skip to main content

Home > @rushstack/node-core-library > FileSystem

FileSystem class

The FileSystem API provides a complete set of recommended operations for interacting with the file system.

Signature:
export declare class FileSystem

Remarks

We recommend to use this instead of the native fs API, because fs is a minimal set of low-level primitives that must be mapped for each supported operating system. The FileSystem API takes a philosophical approach of providing "one obvious way" to do each operation. We also prefer synchronous operations except in cases where there would be a clear performance benefit for using async, since synchronous code is much easier to read and debug. Also, indiscriminate parallelism has been seen to actually worsen performance, versus improving it.

Note that in the documentation, we refer to "filesystem objects", this can be a file, folder, symbolic link, hard link, directory junction, etc.

Methods

MethodModifiersDescription
appendToFile(filePath, contents, options)staticWrites a text string to a file on disk, appending to the file if it already exists. Behind the scenes it uses fs.appendFileSync().
appendToFileAsync(filePath, contents, options)staticAn async version of FileSystem.appendToFile() .
changePosixModeBits(path, mode)staticChanges the permissions (i.e. file mode bits) for a filesystem object. Behind the scenes it uses fs.chmodSync().
changePosixModeBitsAsync(path, mode)staticAn async version of FileSystem.changePosixModeBits() .
copyFile(options)staticCopies a single file from one location to another. By default, destinationPath is overwritten if it already exists.
copyFileAsync(options)staticAn async version of FileSystem.copyFile() .
copyFiles(options)staticCopies a file or folder from one location to another, recursively copying any folder contents. By default, destinationPath is overwritten if it already exists.
copyFilesAsync(options)staticAn async version of FileSystem.copyFiles() .
createHardLink(options)staticCreates a hard link. The link target must be a file, not a folder. Behind the scenes it uses fs.linkSync().
createHardLinkAsync(options)staticAn async version of FileSystem.createHardLink() .
createSymbolicLinkFile(options)staticCreates a symbolic link to a file. On Windows operating systems, this may require administrator elevation. Behind the scenes it uses fs.symlinkSync().
createSymbolicLinkFileAsync(options)staticAn async version of FileSystem.createSymbolicLinkFile() .
createSymbolicLinkFolder(options)staticCreates a symbolic link to a folder. On Windows operating systems, this may require administrator elevation. Behind the scenes it uses fs.symlinkSync().
createSymbolicLinkFolderAsync(options)staticAn async version of FileSystem.createSymbolicLinkFolder() .
createSymbolicLinkJunction(options)staticCreates an NTFS "directory junction" on Windows operating systems; for other operating systems, it creates a regular symbolic link. The link target must be a folder, not a file. Behind the scenes it uses fs.symlinkSync().
createSymbolicLinkJunctionAsync(options)staticAn async version of FileSystem.createSymbolicLinkJunction() .
deleteFile(filePath, options)staticDeletes a file. Can optionally throw if the file doesn't exist. Behind the scenes it uses fs.unlinkSync().
deleteFileAsync(filePath, options)staticAn async version of FileSystem.deleteFile() .
deleteFolder(folderPath)staticDeletes a folder, including all of its contents. Behind the scenes is uses fs-extra.removeSync().
deleteFolderAsync(folderPath)staticAn async version of FileSystem.deleteFolder() .
ensureEmptyFolder(folderPath)staticDeletes the content of a folder, but not the folder itself. Also ensures the folder exists. Behind the scenes it uses fs-extra.emptyDirSync().
ensureEmptyFolderAsync(folderPath)staticAn async version of FileSystem.ensureEmptyFolder() .
ensureFolder(folderPath)staticRecursively creates a folder at a given path. Behind the scenes is uses fs-extra.ensureDirSync().
ensureFolderAsync(folderPath)staticAn async version of FileSystem.ensureFolder() .
exists(path)staticReturns true if the path exists on disk. Behind the scenes it uses fs.existsSync().
existsAsync(path)staticAn async version of FileSystem.exists() .
formatPosixModeBits(modeBits)staticReturns a 10-character string representation of a PosixModeBits value similar to what would be displayed by a command such as "ls -l" on a POSIX-like operating system.
getLinkStatistics(path)staticGets the statistics of a filesystem object. Does NOT follow the link to its target. Behind the scenes it uses fs.lstatSync().
getLinkStatisticsAsync(path)staticAn async version of FileSystem.getLinkStatistics() .
getPosixModeBits(path)staticRetrieves the permissions (i.e. file mode bits) for a filesystem object. Behind the scenes it uses fs.chmodSync().
getPosixModeBitsAsync(path)staticAn async version of FileSystem.getPosixModeBits() .
getRealPath(linkPath)staticFollows a link to its destination and returns the absolute path to the final target of the link. Behind the scenes it uses fs.realpathSync().
getRealPathAsync(linkPath)staticAn async version of FileSystem.getRealPath() .
getStatistics(path)staticGets the statistics for a particular filesystem object. If the path is a link, this function follows the link and returns statistics about the link target. Behind the scenes it uses fs.statSync().
getStatisticsAsync(path)staticAn async version of FileSystem.getStatistics() .
isErrnoException(error)staticDetects if the provided error object is a NodeJS.ErrnoException
isExistError(error)staticReturns true if the error object indicates the file or folder already exists (EEXIST).
isFileDoesNotExistError(error)staticReturns true if the error object indicates the file does not exist (ENOENT).
isFolderDoesNotExistError(error)staticReturns true if the error object indicates the folder does not exist (ENOTDIR).
isNotExistError(error)staticReturns true if the error object indicates the file or folder does not exist (ENOENT or ENOTDIR)
isUnlinkNotPermittedError(error)staticReturns true if the error object indicates that the unlink system call failed due to a permissions issue (EPERM).
move(options)staticMoves a file. The folder must exist, unless the ensureFolderExists option is provided. Behind the scenes it uses fs-extra.moveSync()
moveAsync(options)staticAn async version of FileSystem.move() .
readFile(filePath, options)staticReads the contents of a file into a string. Behind the scenes it uses fs.readFileSync().
readFileAsync(filePath, options)staticAn async version of FileSystem.readFile() .
readFileToBuffer(filePath)staticReads the contents of a file into a buffer. Behind the scenes is uses fs.readFileSync().
readFileToBufferAsync(filePath)staticAn async version of FileSystem.readFileToBuffer() .
readFolder(folderPath, options)static
readFolderAsync(folderPath, options)static
readFolderItemNames(folderPath, options)staticReads the names of folder entries, not including "." or "..". Behind the scenes it uses fs.readdirSync().
readFolderItemNamesAsync(folderPath, options)staticAn async version of FileSystem.readFolderItemNames() .
readFolderItems(folderPath, options)staticReads the contents of the folder, not including "." or "..", returning objects including the entry names and types. Behind the scenes it uses fs.readdirSync().
readFolderItemsAsync(folderPath, options)staticAn async version of FileSystem.readFolderItems() .
readLink(path)staticIf path refers to a symbolic link, this returns the path of the link target, which may be an absolute or relative path.
readLinkAsync(path)staticAn async version of FileSystem.readLink() .
updateTimes(path, times)staticUpdates the accessed and modified timestamps of the filesystem object referenced by path. Behind the scenes it uses fs.utimesSync(). The caller should specify both times in the times parameter.
updateTimesAsync(path, times)staticAn async version of FileSystem.updateTimes() .
writeFile(filePath, contents, options)staticWrites a text string to a file on disk, overwriting the file if it already exists. Behind the scenes it uses fs.writeFileSync().
writeFileAsync(filePath, contents, options)staticAn async version of FileSystem.writeFile() .