Skip to content

tyrus:fs ​

tyrus:fs expone operaciones nativas de filesystem proporcionadas por el runtime nativo. Proporciona variantes síncronas y asíncronas con FsError recuperable.

Importaciones ​

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

Funciones ​

FunciónFirmaFinalidad
readFile(path: string) => Promise<Result<string, FsError>>Lee un archivo UTF-8 de forma asíncrona.
readFileStream(path: string) => Result<ReadableStream<u8[]>, FsError>Lee chunks binarios limitados progresivamente.
readFileSync(path: string) => Result<string, FsError>Lee un archivo UTF-8 de forma síncrona.
writeFile(path: string, data: string) => Promise<Result<void, FsError>>Escribe una string en un archivo de forma asíncrona.
writeFileStream(path: string) => Result<WritableStream<u8[]>, FsError>Escribe chunks binarios limitados progresivamente.
writeFileSync(path: string, data: string) => Result<void, FsError>Escribe una string en un archivo de forma síncrona.
exists(path: string) => booleanVerifica si una ruta existe.
appendFile(path: string, data: string) => Promise<Result<void, FsError>>Añade datos a un archivo de forma asíncrona.
readdir(path: string, options?: ReaddirOptions) => Result<DirEntry[], FsError>Lee entradas de un directorio.
mkdir(path: string) => Result<void, FsError>Crea un directorio.
rm(path: string, options?: RmOptions) => Result<void, FsError>Elimina un archivo o directorio.
cp(src: string, dest: string, options?: CpOptions) => Result<void, FsError>Copia un archivo o directorio.
mv(src: string, dest: string) => Result<void, FsError>Mueve un archivo o directorio.
removeAll(path: string) => Result<void, FsError>Elimina recursivamente un directorio.
stat(path: string) => Result<FileStats, FsError>Obtiene estadísticas del archivo o un error estructurado del sistema de archivos.
metadata(path: string) => Result<Metadata, FsError>Obtiene metadatos detallados.
diskUsage(path: string) => Result<DiskUsage, FsError>Obtiene información de uso de disco.
mime(path: string) => string?Obtiene el tipo MIME de la extensión.
chmod(path: string, mode: FileMode) => Result<void, FsError>Cambia permisos del archivo.
chown(path: string, uid: u32, gid: u32) => Result<void, FsError>Cambia la propiedad del archivo.
readlink(path: string) => Result<string, FsError>Lee el objetivo de un enlace simbólico.
symlink(original: string, link: string) => Result<void, FsError>Crea un enlace simbólico.
symlinkDir(original: string, link: string) => Result<void, FsError>Crea un enlace simbólico a un directorio.
hardLink(original: string, link: string) => Result<void, FsError>Crea un enlace duro.
canonicalize(path: string) => Result<string, FsError>Resuelve a una ruta absoluta.
glob(pattern: string) => Result<string[], FsError>Encuentra archivos por patrón glob.
search(pattern: string, options?: SearchOptions) => Result<string[], FsError>Busca archivos por patrón.
diff(path1: string, path2: string) => Result<DiffResult, FsError>Compara dos archivos o directorios.
atomicWrite(path: string, data: string) => Result<void, FsError>Escribe de forma atómica.
tempDir() => TempDirDevuelve el directorio temporal.
tempFile() => Result<string, FsError>Crea un archivo temporal.
watch(path: string) => Result<FSWatcher, FsError>Comienza a observar un archivo o directorio.

Errores recuperables

Todas las operaciones recuperables del sistema de archivos devuelven Result<T, FsError>. Las llamadas síncronas devuelven Result<T, FsError> directamente, mientras que las operaciones asíncronas de archivos devuelven Promise<Result<T, FsError>>; los constructores de streams devuelven Result<ReadableStream<u8[]>, FsError> o Result<WritableStream<u8[]>, FsError>. Usa match para tratar el resultado o propágalo con ?. El error tiene un campo code estable (p. ej., ERR_FS_NOT_FOUND) y un message legible.

Rutas multiplataforma ​

Toda ruta pasada a cualquier función fs se resuelve de forma transparente antes de llegar al sistema operativo, sin exigir ningún import de módulo path:

  • Separadores: una barra invertida escrita al estilo Windows ("data\\file.txt") se normaliza a barra normal en Linux/macOS. El propio Windows ya acepta nativamente ambas formas, así que ahí no cambia nada.
  • Segmentos relativos: ./ y ../ se resuelven contra el directorio de trabajo actual, sub/../file.txt y file.txt apuntan al mismo lugar, y ninguno de los dos exige que sub exista de verdad en el disco.

Esta es una resolución léxica, una resolución léxica de rutas, no una canonicalización de sistema de archivos: nunca toca el sistema de archivos y nunca exige que la ruta ya exista. Exigir existencia rompería toda llamada que crea un archivo nuevo, que es el caso común de writeFileSync.

Ejemplo ​

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();
};