@flusys/nestjs-storage 1.0.0-beta → 1.0.0

package/README.md

@@ -9,8 +9,10 @@ This comprehensive guide covers the storage package - flexible file storage with
 
 - [Overview](#overview)
 - [Installation](#installation)
+- [Constants](#constants)
 - [Package Architecture](#package-architecture)
 - [Module Setup](#module-setup)
+- [Entities](#entities)
 - [Storage Providers](#storage-providers)
 - [Storage Configuration](#storage-configuration)
 - [File Manager](#file-manager)
@@ -62,6 +64,19 @@ npm install ssh2-sftp-client                                    # For SFTP
 
 ---
 
+## Constants
+
+```typescript
+// Injection Token
+export const STORAGE_MODULE_OPTIONS = 'STORAGE_MODULE_OPTIONS';
+
+// Default Configuration
+export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
+export const DEFAULT_ALLOWED_FILE_TYPES = ['*/*']; // All file types
+```
+
+---
+
 ## Package Architecture
 
 ```
@@ -89,6 +104,7 @@ nestjs-storage/
 │   │   ├── file-manager.service.ts     # File metadata CRUD
 │   │   ├── folder.service.ts           # Folder CRUD
 │   │   ├── storage-provider-config.service.ts
+│   │   ├── storage-datasource.provider.ts  # Dynamic entity loading
 │   │   └── index.ts
 │   │
 │   ├── controllers/
@@ -99,13 +115,15 @@ nestjs-storage/
 │   │   └── index.ts
 │   │
 │   ├── entities/
-│   │   ├── file-manager.entity.ts      # File metadata
 │   │   ├── file-manager-base.entity.ts
+│   │   ├── file-manager.entity.ts
 │   │   ├── file-manager-with-company.entity.ts
-│   │   ├── folder.entity.ts            # Folder structure
 │   │   ├── folder-base.entity.ts
+│   │   ├── folder.entity.ts
 │   │   ├── folder-with-company.entity.ts
-│   │   ├── storage-config.entity.ts    # Provider configs
+│   │   ├── storage-config-base.entity.ts
+│   │   ├── storage-config.entity.ts
+│   │   ├── storage-config-with-company.entity.ts
 │   │   └── index.ts
 │   │
 │   ├── dtos/
@@ -116,8 +134,11 @@ nestjs-storage/
 │   │   └── index.ts
 │   │
 │   ├── interfaces/
-│   │   ├── storage-provider.interface.ts
+│   │   ├── file-manager.interface.ts
+│   │   ├── folder.interface.ts
+│   │   ├── storage-config.interface.ts
 │   │   ├── storage-module-options.interface.ts
+│   │   ├── storage-provider.interface.ts
 │   │   └── index.ts
 │   │
 │   ├── enums/
@@ -253,6 +274,34 @@ This ensures the API documentation accurately reflects the available fields base
 
 ---
 
+## Entities
+
+### Entity Groups
+
+```typescript
+// Core entities (no company feature)
+export const StorageCoreEntities = [FileManager, Folder, StorageConfig];
+
+// Company-specific entities
+export const StorageCompanyEntities = [
+  FileManagerWithCompany,
+  FolderWithCompany,
+  StorageConfigWithCompany,
+];
+
+// Helper function
+export function getStorageEntitiesByConfig(enableCompanyFeature: boolean): any[] {
+  return enableCompanyFeature ? StorageCompanyEntities : StorageCoreEntities;
+}
+
+// Base type aliases for backwards compatibility
+export { FileManager as FileManagerBase } from './file-manager.entity';
+export { Folder as FolderBase } from './folder.entity';
+export { StorageConfig as StorageConfigBase } from './storage-config.entity';
+```
+
+---
+
 ## Storage Providers
 
 ### Provider Types
@@ -412,6 +461,12 @@ export class StorageConfig extends Identity {
   @Column({ type: 'json' })
   config: Record<string, any>; // Provider-specific config
 
+  @Column({ default: true })
+  isActive: boolean; // Whether config is active and usable
+
+  @Column({ default: false })
+  isDefault: boolean; // Set as default configuration
+
   @Column({ nullable: true })
   companyId: string; // Company scope (when enabled)
 }
@@ -438,6 +493,8 @@ export class SetupService {
           accessKeyId: process.env.AWS_ACCESS_KEY,
           secretAccessKey: process.env.AWS_SECRET_KEY,
         },
+        isActive: true,
+        isDefault: true,  // Set as default configuration
       },
       user,
     );
@@ -453,6 +510,8 @@ export class SetupService {
           privateKey: process.env.SFTP_PRIVATE_KEY,
           basePath: '/backups',
         },
+        isActive: true,
+        isDefault: false, // Not the default
       },
       user,
     );
@@ -460,27 +519,123 @@ export class SetupService {
 }
 ```
 
+### Storage Provider Resolution Flow
+
+When performing upload operations, the `UploadService` resolves the storage provider using a multi-level fallback strategy:
+
+**Resolution Flow Diagram:**
+
+```
+Upload Request (with optional storageConfigId)
+                │
+                ▼
+┌─────────────────────────────────────────────────────────┐
+│ 1. Check if storageConfigId provided                    │
+└─────────────────────────────────────────────────────────┘
+                │
+       provided? ─┴── no ──┐
+         │                 │
+         ▼                 ▼
+┌──────────────────┐  ┌─────────────────────────────────────┐
+│ 2. Lookup config │  │ 3. Get default config for company   │
+│    by ID         │  │    - Priority 1: isDefault=true     │
+└────────┬─────────┘  │    - Priority 2: oldest active      │
+         │            └─────────────────────────────────────┘
+         │                 │
+         ▼                 ▼
+┌─────────────────────────────────────────────────────────┐
+│ 4. Validate company ownership (if company feature)     │
+│    - Throws BadRequestException if wrong company       │
+└─────────────────────────────────────────────────────────┘
+                │
+                ▼
+┌─────────────────────────────────────────────────────────┐
+│ 5. Create/reuse storage provider instance              │
+│    - Check provider cache by config hash               │
+│    - Create new if not cached                          │
+└─────────────────────────────────────────────────────────┘
+                │
+                ▼
+           [Perform Upload]
+```
+
+**Code Implementation:**
+
+```typescript
+// UploadService
+private async getStorageProvider(
+  storageConfigId?: string,
+  user?: ILoggedUserInfo,
+): Promise<{ provider: IStorageProvider; config: StorageConfigBase }> {
+  let config: StorageConfigBase | null = null;
+
+  // Step 1: Try to get by ID or fallback to default
+  if (storageConfigId) {
+    config = await this.storageProviderConfigService.findByIdDirect(storageConfigId);
+  }
+
+  if (!config) {
+    config = await this.storageProviderConfigService.getDefaultConfig(user);
+  }
+
+  if (!config) {
+    throw new BadRequestException('No storage configuration available');
+  }
+
+  // Step 2: Validate company ownership
+  if (this.storageConfigService.isCompanyFeatureEnabled() && user?.companyId) {
+    const configWithCompany = config as StorageConfigWithCompany;
+    if (configWithCompany.companyId && configWithCompany.companyId !== user.companyId) {
+      throw new BadRequestException('Storage configuration belongs to another company');
+    }
+  }
+
+  // Step 3: Get or create provider instance
+  const provider = await this.storageFactory.createProvider({
+    provider: config.storage,
+    config: config.config,
+  });
+
+  return { provider, config };
+}
+```
+
+**Key Points:**
+- Always specify `storageConfigId` for deterministic behavior
+- Without `storageConfigId`, system uses company's default config
+- Company ownership is always validated when company feature is enabled
+- Provider instances are cached for connection reuse
+
 ### Default Configuration Resolution
 
+When `storageConfigId` is not provided for uploads, the system automatically resolves the default config:
+
+1. **Priority 1:** Find config with `isDefault: true` and `isActive: true`
+2. **Priority 2:** Fall back to oldest active config
+
 ```typescript
 // StorageProviderConfigService
 async getDefaultConfig(user?: ILoggedUserInfo): Promise<StorageConfigBase | null> {
+  await this.ensureRepositoryInitialized();
+
+  const baseWhere: any = { isActive: true };
+
   // Filter by company if enabled
-  const where: any = {};
-  if (this.isCompanyFeatureEnabled() && user?.companyId) {
-    where.companyId = user.companyId;
+  if (this.storageConfig.isCompanyFeatureEnabled() && user?.companyId) {
+    baseWhere.companyId = user.companyId;
   }
 
-  // First try 'default' named config
+  // First try to find config marked as default
   const defaultConfig = await this.repository.findOne({
-    where: { ...where, name: 'default' },
+    where: { ...baseWhere, isDefault: true },
+    order: { createdAt: 'ASC' },
   });
 
   if (defaultConfig) return defaultConfig;
 
-  // Fall back to any available config
+  // Fall back to oldest active config
   return await this.repository.findOne({
-    where,
+    where: baseWhere,
     order: { createdAt: 'ASC' },
   });
 }
@@ -860,7 +1015,7 @@ curl -X POST http://localhost:3000/upload/single-file \
 
 ---
 
-## DataSource Provider Pattern (Updated 2026-01-16)
+## DataSource Provider Pattern
 
 ### Overview
 
@@ -1211,6 +1366,7 @@ import {
   FileManagerService,
   FolderService,
   StorageProviderConfigService,
+  StorageDataSourceProvider,
 } from '@flusys/nestjs-storage/services';
 
 // Entities
@@ -1241,10 +1397,15 @@ import {
 
 // Interfaces
 import {
+  IFileManager,
+  IFolder,
+  IStorageConfig,
+  IStorageModuleConfig,
   IStorageProvider,
   IStorageProviderConfig,
   IUploadedFileInfo,
   StorageModuleOptions,
+  StorageModuleAsyncOptions,
 } from '@flusys/nestjs-storage/interfaces';
 
 // Enums
@@ -1279,4 +1440,4 @@ The `@flusys/nestjs-storage` package provides:
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-21

package/cjs/config/index.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", {
     value: true
 });
 _export_star(require("./storage.constants"), exports);
-_export_star(require("./storage-config.service"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
         if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {

package/cjs/config/storage.constants.js

@@ -17,29 +17,12 @@ _export(exports, {
     get DEFAULT_MAX_FILE_SIZE () {
         return DEFAULT_MAX_FILE_SIZE;
     },
-    get FILE_VALIDATION_MESSAGES () {
-        return FILE_VALIDATION_MESSAGES;
-    },
-    get STORAGE_CONFIG_SERVICE () {
-        return STORAGE_CONFIG_SERVICE;
-    },
-    get STORAGE_DATA_SOURCE_PROVIDER () {
-        return STORAGE_DATA_SOURCE_PROVIDER;
-    },
     get STORAGE_MODULE_OPTIONS () {
         return STORAGE_MODULE_OPTIONS;
     }
 });
 const STORAGE_MODULE_OPTIONS = 'STORAGE_MODULE_OPTIONS';
-const STORAGE_CONFIG_SERVICE = 'STORAGE_CONFIG_SERVICE';
-const STORAGE_DATA_SOURCE_PROVIDER = 'STORAGE_DATA_SOURCE_PROVIDER';
 const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
 const DEFAULT_ALLOWED_FILE_TYPES = [
     '*/*'
 ]; // All file types
-const FILE_VALIDATION_MESSAGES = {
-    FILE_TOO_LARGE: 'File size exceeds the maximum allowed size',
-    INVALID_FILE_TYPE: 'File type is not allowed',
-    NO_FILE_PROVIDED: 'No file was provided',
-    UPLOAD_FAILED: 'File upload failed'
-};

package/cjs/controllers/file-manager.controller.js

@@ -46,7 +46,50 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let FileManagerController = class FileManagerController extends (0, _classes.createApiController)(_dtos1.CreateFileManagerDto, _dtos1.UpdateFileManagerDto, _dtos1.FileManagerResponseDto, {
-    security: 'jwt'
+    security: {
+        insert: {
+            level: 'permission',
+            permissions: [
+                _classes.FILE_PERMISSIONS.CREATE
+            ]
+        },
+        insertMany: {
+            level: 'permission',
+            permissions: [
+                _classes.FILE_PERMISSIONS.CREATE
+            ]
+        },
+        getById: {
+            level: 'permission',
+            permissions: [
+                _classes.FILE_PERMISSIONS.READ
+            ]
+        },
+        getAll: {
+            level: 'permission',
+            permissions: [
+                _classes.FILE_PERMISSIONS.READ
+            ]
+        },
+        update: {
+            level: 'permission',
+            permissions: [
+                _classes.FILE_PERMISSIONS.UPDATE
+            ]
+        },
+        updateMany: {
+            level: 'permission',
+            permissions: [
+                _classes.FILE_PERMISSIONS.UPDATE
+            ]
+        },
+        delete: {
+            level: 'permission',
+            permissions: [
+                _classes.FILE_PERMISSIONS.DELETE
+            ]
+        }
+    }
 }) {
     async getFiles(dto, req, user) {
         if (!dto || !dto.length) {

package/cjs/controllers/folder.controller.js

@@ -41,7 +41,50 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let FolderController = class FolderController extends (0, _classes.createApiController)(_dtos.CreateFolderDto, _dtos.UpdateFolderDto, _dtos.FolderResponseDto, {
-    security: 'jwt'
+    security: {
+        insert: {
+            level: 'permission',
+            permissions: [
+                _classes.FOLDER_PERMISSIONS.CREATE
+            ]
+        },
+        insertMany: {
+            level: 'permission',
+            permissions: [
+                _classes.FOLDER_PERMISSIONS.CREATE
+            ]
+        },
+        getById: {
+            level: 'permission',
+            permissions: [
+                _classes.FOLDER_PERMISSIONS.READ
+            ]
+        },
+        getAll: {
+            level: 'permission',
+            permissions: [
+                _classes.FOLDER_PERMISSIONS.READ
+            ]
+        },
+        update: {
+            level: 'permission',
+            permissions: [
+                _classes.FOLDER_PERMISSIONS.UPDATE
+            ]
+        },
+        updateMany: {
+            level: 'permission',
+            permissions: [
+                _classes.FOLDER_PERMISSIONS.UPDATE
+            ]
+        },
+        delete: {
+            level: 'permission',
+            permissions: [
+                _classes.FOLDER_PERMISSIONS.DELETE
+            ]
+        }
+    }
 }) {
     constructor(folderService){
         super(folderService), _define_property(this, "folderService", void 0), this.folderService = folderService;

package/cjs/controllers/storage-config.controller.js

@@ -41,7 +41,50 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let StorageConfigController = class StorageConfigController extends (0, _classes.createApiController)(_dtos.CreateStorageConfigDto, _dtos.UpdateStorageConfigDto, _dtos.StorageConfigResponseDto, {
-    security: 'jwt'
+    security: {
+        insert: {
+            level: 'permission',
+            permissions: [
+                _classes.STORAGE_CONFIG_PERMISSIONS.CREATE
+            ]
+        },
+        insertMany: {
+            level: 'permission',
+            permissions: [
+                _classes.STORAGE_CONFIG_PERMISSIONS.CREATE
+            ]
+        },
+        getById: {
+            level: 'permission',
+            permissions: [
+                _classes.STORAGE_CONFIG_PERMISSIONS.READ
+            ]
+        },
+        getAll: {
+            level: 'permission',
+            permissions: [
+                _classes.STORAGE_CONFIG_PERMISSIONS.READ
+            ]
+        },
+        update: {
+            level: 'permission',
+            permissions: [
+                _classes.STORAGE_CONFIG_PERMISSIONS.UPDATE
+            ]
+        },
+        updateMany: {
+            level: 'permission',
+            permissions: [
+                _classes.STORAGE_CONFIG_PERMISSIONS.UPDATE
+            ]
+        },
+        delete: {
+            level: 'permission',
+            permissions: [
+                _classes.STORAGE_CONFIG_PERMISSIONS.DELETE
+            ]
+        }
+    }
 }) {
     constructor(storageConfigService){
         super(storageConfigService), _define_property(this, "storageConfigService", void 0), this.storageConfigService = storageConfigService;

package/cjs/controllers/upload.controller.js

@@ -16,8 +16,6 @@ const _common = require("@nestjs/common");
 const _platformexpress = require("@nestjs/platform-express");
 const _swagger = require("@nestjs/swagger");
 const _uploadservice = require("../services/upload.service");
-const _config = require("../config");
-const _storagefactoryservice = require("../providers/storage-factory.service");
 function _define_property(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -46,35 +44,30 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let UploadController = class UploadController {
+    toFileUploadResponse(file) {
+        return {
+            size: this.uploadService.bytesToKb(file.size),
+            name: file.name,
+            key: file.key,
+            contentType: file.contentType,
+            location: file.location || 'local',
+            storageConfigId: file.storageConfigId || ''
+        };
+    }
     async uploadSingleFile(file, options, user) {
         const result = await this.uploadService.uploadSingleFile(file, options, user);
         return {
             success: true,
             message: 'File uploaded successfully',
-            data: {
-                size: this.uploadService.bytesToKb(result.size),
-                name: result.name,
-                key: result.key,
-                contentType: result.contentType,
-                location: result.location || 'local',
-                storageConfigId: result.storageConfigId || ''
-            }
+            data: this.toFileUploadResponse(result)
         };
     }
     async uploadMultipleFiles(files, options, user) {
         const uploadResponses = await this.uploadService.uploadMultipleFiles(files, options, user);
-        const responseData = uploadResponses.map((file)=>({
-                size: this.uploadService.bytesToKb(file.size),
-                name: file.name,
-                key: file.key,
-                contentType: file.contentType,
-                location: file.location || 'local',
-                storageConfigId: file.storageConfigId || ''
-            }));
         return {
             success: true,
             message: 'Files uploaded successfully',
-            data: responseData
+            data: uploadResponses.map((file)=>this.toFileUploadResponse(file))
         };
     }
     async deleteSingleFile(dto, user) {
@@ -93,17 +86,14 @@ let UploadController = class UploadController {
             data
         };
     }
-    constructor(uploadService, storageConfigService, storageFactoryService){
+    constructor(uploadService){
         _define_property(this, "uploadService", void 0);
-        _define_property(this, "storageConfigService", void 0);
-        _define_property(this, "storageFactoryService", void 0);
         this.uploadService = uploadService;
-        this.storageConfigService = storageConfigService;
-        this.storageFactoryService = storageFactoryService;
     }
 };
 _ts_decorate([
     (0, _common.Post)('single-file'),
+    (0, _decorators.RequirePermission)('file.upload'),
     (0, _decorators.ApiResponseDto)(_dtos.FileUploadResponsePayloadDto, false),
     (0, _swagger.ApiOperation)({
         summary: 'Upload a single file'
@@ -145,6 +135,7 @@ _ts_decorate([
 ], UploadController.prototype, "uploadSingleFile", null);
 _ts_decorate([
     (0, _common.Post)('multiple-file'),
+    (0, _decorators.RequirePermission)('file.upload'),
     (0, _swagger.ApiOperation)({
         summary: 'Upload multiple files (up to 50)'
     }),
@@ -189,6 +180,7 @@ _ts_decorate([
 ], UploadController.prototype, "uploadMultipleFiles", null);
 _ts_decorate([
     (0, _common.Post)('delete-single-file'),
+    (0, _decorators.RequirePermission)('file.delete'),
     (0, _swagger.ApiOperation)({
         summary: 'Delete a single file'
     }),
@@ -206,6 +198,7 @@ _ts_decorate([
 ], UploadController.prototype, "deleteSingleFile", null);
 _ts_decorate([
     (0, _common.Post)('delete-multiple-file'),
+    (0, _decorators.RequirePermission)('file.delete'),
     (0, _swagger.ApiOperation)({
         summary: 'Delete multiple files'
     }),
@@ -227,12 +220,8 @@ UploadController = _ts_decorate([
     (0, _common.Controller)('storage/upload'),
     (0, _common.UseGuards)(_guards.JwtAuthGuard),
     _ts_param(0, (0, _common.Inject)(_uploadservice.UploadService)),
-    _ts_param(1, (0, _common.Inject)(_config.StorageConfigService)),
-    _ts_param(2, (0, _common.Inject)(_storagefactoryservice.StorageFactoryService)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof _uploadservice.UploadService === "undefined" ? Object : _uploadservice.UploadService,
-        typeof _config.StorageConfigService === "undefined" ? Object : _config.StorageConfigService,
-        typeof _storagefactoryservice.StorageFactoryService === "undefined" ? Object : _storagefactoryservice.StorageFactoryService
+        typeof _uploadservice.UploadService === "undefined" ? Object : _uploadservice.UploadService
     ])
 ], UploadController);