Skip to content

tyrus:archive ​

tyrus:archive cria, inspeciona e extrai arquivos ZIP, TAR e TAR.GZ a partir de caminhos em disco. Toda operação é assíncrona, transfere os dados por buffers limitados e nunca carrega um arquivo inteiro na memória; packStream e unpackStream fazem o mesmo com uma stream de bytes no lugar do arquivo.

A extração é segura por padrão: nenhuma entrada pode ser gravada fora do diretório de destino, links e arquivos especiais são recusados, limites de quantidade de entradas, tamanho extraído e razão de compressão barram bombas de descompressão, e toda operação desiste depois de um limite de tempo.

Imports ​

Importaçõesimport { ArchiveEntry, ArchiveEntryKind, ArchiveError, ArchiveFormat, ArchiveSummary, PackOptions, UnpackOptions, list, pack, packStream, unpack, unpackStream } from "tyrus:archive";

Funções ​

ItemAssinaturaFinalidade
pack(source: string, destination: string, options?: PackOptions) => Promise<Result<ArchiveSummary, ArchiveError>>Cria um arquivo a partir de um arquivo ou diretório.
list(archive: string, options?: UnpackOptions) => Promise<Result<ArchiveEntry[], ArchiveError>>Lê as entradas de um arquivo sem extraí-lo.
unpack(archive: string, destination: string, options?: UnpackOptions) => Promise<Result<ArchiveSummary, ArchiveError>>Extrai um arquivo para um diretório.
packStream(source: string, format: ArchiveFormat, options?: PackOptions) => ReadableStream<u8[]>Escreve o arquivo de um arquivo ou diretório numa stream de bytes.
unpackStream(archive: ReadableStream<u8[]>, destination: string, options?: UnpackOptions) => Promise<Result<ArchiveSummary, ArchiveError>>Extrai um arquivo TAR ou TAR.GZ de uma stream de bytes.

Formatos ​

pack decide o formato pela extensão do destino, que deve estar em minúsculas. list e unpack ignoram o nome do arquivo e identificam o formato pelo conteúdo, então um .jar, .epub ou .docx, que são arquivos ZIP, é extraído como qualquer .zip.

ExtensãoFormatoCompressão
.zipZIPDeflate, níveis 0 a 9
.tarTARNenhuma
.tar.gz, .tgzTAR.GZGzip, níveis 0 a 9

Códigos de erro ​

Toda função resolve com um Result e nunca rejeita: o sucesso é Ok com o valor, e uma falha é Err com um ArchiveError. Seu code é estável, seu message é legível e seu entry nomeia a entrada do arquivo que causou a falha, quando houver uma. Dentro de uma função que retorna um Result com o mesmo erro, await pack(...)? entrega o valor ou retorna o erro.

CódigoSignificado
ERR_ARCHIVE_NOT_FOUNDO arquivo, a origem ou o diretório pai do destino não existe.
ERR_ARCHIVE_IOA leitura ou a escrita falhou.
ERR_ARCHIVE_PERMISSION_DENIEDO sistema operacional negou o acesso.
ERR_ARCHIVE_UNSUPPORTED_FORMATO conteúdo não é um arquivo ZIP, TAR ou TAR.GZ.
ERR_ARCHIVE_UNSUPPORTED_EXTENSIONO destino do pack não termina com .zip, .tar, .tar.gz ou .tgz.
ERR_ARCHIVE_INVALID_ARCHIVEO arquivo está malformado ou truncado.
ERR_ARCHIVE_CHECKSUM_MISMATCHOs dados de uma entrada não batem com o checksum.
ERR_ARCHIVE_ENCRYPTEDO arquivo contém uma entrada criptografada.
ERR_ARCHIVE_INVALID_OPTIONUma opção tem valor inválido, como um limite 0.
ERR_ARCHIVE_INVALID_COMPRESSION_LEVELlevel está fora de 0 a 9 ou foi informado para um destino .tar.
ERR_ARCHIVE_DESTINATION_EXISTSO destino já existe e overwrite não foi ativado.
ERR_ARCHIVE_PATH_ESCAPEUma entrada seria gravada fora do diretório de destino.
ERR_ARCHIVE_INVALID_ENTRY_NAMEO nome de uma entrada está malformado ou não pode ser criado em todas as plataformas.
ERR_ARCHIVE_DUPLICATE_ENTRYDuas entradas resultam no mesmo caminho.
ERR_ARCHIVE_UNSAFE_LINKO arquivo contém um link simbólico ou físico.
ERR_ARCHIVE_UNSUPPORTED_ENTRYO arquivo usa um tipo de entrada ou método de compressão não suportado, ou a origem contém um link ou arquivo especial.
ERR_ARCHIVE_ENTRY_LIMITO arquivo tem mais entradas que maxEntries.
ERR_ARCHIVE_SIZE_LIMITA extração gravaria mais bytes que maxBytes.
ERR_ARCHIVE_RATIO_LIMITUma entrada, ou um arquivo TAR.GZ como um todo, expande mais que maxRatio vezes o tamanho comprimido.
ERR_ARCHIVE_ALLOCATION_FAILEDNão foi possível alocar memória para o resultado.
ERR_ARCHIVE_NO_SPACEO disco ficou sem espaço, ou um arquivo ZIP declara mais conteúdo do que o destino tem livre.
ERR_ARCHIVE_TIMEOUTA operação demorou mais que timeoutMs.
ERR_ARCHIVE_ZIP_NOT_STREAMABLEUm arquivo ZIP foi passado a unpackStream, que não extrai ZIP de uma stream.

Exemplo ​

tyrus
import { ArchiveError, ArchiveSummary, pack, unpack } from "tyrus:archive";

async function backup(): Promise<Result<void, ArchiveError>> {
    const packed: ArchiveSummary = await pack("./documents", "./backup.zip")?;
    print(packed.entries); // 12

    const restored: ArchiveSummary = await unpack("./backup.zip", "./restored")?;
    print(restored.bytes); // 48213
    return Ok();
}

const main = async (): Promise<void> => {
    match (await backup()) {
        Ok() => { print("done"); } // done
        Err(error) => { printError(error.code); } // ERR_ARCHIVE_NOT_FOUND
    }
};