Skip to content

tyrus:fs ​

tyrus:fs exposes native filesystem operations provided by the native runtime. It provides both synchronous and asynchronous variants with recoverable FsError.

Imports ​

tyrus
import {
    readFile, readFileStream, readFileSync,
    writeFile, writeFileStream, writeFileSync,
    exists, appendFile,
    readdir, mkdir, rm, cp, mv, removeAll,
} from "tyrus:fs";

Functions ​

FunctionSignaturePurpose
readFile(path: string) => Promise<Result<string, FsError>>Reads a UTF-8 file asynchronously.
readFileStream(path: string) => Result<ReadableStream<u8[]>, FsError>Reads bounded binary chunks progressively.
readFileSync(path: string) => Result<string, FsError>Reads a UTF-8 file synchronously.
writeFile(path: string, data: string) => Promise<Result<void, FsError>>Writes a string to a file asynchronously.
writeFileStream(path: string) => Result<WritableStream<u8[]>, FsError>Writes bounded binary chunks progressively.
writeFileSync(path: string, data: string) => Result<void, FsError>Writes a string to a file synchronously.
exists(path: string) => booleanChecks whether a path exists.
appendFile(path: string, data: string) => Promise<Result<void, FsError>>Appends data to a file asynchronously.
readdir(path: string, options?: ReaddirOptions) => Result<DirEntry[], FsError>Reads directory entries.
mkdir(path: string) => Result<void, FsError>Creates a directory.
rm(path: string, options?: RmOptions) => Result<void, FsError>Removes a file or directory.
cp(src: string, dest: string, options?: CpOptions) => Result<void, FsError>Copies a file or directory.
mv(src: string, dest: string) => Result<void, FsError>Moves a file or directory.
removeAll(path: string) => Result<void, FsError>Recursively removes a directory.
stat(path: string) => Result<FileStats, FsError>Gets file statistics or a structured filesystem error.
metadata(path: string) => Result<Metadata, FsError>Gets detailed file metadata.
diskUsage(path: string) => Result<DiskUsage, FsError>Gets disk usage information.
mime(path: string) => string?Gets MIME type from file extension.
chmod(path: string, mode: FileMode) => Result<void, FsError>Changes file permissions.
chown(path: string, uid: u32, gid: u32) => Result<void, FsError>Changes file ownership.
readlink(path: string) => Result<string, FsError>Reads a symlink target or returns a structured filesystem error.
symlink(original: string, link: string) => Result<void, FsError>Creates a symlink.
symlinkDir(original: string, link: string) => Result<void, FsError>Creates a directory symlink.
hardLink(original: string, link: string) => Result<void, FsError>Creates a hard link.
canonicalize(path: string) => Result<string, FsError>Resolves to an absolute path.
glob(pattern: string) => Result<string[], FsError>Finds files matching a glob pattern.
search(pattern: string, options?: SearchOptions) => Result<string[], FsError>Searches for files matching a pattern.
diff(path1: string, path2: string) => Result<DiffResult, FsError>Compares two files or directories.
atomicWrite(path: string, data: string) => Result<void, FsError>Writes atomically (temp + rename).
tempDir() => TempDirReturns the system temp directory.
tempFile() => Result<string, FsError>Creates a temp file and returns its path.
watch(path: string) => Result<FSWatcher, FsError>Starts watching a file or directory.

Recoverable errors

Every recoverable filesystem operation returns Result<T, FsError>. Synchronous calls return Result<T, FsError> directly, while asynchronous file operations return Promise<Result<T, FsError>>; stream constructors return Result<ReadableStream<u8[]>, FsError> or Result<WritableStream<u8[]>, FsError>. Match the result or propagate it with ?. The error has a stable code field (e.g. ERR_FS_NOT_FOUND) and a human-readable message.

Cross-platform paths ​

Every path passed to any fs function is resolved transparently before it reaches the operating system, with no path module import required:

  • Separators: a backslash written the Windows way ("data\\file.txt") is normalized to a forward slash on Linux/macOS. Windows itself already accepts both natively, so nothing changes there.
  • Relative segments: ./ and ../ are resolved against the current working directory, sub/../file.txt and file.txt refer to the same location, and neither requires sub to actually exist on disk.

This is a lexical resolution, a lexical path resolution, not filesystem canonicalization: it never touches the filesystem and never requires the path to already exist. Requiring existence would break every call that creates a new file, which is the common case for writeFileSync.

Example ​

tyrus
import { FsError, readFile, writeFile, mkdir, rm } from "tyrus:fs";

const run = async (): Promise<Result<void, FsError>> => {
    await writeFile("message.txt", "hello from tyrus")?;
    const message = await readFile("message.txt")?;
    print(message); // hello from tyrus
    mkdir("subdir")?;
    rm("message.txt")?;
    return Ok();
};