Files SDK

¿Qué es Files SDK?

Files SDK es un SDK de almacenamiento unificado que expone una única API consistente para interactuar con backends de almacenamiento de objetos y blobs. Su objetivo es permitirte usar las mismas operaciones de alto nivel —como subir, descargar, listar, eliminar y ayudantes relacionados— mientras utilizas diferentes proveedores en segundo plano.

Funciona enrutando las solicitudes a través de un adaptador específico del proveedor. Esto mantiene estables las partes compartidas de los flujos de almacenamiento y permite que las diferencias entre proveedores (como comportamientos relacionados con URLs o ciertos casos especiales) se gestionen dentro del adaptador sin modificar los puntos de llamada.

Características principales

• Una sola clase Files para todos los proveedores: Usa una única superficie de API para las operaciones de almacenamiento comunes (subir, descargar, listar, eliminar, head, exists, copiar y ayudantes de URL), en lugar de escribir código específico para cada backend.
• Selección de proveedor basada en adaptador al construir la instancia: El adaptador se fija al instanciar new Files({ adapter: ... }), evitando patrones de “elegir proveedor por llamada” que complicarían el uso.
• Soporte para entradas según estándares web: Acepta File, Blob, ReadableStream, ArrayBuffer y string como entradas para subidas.
• Funciona donde se ejecuta fetch: Diseñado para entornos como Node, Bun, Workers y Vercel (según se indica en la página) para un comportamiento consistente en tiempo de ejecución.
• Escapada a proveedor mediante files.raw: Cuando necesitas funcionalidad específica del proveedor, puedes acceder al cliente nativo a través de una propiedad (files.raw), tipada según el adaptador.
• Gestión de errores normalizada: Los errores se presentan como un único tipo FilesError con un código normalizado entre proveedores, y el error original del proveedor se adjunta como causa.

Cómo usar Files SDK

1. Instala el SDK (y solo los adaptadores que planees usar como dependencias pares):
   • npm install files-sdk
2. Importa Files y un adaptador de proveedor, luego crea una instancia de Files con el adaptador configurado para tu bucket/región (por ejemplo, S3).
3. Llama a los métodos compartidos en la instancia, como:
   • files.upload(key, input)
   • files.download(key)
   • files.head(key)
   • files.list({ prefix })
   • files.delete(key)
4. Usa files.raw si necesitas acceder a características específicas del proveedor que no están en la superficie de la API común.

Un ejemplo mínimo de la página:

import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

const files = new Files({
  adapter: s3({ bucket: "uploads", region: "us-east-1" }),
});

await files.upload("hello.txt", "world");
const file = await files.download("hello.txt");
const meta = await files.head("hello.txt");
const items = await files.list();
await files.delete("hello.txt");

Casos de uso

• Construir una capa de almacenamiento que pueda cambiar de proveedor: Comienza con un backend (por ejemplo, almacenamiento compatible con S3) y luego migra a otro adaptador sin reescribir la lógica de subida/descarga/listado/eliminación de tu aplicación.
• Manejar entradas de archivos tipo navegador de forma consistente en código de backend: Usa los tipos de entrada admitidos por el SDK (File, Blob, ReadableStream, ArrayBuffer, string) cuando tu servidor recibe objetos de archivos según estándares web.
• Organizar subidas por prefijos y gestionar ciclos de vida de objetos al nivel de aplicación: Usa list({ prefix }) y delete(key) pat

Alternativas

• SDKs de almacenamiento específicos del proveedor (por ejemplo, clientes nativos de S3/GCS/Azure): Estos ofrecen cobertura completa del proveedor, pero suelen requerir rutas de código diferentes para cada backend y manejo separado de tareas comunes.
• Capas de abstracción de almacenamiento de objetos sin entradas web estándar: Algunas abstracciones proporcionan una interfaz unificada, pero pueden no admitir el mismo conjunto de tipos de entrada nativos de la web ni suposiciones de tiempo de ejecución orientadas a fetch.
• Bibliotecas de carga de archivos del lado del servidor con opción de backend de almacenamiento: Útiles cuando tu objetivo principal es el manejo de cargas, pero pueden no exponer el mismo conjunto de operaciones estandarizadas (ayudantes de head/exists/copy/url) y acceso de escape a través del cliente nativo.
• Integración HTTP directa a endpoints de objetos/Blobs: Si necesitas el máximo control, llamar directamente a las APIs HTTP del proveedor evita la abstracción, pero traslada la gestión de listados, firmas, normalización de errores y diferencias entre proveedores a tu aplicación.