@vlsdev/s3-portable

Portable S3 service for Node.js microservices with TypeScript, DDD layers, and SOLID-oriented design.

Install

npm i @vlsdev/s3-portable

Requirements

• Node.js 18+
• AWS credentials with S3 permissions (s3:GetObject, s3:PutObject, s3:ListBucket, s3:DeleteObject)

Environment variables

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
AWS_S3_BUCKET_NAME=your-bucket

Quick start (from env)

import "dotenv/config";
import { createS3ServiceFromEnv } from "@vlsdev/s3-portable";

const s3Service = createS3ServiceFromEnv();

const files = await s3Service.listFiles("billing-service", "invoices");
console.log(files);

Explicit config

import { createS3Service } from "@vlsdev/s3-portable";

const s3Service = createS3Service({
  region: process.env.AWS_REGION!,
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  bucketName: process.env.AWS_S3_BUCKET_NAME!,
});

API

downloadFile(project, path, fileName)

Returns the S3 object body stream.

const body = await s3Service.downloadFile("billing-service", "invoices", "invoice-1.pdf");

uploadFile(project, path, fileName, body, contentType?)

Uploads a file to the bucket and returns a success message.

await s3Service.uploadFile(
  "billing-service",
  "invoices",
  "invoice-1.pdf",
  Buffer.from("file content"),
  "application/pdf"
);

listFiles(project, path)

Returns object keys under project/path/.

const keys = await s3Service.listFiles("billing-service", "invoices");

deleteFile(project, path, fileName)

Deletes a file and returns a success message.

await s3Service.deleteFile("billing-service", "invoices", "invoice-1.pdf");

generateSignedUrl(project, path, fileName, expiresIn?)

Generates a signed GET URL (default expiration: 3600 seconds).

const url = await s3Service.generateSignedUrl(
  "billing-service",
  "invoices",
  "invoice-1.pdf",
  900
);

Express example

import express from "express";
import "dotenv/config";
import { createS3ServiceFromEnv } from "@vlsdev/s3-portable";

const app = express();
const s3 = createS3ServiceFromEnv();

app.get("/files/:project/:path/:fileName/url", async (req, res) => {
  const { project, path, fileName } = req.params;
  const url = await s3.generateSignedUrl(project, path, fileName, 300);
  res.json({ url });
});

app.listen(3000);

Error handling

This package throws:

• DomainError for invalid input/configuration
• AWS SDK errors for infrastructure failures

import { DomainError } from "@vlsdev/s3-portable";

try {
  await s3Service.generateSignedUrl("p", "docs", "file.pdf", 0);
} catch (error) {
  if (error instanceof DomainError) {
    console.error("Validation error:", error.message);
  }
}