Files SDK

Files SDK：オブジェクト・ブロブストレージ操作を劇的に簡略化する統一SDK

現代のWeb開発において、データの保存先としてオブジェクトストレージやブロブストレージを選択することは一般的です。しかし、AWS S3、Cloudflare R2、Vercel Blobなど、各プロバイダーが提供するSDKはそれぞれ微妙に仕様が異なり、コードの複雑化やベンダーロックインの原因となってきました。Files SDKは、この問題を解決するために誕生した、統合型のストレージSDKです。

What's Files SDK? (Files SDKとは)

Files SDKは、さまざまなオブジェクトおよびブロブストレージのバックエンドを統合し、一つの「正直なAPI」として提供するオープンソースのSDKです。このライブラリの核となる思想は、ストレージ操作の共通部分（アップロード、ダウンロード、リスト取得、削除など）を抽象化し、プロバイダー特有の複雑さを背後に隠すことにあります。

Files SDKを使用することで、開発者はストレージプロバイダーが何であるかを意識することなく、Web標準のI/O（File, Blob, ReadableStreamなど）を用いてデータを扱うことができます。万が一、特定のプロバイダーにしかない高度な機能が必要になった場合でも、「エスケープハッチ」機能によりネイティブクライアントへ即座にアクセスできる柔軟性を備えています。

---

Files SDK の主な特徴 (Features)

Files SDKには、開発効率とメンテナンス性を高めるための優れた特徴が凝縮されています。

1. プロバイダーを横断する単一の小型API

Files SDKは、プロバイダーが変わっても変わらない「共通のスライス」を抽出しています。これにより、一度実装したコードを大幅に書き換えることなく、バックエンドのストレージプロバイダーをS3からR2へ、あるいはVercel Blobへと容易にスワップすることが可能です。

2. Web標準準拠のI/O

Files SDKは、現代のWeb標準を全面的に採用しています。以下のデータ形式をネイティブに受け入れることができます：

• File
• Blob
• ReadableStream
• ArrayBuffer
• string

これにより、Node.js、Bun、Cloudflare Workers、Vercelなど、fetchが動作するあらゆる環境で Files SDK を利用できます。

3. エスケープハッチ（Native Clientへのアクセス）

Files SDKの最大の特徴の一つが、files.raw プロパティです。抽象化層では対応できないバージョン管理、ライフサイクル、ACL、マルチパートアップロードなどのプロバイダー固有の操作が必要な場合、このプロパティを介して型定義されたネイティブクライアントに直接アクセスできます。

4. 予測可能なエラーハンドリング

各プロバイダーは独自のエラー形式を持っていますが、Files SDKはこれらを統合します。単一の FilesError クラスと、プロバイダー間で正規化されたエラーコードを提供するため、例外処理が非常にシンプルになります。元のエラーは cause プロパティに保持されるため、詳細なデバッグも容易です。

5. 効率的な依存関係管理

Files SDK本体は非常に軽量です。各プロバイダーのネイティブSDKはオプションのピア依存関係（peer dependency）となっており、実際に使用するプロバイダーのパッケージのみをインストールするだけで済みます。

---

対応アダプター一覧 (Compatibility matrix)

Files SDKは、業界で広く使われているほぼすべてのオブジェクトストレージをサポートしています。

• AWS S3 / Bun S3
• Cloudflare R2 (HTTP, binding, hybrid)
• Vercel Blob (public, private)
• Netlify Blobs
• MinIO / DigitalOcean Spaces
• Google Cloud Storage (GCS)
• Azure Blob Storage
• Dropbox / Box / Google Drive / OneDrive
• Supabase / Firebase Storage / Appwrite
• Cloudinary / UploadThing
• Filesystem (ローカルファイルシステム)
• その他多数（Wasabi, Backblaze B2, Akamai, Hetzner, Storjなど）

---

Files SDK の使い方 (How to Use)

インストール方法

お好みのパッケージマネージャーを使用して、Files SDKをプロジェクトに追加してください。また、使用するアダプターに対応するネイティブSDKも併せてインストールする必要があります。

npm install files-sdk
# 使用するアダプター例：S3の場合
npm install @aws-sdk/client-s3

クイックスタートガイド

Files SDKを利用する手順は、Files インスタンスを作成し、適切なアダプターを渡すだけです。インスタンス構築時にアダプターが固定されるため、メソッド呼び出しが非常にフラットで分かりやすくなります。

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

// 1. Files SDKのインスタンス化
const files = new Files({
  adapter: s3({ bucket: "uploads", region: "us-east-1" }),
});

// 2. ファイルのアップロード
await files.upload("hello.txt", "world");

// 3. ファイルのダウンロード
const file = await files.download("hello.txt");

// 4. ファイル一覧の取得
const { items } = await files.list({ prefix: "hello" });

// 5. メタデータの取得と削除
const meta = await files.head("hello.txt");
await files.delete("hello.txt");

---

主な活用シーン (Use Case)

• マルチクラウド戦略: データの可用性を高めるために複数のクラウドストレージを併用する場合、Files SDKを使用すれば同一のインターフェースで制御可能です。
• プロバイダー移行: サービス成長に伴うコスト最適化のために、S3からより安価なR2やWasabiへ移行する際、Files SDKを導入していればアプリケーションロジックの大幅な改修は不要です。
• サーバーレス環境: VercelやNetlifyなどのサーバーレス環境で、軽量かつ標準的なWeb I/Oを用いてストレージ操作を行いたい場合に最適です。
• 開発環境と本番環境の切り分け: ローカル開発では Filesystem アダプターを使用し、本番環境では S3 アダプターを使用するといった切り替えがスムーズに行えます。

---

よくある質問 (FAQ)

Q: Files SDKを導入すると、ネイティブSDKの機能は使えなくなりますか？

A: いいえ、使えます。Files SDKには files.raw というエスケープハッチが用意されており、ここから各プロバイダーのネイティブクライアントを直接操作できます。共通操作はFiles SDKで、特殊な操作はネイティブで行うという使い分けが可能です。

Q: すべてのアダプターをインストールする必要がありますか？

A: いいえ、必要ありません。Files SDKはピア依存関係を採用しているため、実際に利用するアダプター（例：@aws-sdk/client-s3）のみをインストールするだけで動作します。

Q: エラーが発生した際、どのプロバイダーが原因か分かりますか？

A: はい。Files SDKが投げる FilesError には、元のSDKから返されたエラーが cause プロパティとしてアタッチされています。これにより、統合されたエラーコードを利用しつつ、詳細な原因究明も可能です。

Q: ファイル一覧の取得（list）でプレフィックス指定は可能ですか？

A: はい、可能です。files.list({ prefix: "xxx" }) のようにオプションを渡すことで、特定ディレクトリ配下のファイルのみをリストアップできます。

---

Files SDKは、ストレージ操作の未来を変えるシンプルかつ強力なツールです。ベンダーロックインを回避し、コードの可読性と保守性を極限まで高めたい開発者にとって、最適な選択肢となるでしょう。