Filesystem

For correct cache invalidation it's important to not read from external things in a Turbo-Engine function, without taking care of invalidations of that external thing.

To allow using filesystem operations correctly, Turbo-Engines provides a filesystem API which includes file watching for invalidation.

It's important to only use the filesystem API to access the filesystem.

API

Constructing

// Create a filesystem
let fs = DiskFileSystem::new(...);

// Get the root path, returns a Vc<FileSystemPath>
let fs_path = fs.root();

Navigating

// Access a sub path (error when leaving the root)
let fs_path = fs_path.join("sub/directory/file.txt".to_string());

// Append to the filename (file.txt.bak)
fs_path.append(".bak".to_string());

// Append to the basename (file.copy.txt)
fs_path.append_to_stem(".copy".to_string());

// Change the extension (file.raw)
fs_path.with_extension("raw".to_string());

// Access a sub path (returns None when leaving the root)
fs_path.try_join("../../file.txt".to_string());

// Access a sub path (returns None when leaving the current path)
fs_path.try_join_inside("file.txt".to_string());

// Get the parent directory as Vc<FileSystemPath>
fs_path.parent();

// Get all glob matches
fs_path.read_glob(...);

Metadata access

// Gets the filesystem
fs_path.fs();

// Gets the extension
fs_path.extension();

// Gets the basename
fs_path.file_stem();

Comparing

// Is the path inside of the other path
fs_path.is_inside(other_fs_path);

// Is the path inside or equal to the other path
fs_path.is_inside_or_equal(other_fs_path);

Reading

// Returns the type of the path (file, directory, symlink, ...)
// This is based on read_dir of the parent directory and much more efficient than .metadata()
fs_path.get_type();

// Reads the file content
fs_path.read();

// Reads a symlink content
fs_path.read_link()

// Reads the file content as JSON
fs_path.read_json();

// Read a directory. Returns a map of new Vc<FileSystemPath>s
fs_path.read_dir();

// Gets a Vc<Completion> that changes when the file content changes
fs_path.track();

// Reads metadata of a file
fs_path.metadata();

// Resolves all symlinks in the path and returns the real path
fs_path.realpath();

// Resolves all symlinks in the path and returns the real path and a list of symlinks
fs_path.real_path_with_symlinks();

Writing

// Write the file content
fs_path.write(...);

// Write the file content
fs_path.write_link(...);