Files SDK

Files SDKとは？

Files SDKは、オブジェクトストレージやブロブストレージ向けに、1つの一貫したAPIを提供する統一ストレージSDKです。アップロード、ダウンロード、リスト、削除などの高レベル操作を同じ方法で呼び出せます。実際のプロバイダーは内部で切り替わります。

リクエストはプロバイダー固有のアダプター経由で処理されます。これにより、共通のストレージワークフローは安定したまま、URLの扱いやエッジケースなどのプロバイダー差異はアダプター内で吸収されます。

主な機能

• プロバイダー共通のFilesクラス: アップロード、ダウンロード、リスト、削除、head、exists、copy、URLヘルパーなどの共通操作を1つのAPIで実行できます。各バックエンドごとにプロバイダー固有のコードを書く必要はありません。
• 構築時にアダプターを選択: new Files({ adapter: ... })でアダプターを固定します。呼び出しごとにプロバイダーを選択するパターンを避けられます。
• Web標準の入力対応: File、Blob、ReadableStream、ArrayBuffer、stringをアップロード入力として受け付けます。
• fetchが実行できる環境で動作: Node、Bun、Workers、Vercelなどの環境で同じ動作を実現します。
• files.rawによるプロバイダーエスケープハッチ: プロバイダー固有の機能が必要な場合、ネイティブクライアントにアクセスできます。タイプはアダプターごとに設定されます。
• 正規化されたエラーハンドリング: すべてのプロバイダーで統一されたFilesError型でエ<|eos|>

代替手段

• プロバイダー固有のストレージSDK（S3/GCS/Azureネイティブクライアントなど）: 各プロバイダーの機能を網羅できますが、バックエンドごとに異なるコードパスが必要になり、共通タスクの処理も別途行う必要があります。
• Web標準入力に対応していないオブジェクトストレージ抽象化レイヤー: 統一インターフェースを提供する抽象化レイヤーもありますが、Webネイティブな入力タイプやfetch指向のランタイム前提をサポートしていない場合があります。
• ストレージバックエンドオプション付きのサーバーサイドファイルアップロードライブラリ: アップロード処理が主な目的の場合に便利ですが、head/exists/copy/urlヘルパーなどの標準化された操作やネイティブクライアントへのエスケープハッチは提供されません。
• オブジェクト/Blobエンドポイントへの直接HTTP統合: 最大限の制御が必要な場合、プロバイダーのHTTP APIを直接呼び出すことで抽象化を避けられますが、リスト表示、署名、エラー標準化、プロバイダー間の違いをアプリケーション側で扱う必要があります。