Files SDK

Что такое Files SDK?

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

SDK маршрутизирует запросы через адаптер конкретного провайдера. Это сохраняет стабильность общих частей рабочих процессов хранения, а различия провайдеров (например, поведение URL или отдельные пограничные случаи) обрабатываются внутри адаптера, без изменения точек вызова.

Ключевые возможности

• Единый класс Files для всех провайдеров: Используйте один API для типовых операций хранения (загрузка, скачивание, получение списка, удаление, head, exists, копирование и работа с URL), вместо написания кода под каждого провайдера.
• Выбор провайдера через адаптер при создании экземпляра: Адаптер фиксируется при создании new Files({ adapter: ... }), что позволяет избежать паттернов «выбор провайдера при каждом вызове».
• Поддержка веб-стандартов для входных данных: Принимает File, Blob, ReadableStream, ArrayBuffer и string в качестве входных данных для загрузки.
• Работает везде, где доступен fetch: Предназначен для сред Node, Bun, Workers и Vercel, обеспечивая единообразное поведение.
• Доступ к нативному клиенту через files.raw: При необходимости использовать функции провайдера можно обратиться к нативному клиенту через свойство (files.raw), типизированное под адаптер.
• Нормализованная обработка ошибок: Ошибки возвращаются как единый тип FilesError с нормализованным кодом для всех провайдеров, а оригинальная ошибка провайдера прикрепляется как cause.

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

1. Установите SDK (и только те адаптеры, которые планируете использовать как peer-зависимости):
   • npm install files-sdk
2. Импортируйте Files и адаптер провайдера, затем создайте экземпляр Files с настроенным адаптером для вашего бакета и региона (например, S3).
3. Вызывайте общие методы на экземпляре, например:
   • files.upload(key, input)
   • files.download(key)
   • files.head(key)
   • files.list({ prefix })
   • files.delete(key)
4. Используйте files.raw если нужно получить доступ к функциям провайдера, не входящим в общий API.

Минимальный пример с страницы:

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

Сценарии использования

• Создание слоя хранения с возможностью смены провайдера: Начинайте с одного бэкенда (например, S3-compatible storage) и позже переходите к другому адаптеру без переписывания логики загрузки, скачивания, получения списка и удаления в приложении.
• Единообразная обработка файловых входных данных в коде бэкенда: Используйте поддерживаемые типы входных данных (File, Blob, ReadableStream, ArrayBuffer, string) при получении от сервера объектов, соответствующих веб-стандартам.
• Организация загрузок по префиксам и управление жизненным циклом объектов на уровне приложения: Используйте list({ prefix }) и delete(key) для реализации коллекций или «папок» над объектным хранилищем, управляемых приложением.
• Интеграция с средами, основاً на доступности fetch: Разворачивайте код в Node, Bun, Workers или Vercel, используя одни и те же API-вызовы и входные данные.
• Использование нормализованных ошибок для последовательной обработки и повторных попыток: Перехватывайте FilesError с нормализованным кодом,并<|eos|>

Альтернативы

• Специализированные SDK провайдеров (например, нативные клиенты S3/GCS/Azure): Они обеспечивают полное покрытие провайдеров, но обычно требуют разных кодовых путей для каждого бэкенда и отдельной обработки общих задач.
• Уровни абстракции объектного хранилища без веб-стандартных входных данных: Некоторые абстракции предоставляют унифицированный интерфейс, но могут не поддерживать тот же набор веб-нативных типов входных данных или fetch-ориентированные предположения среды выполнения.
• Серверные библиотеки загрузки файлов с опцией бэкенда хранения: Полезны, когда основная цель — обработка загрузок, но они могут не предоставлять тот же набор стандартизированных операций (head/exists/copy/url helpers) и доступа к нативному клиенту через escape hatch.
• Прямая HTTP-интеграция с конечными точками object/Blob: Если вам нужен максимальный контроль, прямой вызов HTTP API провайдера позволяет избежать абстракции, но переносит listing, signing, нормализацию ошибок и различия между провайдерами в ваше приложение.