Trabalhando com S3 em TypeScript: bibliotecas e exemplos |…

Trabalhando com S3 e armazenamentos em nuvem em TypeScript

Aplicações web modernas cada vez mais utilizam armazenamentos de objetos em nuvem para guardar arquivos, imagens, backups e conteúdo estático. O Amazon S3 (Simple Storage Service) é o padrão de facto nesta área, e sua API é suportada pela maioria dos provedores de nuvem e soluções locais, como MinIO, DigitalOcean Spaces ou Yandex Object Storage. Neste artigo, veremos como trabalhar com armazenamentos compatíveis com S3 em TypeScript, usando o AWS SDK oficial e bibliotecas alternativas.

Escolhendo uma biblioteca para trabalhar com S3 em TypeScript

Para interagir com S3 a partir do TypeScript, existem várias soluções populares:

@aws-sdk/client-s3 — SDK oficial da Amazon, escrito em TypeScript, modular e moderno.
aws-sdk — versão clássica do SDK (v2), que ainda é suportada, mas é recomendado migrar para a v3.
minio — biblioteca cliente para MinIO e qualquer armazenamento compatível com S3, simples e leve.
s3-client — wrapper minimalista sobre a fetch API para trabalhar com S3.

Vamos nos concentrar no @aws-sdk/client-s3 como a ferramenta mais atual e poderosa, e também mostraremos exemplos com minio para casos onde uma alternativa leve é necessária.

Instalação e configuração

Instale os pacotes necessários via npm:

npm install @aws-sdk/client-s3 @aws-sdk/lib-storagenpm install --save-dev @types/node typescript

Para trabalhar com MinIO:

npm install minio

Agora vamos criar um cliente S3 básico. Certifique-se de ter variáveis de ambiente ou uma configuração com as chaves de acesso.

Exemplo 1: Inicializando o cliente S3

import { S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({  region: process.env.AWS_REGION || "us-east-1",  credentials: {    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,  },  // Para MinIO ou S3 local, especifique o endpoint:  // endpoint: "http://localhost:9000",  // forcePathStyle: true,});

export default s3Client;

Observe o parâmetro forcePathStyle — ele é obrigatório para MinIO e alguns outros armazenamentos que não são da AWS.

Exemplo 2: Fazendo upload de um arquivo para o S3

Para fazer upload de um arquivo, usamos o comando PutObjectCommand:

import { PutObjectCommand } from "@aws-sdk/client-s3";import s3Client from "./s3Client";

async function uploadFile(bucket: string, key: string, body: Buffer | string) {  const command = new PutObjectCommand({    Bucket: bucket,    Key: key,    Body: body,    ContentType: "application/octet-stream",  });

  try {    const response = await s3Client.send(command);    console.log("Arquivo enviado:", response.$metadata.httpStatusCode);    return response;  } catch (error) {    console.error("Erro no upload:", error);    throw error;  }}

// Uso:await uploadFile("my-bucket", "uploads/image.png", bufferFromFile);

Para upload de grandes arquivos em streaming, use @aws-sdk/lib-storage:

import { Upload } from "@aws-sdk/lib-storage";import { Readable } from "stream";

const upload = new Upload({  client: s3Client,  params: {    Bucket: "my-bucket",    Key: "large-file.zip",    Body: Readable.from(fileStream),  },});

upload.on("httpUploadProgress", (progress) => {  console.log(`Enviado: ${progress.loaded} de ${progress.total}`);});

await upload.done();

Exemplo 3: Baixando um arquivo

Para obter um objeto do armazenamento, usamos GetObjectCommand:


                
    
  Também na biblioteca
  
                
                  
                 OkHttp para Kotlin: guia completo com exemplos
      
                
                  
                 Geração de relatórios PDF em Go (Golang): bibliotecas e exemplos
      
                
                  
                 Métricas Prometheus em C# (.NET) — biblioteca prometheus-net
      
                
                  
                 Biblioteca Padrão C# (.NET): Visão Completa
      
                
                  
                 ndarray para Rust: guia completo com exemplos práticos