@ackplus/nest-file-storage 1.1.11 → 1.1.13

package/examples/7-user-avatar.example.ts

@@ -0,0 +1,139 @@
+/**
+ * Example 7: User Avatar Upload
+ * 
+ * This example demonstrates a complete user avatar upload feature with
+ * validation, old avatar cleanup, and database update.
+ */
+
+import { 
+  Controller, 
+  Post, 
+  UseInterceptors, 
+  Body, 
+  Request,
+  BadRequestException,
+  UseGuards,
+} from '@nestjs/common';
+import { FileStorageInterceptor, FileStorageService } from '@ackplus/nest-file-storage';
+import { JwtAuthGuard } from './auth/jwt-auth.guard'; // Your auth guard
+
+// User entity interface
+interface User {
+  id: number;
+  email: string;
+  avatarKey?: string;
+  avatarUrl?: string;
+}
+
+// User service (example)
+class UserService {
+  async findById(id: number): Promise<User> {
+    // Your database query
+    return {} as User;
+  }
+
+  async updateAvatar(id: number, avatarKey: string, avatarUrl: string): Promise<User> {
+    // Your database update
+    return {} as User;
+  }
+}
+
+@Controller('users')
+export class UserAvatarController {
+  constructor(private readonly userService: UserService) {}
+
+  @Post('avatar')
+  @UseGuards(JwtAuthGuard) // Require authentication
+  @UseInterceptors(
+    FileStorageInterceptor('avatar', {
+      fileName: (file, req) => {
+        // Validate file type
+        const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+        if (!allowedTypes.includes(file.mimetype)) {
+          throw new BadRequestException(
+            'Invalid file type. Only JPEG, PNG, GIF, and WebP are allowed.'
+          );
+        }
+
+        // Validate file size (5MB max)
+        const maxSize = 5 * 1024 * 1024; // 5MB
+        if (file.size > maxSize) {
+          throw new BadRequestException('File size must be less than 5MB');
+        }
+
+        // Generate filename: avatar-{userId}-{timestamp}.{ext}
+        const userId = req.user.id;
+        const timestamp = Date.now();
+        const ext = file.originalname.split('.').pop();
+        return `avatar-${userId}-${timestamp}.${ext}`;
+      },
+      
+      fileDist: () => 'avatars', // Store in avatars directory
+      
+      // Return full file object
+      mapToRequestBody: (file) => file,
+    })
+  )
+  async uploadAvatar(@Body() body: any, @Request() req) {
+    const userId = req.user.id;
+    const newAvatar = body.avatar;
+
+    // Get current user
+    const user = await this.userService.findById(userId);
+
+    // Delete old avatar if exists
+    if (user.avatarKey) {
+      try {
+        const storage = await FileStorageService.getStorage();
+        await storage.deleteFile(user.avatarKey);
+      } catch (error) {
+        // Log error but don't fail the upload
+        console.error('Failed to delete old avatar:', error);
+      }
+    }
+
+    // Update user with new avatar
+    const updatedUser = await this.userService.updateAvatar(
+      userId,
+      newAvatar.key,
+      newAvatar.url
+    );
+
+    return {
+      message: 'Avatar updated successfully',
+      avatar: {
+        key: newAvatar.key,
+        url: newAvatar.url,
+        size: newAvatar.size,
+      },
+      user: {
+        id: updatedUser.id,
+        email: updatedUser.email,
+        avatarUrl: updatedUser.avatarUrl,
+      },
+    };
+  }
+
+  @Post('avatar/delete')
+  @UseGuards(JwtAuthGuard)
+  async deleteAvatar(@Request() req) {
+    const userId = req.user.id;
+    const user = await this.userService.findById(userId);
+
+    if (!user.avatarKey) {
+      throw new BadRequestException('No avatar to delete');
+    }
+
+    // Delete from storage
+    const storage = await FileStorageService.getStorage();
+    await storage.deleteFile(user.avatarKey);
+
+    // Update database
+    await this.userService.updateAvatar(userId, null, null);
+
+    return {
+      message: 'Avatar deleted successfully',
+    };
+  }
+}
+

