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
import {
readFile, readFileStream, readFileSync,
writeFile, writeFileStream, writeFileSync,
exists, appendFile,
readdir, mkdir, rm, cp, mv, removeAll,
} from "tyrus:fs";Funciones
| Función | Firma | Finalidad |
|---|---|---|
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) => boolean | Verifica 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 | () => TempDir | Devuelve 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.txtyfile.txtapuntan al mismo lugar, y ninguno de los dos exige quesubexista 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
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();
};