@ackplus/nest-file-storage 1.1.22 → 2.0.0

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

@@ -1,53 +1,40 @@
 /**
  * Example 4: File Upload Controller
- * 
- * This example demonstrates different file upload scenarios using the FileStorageInterceptor.
+ *
+ * Different upload shapes with the FileStorageInterceptor, plus declarative validation.
  */
 
-import { Controller, Post, UseInterceptors, Body, BadRequestException } from '@nestjs/common';
+import { Controller, Post, UseInterceptors, Body } from '@nestjs/common';
 import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
 
 @Controller('upload')
 export class UploadController {
   /**
-   * Single file upload
-   * POST /upload/single
-   * Form field: "file"
+   * 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
-    };
+    return { message: 'File uploaded successfully', fileKey: body.file };
   }
 
   /**
-   * Multiple files upload (same field name)
-   * POST /upload/multiple
-   * Form field: "files" (multiple files)
+   * Multiple files in one field — POST /upload/multiple, form field "files".
    */
   @Post('multiple')
   @UseInterceptors(
-    FileStorageInterceptor({
-      type: 'array',
-      fieldName: 'files',
-      maxCount: 10, // Maximum 10 files
-    })
+    FileStorageInterceptor({ type: 'array', fieldName: 'files', maxCount: 10 })
   )
   uploadMultiple(@Body() body: any) {
     return {
       message: 'Files uploaded successfully',
-      fileKeys: body.files, // Array of file keys
+      fileKeys: body.files, // string[]
       count: body.files.length,
     };
   }
 
   /**
-   * Multiple fields with different files
-   * POST /upload/fields
-   * Form fields: "avatar" (1 file), "photos" (up to 5 files)
+   * Multiple named fields — POST /upload/fields, fields "avatar" and "photos".
    */
   @Post('fields')
   @UseInterceptors(
@@ -62,56 +49,34 @@ export class UploadController {
   uploadFields(@Body() body: any) {
     return {
       message: 'Files uploaded successfully',
-      avatar: body.avatar, // Single file key
-      photos: body.photos, // Array of file keys
+      avatar: body.avatar, // string[] (always an array in 'fields' mode)
+      photos: body.photos, // string[]
     };
   }
 
   /**
-   * Upload with custom file information
-   * Returns full file object instead of just the key
+   * Return the full file object instead of just the key.
    */
   @Post('with-details')
-  @UseInterceptors(
-    FileStorageInterceptor('file', {
-      mapToRequestBody: (file) => {
-        // Return the full file object
-        return file;
-      },
-    })
-  )
+  @UseInterceptors(FileStorageInterceptor('file', { mapToRequestBody: (file) => file }))
   uploadWithDetails(@Body() body: any) {
-    return {
-      message: 'File uploaded successfully',
-      file: body.file, // Full file object with key, url, size, etc.
-    };
+    return { message: 'File uploaded successfully', file: body.file };
   }
 
   /**
-   * Upload with validation
+   * Declarative validation (v2) — type + size checks become typed 400s.
    */
   @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}`;
+      validation: {
+        allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+        maxSize: 5 * 1024 * 1024, // 5 MB
       },
+      fileName: (file) => `image-${Date.now()}.${file.originalname.split('.').pop()}`,
     })
   )
   uploadImage(@Body() body: any) {
-    return {
-      message: 'Image uploaded successfully',
-      imageKey: body.image,
-    };
+    return { message: 'Image uploaded successfully', imageKey: body.image };
   }
 }
-

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

@@ -1,56 +1,40 @@
 /**
- * Example 5: Custom Configuration
- * 
- * This example shows advanced configuration options including custom file naming,
- * directory structure, and file transformations.
+ * Example 5: Custom Key Generation
+ *
+ * Set default fileName/fileDist on the driver so every upload is organized the same way.
+ * Per-route overrides (on the interceptor) still take precedence.
  */
 
 import { Module } from '@nestjs/common';
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
+import { NestFileStorageModule, localDriver } 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,
-          };
-        },
+      default: 'local',
+      drivers: {
+        local: localDriver({
+          rootPath: './uploads',
+          baseUrl: 'http://localhost:3000/uploads',
+
+          // Default filename: uuid-originalname.ext
+          fileName: (file) => {
+            const ext = path.extname(file.originalname);
+            const name = path.basename(file.originalname, ext);
+            return `${uuidv4()}-${name}${ext}`;
+          },
+
+          // Default directory (relative): <type>/year/month/day
+          fileDist: (file) => {
+            const d = new Date();
+            const type = file.mimetype?.startsWith('image/') ? 'images' : 'documents';
+            const mm = String(d.getMonth() + 1).padStart(2, '0');
+            const dd = String(d.getDate()).padStart(2, '0');
+            return path.posix.join(type, String(d.getFullYear()), mm, dd);
+          },
+        }),
       },
     }),
   ],
@@ -58,18 +42,14 @@ import * as path from 'path';
 export class AppModule {}
 
 /**
- * Result directory structure:
- * uploads/
- *   ├── images/
- *   │   └── 2024/
- *   │       └── 01/
- *   │           └── 15/
- *   │               ├── uuid1-photo1.jpg
- *   │               └── uuid2-photo2.png
- *   └── documents/
- *       └── 2024/
- *           └── 01/
- *               └── 15/
- *                   └── uuid3-document.pdf
+ * Resulting keys:
+ *   images/2026/06/12/<uuid>-photo.jpg
+ *   documents/2026/06/12/<uuid>-report.pdf
+ *
+ * Note (v2): the v1 `transformUploadedFileObject` hook is removed. To reshape what lands in
+ * the controller body, use the interceptor's `mapToRequestBody`:
+ *
+ *   FileStorageInterceptor('file', {
+ *     mapToRequestBody: (file) => ({ key: file.key, url: file.url, size: file.size }),
+ *   })
  */
-

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

@@ -1,8 +1,7 @@
 /**
  * Example 6: File Service
- * 
- * This example demonstrates how to use FileStorageService to perform
- * file operations programmatically.
+ *
+ * Use the injectable FileStorageService to work with files programmatically.
  */
 
 import { Injectable, NotFoundException } from '@nestjs/common';
@@ -11,114 +10,58 @@ import * as fs from 'fs';
 
 @Injectable()
 export class FileService {
-  /**
-   * Get file content as Buffer
-   */
+  // v2: inject the service (no more static FileStorageService.getStorage()).
+  constructor(private readonly fileStorage: FileStorageService) {}
+
+  /** Read file content as a Buffer. */
   async getFile(key: string): Promise<Buffer> {
     try {
-      const storage = await FileStorageService.getStorage();
-      return await storage.getFile(key);
-    } catch (error) {
+      return await this.fileStorage.getFile(key);
+    } catch {
       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);
+  /** Delete a file. */
+  deleteFile(key: string): Promise<void> {
+    return this.fileStorage.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);
+  /** Copy a file to a new key. */
+  copyFile(oldKey: string, newKey: string) {
+    return this.fileStorage.copyFile(oldKey, newKey);
   }
 
-  /**
-   * Upload a file from local filesystem
-   */
+  /** Upload a file from the 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);
+    const buffer = await fs.promises.readFile(localPath);
+    return this.fileStorage.putFile(buffer, storageKey);
   }
 
-  /**
-   * 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);
+  /** Public URL for a key. */
+  getFileUrl(key: string): Promise<string> {
+    return this.fileStorage.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,
-    };
+  /** Time-limited signed URL (S3/Azure); falls back to the public URL otherwise. */
+  getSignedUrl(key: string, expiresIn = 3600): Promise<string> {
+    return this.fileStorage.getSignedUrl(key, { expiresIn });
   }
 
-  /**
-   * 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;
-    }
+  /** Upload from a Buffer. */
+  async uploadBuffer(buffer: Buffer, key: string, contentType?: string) {
+    const result = await this.fileStorage.putFile(buffer, key, { contentType });
+    return { key: result.key, url: result.url, size: result.size };
   }
 
-  /**
-   * Delete multiple files
-   */
-  async deleteMultipleFiles(keys: string[]): Promise<void> {
-    const storage = await FileStorageService.getStorage();
-    await Promise.all(keys.map(key => storage.deleteFile(key)));
+  /** Resolve a specific (non-default) driver by name. */
+  async uploadToS3(buffer: Buffer, key: string) {
+    const s3 = await this.fileStorage.getDriver('s3');
+    return s3.putFile(buffer, 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;
+  /** Delete several files. */
+  deleteMany(keys: string[]): Promise<void[]> {
+    return Promise.all(keys.map((key) => this.fileStorage.deleteFile(key)));
   }
 }
-

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

@@ -1,139 +1,84 @@
 /**
  * Example 7: User Avatar Upload
- * 
- * This example demonstrates a complete user avatar upload feature with
- * validation, old avatar cleanup, and database update.
+ *
+ * A complete avatar feature: declarative validation, old-avatar cleanup, and a DB update.
  */
 
-import { 
-  Controller, 
-  Post, 
-  UseInterceptors, 
-  Body, 
-  Request,
-  BadRequestException,
-  UseGuards,
-} from '@nestjs/common';
+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
+import { JwtAuthGuard } from './auth/jwt-auth.guard'; // your auth guard
 
-// User entity interface
 interface User {
   id: number;
   email: string;
-  avatarKey?: string;
-  avatarUrl?: string;
+  avatarKey?: string | null;
+  avatarUrl?: string | null;
 }
 
-// User service (example)
 class UserService {
-  async findById(id: number): Promise<User> {
-    // Your database query
-    return {} as User;
+  async findById(_id: number): Promise<User> {
+    return {} as User; // your DB query
   }
-
-  async updateAvatar(id: number, avatarKey: string, avatarUrl: string): Promise<User> {
-    // Your database update
-    return {} as User;
+  async updateAvatar(_id: number, _avatarKey: string | null, _avatarUrl: string | null): Promise<User> {
+    return {} as User; // your DB update
   }
 }
 
 @Controller('users')
 export class UserAvatarController {
-  constructor(private readonly userService: UserService) {}
+  // v2: inject the service.
+  constructor(
+    private readonly userService: UserService,
+    private readonly fileStorage: FileStorageService,
+  ) {}
 
   @Post('avatar')
-  @UseGuards(JwtAuthGuard) // Require authentication
+  @UseGuards(JwtAuthGuard)
   @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}`;
+      // Validation is declarative now — not thrown inside fileName.
+      validation: {
+        allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+        maxSize: 5 * 1024 * 1024, // 5 MB
       },
-      
-      fileDist: () => 'avatars', // Store in avatars directory
-      
-      // Return full file object
-      mapToRequestBody: (file) => file,
+      fileDist: () => 'avatars',
+      fileName: (file, req) => `avatar-${req!.user.id}-${Date.now()}.${file.originalname.split('.').pop()}`,
+      mapToRequestBody: (file) => file, // full UploadedFile
     })
   )