package/examples/8-document-management.example.ts

@@ -0,0 +1,265 @@
+/**
+ * Example 8: Document Management System
+ * 
+ * This example demonstrates a complete document management system with
+ * upload, download, listing, and deletion features.
+ */
+
+import { 
+  Controller, 
+  Get, 
+  Post, 
+  Delete,
+  Param,
+  UseInterceptors,
+  Body,
+  Res,
+  NotFoundException,
+  StreamableFile,
+} from '@nestjs/common';
+import { Response } from 'express';
+import { FileStorageInterceptor, FileStorageService } from '@ackplus/nest-file-storage';
+
+// Document entity interface
+interface Document {
+  id: number;
+  name: string;
+  key: string;
+  url: string;
+  size: number;
+  mimetype: string;
+  uploadedAt: Date;
+}
+
+// Document service (example)
+class DocumentService {
+  async create(data: Partial<Document>): Promise<Document> {
+    // Save to database
+    return {} as Document;
+  }
+
+  async findAll(): Promise<Document[]> {
+    // Get all documents from database
+    return [] as Document[];
+  }
+
+  async findById(id: number): Promise<Document> {
+    // Get document from database
+    return {} as Document;
+  }
+
+  async delete(id: number): Promise<void> {
+    // Delete from database
+  }
+}
+
+@Controller('documents')
+export class DocumentController {
+  constructor(private readonly documentService: DocumentService) {}
+
+  /**
+   * Upload single document
+   */
+  @Post('upload')
+  @UseInterceptors(
+    FileStorageInterceptor('document', {
+      fileDist: () => 'documents',
+      mapToRequestBody: (file) => file, // Return full file object
+    })
+  )
+  async uploadDocument(@Body() body: any) {
+    const uploadedFile = body.document;
+
+    // Save document info to database
+    const document = await this.documentService.create({
+      name: uploadedFile.originalName,
+      key: uploadedFile.key,
+      url: uploadedFile.url,
+      size: uploadedFile.size,
+      mimetype: uploadedFile.mimetype,
+      uploadedAt: new Date(),
+    });
+
+    return {
+      message: 'Document uploaded successfully',
+      document,
+    };
+  }
+
+  /**
+   * Upload multiple documents
+   */
+  @Post('upload/multiple')
+  @UseInterceptors(
+    FileStorageInterceptor({
+      type: 'array',
+      fieldName: 'documents',
+      maxCount: 10,
+    }, {
+      fileDist: () => 'documents',
+      mapToRequestBody: (files) => files,
+    })
+  )
+  async uploadMultipleDocuments(@Body() body: any) {
+    const uploadedFiles = body.documents;
+
+    // Save all documents to database
+    const documents = await Promise.all(
+      uploadedFiles.map(file =>
+        this.documentService.create({
+          name: file.originalName,
+          key: file.key,
+          url: file.url,
+          size: file.size,
+          mimetype: file.mimetype,
+          uploadedAt: new Date(),
+        })
+      )
+    );
+
+    return {
+      message: `${documents.length} documents uploaded successfully`,
+      documents,
+    };
+  }
+
+  /**
+   * Get all documents
+   */
+  @Get()
+  async getAllDocuments() {
+    const documents = await this.documentService.findAll();
+    return { documents };
+  }
+
+  /**
+   * Download document
+   */
+  @Get(':id/download')
+  async downloadDocument(
+    @Param('id') id: number,
+    @Res({ passthrough: true }) res: Response,
+  ): Promise<StreamableFile> {
+    // Get document from database
+    const document = await this.documentService.findById(id);
+    if (!document) {
+      throw new NotFoundException('Document not found');
+    }
+
+    // Get file from storage
+    const storage = await FileStorageService.getStorage();
+    const fileBuffer = await storage.getFile(document.key);
+
+    // Set response headers
+    res.set({
+      'Content-Type': document.mimetype || 'application/octet-stream',
+      'Content-Disposition': `attachment; filename="${document.name}"`,
+      'Content-Length': document.size,
+    });
+
+    return new StreamableFile(fileBuffer);
+  }
+
+  /**
+   * Get document URL (for preview or direct access)
+   */
+  @Get(':id/url')
+  async getDocumentUrl(@Param('id') id: number) {
+    const document = await this.documentService.findById(id);
+    if (!document) {
+      throw new NotFoundException('Document not found');
+    }
+
+    return {
+      url: document.url,
+      expiresIn: null, // Permanent URL
+    };
+  }
+
+  /**
+   * Get signed URL (for S3, temporary access)
+   */
+  @Get(':id/signed-url')
+  async getSignedUrl(@Param('id') id: number) {
+    const document = await this.documentService.findById(id);
+    if (!document) {
+      throw new NotFoundException('Document not found');
+    }
+
+    const storage = await FileStorageService.getStorage();
+    
+    let url: string;
+    if ('getSignedUrl' in storage) {
+      // Generate signed URL (valid for 1 hour)
+      url = await storage.getSignedUrl(document.key, { expiresIn: 3600 });
+    } else {
+      // Fallback to regular URL
+      url = storage.getUrl(document.key);
+    }
+
+    return {
+      url,
+      expiresIn: 3600, // seconds
+    };
+  }
+
+  /**
+   * Delete document
+   */
+  @Delete(':id')
+  async deleteDocument(@Param('id') id: number) {
+    const document = await this.documentService.findById(id);
+    if (!document) {
+      throw new NotFoundException('Document not found');
+    }
+
+    // Delete from storage
+    const storage = await FileStorageService.getStorage();
+    await storage.deleteFile(document.key);
+
+    // Delete from database
+    await this.documentService.delete(id);
+
+    return {
+      message: 'Document deleted successfully',
+    };
+  }
+
+  /**
+   * Copy document
+   */
+  @Post(':id/copy')
+  async copyDocument(@Param('id') id: number) {
+    const document = await this.documentService.findById(id);
+    if (!document) {
+      throw new NotFoundException('Document not found');
+    }
+
+    // Generate new key for the copy
+    const timestamp = Date.now();
+    const newKey = document.key.replace(
+      /(\.[^.]+)$/,
+      `-copy-${timestamp}$1`
+    );
+
+    // Copy file in storage
+    const storage = await FileStorageService.getStorage();
+    const copiedFile = await storage.copyFile(document.key, newKey);
+
+    // Save copy to database
+    const copiedDocument = await this.documentService.create({
+      name: `${document.name} (Copy)`,
+      key: copiedFile.key,
+      url: copiedFile.url,
+      size: copiedFile.size,
+      mimetype: document.mimetype,
+      uploadedAt: new Date(),
+    });
+
+    return {
+      message: 'Document copied successfully',
+      document: copiedDocument,
+    };
+  }
+}
+

