@ackplus/nest-file-storage 1.1.11 → 1.1.13

package/examples/1-basic-local-storage.example.ts

@@ -0,0 +1,22 @@
+/**
+ * Example 1: Basic Local Storage Configuration
+ * 
+ * This example shows how to set up local file storage with basic configuration.
+ */
+
+import { Module } from '@nestjs/common';
+import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+
+@Module({
+  imports: [
+    NestFileStorageModule.forRoot({
+      storage: FileStorageEnum.LOCAL,
+      localConfig: {
+        rootPath: './uploads', // Directory where files will be stored
+        baseUrl: 'http://localhost:3000/uploads', // Base URL for accessing files
+      },
+    }),
+  ],
+})
+export class AppModule {}
+

package/examples/10-testing.example.ts

@@ -0,0 +1,233 @@
+/**
+ * Example 10: Testing File Storage
+ * 
+ * This example demonstrates how to write tests for file storage functionality.
+ */
+
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import * as request from 'supertest';
+import * as fs from 'fs';
+import * as path from 'path';
+import { 
+  NestFileStorageModule, 
+  FileStorageService,
+  FileStorageEnum,
+} from '@ackplus/nest-file-storage';
+
+describe('File Storage (e2e)', () => {
+  let app: INestApplication;
+  let storage: any;
+  const testDir = './test-uploads';
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [
+        NestFileStorageModule.forRoot({
+          storage: FileStorageEnum.LOCAL,
+          localConfig: {
+            rootPath: testDir,
+            baseUrl: 'http://localhost:3000/test-uploads',
+          },
+        }),
+        // Import your controllers and services
+      ],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+
+    storage = await FileStorageService.getStorage();
+  });
+
+  afterAll(async () => {
+    // Cleanup test directory
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+    await app.close();
+  });
+
+  describe('File Upload', () => {
+    it('should upload a single file', async () => {
+      const response = await request(app.getHttpServer())
+        .post('/upload/single')
+        .attach('file', Buffer.from('test content'), 'test.txt')
+        .expect(201);
+
+      expect(response.body.fileKey).toBeDefined();
+      expect(response.body.message).toBe('File uploaded successfully');
+    });
+
+    it('should upload multiple files', async () => {
+      const response = await request(app.getHttpServer())
+        .post('/upload/multiple')
+        .attach('files', Buffer.from('test 1'), 'test1.txt')
+        .attach('files', Buffer.from('test 2'), 'test2.txt')
+        .expect(201);
+
+      expect(response.body.fileKeys).toHaveLength(2);
+    });
+
+    it('should reject invalid file types', async () => {
+      await request(app.getHttpServer())
+        .post('/upload/image')
+        .attach('image', Buffer.from('not an image'), 'test.txt')
+        .expect(400);
+    });
+  });
+
+  describe('FileStorageService', () => {
+    const testKey = 'test/file.txt';
+    const testContent = Buffer.from('Hello, World!');
+
+    it('should upload a file', async () => {
+      const result = await storage.putFile(testContent, testKey);
+
+      expect(result.key).toBe(testKey);
+      expect(result.size).toBe(testContent.length);
+      expect(result.url).toContain(testKey);
+    });
+
+    it('should retrieve a file', async () => {
+      await storage.putFile(testContent, testKey);
+      const retrieved = await storage.getFile(testKey);
+
+      expect(retrieved.toString()).toBe(testContent.toString());
+    });
+
+    it('should get file URL', () => {
+      const url = storage.getUrl(testKey);
+      expect(url).toContain(testKey);
+      expect(url).toContain('http://localhost:3000');
+    });
+
+    it('should delete a file', async () => {
+      await storage.putFile(testContent, testKey);
+      await storage.deleteFile(testKey);
+
+      await expect(storage.getFile(testKey)).rejects.toThrow();
+    });
+
+    it('should copy a file', async () => {
+      const sourceKey = 'test/source.txt';
+      const targetKey = 'test/target.txt';
+
+      await storage.putFile(testContent, sourceKey);
+      const result = await storage.copyFile(sourceKey, targetKey);
+
+      expect(result.key).toBe(targetKey);
+
+      const copiedContent = await storage.getFile(targetKey);
+      expect(copiedContent.toString()).toBe(testContent.toString());
+
+      // Cleanup
+      await storage.deleteFile(sourceKey);
+      await storage.deleteFile(targetKey);
+    });
+
+    it('should handle multiple files', async () => {
+      const files = [
+        { key: 'test/file1.txt', content: Buffer.from('Content 1') },
+        { key: 'test/file2.txt', content: Buffer.from('Content 2') },
+        { key: 'test/file3.txt', content: Buffer.from('Content 3') },
+      ];
+
+      // Upload multiple files
+      await Promise.all(
+        files.map(file => storage.putFile(file.content, file.key))
+      );
+
+      // Verify all files exist
+      const results = await Promise.all(
+        files.map(file => storage.getFile(file.key))
+      );
+
+      expect(results).toHaveLength(3);
+      expect(results[0].toString()).toBe('Content 1');
+
+      // Cleanup
+      await Promise.all(
+        files.map(file => storage.deleteFile(file.key))
+      );
+    });
+  });
+
+  describe('File Service', () => {
+    // Test your custom file service
+    it('should handle file operations', async () => {
+      // Your file service tests here
+    });
+  });
+});
+
+/**
+ * Unit Test Example
+ */
+describe('FileService', () => {
+  let service: any; // Your file service
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      imports: [
+        NestFileStorageModule.forRoot({
+          storage: FileStorageEnum.LOCAL,
+          localConfig: {
+            rootPath: './test-uploads',
+            baseUrl: 'http://localhost:3000/test-uploads',
+          },
+        }),
+      ],
+      providers: [/* Your FileService */],
+    }).compile();
+
+    service = module.get(/* Your FileService */);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  // Add more unit tests...
+});
+
+/**
+ * Mock Storage for Testing
+ */
+class MockStorage {
+  private files = new Map<string, Buffer>();
+
+  async putFile(content: Buffer, key: string) {
+    this.files.set(key, content);
+    return {
+      key,
+      url: `http://mock/${key}`,
+      size: content.length,
+      fileName: path.basename(key),
+      originalName: path.basename(key),
+      fullPath: key,
+    };
+  }
+
+  async getFile(key: string): Promise<Buffer> {
+    const file = this.files.get(key);
+    if (!file) {
+      throw new Error('File not found');
+    }
+    return file;
+  }
+
+  async deleteFile(key: string): Promise<void> {
+    this.files.delete(key);
+  }
+
+  async copyFile(oldKey: string, newKey: string) {
+    const file = await this.getFile(oldKey);
+    return await this.putFile(file, newKey);
+  }
+
+  getUrl(key: string): string {
+    return `http://mock/${key}`;
+  }
+}
+

