tools-filesystem

@rnx-kit/tools-filesystem is a collection of commonly used functions for manipulating the filesystem.

You can import the entire package, or, to save space, import individual categories:

import * as tools from "@rnx-kit/tools-filesystem";

// Alternatively...
import * as mocks from "@rnx-kit/tools-filesystem/mocks";

Filesystem helpers

The bulk of this package contains a set of convenience wrappers for working with the filesystem. This ensures people use the same constants when referencing files, handle certain patterns like BOM stripping and new line appending for JSON files correctly, and provides implementations for some more complex patterns like file matching.

MockFS submodule

This package has an export entry for mocking the filesystem for testing. This uses memfs for its implementation. This is marked as an optional peer dependency but it is required when using the mockFS convenience wrapper.

Category	Function	Description
compare	filesMatch(pathA, pathB)	Try to efficiently determine if two files match by size and content
compare	filesMatchSync(path1, path2)	Compare two files to determine if two files are identical in content. This means either the content matches or they are actually referencing the same file on disk (e.g. via a hardlink).
compare	isSameFileFromStats(stats1, stats2)	Compares the stats of two files to determine if they refer to the same file. This preempts more expensive file comparisons by comparing the stats first. This will return: - true if the stats indicate the files are the same (e.g. same inode and device) - false if the stats indicate the files are different (e.g. different sizes) - undefined if the stats are inconclusive and further checks are needed (e.g. same size but different inodes)
dirs	ensureDir(path)	Asynchronously ensures that a directory exists, creating it if necessary.
dirs	ensureDirForFile(p)	Asynchronously ensures that the directory for a given file path exists, creating it if necessary.
dirs	ensureDirForFileSync(p)	Ensures that the directory for a given file path exists, creating it if necessary.
dirs	ensureDirSync(path)	Ensures that a directory exists, creating it if necessary.
entry	toFSEntry(path)	Helper function to convert a string path to an FSEntry if it is not already an FSEntry
fileio	readJSONFile(filePath)	Asynchronously reads the content of a file as JSON, stripping a UTF-8 BOM if present. This is a convenience method that combines readTextFile with JSON.parse, and is useful for reading JSON files without having to worry about BOMs causing parse failures.
fileio	readJSONFileSync(filePath)	Synchronously reads the content of a file as JSON, stripping a UTF-8 BOM if present. This is a convenience method that combines readFileSync with JSON.parse, and is useful for reading JSON files without having to worry about BOMs causing parse failures.
fileio	readTextFile(filePath)	Asynchronously reads the content of a file as a UTF-8 string.
fileio	readTextFileSync(filePath)	Synchronously reads the content of a file as a UTF-8 string.
fileio	writeJSONFile(path, data, space)	Writes specified data to a file asynchronously, serialized as JSON format.
fileio	writeJSONFileSync(path, data, space)	Writes specified data to a file, serialized as JSON format.
fileio	writeTextFile(path, data)	Writes specified data to a file asynchronously, assuming the data is UTF-8 encoded text.
fileio	writeTextFileSync(path, data)	Writes specified data to a file, assuming the data is UTF-8 encoded text.
json	parseJSON(content)	Parse JSON via the internal JSON.parse, checking for and stripping a UTF-8 byte order mark if present to avoid parse failures.
json	serializeJSON(data, space)	Serialize data to JSON format, optionally pretty-printing with a specified number of spaces.
json	stripBOM(content)	Strip a UTF-8 BOM (Byte Order Mark) from the beginning of a string, if present.