Files SDK

Che cos'è Files SDK?

Files SDK è un unified storage SDK che espone un'unica API coerente per interagire con backend di object e blob storage. L'obiettivo è consentirti di chiamare le stesse operazioni di alto livello — come upload, download, list, delete e helper correlati — utilizzando diversi provider dietro le quinte.

Funziona instradando le richieste attraverso un adapter specifico per provider. Questo mantiene stabili le parti condivise dei flussi di storage, mentre le differenze tra provider (come comportamenti relativi agli URL o determinati casi limite) vengono gestite all'interno dell'adapter senza modificare i punti di chiamata.

Funzionalità principali

• Classe Files unica per tutti i provider: Usa un'unica superficie API per le operazioni di storage comuni (upload, download, list, delete, head, exists, copy e helper per gli URL), invece di scrivere codice specifico per ogni backend.
• Selezione del provider basata su adapter al momento della costruzione: L'adapter viene fissato quando istanzi new Files({ adapter: ... }), evitando pattern di "scelta del provider per chiamata" che appesantirebbero l'utilizzo.
• Supporto per input web-standard: Accetta File, Blob, ReadableStream, ArrayBuffer e string come input per gli upload.
• Esegue ovunque sia disponibile fetch: Progettato per funzionare in ambienti come Node, Bun, Workers e Vercel (come indicato nella pagina) per un comportamento runtime coerente.
• Escape hatch del provider tramite files.raw: Quando hai bisogno di funzionalità specifiche del provider, puoi accedere al client nativo attraverso una proprietà (files.raw), tipizzata per adapter.
• Gestione degli errori normalizzata: Gli errori vengono esposti come un unico tipo FilesError con un codice normalizzato tra i provider, con l'errore originale del provider allegato come causa.

Come usare Files SDK

1. Installa l'SDK (e solo gli adapter che intendi usare come peer dependencies):
   • npm install files-sdk
2. Importa Files e un adapter del provider, quindi crea un'istanza Files con l'adapter configurato per il tuo bucket/region (ad esempio S3).
3. Chiama i metodi condivisi sull'istanza, come:
   • files.upload(key, input)
   • files.download(key)
   • files.head(key)
   • files.list({ prefix })
   • files.delete(key)
4. Usa files.raw se hai bisogno di accedere a funzionalità specifiche del provider non coperte dalla superficie API comune.

Un esempio minimo dalla pagina:

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");

Casi d'uso

• Costruire uno strato di storage che possa cambiare provider: Inizia con un backend (ad esempio S3-compatible storage) e later migra a un altro adapter senza riscrivere la logica di upload/download/list/delete della tua applicazione.
• Gestire input file browser-like in modo coerente nel codice backend: Usa i tipi di input supportati dall'SDK (File, Blob, ReadableStream, ArrayBuffer, string) quando il tuo server riceve oggetti file web-standard.
• Organizzare upload per prefix e gestire i cicli di vita degli oggetti a livello di app: Usa list({ prefix }) e delete(key) patterns per implementare collezioni gestite dall'app o "folder" su object storage.
• Integrare con ambienti basati sulla disponibilità di fetch: Deploya codice su Node, Bun, Workers o Vercel mentre usi le stesse API calls e inputs.
• Usare errori normalizzati per retry/handling coerenti: Cattura FilesError con un codice normalizzato,检查

Alternative

• SDK di storage specifici per provider (es. client nativi S3/GCS/Azure): Offrono una copertura completa per ogni provider, ma richiedono generalmente percorsi di codice diversi per ciascun backend e una gestione separata delle attività comuni.
• Livelli di astrazione per object storage senza input web-standard: Alcune astrazioni forniscono un’interfaccia unificata, ma potrebbero non supportare lo stesso set di tipi di input web-native o le assunzioni runtime orientate a fetch.
• Librerie server-side per l’upload di file con opzione backend di storage: Utili quando l’obiettivo principale è la gestione degli upload, ma potrebbero non esporre lo stesso set di operazioni standardizzate (head/exists/copy/url helpers) e l’accesso escape-hatch al client nativo.
• Integrazione HTTP diretta agli endpoint object/Blob: Se hai bisogno del massimo controllo, chiamare direttamente le API HTTP dei provider evita l’astrazione, ma sposta la gestione di listing, signing, normalizzazione degli errori e differenze tra provider nella tua applicazione.