package/examples/9-dynamic-storage.example.ts

@@ -0,0 +1,175 @@
+/**
+ * Example 9: Dynamic Storage Selection
+ * 
+ * This example demonstrates how to dynamically choose storage provider
+ * based on request, user preferences, or business logic.
+ */
+
+import { 
+  Controller, 
+  Post, 
+  UseInterceptors, 
+  Body,
+  Query,
+} from '@nestjs/common';
+import { 
+  FileStorageInterceptor, 
+  FileStorageEnum,
+} from '@ackplus/nest-file-storage';
+
+@Controller('upload')
+export class DynamicStorageController {
+  /**
+   * Upload to specific storage based on query parameter
+   * Example: POST /upload/dynamic?storage=s3
+   */
+  @Post('dynamic')
+  @UseInterceptors(
+    FileStorageInterceptor('file', {
+      // Storage type will be determined at runtime
+    })
+  )
+  uploadDynamic(
+    @Body() body: any,
+    @Query('storage') storage: string,
+  ) {
+    return {
+      message: 'File uploaded successfully',
+      storage,
+      fileKey: body.file,
+    };
+  }
+
+  /**
+   * Upload large files to S3, small files to local storage
+   */
+  @Post('smart')
+  @UseInterceptors(
+    FileStorageInterceptor('file', {
+      fileName: (file, req) => {
+        const timestamp = Date.now();
+        const ext = file.originalname.split('.').pop();
+        return `${timestamp}-${file.originalname}`;
+      },
+      // Determine storage based on file size
+      storageType: FileStorageEnum.LOCAL, // Can be overridden
+    })
+  )
+  uploadSmart(@Body() body: any) {
+    return {
+      message: 'File uploaded successfully',
+      fileKey: body.file,
+    };
+  }
+
+  /**
+   * Upload to S3 explicitly (override default storage)
+   */
+  @Post('to-s3')
+  @UseInterceptors(
+    FileStorageInterceptor('file', {
+      storageType: FileStorageEnum.S3,
+    })
+  )
+  uploadToS3(@Body() body: any) {
+    return {
+      message: 'File uploaded to S3',
+      fileKey: body.file,
+    };
+  }
+
+  /**
+   * Upload to Azure explicitly
+   */
+  @Post('to-azure')
+  @UseInterceptors(
+    FileStorageInterceptor('file', {
+      storageType: FileStorageEnum.AZURE,
+    })
+  )
+  uploadToAzure(@Body() body: any) {
+    return {
+      message: 'File uploaded to Azure',
+      fileKey: body.file,
+    };
+  }
+
+  /**
+   * Upload to local storage explicitly
+   */
+  @Post('to-local')
+  @UseInterceptors(
+    FileStorageInterceptor('file', {
+      storageType: FileStorageEnum.LOCAL,
+    })
+  )
+  uploadToLocal(@Body() body: any) {
+    return {
+      message: 'File uploaded to local storage',
+      fileKey: body.file,
+    };
+  }
+}
+
+/**
+ * Advanced: Custom logic for storage selection
+ */
+import { Injectable } from '@nestjs/common';
+import { FileStorageService } from '@ackplus/nest-file-storage';
+
+@Injectable()
+export class SmartStorageService {
+  /**
+   * Select storage based on file size
+   */
+  async uploadFile(buffer: Buffer, fileName: string, fileSize: number) {
+    // Use local storage for small files (< 10MB)
+    // Use S3 for large files
+    const storageType = fileSize < 10 * 1024 * 1024 
+      ? FileStorageEnum.LOCAL 
+      : FileStorageEnum.S3;
+
+    const storage = await FileStorageService.getStorage(storageType);
+    return await storage.putFile(buffer, fileName);
+  }
+
+  /**
+   * Select storage based on file type
+   */
+  async uploadByType(buffer: Buffer, fileName: string, mimetype: string) {
+    let storageType: FileStorageEnum;
+
+    if (mimetype.startsWith('image/')) {
+      // Store images on S3 with CloudFront CDN
+      storageType = FileStorageEnum.S3;
+    } else if (mimetype.startsWith('video/')) {
+      // Store videos on Azure
+      storageType = FileStorageEnum.AZURE;
+    } else {
+      // Store other files locally
+      storageType = FileStorageEnum.LOCAL;
+    }
+
+    const storage = await FileStorageService.getStorage(storageType);
+    return await storage.putFile(buffer, fileName);
+  }
+
+  /**
+   * Select storage based on user plan
+   */
+  async uploadForUser(
+    buffer: Buffer, 
+    fileName: string, 
+    userPlan: 'free' | 'premium'
+  ) {
+    // Free users: local storage
+    // Premium users: S3 with better performance
+    const storageType = userPlan === 'premium' 
+      ? FileStorageEnum.S3 
+      : FileStorageEnum.LOCAL;
+
+    const storage = await FileStorageService.getStorage(storageType);
+    return await storage.putFile(buffer, fileName);
+  }
+}
+

