tyrus:fs
tyrus:fs expõe operações nativas de filesystem fornecidas pelo runtime nativo. Ele fornece variantes síncronas e assíncronas com FsError recuperável.
Importações
import {
readFile, readFileStream, readFileSync,
writeFile, writeFileStream, writeFileSync,
exists, appendFile,
readdir, mkdir, rm, cp, mv, removeAll,
} from "tyrus:fs";Funções
| Função | Assinatura | Finalidade |
|---|---|---|
readFile | (path: string) => Promise<Result<string, FsError>> | Lê um arquivo UTF-8 de forma assíncrona. |
readFileStream | (path: string) => Result<ReadableStream<u8[]>, FsError> | Lê chunks binários limitados progressivamente. |
readFileSync | (path: string) => Result<string, FsError> | Lê um arquivo UTF-8 de forma síncrona. |
writeFile | (path: string, data: string) => Promise<Result<void, FsError>> | Escreve uma string em um arquivo de forma assíncrona. |
writeFileStream | (path: string) => Result<WritableStream<u8[]>, FsError> | Escreve chunks binários limitados progressivamente. |
writeFileSync | (path: string, data: string) => Result<void, FsError> | Escreve uma string em um arquivo de forma síncrona. |
exists | (path: string) => boolean | Verifica se um caminho existe. |
appendFile | (path: string, data: string) => Promise<Result<void, FsError>> | Acrescenta dados a um arquivo de forma assíncrona. |
readdir | (path: string, options?: ReaddirOptions) => Result<DirEntry[], FsError> | Lê entradas de um diretório. |
mkdir | (path: string) => Result<void, FsError> | Cria um diretório. |
rm | (path: string, options?: RmOptions) => Result<void, FsError> | Remove um arquivo ou diretório. |
cp | (src: string, dest: string, options?: CpOptions) => Result<void, FsError> | Copia um arquivo ou diretório. |
mv | (src: string, dest: string) => Result<void, FsError> | Move um arquivo ou diretório. |
removeAll | (path: string) => Result<void, FsError> | Remove recursivamente um diretório. |
stat | (path: string) => Result<FileStats, FsError> | Obtém estatísticas do arquivo ou um erro estruturado do filesystem. |
metadata | (path: string) => Result<Metadata, FsError> | Obtém metadados detalhados. |
diskUsage | (path: string) => Result<DiskUsage, FsError> | Obtém informações de uso de disco. |
mime | (path: string) => string? | Obtém tipo MIME da extensão. |
chmod | (path: string, mode: FileMode) => Result<void, FsError> | Altera permissões do arquivo. |
chown | (path: string, uid: u32, gid: u32) => Result<void, FsError> | Altera propriedade do arquivo. |
readlink | (path: string) => Result<string, FsError> | Lê o alvo de um link simbólico. |
symlink | (original: string, link: string) => Result<void, FsError> | Cria um link simbólico. |
symlinkDir | (original: string, link: string) => Result<void, FsError> | Cria um link simbólico para diretório. |
hardLink | (original: string, link: string) => Result<void, FsError> | Cria um link físico. |
canonicalize | (path: string) => Result<string, FsError> | Resolve para um caminho absoluto. |
glob | (pattern: string) => Result<string[], FsError> | Encontra arquivos por padrão glob. |
search | (pattern: string, options?: SearchOptions) => Result<string[], FsError> | Busca arquivos por padrão. |
diff | (path1: string, path2: string) => Result<DiffResult, FsError> | Compara dois arquivos ou diretórios. |
atomicWrite | (path: string, data: string) => Result<void, FsError> | Escreve atomicamente. |
tempDir | () => TempDir | Retorna o diretório temporário. |
tempFile | () => Result<string, FsError> | Cria um arquivo temporário. |
watch | (path: string) => Result<FSWatcher, FsError> | Começa a observar um arquivo ou diretório. |
Erros recuperáveis
Todas as operações recuperáveis do sistema de arquivos retornam Result<T, FsError>. Chamadas síncronas retornam Result<T, FsError> diretamente, enquanto operações assíncronas de arquivo retornam Promise<Result<T, FsError>>; construtores de stream retornam Result<ReadableStream<u8[]>, FsError> ou Result<WritableStream<u8[]>, FsError>. Use match para tratar o resultado ou propague-o com ?. O erro possui um campo code estável (ex.: ERR_FS_NOT_FOUND) e uma message legível.
Caminhos multiplataforma
Todo caminho passado a qualquer função fs é resolvido de forma transparente antes de chegar ao sistema operacional, sem exigir nenhum import de módulo path:
- Separadores: uma contrabarra escrita no estilo Windows (
"data\\file.txt") é normalizada para barra normal no Linux/macOS. O próprio Windows já aceita nativamente as duas formas, então nada muda lá. - Segmentos relativos:
./e../são resolvidos contra o diretório de trabalho atual,sub/../file.txtefile.txtapontam para o mesmo lugar, e nenhum dos dois exige quesubde fato exista no disco.
Esta é uma resolução lexical, uma resolução lexical de caminhos, não uma canonicalização de sistema de arquivos: ela nunca toca o sistema de arquivos e nunca exige que o caminho já exista. Exigir existência quebraria toda chamada que cria um arquivo novo, que é o caso comum de writeFileSync.
Exemplo
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();
};