package/examples/2-s3-storage.example.ts

@@ -0,0 +1,40 @@
+/**
+ * Example 2: AWS S3 Storage Configuration
+ * 
+ * This example shows how to configure AWS S3 for file storage.
+ * Requires: @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+ */
+
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    // Async configuration with ConfigService
+    NestFileStorageModule.forRootAsync({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => ({
+        storage: FileStorageEnum.S3,
+        s3Config: {
+          accessKeyId: configService.get('AWS_ACCESS_KEY_ID'),
+          secretAccessKey: configService.get('AWS_SECRET_ACCESS_KEY'),
+          region: configService.get('AWS_REGION', 'us-east-1'),
+          bucket: configService.get('AWS_BUCKET'),
+          cloudFrontUrl: configService.get('AWS_CLOUDFRONT_URL'), // Optional CloudFront URL
+        },
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+
+// Environment variables (.env file):
+// AWS_ACCESS_KEY_ID=your-access-key
+// AWS_SECRET_ACCESS_KEY=your-secret-key
+// AWS_REGION=us-east-1
+// AWS_BUCKET=your-bucket-name
+// AWS_CLOUDFRONT_URL=https://d1234567890.cloudfront.net (optional)
+

package/examples/3-azure-storage.example.ts

@@ -0,0 +1,35 @@
+/**
+ * Example 3: Azure Blob Storage Configuration
+ * 
+ * This example shows how to configure Azure Blob Storage.
+ * Requires: @azure/storage-blob
+ */
+
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    NestFileStorageModule.forRootAsync({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => ({
+        storage: FileStorageEnum.AZURE,
+        azureConfig: {
+          account: configService.get('AZURE_STORAGE_ACCOUNT'),
+          accountKey: configService.get('AZURE_STORAGE_KEY'),
+          container: configService.get('AZURE_CONTAINER', 'uploads'),
+        },
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+
+// Environment variables (.env file):
+// AZURE_STORAGE_ACCOUNT=your-account-name
+// AZURE_STORAGE_KEY=your-account-key
+// AZURE_CONTAINER=uploads
+

package/examples/4-upload-controller.example.ts

@@ -0,0 +1,117 @@
+/**
+ * Example 4: File Upload Controller
+ * 
+ * This example demonstrates different file upload scenarios using the FileStorageInterceptor.
+ */
+
+import { Controller, Post, UseInterceptors, Body, BadRequestException } from '@nestjs/common';
+import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
+
+@Controller('upload')
+export class UploadController {
+  /**
+   * Single file upload
+   * POST /upload/single
+   * Form field: "file"
+   */
+  @Post('single')
+  @UseInterceptors(FileStorageInterceptor('file'))
+  uploadSingle(@Body() body: any) {
+    return {
+      message: 'File uploaded successfully',
+      fileKey: body.file, // File key is automatically added to body
+    };
+  }
+
+  /**
+   * Multiple files upload (same field name)
+   * POST /upload/multiple
+   * Form field: "files" (multiple files)
+   */
+  @Post('multiple')
+  @UseInterceptors(
+    FileStorageInterceptor({
+      type: 'array',
+      fieldName: 'files',
+      maxCount: 10, // Maximum 10 files
+    })
+  )
+  uploadMultiple(@Body() body: any) {
+    return {
+      message: 'Files uploaded successfully',
+      fileKeys: body.files, // Array of file keys
+      count: body.files.length,
+    };
+  }
+
+  /**
+   * Multiple fields with different files
+   * POST /upload/fields
+   * Form fields: "avatar" (1 file), "photos" (up to 5 files)
+   */
+  @Post('fields')
+  @UseInterceptors(
+    FileStorageInterceptor({
+      type: 'fields',
+      fields: [
+        { name: 'avatar', maxCount: 1 },
+        { name: 'photos', maxCount: 5 },
+      ],
+    })
+  )
+  uploadFields(@Body() body: any) {
+    return {
+      message: 'Files uploaded successfully',
+      avatar: body.avatar, // Single file key
+      photos: body.photos, // Array of file keys
+    };
+  }
+
+  /**
+   * Upload with custom file information
+   * Returns full file object instead of just the key
+   */
+  @Post('with-details')
+  @UseInterceptors(
+    FileStorageInterceptor('file', {
+      mapToRequestBody: (file) => {
+        // Return the full file object
+        return file;
+      },
+    })
+  )
+  uploadWithDetails(@Body() body: any) {
+    return {
+      message: 'File uploaded successfully',
+      file: body.file, // Full file object with key, url, size, etc.
+    };
+  }
+
+  /**
+   * Upload with validation
+   */
+  @Post('image')
+  @UseInterceptors(
+    FileStorageInterceptor('image', {
+      fileName: (file) => {
+        // Validate file type
+        const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+        if (!allowedTypes.includes(file.mimetype)) {
+          throw new BadRequestException('Only image files are allowed');
+        }
+
+        // Generate filename with timestamp
+        const timestamp = Date.now();
+        const ext = file.originalname.split('.').pop();
+        return `image-${timestamp}.${ext}`;
+      },
+    })
+  )
+  uploadImage(@Body() body: any) {
+    return {
+      message: 'Image uploaded successfully',
+      imageKey: body.image,
+    };
+  }
+}
+

package/examples/5-custom-configuration.example.ts

@@ -0,0 +1,75 @@
+/**
+ * Example 5: Custom Configuration
+ * 
+ * This example shows advanced configuration options including custom file naming,
+ * directory structure, and file transformations.
+ */
+
+import { Module } from '@nestjs/common';
+import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+import { v4 as uuidv4 } from 'uuid';
+import * as path from 'path';
+
+@Module({
+  imports: [
+    NestFileStorageModule.forRoot({
+      storage: FileStorageEnum.LOCAL,
+      localConfig: {
+        rootPath: './uploads',
+        baseUrl: 'http://localhost:3000/uploads',
+        
+        // Custom file naming function
+        fileName: (file, req) => {
+          // Generate unique filename: uuid-originalname.ext
+          const uuid = uuidv4();
+          const ext = path.extname(file.originalname);
+          const name = path.basename(file.originalname, ext);
+          return `${uuid}-${name}${ext}`;
+        },
+        
+        // Custom directory structure: year/month/day
+        fileDist: (file, req) => {
+          const date = new Date();
+          const year = date.getFullYear();
+          const month = String(date.getMonth() + 1).padStart(2, '0');
+          const day = String(date.getDate()).padStart(2, '0');
+          
+          // Optional: organize by file type
+          const isImage = file.mimetype?.startsWith('image/');
+          const type = isImage ? 'images' : 'documents';
+          
+          return path.join(type, String(year), month, day);
+        },
+        
+        // Transform uploaded file object (return only necessary fields)
+        transformUploadedFileObject: (file) => {
+          return {
+            key: file.key,
+            url: file.url,
+            size: file.size,
+            mimetype: file.mimetype,
+            originalName: file.originalName,
+          };
+        },
+      },
+    }),
+  ],
+})
+export class AppModule {}
+
+/**
+ * Result directory structure:
+ * uploads/
+ *   ├── images/
+ *   │   └── 2024/
+ *   │       └── 01/
+ *   │           └── 15/
+ *   │               ├── uuid1-photo1.jpg
+ *   │               └── uuid2-photo2.png
+ *   └── documents/
+ *       └── 2024/
+ *           └── 01/
+ *               └── 15/
+ *                   └── uuid3-document.pdf
+ */
+

package/examples/6-file-service.example.ts

@@ -0,0 +1,124 @@
+/**
+ * Example 6: File Service
+ * 
+ * This example demonstrates how to use FileStorageService to perform
+ * file operations programmatically.
+ */
+
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { FileStorageService } from '@ackplus/nest-file-storage';
+import * as fs from 'fs';
+
+@Injectable()
+export class FileService {
+  /**
+   * Get file content as Buffer
+   */
+  async getFile(key: string): Promise<Buffer> {
+    try {
+      const storage = await FileStorageService.getStorage();
+      return await storage.getFile(key);
+    } catch (error) {
+      throw new NotFoundException(`File not found: ${key}`);
+    }
+  }
+
+  /**
+   * Delete a file
+   */
+  async deleteFile(key: string): Promise<void> {
+    const storage = await FileStorageService.getStorage();
+    await storage.deleteFile(key);
+  }
+
+  /**
+   * Copy a file to a new location
+   */
+  async copyFile(oldKey: string, newKey: string) {
+    const storage = await FileStorageService.getStorage();
+    return await storage.copyFile(oldKey, newKey);
+  }
+
+  /**
+   * Upload a file from local filesystem
+   */
+  async uploadFromLocal(localPath: string, storageKey: string) {
+    const fileBuffer = await fs.promises.readFile(localPath);
+    const storage = await FileStorageService.getStorage();
+    return await storage.putFile(fileBuffer, storageKey);
+  }
+
+  /**
+   * Get public URL for a file
+   */
+  async getFileUrl(key: string): Promise<string> {
+    const storage = await FileStorageService.getStorage();
+    return storage.getUrl(key);
+  }
+
+  /**
+   * Get signed URL (for S3)
+   * Useful for temporary access to private files
+   */
+  async getSignedUrl(key: string, expiresIn: number = 3600): Promise<string> {
+    const storage = await FileStorageService.getStorage();
+    
+    // Check if storage supports signed URLs (S3)
+    if ('getSignedUrl' in storage) {
+      return await storage.getSignedUrl(key, { expiresIn });
+    }
+    
+    // Fallback to regular URL for other storage types
+    return storage.getUrl(key);
+  }
+
+  /**
+   * Upload file from Buffer
+   */
+  async uploadBuffer(buffer: Buffer, key: string, mimetype?: string) {
+    const storage = await FileStorageService.getStorage();
+    const result = await storage.putFile(buffer, key);
+    
+    return {
+      key: result.key,
+      url: result.url,
+      size: result.size,
+      mimetype,
+    };
+  }
+
+  /**
+   * Check if file exists
+   */
+  async fileExists(key: string): Promise<boolean> {
+    try {
+      const storage = await FileStorageService.getStorage();
+      await storage.getFile(key);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Delete multiple files
+   */
+  async deleteMultipleFiles(keys: string[]): Promise<void> {
+    const storage = await FileStorageService.getStorage();
+    await Promise.all(keys.map(key => storage.deleteFile(key)));
+  }
+
+  /**
+   * Get file path (Local storage only)
+   */
+  async getFilePath(key: string): Promise<string | undefined> {
+    const storage = await FileStorageService.getStorage();
+    
+    if ('path' in storage) {
+      return storage.path(key);
+    }
+    
+    return undefined;
+  }
+}
+