package/examples/README.md

@@ -0,0 +1,122 @@
+# Examples
+
+This directory contains comprehensive examples demonstrating various features and use cases of `@ackplus/nest-file-storage`.
+
+## 📚 Available Examples
+
+### Getting Started
+
+1. **[Basic Local Storage](./1-basic-local-storage.example.ts)**
+   - Setting up local file storage
+   - Basic configuration
+   - Perfect for development
+
+2. **[AWS S3 Storage](./2-s3-storage.example.ts)**
+   - Configure AWS S3
+   - Async configuration with ConfigService
+   - Environment variables setup
+
+3. **[Azure Blob Storage](./3-azure-storage.example.ts)**
+   - Configure Azure Blob Storage
+   - Connection string setup
+   - Container management
+
+### Core Features
+
+4. **[File Upload Controller](./4-upload-controller.example.ts)**
+   - Single file upload
+   - Multiple files upload
+   - Multiple fields upload
+   - File validation
+   - Custom file mapping
+
+5. **[Custom Configuration](./5-custom-configuration.example.ts)**
+   - Custom file naming
+   - Custom directory structure
+   - File transformations
+   - Organized file storage
+
+6. **[File Service](./6-file-service.example.ts)**
+   - File operations (get, delete, copy)
+   - Upload from local filesystem
+   - Get public URLs
+   - Generate signed URLs (S3)
+   - Batch operations
+
+### Real-World Use Cases
+
+7. **[User Avatar Upload](./7-user-avatar.example.ts)**
+   - Complete avatar upload feature
+   - File validation
+   - Old file cleanup
+   - Database integration
+
+8. **[Document Management System](./8-document-management.example.ts)**
+   - Upload/download documents
+   - Document listing
+   - File copying
+   - Signed URLs for secure access
+
+9. **[Dynamic Storage Selection](./9-dynamic-storage.example.ts)**
+   - Switch storage per request
+   - Storage selection by file size
+   - Storage selection by file type
+   - Storage selection by user plan
+
+10. **[Testing](./10-testing.example.ts)**
+    - E2E testing examples
+    - Unit testing
+    - Mock storage implementation
+    - Test setup and cleanup
+
+## 🚀 How to Use These Examples
+
+### 1. Copy Example Code
+
+Simply copy the relevant example code to your project:
+
+```bash
+# Copy specific example
+cp examples/1-basic-local-storage.example.ts src/config/storage.config.ts
+```
+
+### 2. Modify for Your Needs
+
+Each example is well-documented with comments explaining:
+- What the code does
+- Configuration options
+- Environment variables needed
+- Expected behavior
+
+### 3. Run Your Application
+
+```bash
+npm run start:dev
+```
+
+## 💡 Tips
+
+- **Start Simple**: Begin with Example 1 (Local Storage) for development
+- **Environment Variables**: Use Example 2 or 3 for production with proper secrets management
+- **Validation**: See Example 4 for file type and size validation
+- **Custom Logic**: Examples 5-9 show advanced customization options
+- **Testing**: Example 10 provides complete testing setup
+
+## 📖 More Resources
+
+- **[Main Documentation](../README.md)** - Complete feature guide
+- **[GitHub Issues](https://github.com/ack-solutions/nest-file-storage/issues)** - Report issues or request features
+- **[NPM Package](https://www.npmjs.com/package/@ackplus/nest-file-storage)** - Published package
+
+## 🤝 Contributing
+
+Found a bug in an example? Want to add a new example? PRs are welcome!
+
+1. Add your example file: `[number]-[name].example.ts`
+2. Add it to this README
+3. Submit a PR
+
+---
+
+**Need help?** Open an issue on [GitHub](https://github.com/ack-solutions/nest-file-storage/issues)
+