@rnx-kit/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. |