Работа с S3 и облачными хранилищами в TypeScript: библиотеки и примеры

Работа с S3 и облачными хранилищами в TypeScript: библиотеки, настройка и примеры кода

Облачные объектные хранилища, совместимые с Amazon S3 API, стали стандартом де-факто для хранения и доставки файлов в современных веб-приложениях. В экосистеме TypeScript и Node.js для работы с S3 существует несколько мощных инструментов. В этой статье мы разберем основные библиотеки, их настройку и приведем практические примеры кода для типичных задач: загрузка, скачивание, удаление файлов и управление бакетами.

Основные библиотеки для работы с S3 в TypeScript

Наиболее популярным и официальным решением является AWS SDK for JavaScript v3. Эта библиотека полностью переписана на TypeScript, модульная и поддерживает tree-shaking. Альтернативой выступает MinIO JavaScript Client — легковесная библиотека, полностью совместимая с S3 API, которая отлично подходит для работы с локальными или self-hosted S3-совместимыми хранилищами (например, MinIO, Ceph, DigitalOcean Spaces).

Для простых сценариев также можно использовать @aws-sdk/client-s3 — отдельный пакет из состава AWS SDK v3, который содержит только необходимый функционал для S3.

Установка и инициализация

Установим основной пакет для работы с S3 через AWS SDK v3:

npm install @aws-sdk/client-s3 @aws-sdk/credential-providers

Для работы с MinIO:

npm install minio

Пример инициализации клиента S3 с использованием AWS SDK v3:

import { S3Client } from "@aws-sdk/client-s3";
import { fromEnv } from "@aws-sdk/credential-providers";

const s3Client = new S3Client({
  region: "us-east-1",
  credentials: fromEnv(), // использует AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY из переменных окружения
});

Для MinIO клиент настраивается следующим образом:

import * as Minio from "minio";

const minioClient = new Minio.Client({
  endPoint: "play.min.io",
  port: 9000,
  useSSL: true,
  accessKey: "YOUR_ACCESS_KEY",
  secretKey: "YOUR_SECRET_KEY",
});

Типизация и строгие типы

Одним из главных преимуществ TypeScript является строгая типизация. Обе библиотеки предоставляют полные типы для всех запросов и ответов. Например, при загрузке файла в S3 вы получаете автодополнение для всех параметров:

import { PutObjectCommand } from "@aws-sdk/client-s3";

const uploadParams: PutObjectCommand["input"] = {
  Bucket: "my-bucket",
  Key: "uploads/photo.jpg",
  Body: fileBuffer,
  ContentType: "image/jpeg",
  ACL: "public-read",
};

const command = new PutObjectCommand(uploadParams);
const result = await s3Client.send(command);

Основные операции: загрузка, скачивание, удаление

1. Загрузка файла (Upload)

import { PutObjectCommand } from "@aws-sdk/client-s3";

async function uploadFile(bucket: string, key: string, body: Buffer | Uint8Array | string) {
  const command = new PutObjectCommand({
    Bucket: bucket,
    Key: key,
    Body: body,
  });
  return await s3Client.send(command);
}

// Пример использования
const buffer = Buffer.from("Hello, S3!");
await uploadFile("my-bucket", "hello.txt", buffer);

2. Скачивание файла (Download)

import { GetObjectCommand } from "@aws-sdk/client-s3";

async function downloadFile(bucket: string, key: string): Promise<Buffer> {
  const command = new GetObjectCommand({ Bucket: bucket, Key: key });
  const response = await s3Client.send(command);
  return Buffer.from(await response.Body!.transformToByteArray());
}

// Пример
const fileContent = await downloadFile("my-bucket", "hello.txt");
console.log(fileContent.toString());

3. Удаление файла

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

async function deleteFile(bucket: string, key: string) {
  const command = new DeleteObjectCommand({ Bucket: bucket, Key: key });
  return await s3Client.send(command);
}

await deleteFile("my-bucket", "hello.txt");

Управление бакетами

Создание и удаление бакетов также реализуется через команды S3:

import { CreateBucketCommand, ListBucketsCommand, DeleteBucketCommand } from "@aws-sdk/client-s3";

// Создание бакета
async function createBucket(bucketName: string) {
  const command = new CreateBucketCommand({ Bucket: bucketName });
  return await s3Client.send(command);
}

// Получение списка бакетов
async function listBuckets() {
  const command = new ListBucketsCommand({});
  const response = await s3