cca-aws-sdk-s3

TypeScript module for S3 image storage with automatic resizing, signed URLs, and metadata.

What It Does

• Uploads one or multiple images to S3 and stores metadata.json
• Generates signed URLs for each size
• Deletes an image and all its sizes
• Returns a paginated list of images based on metadata.json

Requirements

• Node.js 18+ (uses fetch)
• AWS S3 bucket

Installation

pnpm add cca-aws-sdk-s3

Usage

Initialization

import { S3ImageStorage, S3Config } from 'cca-aws-sdk-s3';

const config: S3Config = {
  region: process.env.AWS_REGION ?? '',
  bucket: process.env.AWS_BUCKET ?? '',
  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? ''
};

const imageStorage = new S3ImageStorage(config);

Basic Operations

import { ImageSize } from 'cca-aws-sdk-s3';

const metadata = await imageStorage.uploadImage(req.file);
const metadataArray = await imageStorage.uploadMultipleImages(req.files);

const urls = await imageStorage.getImageUrls(imageId);
const mdUrl = await imageStorage.getImageUrl(imageId, ImageSize.MD);

await imageStorage.deleteImage(imageId);
await imageStorage.deleteMultipleImages([id1, id2]);

const result = await imageStorage.getImagesList(1, 10);

API

S3ImageStorage

• constructor(config: S3Config)
• uploadImage(file: Express.Multer.File): Promise<ImageMetadata>
• uploadMultipleImages(files: Express.Multer.File[]): Promise<ImageMetadata[]>
• getImageUrl(id: string, size: ImageSize): Promise<string>
• getImageUrls(id: string): Promise<Record<ImageSize, string>>
• deleteImage(id: string): Promise<void>
• deleteMultipleImages(ids: string[]): Promise<void>
• getImagesList(page?: number, limit?: number): Promise<PaginatedResult<ImageMetadata>>

S3Config

interface S3Config {
  region: string;
  bucket: string;
  accessKeyId: string;
  secretAccessKey: string;
}

ImageMetadata

import { ImageSize } from 'cca-image-resize-convert-module';

interface ImageMetadata {
  id: string;
  originalName: string;
  mimeType: string;
  ORIGINAL_size_kb: number;
  THUMB_size_kb: number;
  SM_size_kb: number;
  MD_size_kb: number;
  LG_size_kb: number;
  XL_size_kb: number;
  createdAt: Date;
  urls: Record<ImageSize, string>;
}

ImageSize

enum ImageSize {
  ORIGINAL = 'original',
  THUMB = 'thumb',
  SM = 'sm',
  MD = 'md',
  LG = 'lg',
  XL = 'xl'
}

Behavior Notes

• id accepts only [a-zA-Z0-9_-] and up to 128 characters.
• getImagesList enforces limit <= 100.
• If metadata.json is not available, URLs are derived from the S3 object list.

Express Example

import express from 'express';
import multer from 'multer';
import { S3ImageStorage } from 'cca-aws-sdk-s3';

const app = express();
const upload = multer({ storage: multer.memoryStorage() });
const imageStorage = new S3ImageStorage({
  region: process.env.AWS_REGION ?? '',
  bucket: process.env.AWS_BUCKET ?? '',
  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? ''
});

app.post('/upload', upload.single('image'), async (req, res) => {
  try {
    const metadata = await imageStorage.uploadImage(req.file);
    res.status(200).json({ success: true, metadata });
  } catch (error) {
    res.status(400).json({ success: false, error: (error as Error).message });
  }
});

Build and Test

pnpm run build:tsup
pnpm test

License

MIT