mv-s3-manager/core

Gestione bucket S3-compatibili indipendente dal framework per Node.js.

Funziona con AWS S3, MinIO, Cloudflare R2, Backblaze B2 e qualsiasi provider S3-compatibile.

Installazione

npm install mv-s3-manager/core @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
# oppure
pnpm add mv-s3-manager/core @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Avvio rapido

import { createClient, uploadObject, downloadObjectAsBuffer } from "mv-s3-manager/core";
import type { S3ManagerConfig } from "mv-s3-manager/core";

const config: S3ManagerConfig = {
  region: "us-east-1",
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  bucket: "mio-bucket",
};

const client = createClient(config);

// Upload
await uploadObject(client, config, "ciao.txt", "Ciao, mondo!", {
  contentType: "text/plain",
});

// Download
const buffer = await downloadObjectAsBuffer(client, config, "ciao.txt");
console.log(buffer.toString("utf-8")); // "Ciao, mondo!"

Configurazione

| Campo | Tipo | Obbligatorio | Descrizione | |---|---|---|---| | region | string | ✅ | Regione AWS o del provider (es. "auto" per Cloudflare R2) | | credentials.accessKeyId | string | ✅ | Access key ID | | credentials.secretAccessKey | string | ✅ | Secret access key | | bucket | string | ✅ | Nome del bucket di destinazione | | endpoint | string | — | URL endpoint personalizzato per provider non-AWS | | forcePathStyle | boolean | — | Obbligatorio per MinIO e Ceph. Default: false |

MinIO

const config: S3ManagerConfig = {
  endpoint: "http://localhost:9000",
  region: "us-east-1",
  credentials: { accessKeyId: "minioadmin", secretAccessKey: "minioadmin" },
  bucket: "mio-bucket",
  forcePathStyle: true,
};

Cloudflare R2

const config: S3ManagerConfig = {
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  region: "auto",
  credentials: { accessKeyId: R2_ACCESS_KEY, secretAccessKey: R2_SECRET_KEY },
  bucket: "mio-bucket",
};

Riferimento API

createClient(config)

Crea un S3Client configurato. Riutilizzalo tra le richieste — l'SDK gestisce il connection pooling.

validateConfig(config)

Verifica a runtime che config sia una S3ManagerConfig valida. Lancia S3ManagerConfigError in caso di errore. Da chiamare una volta all'avvio.

uploadObject(client, config, key, body, options?)

| Parametro | Tipo | Descrizione | |---|---|---| | key | string | Chiave dell'oggetto (percorso nel bucket) | | body | Uint8Array \| ReadableStream \| string | Contenuto da caricare | | options.contentType | string | Tipo MIME. Default: "application/octet-stream" | | options.metadata | Record<string, string> | Metadati chiave-valore | | options.storageClass | string | Override della classe di storage |

Restituisce UploadResult: { key, etag, url }.

downloadObject(client, config, key)

Restituisce DownloadResult: { body: Readable, contentType, contentLength, metadata, etag }.

Lancia S3ManagerNotFoundError se la chiave non esiste.

downloadObjectAsBuffer(client, config, key)

Wrapper di convenienza che bufferizza l'intero oggetto in memoria. Sconsigliato per file di grandi dimensioni.

deleteObject(client, config, key)

Idempotente. Non lancia errori se la chiave non esiste.

deleteObjects(client, config, keys)

Eliminazione batch fino a 1000 chiavi per chiamata (le liste più grandi vengono divise automaticamente). Restituisce un array delle chiavi fallite.

listObjects(client, config, options?)

| Opzione | Tipo | Descrizione | |---|---|---| | prefix | string | Filtra per prefisso della chiave | | maxKeys | number | Numero massimo di risultati per pagina | | continuationToken | string | Token di paginazione dal risultato precedente |

Restituisce ListResult: { objects: S3Object[], nextContinuationToken, isTruncated }.

listAllObjects(client, config, options?)

Generatore asincrono che pagina automaticamente. Produce un S3Object alla volta.

for await (const obj of listAllObjects(client, config, { prefix: "log/" })) {
  console.log(obj.key, obj.size);
}

getPresignedDownloadUrl(client, config, key, options?)

Genera un URL GET a tempo limitato. Scadenza predefinita: 3600 secondi.

getPresignedUploadUrl(client, config, key, options?)

Genera un URL PUT a tempo limitato per l'upload diretto lato client.

Tipi di errore

| Classe | Quando viene lanciata | |---|---| | S3ManagerConfigError | Configurazione non valida | | S3ManagerNotFoundError | La chiave oggetto non esiste | | S3ManagerUploadError | Upload fallito | | S3ManagerDeleteError | Eliminazione fallita | | S3ManagerListError | Listaggio fallito | | S3ManagerPresignError | Generazione URL prefirmato fallita |

Tutte estendono S3ManagerError (che estende Error) e portano un campo cause.