Trabajo con S3 en TypeScript: bibliotecas y ejemplos |…

Trabajo con S3 y almacenamiento en la nube en TypeScript

Las aplicaciones web modernas utilizan cada vez más almacenamiento de objetos en la nube para guardar archivos, imágenes, copias de seguridad y contenido estático. Amazon S3 (Simple Storage Service) es el estándar de facto en esta área, y su API es compatible con la mayoría de los proveedores de nube y soluciones locales, como MinIO, DigitalOcean Spaces o Yandex Object Storage. En este artículo, veremos cómo trabajar con almacenamiento compatible con S3 en TypeScript, utilizando el AWS SDK oficial y bibliotecas alternativas.

Elección de una biblioteca para trabajar con S3 en TypeScript

Para interactuar con S3 desde TypeScript, existen varias soluciones populares:

@aws-sdk/client-s3 — SDK oficial de Amazon, escrito en TypeScript, modular y moderno.
aws-sdk — versión clásica del SDK (v2), que aún tiene soporte, pero se recomienda migrar a v3.
minio — biblioteca cliente para MinIO y cualquier almacenamiento compatible con S3, simple y ligera.
s3-client — envoltorio minimalista sobre fetch API para trabajar con S3.

Nos centraremos en @aws-sdk/client-s3 como la herramienta más actual y potente, y también mostraremos ejemplos con minio para casos donde se necesite una alternativa ligera.

Instalación y configuración

Instale los paquetes necesarios a través de npm:

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

Para trabajar con MinIO:

npm install minio

Ahora creemos un cliente S3 básico. Asegúrese de tener variables de entorno o una configuración con las claves de acceso.

Ejemplo 1: Inicialización del 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 o S3 local, especifique el endpoint:  // endpoint: "http://localhost:9000",  // forcePathStyle: true,});

export default s3Client;

Tenga en cuenta el parámetro forcePathStyle — es obligatorio para MinIO y algunos otros almacenamientos que no son de AWS.

Ejemplo 2: Carga de un archivo en S3

Para cargar un archivo, usamos el 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("Archivo cargado:", response.$metadata.httpStatusCode);    return response;  } catch (error) {    console.error("Error de carga:", error);    throw error;  }}

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

Para la carga por streaming de archivos grandes, 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(`Cargado: ${progress.loaded} de ${progress.total}`);});

await upload.done();

Ejemplo 3: Descarga de un archivo

Para obtener un objeto del almacenamiento, usamos GetObjectCommand:


                
    
  También en la biblioteca
  
                
                  
                 vitest para TypeScript: guía completa con ejemplos
      
                
                  
                 Planificador de tareas en Node.js: node-schedule y node-cron
      
                
                  
                 Frameworks CLI para C# (.NET): creación de aplicaciones de consola
      
                
                  
                 frozen para C++: guía completa con ejemplos prácticos
      
                
                  
                 Trabajo con XML en JavaScript (Node.js): bibliotecas y herramientas