Files SDK

Files SDK: Универсальный интерфейс для облачных хранилищ

В современной разработке выбор правильного решения для хранения данных является критически важным. Однако разные провайдеры объектных хранилищ часто используют свои уникальные SDK, что затрудняет миграцию и поддержку кода. Files SDK решает эту проблему, предлагая единый, честный и эффективный API для работы с любыми blob-бэкендами.

Что такое Files SDK?

Files SDK — это унифицированный SDK для объектных и блочных хранилищ. Основная идея проекта заключается в том, что базовые операции с файлами — загрузка, скачивание, вывод списка и удаление — идентичны практически у всех провайдеров. Files SDK выделяет этот общий функционал в один компактный класс, обеспечивая предсказуемую работу независимо от того, используете ли вы AWS S3, Google Cloud Storage или локальную файловую систему.

Библиотека построена на базе веб-стандартов I/O, что делает её совместимой с любыми средами исполнения, где работает fetch, включая Node.js, Bun, Vercel и Cloudflare Workers.

Ключевые особенности Files SDK

Разработка с использованием Files SDK предоставляет ряд преимуществ для инженеров и компаний, стремящихся к гибкости своей инфраструктуры.

Единый API для всех провайдеров

Главное преимущество Files SDK — это возможность смены провайдера хранилища без необходимости переписывать вызовы методов в коде. Один и тот же метод upload или download будет работать одинаково для S3, R2 и других систем.

Поддержка веб-стандартов I/O

Files SDK спроектирован для работы с современными стандартами. Он принимает и обрабатывает:

• File
• Blob
• ReadableStream
• ArrayBuffer
• String

Это обеспечивает бесшовную интеграцию в современные веб-приложения и серверные функции.

Механизм «Escape Hatch» через files.raw

Если вам требуются специфические функции конкретного провайдера (например, настройка жизненного цикла объектов, списки управления доступом ACL или многослойная загрузка), Files SDK не ограничивает вас. Свойство files.raw предоставляет прямой доступ к нативному клиенту адаптера с полной поддержкой типов.

Предсказуемая обработка ошибок

Вместо того чтобы разбираться в специфических кодах ошибок каждого провайдера, Files SDK использует единый класс FilesError с нормализованными кодами. При этом оригинальная ошибка всегда доступна в поле cause для глубокой отладки.

Поддерживаемые адаптеры и совместимость

Files SDK поддерживает широчайший спектр провайдеров через систему адаптеров. В список входят:

• Облачные гиганты: AWS S3, Google Cloud Storage (GCS), Azure, Oracle Cloud.
• Современные Edge-платформы: Vercel Blob, Netlify Blobs, Cloudflare R2.
• S3-совместимые решения: MinIO, DigitalOcean Spaces, Backblaze B2, Wasabi, Scaleway, Yandex Object Storage, Tigris.
• Специализированные сервисы: Supabase, Firebase Storage, Cloudinary, UploadThing, Appwrite.
• Популярные диски и хранилища: Google Drive, OneDrive, SharePoint, Dropbox, Box.
• Локальные решения: Filesystem для разработки и тестирования.

Каждый адаптер реализует стандартный набор из десяти методов, обеспечивая высокую степень переносимости кода.

Как использовать Files SDK

Интеграция Files SDK в ваш проект проста и не требует сложной настройки.

Установка

Вы можете установить основной пакет с помощью любого предпочтительного менеджера пакетов:

npm install files-sdk
# или
pnpm install files-sdk
# или
bun install files-sdk
# или
yarn add files-sdk

Важное примечание: Нативные SDK провайдеров являются необязательными зависимостями (peer dependencies). Вам нужно устанавливать только те пакеты, адаптеры которых вы реально используете.

Быстрый старт

Для начала работы создайте экземпляр класса Files, указав нужный адаптер. Адаптер фиксируется при создании экземпляра, что делает вызовы методов плоскими и понятными.

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

// Инициализация с адаптером 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 { items } = await files.list({ prefix: "hello" });
await files.delete("hello.txt");

Варианты использования (Use Case)

Files SDK идеально подходит для различных сценариев разработки:

1. Мультиоблачные стратегии: Если ваше приложение должно хранить данные у разных провайдеров или иметь возможность быстрого переезда из одного облака в другое.
2. Edge-вычисления: Использование в Vercel Functions или Cloudflare Workers, где важна поддержка веб-стандартов и малый размер библиотеки.
3. Унифицированные интерфейсы управления файлами: Создание панелей управления, которые могут работать с любым бэкендом (S3, Dropbox, Google Drive) через один программный интерфейс.
4. Локальная разработка: Использование адаптера Filesystem для тестирования функций загрузки файлов на локальной машине без затрат на облачные ресурсы.

Часто задаваемые вопросы (FAQ)

Нужно ли мне устанавливать все зависимости для всех провайдеров? Нет. Files SDK использует концепцию peer dependencies. Вы устанавливаете только files-sdk и нативный пакет того провайдера, который используете в данный момент.

Что произойдет, если я импортирую адаптер без установленного нативного SDK? В этом случае среда исполнения (например, Node.js) выдаст ошибку ERR_MODULE_NOT_FOUND с указанием отсутствующего пакета.

Могу ли я получить доступ к специфическим функциям AWS S3 через Files SDK? Да, для этого существует свойство files.raw. Оно предоставляет прямой доступ к нативному клиенту, позволяя использовать все возможности конкретного провайдера, которые не входят в стандартный API.

На каких платформах работает Files SDK? Библиотека универсальна и работает везде, где поддерживается fetch: Node.js, Bun, Deno, Vercel, Cloudflare Workers и в браузерах.