-  async uploadAvatar(@Body() body: any, @Request() req) {
+  async uploadAvatar(@Body() body: any, @Request() req: any) {
     const userId = req.user.id;
     const newAvatar = body.avatar;
 
-    // Get current user
     const user = await this.userService.findById(userId);
 
-    // Delete old avatar if exists
+    // Delete the old avatar if present (don't fail the request if cleanup fails).
     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);
+        await this.fileStorage.deleteFile(user.avatarKey);
+      } catch (err) {
+        console.error('Failed to delete old avatar:', err);
       }
     }
 
-    // Update user with new avatar
-    const updatedUser = await this.userService.updateAvatar(
-      userId,
-      newAvatar.key,
-      newAvatar.url
-    );
+    const updated = 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,
-      },
+      avatar: { key: newAvatar.key, url: newAvatar.url, size: newAvatar.size },
+      user: { id: updated.id, email: updated.email, avatarUrl: updated.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);
+  async deleteAvatar(@Request() req: any) {
+    const user = await this.userService.findById(req.user.id);
+    if (!user.avatarKey) throw new BadRequestException('No avatar to delete');
 
-    // Update database
-    await this.userService.updateAvatar(userId, null, null);
+    await this.fileStorage.deleteFile(user.avatarKey);
+    await this.userService.updateAvatar(req.user.id, null, null);
 
-    return {
-      message: 'Avatar deleted successfully',
-    };
+    return { message: 'Avatar deleted successfully' };
   }
 }
-