@ackplus/nest-file-storage 1.0.1 → 1.1.1

package/README.md

@@ -1,409 +1,11 @@
-# @ackplus/nest-file-storage
+# nest-auth
 
-A flexible file storage library for NestJS that supports multiple storage providers with simple file mapping capabilities.
+This library was generated with [Nx](https://nx.dev).
 
-## Installation
+## Building
 
-```bash
-npm install @ackplus/nest-file-storage
-```
+Run `nx build nest-auth` to build the library.
 
-## Storage Providers
+## Running unit tests
 
-This library supports multiple storage providers. You only need to install the dependencies for the storage providers you plan to use.
-
-### Local Storage
-
-No additional dependencies required. Works out of the box.
-
-### Azure Blob Storage
-
-To use Azure Blob Storage, install the Azure SDK:
-
-```bash
-npm install @azure/storage-blob
-```
-
-### AWS S3 Storage
-
-To use AWS S3 Storage, install the AWS SDK:
-
-```bash
-npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
-```
-
-## Usage
-
-The library supports two approaches: **Configuration-based** and **Class Factory**.
-
-### Configuration-based Approach (Recommended)
-
-This approach uses lazy loading and only loads the storage provider when needed.
-
-#### Local Storage
-
-```typescript
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
-
-@Module({
-  imports: [
-    NestFileStorageModule.forRoot({
-      storage: FileStorageEnum.LOCAL,
-      localConfig: {
-        destination: './uploads'
-      }
-    })
-  ]
-})
-export class AppModule {}
-```
-
-#### Azure Blob Storage
-
-```typescript
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
-
-@Module({
-  imports: [
-    NestFileStorageModule.forRoot({
-      storage: FileStorageEnum.AZURE,
-      azureConfig: {
-        account: 'your-storage-account',
-        accountKey: 'your-account-key',
-        container: 'your-container'
-      }
-    })
-  ]
-})
-export class AppModule {}
-```
-
-#### AWS S3 Storage
-
-```typescript
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
-
-@Module({
-  imports: [
-    NestFileStorageModule.forRoot({
-      storage: FileStorageEnum.S3,
-      s3Config: {
-        region: 'us-east-1',
-        bucket: 'your-bucket',
-        accessKeyId: 'your-access-key',
-        secretAccessKey: 'your-secret-key'
-      }
-    })
-  ]
-})
-export class AppModule {}
-```
-
-### Class Factory Approach
-
-This approach allows you to provide your own storage class directly.
-
-```typescript
-import { NestFileStorageModule } from '@ackplus/nest-file-storage';
-
-@Module({
-  imports: [
-    NestFileStorageModule.forRoot({
-      storageFactory: async () => {
-        // Lazy load the storage class
-        const { AzureStorage } = await import('@ackplus/nest-file-storage/lib/storage/azure.storage');
-        return AzureStorage;
-      },
-      options: {
-        account: 'your-storage-account',
-        accountKey: 'your-account-key',
-        container: 'your-container'
-      }
-    })
-  ]
-})
-export class AppModule {}
-```
-
-#### Custom Storage Class
-
-You can also provide your own custom storage implementation:
-
-```typescript
-import { NestFileStorageModule, Storage } from '@ackplus/nest-file-storage';
-
-class CustomStorage implements Storage {
-  // Implement your custom storage logic
-  async getFile(key: string): Promise<Buffer> { /* ... */ }
-  async deleteFile(key: string): Promise<void> { /* ... */ }
-  async putFile(fileContent: Buffer, key: string): Promise<UploadedFile> { /* ... */ }
-  getUrl(key: string): string { /* ... */ }
-  async copyFile(oldKey: string, newKey: string): Promise<UploadedFile> { /* ... */ }
-}
-
-@Module({
-  imports: [
-    NestFileStorageModule.forRoot({
-      storageFactory: () => CustomStorage,
-      options: {
-        // Your custom options
-      }
-    })
-  ]
-})
-export class AppModule {}
-```
-
-### When to Use Each Approach
-
-**Configuration-based Approach:**
-- ✅ Recommended for most use cases
-- ✅ Automatic lazy loading
-- ✅ Built-in error handling for missing dependencies
-- ✅ Simpler configuration
-- ✅ Better for switching between providers
-- ✅ Supports async configuration with dependency injection
-
-**Class Factory Approach:**
-- ✅ More control over storage instantiation
-- ✅ Custom storage implementations
-- ✅ Advanced use cases
-- ✅ Still supports lazy loading if implemented correctly
-- ⚠️ More complex configuration
-- ⚠️ Manual dependency management
-
-**Async Configuration (forRootAsync):**
-- ✅ Full dependency injection support
-- ✅ `useFactory`, `useClass`, and `useExisting` patterns
-- ✅ Integration with ConfigService and other providers
-- ✅ Environment-based configuration
-- ✅ Perfect for complex application setups
-
-### Async Configuration (forRootAsync)
-
-For more advanced scenarios, you can use `forRootAsync` with dependency injection:
-
-#### Using useFactory
-
-```typescript
-import { NestFileStorageModule, FileStorageEnum } from '@ackplus/nest-file-storage';
-import { ConfigModule, ConfigService } from '@nestjs/config';
-
-@Module({
-  imports: [
-    ConfigModule,
-    NestFileStorageModule.forRootAsync({
-      imports: [ConfigModule],
-      useFactory: async (configService: ConfigService) => ({
-        storage: FileStorageEnum.S3,
-        s3Config: {
-          region: configService.get('AWS_REGION'),
-          bucket: configService.get('AWS_BUCKET'),
-          accessKeyId: configService.get('AWS_ACCESS_KEY_ID'),
-          secretAccessKey: configService.get('AWS_SECRET_ACCESS_KEY'),
-        }
-      }),
-      inject: [ConfigService],
-    })
-  ]
-})
-export class AppModule {}
-```
-
-#### Using useClass
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { NestFileStorageModule, FileStorageOptionsFactory, FileStorageModuleOptions, FileStorageEnum } from '@ackplus/nest-file-storage';
-import { ConfigService } from '@nestjs/config';
-
-@Injectable()
-export class FileStorageConfigService implements FileStorageOptionsFactory {
-  constructor(private configService: ConfigService) {}
-
-  createFileStorageOptions(): FileStorageModuleOptions {
-    return {
-      storage: FileStorageEnum.AZURE,
-      azureConfig: {
-        account: this.configService.get('AZURE_STORAGE_ACCOUNT'),
-        accountKey: this.configService.get('AZURE_STORAGE_KEY'),
-        container: this.configService.get('AZURE_STORAGE_CONTAINER'),
-      }
-    };
-  }
-}
-
-@Module({
-  imports: [
-    ConfigModule,
-    NestFileStorageModule.forRootAsync({
-      imports: [ConfigModule],
-      useClass: FileStorageConfigService,
-    })
-  ]
-})
-export class AppModule {}
-```
-
-#### Using useExisting
-
-```typescript
-@Module({
-  imports: [
-    ConfigModule,
-    NestFileStorageModule.forRootAsync({
-      imports: [ConfigModule],
-      useExisting: FileStorageConfigService,
-    })
-  ],
-  providers: [FileStorageConfigService]
-})
-export class AppModule {}
-```
-
-### Direct Usage with Storage Factory
-
-You can also use the storage factory directly for more control:
-
-```typescript
-import { StorageFactory, FileStorageEnum } from '@ackplus/nest-file-storage';
-
-// This will lazy load only the Azure storage provider
-const azureStorage = await StorageFactory.createStorage(FileStorageEnum.AZURE, {
-  account: 'your-storage-account',
-  accountKey: 'your-account-key',
-  container: 'your-container'
-});
-
-// Use the storage instance
-const uploadedFile = await azureStorage.putFile(buffer, 'path/to/file.jpg');
-```
-
-## Flexible File Mapping
-
-The library includes flexible file mapping functionality that allows you to define custom logic for how uploaded files are transformed and stored in the request body.
-
-**Default Behavior**: Without any configuration, uploaded files are automatically mapped to their storage key (path) in the request body.
-
-### Default Behavior (No Configuration)
-
-```typescript
-import { FileStorageInterceptor } from '@ackplus/nest-file-storage';
-
-@Controller('upload')
-export class UploadController {
-    @Post('document')
-    @UseInterceptors(FileStorageInterceptor('document'))
-    async uploadDocument(@Body() body: any) {
-        // body.document will contain the file key (storage path)
-        console.log(body.document); // "documents/2024/1/1234567890-resume.pdf"
-        return { message: 'Document uploaded', data: body };
-    }
-}
-```
-
-### Return File URL String (Custom Logic)
-
-```typescript
-@Post('avatar')
-@UseInterceptors(FileStorageInterceptor('avatar', {
-    mapToRequestBody: (file, fieldName, req) => {
-        // Return just the URL string for direct DB storage
-        return file.url;
-    }
-}))
-async uploadAvatar(@Body() body: any) {
-    // body.avatar will be a string URL
-    console.log(body.avatar); // "http://localhost:3000/uploads/images/avatar.jpg"
-    return { message: 'Avatar uploaded', data: body };
-}
-```
-
-### Return Custom Object with Business Logic
-
-```typescript
-@Post('document')
-@UseInterceptors(FileStorageInterceptor('document', {
-    mapToRequestBody: (file, fieldName, req) => {
-        // Return custom object with business logic
-        return {
-            fileId: `file_${Date.now()}`,
-            url: file.url,
-            originalName: file.originalName,
-            uploadedBy: req.user?.id || 'anonymous',
-            uploadedAt: new Date().toISOString(),
-            isPublic: req.body.isPublic === 'true'
-        };
-    }
-}))
-async uploadDocument(@Body() body: any) {
-    // body.document will be a custom object
-    console.log(body.document);
-    return { message: 'Document uploaded', data: body };
-}
-```
-
-### Multiple Files with Custom Logic
-
-```typescript
-@Post('gallery')
-@UseInterceptors(FileStorageInterceptor({
-    type: 'array',
-    fieldName: 'images',
-    maxCount: 5
-}, {
-    mapToRequestBody: (files, fieldName, req) => {
-        // Return array of custom objects
-        return files.map((file, index) => ({
-            id: `img_${Date.now()}_${index}`,
-            url: file.url,
-            isPrimary: index === 0,
-            alt: req.body.imageAlts?.[index] || `Image ${index + 1}`
-        }));
-    }
-}))
-async uploadGallery(@Body() body: any) {
-    // body.images will be an array of custom objects
-    console.log(body.images);
-    return { message: 'Gallery uploaded', data: body };
-}
-```
-
-**Key Features**:
-- **Return anything**: String, object, array, or custom structure
-- **Access request data**: Use `req` parameter for user info, body data, etc.
-- **Field-specific logic**: Use `fieldName` to handle different fields differently
-- **Business logic**: Implement any custom transformation you need
-
-For detailed examples, see [FILE_KEY_MAPPING.md](./docs/FILE_KEY_MAPPING.md).
-
-## Error Handling
-
-If you try to use a storage provider without installing its required dependencies, you'll get a clear error message:
-
-- **Azure Storage**: `Azure Storage SDK (@azure/storage-blob) is required when using AzureStorage. Please install it: npm install @azure/storage-blob`
-- **S3 Storage**: `AWS SDK (@aws-sdk/client-s3 and @aws-sdk/s3-request-presigner) is required when using S3Storage. Please install them: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner`
-
-## How Lazy Loading Works
-
-The library uses dynamic imports to load storage providers only when they're actually needed:
-
-1. **At build time**: Only the storage factory and types are bundled
-2. **At runtime**: When you use a storage provider, it's dynamically imported
-3. **Caching**: Once loaded, storage instances are cached for reuse
-4. **Error handling**: Missing dependencies are caught and provide clear error messages
-
-This means:
-- If you only use local storage, Azure/S3 code is never loaded
-- If you only use Azure storage, S3 code is never loaded
-- Your bundle size stays minimal regardless of how many storage providers are available
-
-## Benefits
-
-- **Lazy Loading**: Storage providers are only loaded when actually used
-- **Smaller bundle size**: Only install the dependencies you need
-- **Flexible**: Switch between storage providers easily
-- **Clear error messages**: Know exactly what to install if a dependency is missing
-- **TypeScript support**: Full type safety for all storage providers
-- **Caching**: Storage instances are cached to avoid repeated initialization
-- **Zero overhead**: Unused storage providers don't affect your application
+Run `nx test nest-auth` to execute the unit tests via [Jest](https://jestjs.io).

package/eslint.config.mjs

@@ -0,0 +1,22 @@
+import baseConfig from '../../eslint.base.config';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+  {
+    ignores: ['**/out-tsc'],
+  },
+];

package/jest.config.ts

@@ -0,0 +1,10 @@
+export default {
+  displayName: 'nest-file-storage',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/packages/nest-file-storage',
+};

package/package.json

@@ -1,67 +1,10 @@
 {
   "name": "@ackplus/nest-file-storage",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "type": "commonjs",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ack-solutions/packages.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "homepage": "https://github.com/ack-solutions/packages.git#readme",
-  "peerDependencies": {
-    "typeorm": "^0.3.23",
-    "@nestjs/typeorm": "^11.0.0",
-    "@nestjs/common": "^10.0.0 || ^11.0.0",
-    "@nestjs/core": "^10.0.0 || ^11.0.0",
-    "@azure/storage-blob": "^12.0.0",
-    "@aws-sdk/client-s3": "^3.0.0",
-    "@aws-sdk/s3-request-presigner": "^3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@azure/storage-blob": {
-      "optional": true
-    },
-    "@aws-sdk/client-s3": {
-      "optional": true
-    },
-    "@aws-sdk/s3-request-presigner": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "typeorm": "^0.3.23",
-    "@nestjs/typeorm": "^11.0.0",
-    "@nestjs/common": "^11.1.3",
-    "@nestjs/core": "^11.1.3",
-    "@types/multer": "^2.0.0",
-    "@types/node": "^20.0.0",
-    "@types/uuid": "^9.0.0",
-    "@types/concat-stream": "^2.0.0"
-  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "dependencies": {
-    "tslib": "^2.3.0",
-    "deepmerge": "4.3.1",
-    "class-transformer": "^0.5.1",
-    "class-validator": "^0.14.1",
-    "pluralize": "8.0.0",
-    "lodash": "^4.17.21",
-    "rxjs": "^7.8.0",
-    "multer": "^2.0.1",
-    "moment": "^2.30.1",
-    "uuid": "^9.0.0",
-    "concat-stream": "^2.0.0"
-  },
-  "scripts": {
-    "build": "pnpm run clean && tsc -p tsconfig.lib.json",
-    "clean": "rimraf dist",
-    "dev": "tsc -p tsconfig.lib.json --watch --preserveWatchOutput"
+    "tslib": "^2.3.0"
   }
-}
+}

package/project.json

@@ -0,0 +1,38 @@
+{
+  "name": "nest-file-storage",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/nest-file-storage/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "manifestRootsToUpdate": [
+        "dist/{projectRoot}"
+      ],
+      "currentVersionResolver": "git-tag",
+      "fallbackCurrentVersionResolver": "disk"
+    }
+  },
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": [
+        "{options.outputPath}"
+      ],
+      "options": {
+        "outputPath": "dist/packages/nest-file-storage",
+        "tsConfig": "packages/nest-file-storage/tsconfig.lib.json",
+        "packageJson": "packages/nest-file-storage/package.json",
+        "main": "packages/nest-file-storage/src/index.ts",
+        "assets": [
+          "packages/nest-file-storage/*.md"
+        ]
+      }
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    }
+  }
+}

package/{dist/index.d.ts → src/index.ts}

@@ -2,4 +2,3 @@ export * from './lib/nest-file-storage.module';
 export * from './lib/file-storage.service';
 export * from './lib/interceptor/file-storage.interceptor';
 export * from './lib/types';
-//# sourceMappingURL=index.d.ts.map

package/src/lib/constants.ts

@@ -0,0 +1 @@
+export const FILE_STORAGE_OPTIONS = 'FileStorageOptions';

package/src/lib/file-storage.service.ts

@@ -0,0 +1,36 @@
+import { StorageFactory } from './storage.factory';
+import { FileStorageEnum, FileStorageModuleOptions, FileStorageConfigOptions, FileStorageClassOptions } from './types';
+
+
+export class FileStorageService {
+
+    private static options: FileStorageModuleOptions; // ✅ Static global property
+
+    static setOptions(options: FileStorageModuleOptions) {
+        FileStorageService.options = options;
+    }
+
+    static getOptions(): FileStorageModuleOptions {
+        return FileStorageService.options;
+    }
+
+    static async getStorage(storageType?: FileStorageEnum) {
+        const options = this.getOptions();
+
+        // Check if it's a class factory approach
+        if ('storageFactory' in options) {
+            const classOptions = options as FileStorageClassOptions;
+            const StorageClass = await classOptions.storageFactory();
+            return new StorageClass(classOptions.options);
+        }
+
+        // Configuration-based approach
+        const configOptions = options as FileStorageConfigOptions;
+        if (!storageType) {
+            storageType = configOptions.storage;
+        }
+        const config = (configOptions as any)[`Config`];
+        return await StorageFactory.createStorage(storageType, config);
+    }
+
+}

package/{dist/lib/index.d.ts → src/lib/index.ts}

@@ -3,4 +3,3 @@ export * from './types';
 export * from './storage.factory';
 export * from './interceptor/file-storage.interceptor';
 export * from './file-storage.service';
-//# sourceMappingURL=index.d.ts.map