@ackplus/nest-file-storage 1.1.22 → 2.0.0

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

@@ -1,26 +1,13 @@
 /**
  * Example 8: Document Management System
- * 
- * This example demonstrates a complete document management system with
- * upload, download, listing, and deletion features.
+ *
+ * Upload, download, list, copy, and delete documents — using the injected service.
  */
 
-import { 
-  Controller, 
-  Get, 
-  Post, 
-  Delete,
-  Param,
-  UseInterceptors,
-  Body,
-  Res,
-  NotFoundException,
-  StreamableFile,
-} from '@nestjs/common';
+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;
@@ -31,235 +18,97 @@ interface Document {
   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
-  }
+  async create(_data: Partial<Document>): Promise<Document> { return {} as Document; }
+  async findAll(): Promise<Document[]> { return []; }
+  async findById(_id: number): Promise<Document> { return {} as Document; }
+  async delete(_id: number): Promise<void> {}
 }
 
 @Controller('documents')
 export class DocumentController {
-  constructor(private readonly documentService: DocumentService) {}
+  constructor(
+    private readonly documentService: DocumentService,
+    private readonly fileStorage: FileStorageService,
+  ) {}
 
-  /**
-   * Upload single document
-   */
   @Post('upload')
   @UseInterceptors(
-    FileStorageInterceptor('document', {
-      fileDist: () => 'documents',
-      mapToRequestBody: (file) => file, // Return full file object
-    })
+    FileStorageInterceptor('document', { fileDist: () => 'documents', mapToRequestBody: (file) => file })
   )
   async uploadDocument(@Body() body: any) {
-    const uploadedFile = body.document;
-
-    // Save document info to database
+    const file = body.document;
     const document = await this.documentService.create({
-      name: uploadedFile.originalName,
-      key: uploadedFile.key,
-      url: uploadedFile.url,
-      size: uploadedFile.size,
-      mimetype: uploadedFile.mimetype,
-      uploadedAt: new Date(),
+      name: file.originalName, key: file.key, url: file.url,
+      size: file.size, mimetype: file.mimetype, uploadedAt: new Date(),
     });
-
-    return {
-      message: 'Document uploaded successfully',
-      document,
-    };
+    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,
-    })
+    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
+  async uploadMany(@Body() body: any) {
     const documents = await Promise.all(
-      uploadedFiles.map(file =>
+      body.documents.map((file: any) =>
         this.documentService.create({
-          name: file.originalName,
-          key: file.key,
-          url: file.url,
-          size: file.size,
-          mimetype: file.mimetype,
-          uploadedAt: new Date(),
+          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,
-    };
+    return { message: `${documents.length} documents uploaded successfully`, documents };
   }
 
-  /**
-   * Get all documents
-   */
   @Get()
-  async getAllDocuments() {
-    const documents = await this.documentService.findAll();
-    return { documents };
+  async getAll() {
+    return { documents: await this.documentService.findAll() };
   }
 
-  /**
-   * Download document
-   */
   @Get(':id/download')
-  async downloadDocument(
-    @Param('id') id: number,
-    @Res({ passthrough: true }) res: Response,
-  ): Promise<StreamableFile> {
-    // Get document from database
+  async download(@Param('id') id: number, @Res({ passthrough: true }) res: Response): Promise<StreamableFile> {
     const document = await this.documentService.findById(id);
-    if (!document) {
-      throw new NotFoundException('Document not found');
-    }
+    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
+    const buffer = await this.fileStorage.getFile(document.key);
     res.set({
       'Content-Type': document.mimetype || 'application/octet-stream',
       'Content-Disposition': `attachment; filename="${document.name}"`,
-      'Content-Length': document.size,
     });
-
-    return new StreamableFile(fileBuffer);
+    return new StreamableFile(buffer);
   }
 
-  /**
-   * 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) {
+  async signedUrl(@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
-    };
+    if (!document) throw new NotFoundException('Document not found');
+    return { url: await this.fileStorage.getSignedUrl(document.key, { expiresIn: 3600 }), expiresIn: 3600 };
   }
 
-  /**
-   * Delete document
-   */
   @Delete(':id')
-  async deleteDocument(@Param('id') id: number) {
+  async remove(@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
+    if (!document) throw new NotFoundException('Document not found');
+    await this.fileStorage.deleteFile(document.key);
     await this.documentService.delete(id);
-
-    return {
-      message: 'Document deleted successfully',
-    };
+    return { message: 'Document deleted successfully' };
   }
 
-  /**
-   * Copy document
-   */
   @Post(':id/copy')
-  async copyDocument(@Param('id') id: number) {
+  async copy(@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`
-    );
+    if (!document) throw new NotFoundException('Document not found');
 
-    // Copy file in storage
-    const storage = await FileStorageService.getStorage();
-    const copiedFile = await storage.copyFile(document.key, newKey);
-
-    // Save copy to database
+    const newKey = document.key.replace(/(\.[^.]+)$/, `-copy-${Date.now()}$1`);
+    const copied = await this.fileStorage.copyFile(document.key, newKey);
     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(),
+      name: `${document.name} (Copy)`, key: copied.key, url: copied.url,
+      size: copied.size, mimetype: document.mimetype, uploadedAt: new Date(),
     });
-
-    return {
-      message: 'Document copied successfully',
-      document: copiedDocument,
-    };
+    return { message: 'Document copied successfully', document: copiedDocument };
   }
 }
-

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

@@ -1,175 +1,57 @@
 /**
  * Example 9: Dynamic Storage Selection
- * 
- * This example demonstrates how to dynamically choose storage provider
- * based on request, user preferences, or business logic.
+ *
+ * Choose the storage driver per request (by query, user plan, file type, …). Register the
+ * candidate drivers in the module, then select one by name on the route or in the service.
  */
 
-import { 
-  Controller, 
-  Post, 
-  UseInterceptors, 
-  Body,
-  Query,
-} from '@nestjs/common';
-import { 
-  FileStorageInterceptor, 
-  FileStorageEnum,
-} from '@ackplus/nest-file-storage';
+import { Controller, Post, UseInterceptors, Body, Injectable } from '@nestjs/common';
+import { FileStorageInterceptor, FileStorageService } from '@ackplus/nest-file-storage';
+
+// Assumes the module registered drivers named 'local' and 's3' (see examples 1–2).
 
 @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)
-   */
+  /** Force a specific registered driver for this route. */
   @Post('to-s3')
-  @UseInterceptors(
-    FileStorageInterceptor('file', {
-      storageType: FileStorageEnum.S3,
-    })
-  )
+  @UseInterceptors(FileStorageInterceptor('file', { driver: '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,
-    };
+    return { message: 'Uploaded to S3', fileKey: body.file };
   }
 
-  /**
-   * Upload to local storage explicitly
-   */
-  @Post('to-local')
+  /** Pick the driver dynamically from the request (e.g. premium users -> s3). */
+  @Post('smart')
   @UseInterceptors(
     FileStorageInterceptor('file', {
-      storageType: FileStorageEnum.LOCAL,
+      driver: (req) => (req.user?.plan === 'premium' ? 's3' : 'local'),
     })
   )
-  uploadToLocal(@Body() body: any) {
-    return {
-      message: 'File uploaded to local storage',
-      fileKey: body.file,
-    };
+  uploadSmart(@Body() body: any) {
+    return { message: 'Uploaded', fileKey: body.file };
   }
 }
 
 /**
- * Advanced: Custom logic for storage selection
+ * Programmatic selection in a service — resolve any registered driver by name.
  */
-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;
+  constructor(private readonly fileStorage: FileStorageService) {}
 
-    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);
+  /** Small files -> local, large files -> s3. */
+  async uploadBySize(buffer: Buffer, key: string) {
+    const driverName = buffer.length < 10 * 1024 * 1024 ? 'local' : 's3';
+    const driver = await this.fileStorage.getDriver(driverName);
+    return driver.putFile(buffer, key);
   }
 
-  /**
-   * 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);
+  /** Route by content type. */
+  async uploadByType(buffer: Buffer, key: string, mimetype: string) {
+    const driverName = mimetype.startsWith('video/') ? 'azure' : 's3';
+    const driver = await this.fileStorage.getDriver(driverName);
+    return driver.putFile(buffer, key, { contentType: mimetype });
   }
 }
 
+// Tip: for per-tenant routing, prefer the module's `tenant` config (see example 12) — it caches
+// the resolved driver per tenant instead of selecting on every request.

package/examples/README.md

@@ -1,122 +1,40 @@
 # Examples
 
-This directory contains comprehensive examples demonstrating various features and use cases of `@ackplus/nest-file-storage`.
+Runnable-style snippets for `@ackplus/nest-file-storage` (v2). Copy what you need into your app.
 
-## 📚 Available Examples
+> New to the library? Start with the [docs](https://ack-solutions.github.io/nest-file-storage/) or the package [README](../README.md). Upgrading from v1? See [MIGRATION.md](../MIGRATION.md).
 
-### Getting Started
+## Configuration
 
-1. **[Basic Local Storage](./1-basic-local-storage.example.ts)**
-   - Setting up local file storage
-   - Basic configuration
-   - Perfect for development
+1. **[Basic local storage](./1-basic-local-storage.example.ts)** — one `localDriver`, made the default.
+2. **[AWS S3](./2-s3-storage.example.ts)** — `s3Driver` via `forRootAsync` + `ConfigService`.
+3. **[Azure Blob](./3-azure-storage.example.ts)** — `azureDriver` via `forRootAsync` + `ConfigService`.
+5. **[Custom key generation](./5-custom-configuration.example.ts)** — default `fileName` / `fileDist` on the driver.
 
-2. **[AWS S3 Storage](./2-s3-storage.example.ts)**
-   - Configure AWS S3
-   - Async configuration with ConfigService
-   - Environment variables setup
+## Uploading
 
-3. **[Azure Blob Storage](./3-azure-storage.example.ts)**
-   - Configure Azure Blob Storage
-   - Connection string setup
-   - Container management
+4. **[Upload controller](./4-upload-controller.example.ts)** — single / array / fields, and declarative validation.
+7. **[User avatar](./7-user-avatar.example.ts)** — validation, old-file cleanup, DB update.
+8. **[Document management](./8-document-management.example.ts)** — upload, download, copy, delete.
 
-### Core Features
+## Programmatic & advanced
 
-4. **[File Upload Controller](./4-upload-controller.example.ts)**
-   - Single file upload
-   - Multiple files upload
-   - Multiple fields upload
-   - File validation
-   - Custom file mapping
+6. **[File service](./6-file-service.example.ts)** — the injectable `FileStorageService`.
+9. **[Dynamic storage](./9-dynamic-storage.example.ts)** — pick a driver per route/request by name.
+11. **[Custom driver](./11-custom-driver.example.ts)** — implement `StorageDriver` + `defineDriver`.
+12. **[Multi-tenant](./12-multi-tenant.example.ts)** — route storage per tenant (shared + prefix or dedicated).
 
-5. **[Custom Configuration](./5-custom-configuration.example.ts)**
-   - Custom file naming
-   - Custom directory structure
-   - File transformations
-   - Organized file storage
+## Testing
 
-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
+10. **[Testing](./10-testing.example.ts)** — a local driver against a temp dir, and an in-memory mock driver.
 
 ---
 
-**Need help?** Open an issue on [GitHub](https://github.com/ack-solutions/nest-file-storage/issues)
+**Key v2 changes you'll see in these examples**
+
+- Config is `{ default, drivers: { name: someDriver(...) } }` — not `{ storage, localConfig }`.
+- The service is **injected** (`constructor(private fileStorage: FileStorageService)`), not static.
+- Validation is **declarative** (`validation: { maxSize, allowedMimeTypes, ... }`), not thrown inside `fileName`.
+- Custom storage is a first-class `StorageDriver` registered with `defineDriver` — and works everywhere.
 
+Found an issue or want a new example? PRs welcome — open one on [GitHub](https://github.com/ack-solutions/nest-file-storage).