S3 JavaScript SDK

SDK en JavaScript para el servicio S3 compatible de NestJS. Funciona en navegador y Node.js.

Instalación

npm install s3-javascript-sdk

Uso básico

En navegador

import S3 from 's3-javascript-sdk';

const s3 = new S3({
  endpoint: 'http://localhost:3000/s3',
  bucket: 'mi-bucket'
});

// Subir archivo
const file = document.getElementById('fileInput').files[0];
const result = await s3.uploadFile(file, {
  onProgress: (progress) => {
    console.log(`${progress.percentage}%`);
  }
});

console.log('Archivo subido:', result);

En Node.js

const S3 = require('s3-javascript-sdk');
const fs = require('fs');

const s3 = new S3({
  endpoint: 'http://localhost:3000/s3',
  bucket: 'mi-bucket'
});

// Subir archivo desde disco
const fileBuffer = fs.readFileSync('./archivo.pdf');
const result = await s3.uploadBuffer(fileBuffer, 'documentos/archivo.pdf', {
  contentType: 'application/pdf'
});

console.log('Archivo subido:', result);

API

Constructor

const s3 = new S3(config);

config: Objeto con las siguientes propiedades:

• endpoint (string): URL base del servicio S3 (ej: 'http://localhost:3000/s3')
• accessKeyId (string, opcional): Access key ID para autenticación
• secretAccessKey (string, opcional): Secret access key para autenticación
• region (string, opcional): Región (default: 'us-east-1')
• bucket (string, opcional): Bucket por defecto
• timeout (number, opcional): Timeout en ms (default: 30000)
• retries (number, opcional): Número de reintentos (default: 3)

Métodos principales

Buckets

• listBuckets() - Lista todos los buckets
• createBucket(name, region?) - Crea un nuevo bucket
• deleteBucket(name) - Elimina un bucket

Objetos

• listObjects(bucket, options?) - Lista objetos en un bucket
• uploadFile(file, options?) - Sube un archivo (File/Blob)
• uploadBuffer(buffer, key, options?) - Sube un buffer (Node.js)
• uploadMultipleFiles(files, options?) - Sube múltiples archivos
• downloadFile(bucket, key) - Descarga un archivo
• deleteFile(bucket, key) - Elimina un archivo
• getFileUrl(bucket, key, expiresIn?) - Obtiene URL pública
• copyFile(sourceBucket, sourceKey, destBucket, destKey) - Copia un archivo

URLs presignadas

• generatePresignedUrl(bucket, key, options?) - Genera URL temporal
• generatePostPolicy(bucket, key, options?) - Genera política POST

Multipart Uploads

• initiateMultipartUpload(bucket, key, metadata?) - Inicia upload multiparte
• uploadPart(bucket, key, uploadId, partNumber, data) - Sube una parte
• completeMultipartUpload(bucket, key, uploadId, parts) - Completa upload
• abortMultipartUpload(bucket, key, uploadId) - Aborta upload

Ejemplos completos

Subida con progreso

const result = await s3.uploadFile(file, {
  bucket: 'mi-bucket',
  key: 'carpeta/' + file.name,
  metadata: {
    author: 'usuario',
    project: 'demo'
  },
  onProgress: (progress) => {
    console.log(`Progreso: ${progress.percentage}%`);
  }
});

Subida múltiple

const results = await s3.uploadMultipleFiles(files, {
  bucket: 'mi-bucket',
  onProgress: (progress) => {
    console.log(`Archivo ${progress.fileName}: ${progress.percentage}%`);
  },
  onFileComplete: (result) => {
    console.log('Archivo completado:', result.file.name);
  }
});

Generar URL firmada

const url = await s3.generatePresignedUrl('mi-bucket', 'documento.pdf', {
  expiresIn: 3600, // 1 hora
  method: 'GET'
});

// Usar la URL
window.open(url);

Licencia

MIT