express-storage 1.0.0 → 1.1.2

package/README.md

@@ -1,490 +1,661 @@
 # Express Storage
 
-A powerful, TypeScript-first file upload and storage management package for Express.js applications. Supports multiple cloud storage providers with a simple, unified API.
+**Secure, unified file uploads for Express.js — one API for all cloud providers.**
 
-## 🚀 Features
+Stop writing separate upload code for every storage provider. Express Storage gives you a single, secure interface that works with AWS S3, Google Cloud Storage, Azure Blob Storage, and local disk. Switch providers by changing one environment variable. No code changes required.
 
-- **TypeScript First**: Fully written in TypeScript with complete type definitions
-- **Multiple Storage Drivers**: Support for AWS S3, Google Cloud Storage, Oracle Cloud Infrastructure, and local storage
-- **Presigned URLs**: Generate secure, time-limited URLs for direct client uploads
-- **Flexible File Handling**: Support for single and multiple file uploads
-- **Automatic File Organization**: Files stored in month/year directories for local storage
-- **Unique File Naming**: Unix timestamp-based unique filenames with sanitization
-- **Environment-based Configuration**: Simple setup using environment variables
-- **Class-based API**: Clean, object-oriented interface with `StorageManager`
-- **Comprehensive Testing**: Full test coverage with Jest
-- **Error Handling**: Consistent error responses with detailed messages
+[![npm version](https://img.shields.io/npm/v/express-storage.svg)](https://www.npmjs.com/package/express-storage)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-## 📦 Installation
+---
+
+## Why Express Storage?
+
+Every application needs file uploads. And every application gets it wrong at first.
+
+You start with local storage, then realize you need S3 for production. You copy-paste upload code from Stack Overflow, then discover it's vulnerable to path traversal attacks. You build presigned URL support, then learn Azure handles it completely differently than AWS.
+
+**Express Storage solves these problems once, so you don't have to.**
+
+### What Makes It Different
+
+- **One API, Four Providers** — Write upload code once. Deploy to any cloud.
+- **Security Built In** — Path traversal prevention, filename sanitization, file validation, and null byte protection come standard.
+- **Presigned URLs Done Right** — Client-side uploads that bypass your server, with proper validation for each provider's quirks.
+- **TypeScript Native** — Full type safety with intelligent autocomplete. No `any` types hiding bugs.
+- **Zero Config Switching** — Change `FILE_DRIVER=local` to `FILE_DRIVER=s3` and you're done.
+
+---
+
+## Quick Start
+
+### Installation
 
 ```bash
 npm install express-storage
 ```
 
-## 🔧 Quick Setup
+### Basic Setup
+
+```typescript
+import express from "express";
+import multer from "multer";
+import { StorageManager } from "express-storage";
+
+const app = express();
+const upload = multer();
+const storage = new StorageManager();
+
+app.post("/upload", upload.single("file"), async (req, res) => {
+    const result = await storage.uploadFile(req.file, {
+        maxSize: 10 * 1024 * 1024, // 10MB limit
+        allowedMimeTypes: ["image/jpeg", "image/png", "application/pdf"],
+    });
 
-### 1. Environment Configuration
+    if (result.success) {
+        res.json({ url: result.fileUrl });
+    } else {
+        res.status(400).json({ error: result.error });
+    }
+});
+```
 
-Create a `.env` file in your project root:
+### Environment Configuration
+
+Create a `.env` file:
 
 ```env
-# Required: Choose your storage driver
+# Choose your storage provider
 FILE_DRIVER=local
 
-# For local storage (optional - defaults to public/express-storage)
-LOCAL_PATH=public/uploads
+# For local storage
+LOCAL_PATH=uploads
 
-# For cloud storage (AWS S3 example)
+# For AWS S3
 FILE_DRIVER=s3
 BUCKET_NAME=my-bucket
 AWS_REGION=us-east-1
-AWS_ACCESS_KEY=your-access-key
-AWS_SECRET_KEY=your-secret-key
+AWS_ACCESS_KEY=your-key
+AWS_SECRET_KEY=your-secret
+
+# For Google Cloud Storage
+FILE_DRIVER=gcs
+BUCKET_NAME=my-bucket
+GCS_PROJECT_ID=my-project
 
-# Optional: Presigned URL expiry (default: 600 seconds / 10 minutes)
-PRESIGNED_URL_EXPIRY=600
+# For Azure Blob Storage
+FILE_DRIVER=azure
+BUCKET_NAME=my-container
+AZURE_CONNECTION_STRING=your-connection-string
 ```
 
-### 2. Basic Usage
+That's it. Your upload code stays the same regardless of which provider you choose.
+
+---
+
+## Supported Storage Providers
+
+| Provider         | Direct Upload | Presigned URLs    | Best For                  |
+| ---------------- | ------------- | ----------------- | ------------------------- |
+| **Local Disk**   | `local`       | —                 | Development, small apps   |
+| **AWS S3**       | `s3`          | `s3-presigned`    | Most production apps      |
+| **Google Cloud** | `gcs`         | `gcs-presigned`   | GCP-hosted applications   |
+| **Azure Blob**   | `azure`       | `azure-presigned` | Azure-hosted applications |
+
+---
+
+## Security Features
+
+File uploads are one of the most exploited attack vectors in web applications. Express Storage protects you by default.
+
+### Path Traversal Prevention
+
+Attackers try filenames like `../../../etc/passwd` to escape your upload directory. We block this:
 
 ```typescript
-import express from 'express';
-import multer from 'multer';
-import { StorageManager } from 'express-storage';
+// These malicious filenames are automatically rejected
+"../secret.txt"; // Blocked: path traversal
+"..\\config.json"; // Blocked: Windows path traversal
+"file\0.txt"; // Blocked: null byte injection
+```
 
-const app = express();
-const upload = multer();
+### Automatic Filename Sanitization
 
-// Initialize storage manager
-const storage = new StorageManager();
+User-provided filenames can't be trusted. We transform them into safe, unique identifiers:
 
-// Single file upload
-app.post('/upload', upload.single('file'), async (req, res) => {
-  try {
-    const result = await storage.uploadFile(req.file!);
-    
-    if (result.success) {
-      res.json({
-        success: true,
-        fileName: result.fileName,
-        fileUrl: result.fileUrl
-      });
-    } else {
-      res.status(400).json({ success: false, error: result.error });
-    }
-  } catch (error) {
-    res.status(500).json({ success: false, error: 'Upload failed' });
-  }
+```
+User uploads: "My Photo (1).jpg"
+Stored as:    "1706123456789_a1b2c3d4e5_my_photo_1_.jpg"
+```
+
+The format `{timestamp}_{random}_{sanitized_name}` prevents collisions and removes dangerous characters.
+
+### File Validation
+
+Validate before processing. Reject before storing.
+
+```typescript
+await storage.uploadFile(file, {
+    maxSize: 5 * 1024 * 1024, // 5MB limit
+    allowedMimeTypes: ["image/jpeg", "image/png"],
+    allowedExtensions: [".jpg", ".png"],
 });
+```
+
+### Presigned URL Security
+
+For S3 and GCS, file constraints are enforced at the URL level — clients physically cannot upload the wrong file type or size. For Azure (which doesn't support URL-level constraints), we validate after upload and automatically delete invalid files.
+
+---
+
+## Presigned URLs: Client-Side Uploads
+
+Large files shouldn't flow through your server. Presigned URLs let clients upload directly to cloud storage.
+
+### The Flow
+
+```
+1. Client → Your Server: "I want to upload photo.jpg (2MB, image/jpeg)"
+2. Your Server → Client: "Here's a presigned URL, valid for 10 minutes"
+3. Client → Cloud Storage: Uploads directly (your server never touches the bytes)
+4. Client → Your Server: "Upload complete, please verify"
+5. Your Server: Confirms file exists, returns permanent URL
+```
+
+### Implementation
+
+```typescript
+// Step 1: Generate upload URL
+app.post("/upload/init", async (req, res) => {
+    const { fileName, contentType, fileSize } = req.body;
+
+    const result = await storage.generateUploadUrl(
+        fileName,
+        contentType,
+        fileSize,
+        "user-uploads", // Optional folder
+    );
 
-// Multiple files upload
-app.post('/upload-multiple', upload.array('files', 10), async (req, res) => {
-  try {
-    const results = await storage.uploadFiles(req.files as Express.Multer.File[]);
-    
-    const successful = results.filter(r => r.success);
-    const failed = results.filter(r => !r.success);
-    
     res.json({
-      success: true,
-      uploaded: successful.length,
-      failed: failed.length,
-      results
+        uploadUrl: result.uploadUrl,
+        reference: result.reference, // Save this for later
     });
-  } catch (error) {
-    res.status(500).json({ success: false, error: 'Upload failed' });
-  }
+});
+
+// Step 2: Confirm upload
+app.post("/upload/confirm", async (req, res) => {
+    const { reference, expectedContentType, expectedFileSize } = req.body;
+
+    const result = await storage.validateAndConfirmUpload(reference, {
+        expectedContentType,
+        expectedFileSize,
+    });
+
+    if (result.success) {
+        res.json({ viewUrl: result.viewUrl });
+    } else {
+        res.status(400).json({ error: result.error });
+    }
 });
 ```
 
-## 🗂️ Supported Storage Drivers
+### Provider-Specific Behavior
+
+| Provider | Content-Type Enforced | File Size Enforced | Post-Upload Validation |
+| -------- | --------------------- | ------------------ | ---------------------- |
+| S3       | At URL level          | At URL level       | Optional               |
+| GCS      | At URL level          | At URL level       | Optional               |
+| Azure    | **Not enforced**      | **Not enforced**   | **Required**           |
+
+For Azure, always call `validateAndConfirmUpload()` with expected values. Invalid files are automatically deleted.
 
-| Driver | Type | Description | Required Environment Variables |
-|--------|------|-------------|-------------------------------|
-| `local` | Direct | Local file system storage | `LOCAL_PATH` (optional) |
-| `s3` | Direct | AWS S3 direct upload | `BUCKET_NAME`, `AWS_REGION`, `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` |
-| `s3-presigned` | Presigned | AWS S3 presigned URLs | `BUCKET_NAME`, `AWS_REGION`, `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` |
-| `gcs` | Direct | Google Cloud Storage direct upload | `BUCKET_NAME`, `GCS_PROJECT_ID`, `GCS_CREDENTIALS` |
-| `gcs-presigned` | Presigned | Google Cloud Storage presigned URLs | `BUCKET_NAME`, `GCS_PROJECT_ID`, `GCS_CREDENTIALS` |
-| `oci` | Direct | Oracle Cloud Infrastructure direct upload | `BUCKET_NAME`, `OCI_REGION`, `OCI_CREDENTIALS` |
-| `oci-presigned` | Presigned | Oracle Cloud Infrastructure presigned URLs | `BUCKET_NAME`, `OCI_REGION`, `OCI_CREDENTIALS` |
+---
+
+## Large File Uploads
 
-## 📋 Environment Variables Reference
+For files larger than 100MB, we recommend using **presigned URLs** instead of direct server uploads. Here's why:
 
-### Core Configuration
-- `FILE_DRIVER` (required): Storage driver to use
-- `BUCKET_NAME`: Cloud storage bucket name
-- `LOCAL_PATH`: Local storage directory path (default: `public/express-storage`)
-- `PRESIGNED_URL_EXPIRY`: Presigned URL expiry in seconds (default: 600)
+### Memory Efficiency
 
-### AWS S3 Configuration
-- `AWS_REGION`: AWS region (e.g., `us-east-1`)
-- `AWS_ACCESS_KEY`: AWS access key ID
-- `AWS_SECRET_KEY`: AWS secret access key
+When you upload through your server, the entire file must be buffered in memory (or stored temporarily on disk). For a 500MB video file, that's 500MB of RAM per concurrent upload. With presigned URLs, the file goes directly to cloud storage — your server only handles small JSON requests.
 
-### Google Cloud Storage Configuration
-- `GCS_PROJECT_ID`: Google Cloud project ID
-- `GCS_CREDENTIALS`: Path to service account JSON file
+### Automatic Streaming
 
-### Oracle Cloud Infrastructure Configuration
-- `OCI_REGION`: OCI region (e.g., `us-ashburn-1`)
-- `OCI_CREDENTIALS`: Path to OCI credentials file
+For files that must go through your server, Express Storage automatically uses streaming uploads for files larger than 100MB:
 
-## 🔌 API Reference
+- **S3**: Uses multipart upload with 10MB chunks
+- **GCS**: Uses resumable uploads with streaming
+- **Azure**: Uses block upload with streaming
 
-### StorageManager Class
+This happens transparently — you don't need to change your code.
 
-The main class for managing file storage operations.
+### Recommended Approach for Large Files
 
-#### Constructor
 ```typescript
-const storage = new StorageManager();
+// Frontend: Request presigned URL
+const { uploadUrl, reference } = await fetch("/api/upload/init", {
+    method: "POST",
+    body: JSON.stringify({
+        fileName: "large-video.mp4",
+        contentType: "video/mp4",
+        fileSize: 524288000, // 500MB
+    }),
+}).then((r) => r.json());
+
+// Frontend: Upload directly to cloud (bypasses your server!)
+await fetch(uploadUrl, {
+    method: "PUT",
+    body: file,
+    headers: { "Content-Type": "video/mp4" },
+});
+
+// Frontend: Confirm upload
+await fetch("/api/upload/confirm", {
+    method: "POST",
+    body: JSON.stringify({ reference }),
+});
 ```
 
-#### Methods
+### Size Limits
 
-##### File Upload
-```typescript
-// Single file upload
-const result = await storage.uploadFile(file: Express.Multer.File): Promise<FileUploadResult>
+| Scenario                       | Recommended Limit | Reason                         |
+| ------------------------------ | ----------------- | ------------------------------ |
+| Direct upload (memory storage) | < 100MB           | Node.js memory constraints     |
+| Direct upload (disk storage)   | < 500MB           | Temp file management           |
+| Presigned URL upload           | 5GB+              | Limited only by cloud provider |
 
-// Multiple files upload
-const results = await storage.uploadFiles(files: Express.Multer.File[]): Promise<FileUploadResult[]>
+---
 
-// Generic upload (handles both single and multiple)
-const result = await storage.upload(input: FileInput): Promise<FileUploadResult | FileUploadResult[]>
-```
+## API Reference
 
-##### Presigned URLs
-```typescript
-// Generate upload URL
-const result = await storage.generateUploadUrl(fileName: string): Promise<PresignedUrlResult>
+### StorageManager
 
-// Generate view URL
-const result = await storage.generateViewUrl(fileName: string): Promise<PresignedUrlResult>
+The main class you'll interact with.
 
-// Generate multiple upload URLs
-const results = await storage.generateUploadUrls(fileNames: string[]): Promise<PresignedUrlResult[]>
+```typescript
+import { StorageManager } from "express-storage";
 
-// Generate multiple view URLs
-const results = await storage.generateViewUrls(fileNames: string[]): Promise<PresignedUrlResult[]>
+// Use environment variables
+const storage = new StorageManager();
+
+// Or configure programmatically
+const storage = new StorageManager({
+    driver: "s3",
+    credentials: {
+        bucketName: "my-bucket",
+        awsRegion: "us-east-1",
+        maxFileSize: 50 * 1024 * 1024, // 50MB
+    },
+    logger: console, // Optional: enable debug logging
+});
 ```
 
-##### File Deletion
+### File Upload Methods
+
 ```typescript
-// Delete single file
-const success = await storage.deleteFile(fileName: string): Promise<boolean>
+// Single file
+const result = await storage.uploadFile(file, validation?, options?);
 
-// Delete multiple files
-const results = await storage.deleteFiles(fileNames: string[]): Promise<boolean[]>
+// Multiple files (processed in parallel with concurrency limits)
+const results = await storage.uploadFiles(files, validation?, options?);
+
+// Generic upload (auto-detects single vs multiple)
+const result = await storage.upload(input, validation?, options?);
 ```
 
-##### Utility Methods
+### Presigned URL Methods
+
 ```typescript
-// Get current configuration
-const config = storage.getConfig(): StorageConfig
+// Generate upload URL with constraints
+const result = await storage.generateUploadUrl(fileName, contentType?, fileSize?, folder?);
+
+// Generate view URL for existing file
+const result = await storage.generateViewUrl(reference);
 
-// Get driver type
-const driverType = storage.getDriverType(): string
+// Validate upload (required for Azure, recommended for all)
+const result = await storage.validateAndConfirmUpload(reference, options?);
 
-// Check if presigned URLs are supported
-const isSupported = storage.isPresignedSupported(): boolean
+// Batch operations
+const results = await storage.generateUploadUrls(files, folder?);
+const results = await storage.generateViewUrls(references);
 ```
 
-### Static Methods
+### File Management
 
 ```typescript
-// Initialize with custom configuration
-const storage = StorageManager.initialize({
-  driver: 's3',
-  bucketName: 'my-bucket',
-  awsRegion: 'us-east-1'
-});
+// Delete single file
+const success = await storage.deleteFile(reference);
 
-// Get available drivers
-const drivers = StorageManager.getAvailableDrivers(): string[]
+// Delete multiple files
+const results = await storage.deleteFiles(references);
 
-// Clear driver cache
-StorageManager.clearCache(): void
+// List files with pagination
+const result = await storage.listFiles(prefix?, maxResults?, continuationToken?);
 ```
 
-### Convenience Functions
+### Upload Options
 
 ```typescript
-import { 
-  uploadFile, 
-  uploadFiles, 
-  generateUploadUrl, 
-  generateViewUrl,
-  deleteFile,
-  deleteFiles,
-  getStorageManager,
-  initializeStorageManager
-} from 'express-storage';
-
-// Use default storage manager
-const result = await uploadFile(file);
-const results = await uploadFiles(files);
-const urlResult = await generateUploadUrl('filename.jpg');
-const success = await deleteFile('filename.jpg');
-
-// Initialize custom storage manager
-const storage = initializeStorageManager({
-  driver: 'local',
-  localPath: 'uploads'
+interface UploadOptions {
+    contentType?: string; // Override detected type
+    metadata?: Record<string, string>; // Custom metadata
+    cacheControl?: string; // e.g., 'max-age=31536000'
+    contentDisposition?: string; // e.g., 'attachment; filename="doc.pdf"'
+}
+
+// Example: Upload with caching headers
+await storage.uploadFile(file, undefined, {
+    cacheControl: "public, max-age=31536000",
+    metadata: { uploadedBy: "user-123" },
 });
 ```
 
-## 📁 File Organization
+### Validation Options
 
-### Local Storage
-Files are organized in month/year directories:
-```
-public/express-storage/
-├── january/
-│   └── 2024/
-│       ├── 1703123456_image.jpg
-│       └── 1703123457_document.pdf
-├── february/
-│   └── 2024/
-│       └── 1705800000_video.mp4
-└── ...
+```typescript
+interface FileValidationOptions {
+    maxSize?: number; // Maximum file size in bytes
+    allowedMimeTypes?: string[]; // e.g., ['image/jpeg', 'image/png']
+    allowedExtensions?: string[]; // e.g., ['.jpg', '.png']
+}
 ```
 
-### Cloud Storage
-Files are stored with unique timestamps:
-```
-bucket/
-├── 1703123456_image.jpg
-├── 1703123457_document.pdf
-└── 1705800000_video.mp4
-```
+---
+
+## Environment Variables
+
+### Core Settings
+
+| Variable               | Description                         | Default                  |
+| ---------------------- | ----------------------------------- | ------------------------ |
+| `FILE_DRIVER`          | Storage driver to use               | `local`                  |
+| `BUCKET_NAME`          | Cloud storage bucket/container name | —                        |
+| `BUCKET_PATH`          | Default folder path within bucket   | `""` (root)              |
+| `LOCAL_PATH`           | Directory for local storage         | `public/express-storage` |
+| `PRESIGNED_URL_EXPIRY` | URL validity in seconds             | `600` (10 min)           |
+| `MAX_FILE_SIZE`        | Maximum upload size in bytes        | `5368709120` (5GB)       |
+
+### AWS S3
 
-## 🔐 Presigned URLs
+| Variable         | Description                                     |
+| ---------------- | ----------------------------------------------- |
+| `AWS_REGION`     | AWS region (e.g., `us-east-1`)                  |
+| `AWS_ACCESS_KEY` | Access key ID (optional if using IAM roles)     |
+| `AWS_SECRET_KEY` | Secret access key (optional if using IAM roles) |
 
-For cloud storage providers, you can generate presigned URLs for secure, direct client uploads:
+### Google Cloud Storage
+
+| Variable          | Description                                      |
+| ----------------- | ------------------------------------------------ |
+| `GCS_PROJECT_ID`  | Google Cloud project ID                          |
+| `GCS_CREDENTIALS` | Path to service account JSON (optional with ADC) |
+
+### Azure Blob Storage
+
+| Variable                  | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `AZURE_CONNECTION_STRING` | Full connection string (recommended)              |
+| `AZURE_ACCOUNT_NAME`      | Storage account name (alternative)                |
+| `AZURE_ACCOUNT_KEY`       | Storage account key (alternative)                 |
+
+**Note**: Azure uses `BUCKET_NAME` for the container name (same as S3/GCS).
+
+---
+
+## Utilities
+
+Express Storage includes battle-tested utilities you can use directly.
+
+### Retry with Exponential Backoff
 
 ```typescript
-// Generate upload URL for client-side upload
-const uploadResult = await storage.generateUploadUrl('my-file.jpg');
-if (uploadResult.success) {
-  // Client can use uploadResult.uploadUrl to upload directly
-  console.log(uploadResult.uploadUrl);
-}
+import { withRetry } from "express-storage";
 
-// Generate view URL for secure file access
-const viewResult = await storage.generateViewUrl('my-file.jpg');
-if (viewResult.success) {
-  // Client can use viewResult.viewUrl to view the file
-  console.log(viewResult.viewUrl);
-}
+const result = await withRetry(() => storage.uploadFile(file), {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    maxDelay: 10000,
+    exponentialBackoff: true,
+});
 ```
 
-## 🛠️ Advanced Usage Examples
+### File Type Helpers
 
-### Custom Configuration
+```typescript
+import {
+    isImageFile,
+    isDocumentFile,
+    getFileExtension,
+    formatFileSize,
+} from "express-storage";
+
+isImageFile("image/jpeg"); // true
+isDocumentFile("application/pdf"); // true
+getFileExtension("photo.jpg"); // '.jpg'
+formatFileSize(1048576); // '1 MB'
+```
+
+### Custom Logging
 
 ```typescript
-import { StorageManager } from 'express-storage';
-
-// Initialize with custom config
-const storage = StorageManager.initialize({
-  driver: 's3',
-  bucketName: 'my-bucket',
-  awsRegion: 'us-east-1',
-  awsAccessKey: process.env.AWS_ACCESS_KEY,
-  awsSecretKey: process.env.AWS_SECRET_KEY,
-  presignedUrlExpiry: 1800 // 30 minutes
-});
+import { StorageManager, Logger } from "express-storage";
+
+const logger: Logger = {
+    debug: (msg, ...args) => console.debug(`[Storage] ${msg}`, ...args),
+    info: (msg, ...args) => console.info(`[Storage] ${msg}`, ...args),
+    warn: (msg, ...args) => console.warn(`[Storage] ${msg}`, ...args),
+    error: (msg, ...args) => console.error(`[Storage] ${msg}`, ...args),
+};
+
+const storage = new StorageManager({ driver: "s3", logger });
 ```
 
-### Error Handling
+---
+
+## Real-World Examples
+
+### Profile Picture Upload
 
 ```typescript
-app.post('/upload', upload.single('file'), async (req, res) => {
-  try {
-    const result = await storage.uploadFile(req.file!);
-    
+app.post("/users/:id/avatar", upload.single("avatar"), async (req, res) => {
+    const result = await storage.uploadFile(
+        req.file,
+        {
+            maxSize: 2 * 1024 * 1024, // 2MB
+            allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
+        },
+        {
+            cacheControl: "public, max-age=86400",
+            metadata: { userId: req.params.id },
+        },
+    );
+
     if (result.success) {
-      res.json({
-        success: true,
-        fileName: result.fileName,
-        fileUrl: result.fileUrl
-      });
+        await db.users.update(req.params.id, { avatarUrl: result.fileUrl });
+        res.json({ avatarUrl: result.fileUrl });
     } else {
-      res.status(400).json({
-        success: false,
-        error: result.error
-      });
+        res.status(400).json({ error: result.error });
     }
-  } catch (error) {
-    res.status(500).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Unknown error'
-    });
-  }
 });
 ```
 
-### File Validation
+### Document Upload with Presigned URLs
 
 ```typescript
-app.post('/upload', upload.single('file'), async (req, res) => {
-  const file = req.file!;
-  
-  // Validate file size (5MB limit)
-  if (file.size > 5 * 1024 * 1024) {
-    return res.status(400).json({
-      success: false,
-      error: 'File size too large. Maximum 5MB allowed.'
+// Frontend requests upload URL
+app.post("/documents/request-upload", async (req, res) => {
+    const { fileName, fileSize } = req.body;
+
+    const result = await storage.generateUploadUrl(
+        fileName,
+        "application/pdf",
+        fileSize,
+        `documents/${req.user.id}`,
+    );
+
+    // Store pending upload in database
+    await db.documents.create({
+        reference: result.reference,
+        userId: req.user.id,
+        status: "pending",
     });
-  }
-  
-  // Validate file type
-  const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
-  if (!allowedTypes.includes(file.mimetype)) {
-    return res.status(400).json({
-      success: false,
-      error: 'Invalid file type. Only JPEG, PNG, and GIF allowed.'
+
+    res.json({
+        uploadUrl: result.uploadUrl,
+        reference: result.reference,
     });
-  }
-  
-  const result = await storage.uploadFile(file);
-  res.json(result);
 });
-```
 
-### Multiple File Upload with Progress
+// Frontend confirms upload complete
+app.post("/documents/confirm-upload", async (req, res) => {
+    const { reference } = req.body;
 
-```typescript
-app.post('/upload-multiple', upload.array('files', 10), async (req, res) => {
-  const files = req.files as Express.Multer.File[];
-  const results = await storage.uploadFiles(files);
-  
-  const summary = {
-    total: files.length,
-    successful: results.filter(r => r.success).length,
-    failed: results.filter(r => !r.success).length,
-    files: results.map((result, index) => ({
-      originalName: files[index].originalname,
-      success: result.success,
-      fileName: result.fileName,
-      fileUrl: result.fileUrl,
-      error: result.error
-    }))
-  };
-  
-  res.json(summary);
+    const result = await storage.validateAndConfirmUpload(reference, {
+        expectedContentType: "application/pdf",
+    });
+
+    if (result.success) {
+        await db.documents.update(
+            { reference },
+            {
+                status: "uploaded",
+                size: result.actualFileSize,
+            },
+        );
+        res.json({ success: true, viewUrl: result.viewUrl });
+    } else {
+        await db.documents.delete({ reference });
+        res.status(400).json({ error: result.error });
+    }
 });
 ```
 
-## 🧪 Testing
+### Bulk File Upload
 
-Run the test suite:
+```typescript
+app.post("/gallery/upload", upload.array("photos", 20), async (req, res) => {
+    const files = req.files as Express.Multer.File[];
 
-```bash
-# Run all tests
-npm test
+    const results = await storage.uploadFiles(files, {
+        maxSize: 10 * 1024 * 1024,
+        allowedMimeTypes: ["image/jpeg", "image/png"],
+    });
 
-# Run tests in watch mode
-npm run test:watch
+    const successful = results.filter((r) => r.success);
+    const failed = results.filter((r) => !r.success);
 
-# Run tests with coverage
-npm run test:coverage
+    res.json({
+        uploaded: successful.length,
+        failed: failed.length,
+        files: successful.map((r) => ({
+            fileName: r.fileName,
+            url: r.fileUrl,
+        })),
+        errors: failed.map((r) => r.error),
+    });
+});
 ```
 
-## 🛠️ Development
+---
 
-### Prerequisites
-- Node.js >= 16.0.0
-- TypeScript >= 5.1.6
+## Migrating Between Providers
 
-### Development Commands
+Moving from local development to cloud production? Or switching cloud providers? Here's how.
 
-```bash
-# Install dependencies
-npm install
+### Local to S3
 
-# Build the package
-npm run build
+```env
+# Before (development)
+FILE_DRIVER=local
+LOCAL_PATH=uploads
 
-# Development mode (watch for changes)
-npm run dev
+# After (production)
+FILE_DRIVER=s3
+BUCKET_NAME=my-app-uploads
+AWS_REGION=us-east-1
+```
 
-# Clean build directory
-npm run clean
+Your code stays exactly the same. Files uploaded before migration remain in their original location — you'll need to migrate existing files separately if needed.
 
-# Type checking
-npm run type-check
+### S3 to Azure
 
-# Linting
-npm run lint
-npm run lint:fix
+```env
+# Before
+FILE_DRIVER=s3
+BUCKET_NAME=my-bucket
+AWS_REGION=us-east-1
 
-# Formatting
-npm run format
+# After
+FILE_DRIVER=azure
+BUCKET_NAME=my-container
+AZURE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
 ```
 
-### Project Structure
+**Important**: If using presigned URLs, remember that Azure requires post-upload validation. Add `validateAndConfirmUpload()` calls to your confirmation endpoints.
 
-```
-express-storage/
-├── src/
-│   ├── types/
-│   │   └── storage.types.ts      # Type definitions
-│   ├── utils/
-│   │   ├── config.utils.ts       # Configuration utilities
-│   │   └── file.utils.ts         # File operation utilities
-│   ├── drivers/
-│   │   ├── base.driver.ts        # Abstract base driver
-│   │   ├── local.driver.ts       # Local storage driver
-│   │   ├── s3.driver.ts          # AWS S3 driver
-│   │   ├── gcs.driver.ts         # Google Cloud Storage driver
-│   │   └── oci.driver.ts         # Oracle Cloud Infrastructure driver
-│   ├── factory/
-│   │   └── driver.factory.ts     # Driver factory
-│   ├── storage-manager.ts        # Main StorageManager class
-│   └── index.ts                  # Package entry point
-├── tests/                        # Test files
-├── examples/                     # Usage examples
-├── dist/                         # Compiled output
-└── package.json
+---
+
+## TypeScript Support
+
+Express Storage is written in TypeScript and exports all types:
+
+```typescript
+import {
+    StorageManager,
+    StorageDriver,
+    FileUploadResult,
+    PresignedUrlResult,
+    FileValidationOptions,
+    UploadOptions,
+    Logger,
+} from "express-storage";
+
+// Full autocomplete and type checking
+const result: FileUploadResult = await storage.uploadFile(file);
+
+if (result.success) {
+    console.log(result.fileName); // TypeScript knows this exists
+    console.log(result.fileUrl); // TypeScript knows this exists
+}
 ```
 
-## 🤝 Contributing
+---
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+## Contributing
 
-### Development Guidelines
+Contributions are welcome! Please read our contributing guidelines before submitting a pull request.
 
-- Follow TypeScript best practices
-- Write comprehensive tests for new features
-- Update documentation for API changes
-- Ensure all tests pass before submitting PR
+```bash
+# Clone the repository
+git clone https://github.com/th3hero/express-storage.git
 
-## 📄 License
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+# Build for production
+npm run build
 
-## 🆘 Support
+# Run linting
+npm run lint
+```
 
-- **Issues**: Report bugs and feature requests on GitHub
-- **Documentation**: Check the examples folder for usage patterns
-- **Questions**: Open a GitHub discussion for questions
+---
+
+## License
+
+MIT License — use it however you want.
+
+---
 
-## 🔄 Changelog
+## Support
 
-### v1.0.0
-- Initial release
-- Support for local, S3, GCS, and OCI storage
-- Presigned URL generation
-- TypeScript-first implementation
-- Comprehensive test coverage
+- **Issues**: [GitHub Issues](https://github.com/th3hero/express-storage/issues)
+- **Author**: Alok Kumar ([@th3hero](https://github.com/th3hero))
 
 ---
 
-**Made with ❤️ for the Express.js community**
+**Made for developers who are tired of writing upload code from scratch.**