@unidev-hub/cloud-utils

A unified interface for cloud storage providers (AWS S3, Azure Blob Storage, Google Cloud Storage) that makes it easy to switch between different providers or support multiple providers with the same codebase.

Features

• Unified Interface: Work with any supported cloud provider using the same API
• Provider Agnostic: Easily switch between cloud providers without changing your code
• Factory Pattern: Use the factory to create the right uploader based on your configuration
• Flexible: Support for uploading files, buffers, and managing cloud storage
• TypeScript: Full TypeScript support with interfaces and type definitions

Installation

npm install cloud-utils

Supported Providers

• AWS S3: Amazon Simple Storage Service
• Azure Blob Storage: Microsoft Azure's object storage solution
• Google Cloud Storage: Google Cloud Platform's object storage (optional)

Usage

Basic Example

import { FileUploaderFactory } from 'cloud-utils';

// Create an uploader for AWS S3
const uploader = FileUploaderFactory.createUploader('aws', {
  accessKeyId: 'YOUR_ACCESS_KEY_ID',
  secretAccessKey: 'YOUR_SECRET_ACCESS_KEY',
  region: 'us-east-1',
  bucket: 'your-bucket-name'
});

// Upload a file
const url = await uploader.uploadFile('/path/to/local/file.jpg', 'uploads/file.jpg', {
  contentType: 'image/jpeg',
  accessControl: 'public-read',
  metadata: {
    owner: 'user123',
    project: 'profile-pictures'
  }
});

console.log(`File uploaded to: ${url}`);

Using Environment Variables

import { FileUploaderFactory } from 'cloud-utils';

// Create an uploader based on environment variables
const uploader = FileUploaderFactory.createFromEnv();

// Upload a buffer
const buffer = Buffer.from('Hello, World!');
const url = await uploader.uploadBuffer(buffer, 'hello.txt', {
  contentType: 'text/plain'
});

console.log(`File uploaded to: ${url}`);

Switching Providers

import { FileUploaderFactory } from 'cloud-utils';

// Start with AWS
let uploader = FileUploaderFactory.createUploader('aws', {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  region: process.env.AWS_REGION!,
  bucket: process.env.AWS_S3_BUCKET!
});

// Later, switch to Azure
uploader = FileUploaderFactory.createUploader('azure', {
  connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING!,
  container: process.env.AZURE_STORAGE_CONTAINER!
});

// Your code that uses the uploader stays the same!
const url = await uploader.uploadFile('local.txt', 'remote.txt');

Direct Provider Usage

If you prefer to use a specific provider directly:

import { AzureFileUploader, S3FileUploader, GCSFileUploader } from 'cloud-utils';

// Azure
const azureUploader = new AzureFileUploader(
  'your-connection-string',
  'your-container'
);

// AWS S3
const s3Uploader = new S3FileUploader(
  'your-access-key-id',
  'your-secret-access-key',
  'us-east-1',
  'your-bucket'
);

// Google Cloud Storage
const gcsUploader = new GCSFileUploader(
  '/path/to/service-account-key.json',
  'your-bucket'
);

API Reference

FileUploader Interface

The main interface that all cloud providers implement:

interface FileUploader {
  uploadFile(filePath: string, destination: string, options?: UploadOptions): Promise<string>;
  uploadBuffer(buffer: Buffer, destination: string, options?: UploadOptions): Promise<string>;
  deleteFile(filePath: string): Promise<boolean>;
  listFiles(path: string, options?: ListOptions): Promise<FileInfo[]>;
  generateSignedUrl(filePath: string, expiresIn: number, options?: SignOptions): Promise<string>;
}

FileUploaderFactory

Factory for creating FileUploader instances:

class FileUploaderFactory {
  static createUploader(provider: CloudProvider, config: CloudConfig): FileUploader;
  static createFromEnv(provider?: CloudProvider): FileUploader;
}

Provider-Specific Notes

AWS S3

• Supports both bucket/key format and s3:// protocol in destination paths
• Returns URLs in the format https://{bucket}.s3.{region}.amazonaws.com/{key}

Azure Blob Storage

• Supports container/blob format in destination paths
• Container-level access control (public/private)

Google Cloud Storage

• Supports both bucket/object format and gs:// protocol in destination paths
• Two authentication methods: keyFilename or credentials object

Dependencies

This package uses peer dependencies to avoid bundling cloud SDKs you don't need:

• @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner (for AWS S3)
• @azure/storage-blob (for Azure Blob Storage)
• @google-cloud/storage (for Google Cloud Storage)

Only install the dependencies for the providers you're using.

License

MIT