Files SDK

Files SDK: Die universelle Lösung für Unified Storage und Object-Backends

In der modernen Webentwicklung ist die effiziente Verwaltung von Daten in der Cloud essenziell. Das Files SDK (haydenbleasel/files-sdk) stellt ein vereinheitlichtes Speicher-SDK dar, das speziell für Object- und Blob-Backends entwickelt wurde. Mit einer einzigen, ehrlichen API ermöglicht das Files SDK den nahtlosen Zugriff auf eine Vielzahl von Providern, ohne dass Entwickler für jeden Dienst einen neuen SDK-Stil erlernen müssen. Ob Sie mit AWS S3, Cloudflare R2, Vercel Blob oder Netlify Blobs arbeiten – das Files SDK bietet eine konsistente Schnittstelle für Ihre Speicheranforderungen.

Was ist das Files SDK?

Das Files SDK ist ein abstrahiertes Framework, das die Gemeinsamkeiten verschiedener Object-Storage-SDKs nutzt und sie hinter einer einzigen Klasse vereint. Oftmals unterscheiden sich die SDKs der Provider subtil in ihrer Handhabung. Das Files SDK extrahiert genau den Teil, der überall gleich ist: das Hochladen, Herunterladen, Auflisten und Löschen von Dateien.

Es wurde mit dem Ziel entwickelt, Entwicklern den Wechsel zwischen Speicheranbietern zu ermöglichen, ohne jemals die Funktionsaufrufe umschreiben zu müssen. Dank der Unterstützung von Web-Standards-I/O ist das Files SDK extrem flexibel und läuft überall dort, wo auch fetch ausgeführt werden kann – sei es in Node.js, Bun, Cloudflare Workers oder Vercel-Umgebungen.

Die wichtigsten Features des Files SDK

Das Files SDK zeichnet sich durch eine Reihe von Funktionen aus, die es von herkömmlichen, anbieterspezifischen Lösungen abheben:

1. Eine kleine, konsistente API

Anstatt sich mit den komplexen Eigenheiten jedes einzelnen Cloud-Speichers auseinanderzusetzen, bietet das Files SDK eine minimalistische API über alle Provider hinweg. Dies reduziert die kognitive Last für Entwickler erheblich.

2. Web-Standards I/O

Das Files SDK akzeptiert eine Vielzahl von Datenformaten, darunter:

• File
• Blob
• ReadableStream
• ArrayBuffer
• String

Diese Flexibilität stellt sicher, dass das SDK nahtlos in moderne Web-Workflows integriert werden kann.

3. Der "Escape Hatch" (Notausstieg)

Sollten Sie jemals native Funktionen eines Anbieters benötigen, die über die Standard-API hinausgehen (wie Versionierung, Lifecycle-Management oder ACLs), bietet das Files SDK über die Eigenschaft files.raw direkten Zugriff auf den nativen Client. Dieser ist pro Adapter korrekt typisiert.

4. Vorhersehbare Fehlermeldungen

Fehler werden im Files SDK normalisiert. Es wird ein einheitlicher FilesError mit einem standardisierten Code zurückgegeben, wobei der ursprüngliche Fehler des Providers zur Fehlerdiagnose angehängt bleibt.

5. Umfassende Adapter-Unterstützung

Das Files SDK unterstützt über 26 verschiedene Adapter, darunter:

• AWS S3 & Bun S3
• Cloudflare R2 (HTTP, Binding & Hybrid)
• Vercel Blob (Public & Private)
• Netlify Blobs
• MinIO, DigitalOcean, Hetzner, Akamai, Linode
• Google Cloud Storage (GCS), Dropbox, OneDrive, SharePoint
• Azure, Supabase, Firebase Storage, Appwrite
• Filesystem (lokaler Speicher)

Installation des Files SDK

Die Installation des Files SDK ist einfach und modular aufgebaut. Um das Kern-Paket zu installieren, nutzen Sie einen der folgenden Befehle:

• npm: npm install files-sdk
• pnpm: pnpm add files-sdk
• bun: bun add files-sdk
• yarn: yarn add files-sdk

Hinweis: Die nativen SDKs der jeweiligen Provider sind optionale Peer-Dependencies. Installieren Sie nur die SDKs, die Sie tatsächlich verwenden möchten. Wenn Sie einen Adapter ohne das entsprechende native Paket importieren, wird ein ERR_MODULE_NOT_FOUND Fehler geworfen.

How to Use: So nutzen Sie das Files SDK

Die Verwendung des Files SDK folgt einem einfachen Muster: Sie konstruieren eine Files-Instanz mit dem gewünschten Adapter und rufen anschließend die Methoden auf.

Schritt 1: Initialisierung

Zuerst importieren Sie das SDK und den gewünschten Adapter (hier am Beispiel von AWS S3):

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

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

Schritt 2: Datei-Operationen ausführen

Sobald die Instanz erstellt ist, können Sie standardisierte Methoden verwenden:

• Datei hochladen: await files.upload("hello.txt", "world");

• Datei herunterladen: const file = await files.download("hello.txt");

• Metadaten abrufen (Head): const meta = await files.head("hello.txt");

• Dateien auflisten: const { items } = await files.list({ prefix: "hello" });

• Datei löschen: await files.delete("hello.txt");

Da der Adapter bei der Konstruktion festgelegt wird, bleiben die Aufrufstellen im Code flach und übersichtlich.

Use Case: Wann ist das Files SDK die richtige Wahl?

Das Files SDK ist ideal für Projekte, die:

• Provider-Agnostik erfordern: Wenn Sie sich nicht an einen Anbieter wie AWS binden wollen und die Freiheit brauchen, später zu Cloudflare oder Vercel zu wechseln.
• Plattformübergreifend arbeiten: Da das SDK überall dort läuft, wo fetch verfügbar ist, eignet es sich hervorragend für Edge-Computing (Vercel Edge, Cloudflare Workers).
• Sauberen Code priorisieren: Durch die Normalisierung von Fehlern und die einheitliche API-Struktur wird der Code wartbarer und weniger fehleranfällig.

FAQ - Häufig gestellte Fragen zum Files SDK

F: Muss ich alle Provider-SDKs installieren? A: Nein. Das Files SDK nutzt Peer-Dependencies. Sie installieren nur das native SDK für den Provider, den Sie tatsächlich nutzen (z.B. @aws-sdk/client-s3 für S3).

F: Kann ich auf herstellerspezifische Funktionen zugreifen? A: Ja. Über den "Escape Hatch" files.raw haben Sie vollen Zugriff auf den nativen Client des jeweiligen Adapters.

F: Welche Laufzeitumgebungen werden unterstützt? A: Das Files SDK ist kompatibel mit Node.js, Bun, Cloudflare Workers und Vercel – also jeder Umgebung, die Web-Standards wie fetch unterstützt.

F: Wie werden Fehler gehandhabt? A: Das SDK liefert einen einheitlichen FilesError. Dieser enthält einen normalisierten Fehlercode, sodass Ihre Fehlerbehandlung über verschiedene Provider hinweg identisch bleiben kann.