@ackplus/nest-file-storage 0.1.35

package/README.md

@@ -0,0 +1,409 @@
+# @ackplus/nest-file-storage
+
+A flexible file storage library for NestJS that supports multiple storage providers with simple file mapping capabilities.
+
+## Installation
+
+```bash
+npm install @ackplus/nest-file-storage
+```
+
+## Storage Providers
+
+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

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ackplus/nest-file-storage",
+  "version": "0.1.35",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "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.4.5",
+    "@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": "^10.4.5",
+    "@types/multer": "^2.0.0"
+  },
+  "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"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lib/nest-file-storage.module';
+export * from './lib/file-storage.service';
+export * from './lib/interceptor/file-storage.interceptor';
+export * from './lib/types';

package/src/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/nest-file-storage.module"), exports);
+tslib_1.__exportStar(require("./lib/file-storage.service"), exports);
+tslib_1.__exportStar(require("./lib/interceptor/file-storage.interceptor"), exports);
+tslib_1.__exportStar(require("./lib/types"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/nest-file-storage/src/index.ts"],"names":[],"mappings":";;;AAAA,yEAA+C;AAC/C,qEAA2C;AAC3C,qFAA2D;AAC3D,sDAA4B"}

package/src/lib/constants.d.ts

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

package/src/lib/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_STORAGE_OPTIONS = void 0;
+exports.FILE_STORAGE_OPTIONS = 'FileStorageOptions';
+//# sourceMappingURL=constants.js.map

package/src/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../packages/nest-file-storage/src/lib/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,oBAAoB,GAAG,oBAAoB,CAAC"}

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

@@ -0,0 +1,7 @@
+import { FileStorageEnum, FileStorageModuleOptions } from './types';
+export declare class FileStorageService {
+    private static options;
+    static setOptions(options: FileStorageModuleOptions): void;
+    static getOptions(): FileStorageModuleOptions;
+    static getStorage(storageType?: FileStorageEnum): Promise<import("./types").Storage>;
+}

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

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileStorageService = void 0;
+const tslib_1 = require("tslib");
+const storage_factory_1 = require("./storage.factory");
+class FileStorageService {
+    static setOptions(options) {
+        FileStorageService.options = options;
+    }
+    static getOptions() {
+        return FileStorageService.options;
+    }
+    static getStorage(storageType) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const options = this.getOptions();
+            if ('storageFactory' in options) {
+                const classOptions = options;
+                const StorageClass = yield classOptions.storageFactory();
+                return new StorageClass(classOptions.options);
+            }
+            const configOptions = options;
+            if (!storageType) {
+                storageType = configOptions.storage;
+            }
+            const config = configOptions[`${storageType}Config`];
+            return yield storage_factory_1.StorageFactory.createStorage(storageType, config);
+        });
+    }
+}
+exports.FileStorageService = FileStorageService;
+//# sourceMappingURL=file-storage.service.js.map

package/src/lib/file-storage.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-storage.service.js","sourceRoot":"","sources":["../../../../../packages/nest-file-storage/src/lib/file-storage.service.ts"],"names":[],"mappings":";;;;AAAA,uDAAmD;AAInD,MAAa,kBAAkB;IAI3B,MAAM,CAAC,UAAU,CAAC,OAAiC;QAC/C,kBAAkB,CAAC,OAAO,GAAG,OAAO,CAAC;IACzC,CAAC;IAED,MAAM,CAAC,UAAU;QACb,OAAO,kBAAkB,CAAC,OAAO,CAAC;IACtC,CAAC;IAED,MAAM,CAAO,UAAU,CAAC,WAA6B;;YACjD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAGlC,IAAI,gBAAgB,IAAI,OAAO,EAAE,CAAC;gBAC9B,MAAM,YAAY,GAAG,OAAkC,CAAC;gBACxD,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,cAAc,EAAE,CAAC;gBACzD,OAAO,IAAI,YAAY,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;YAClD,CAAC;YAGD,MAAM,aAAa,GAAG,OAAmC,CAAC;YAC1D,IAAI,CAAC,WAAW,EAAE,CAAC;gBACf,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC;YACxC,CAAC;YACD,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,WAAW,QAAQ,CAAC,CAAC;YACrD,OAAO,MAAM,gCAAc,CAAC,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACnE,CAAC;KAAA;CAEJ;AA/BD,gDA+BC"}

package/src/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from './nest-file-storage.module';
+export * from './types';
+export * from './storage.factory';
+export * from './interceptor/file-storage.interceptor';
+export * from './file-storage.service';

package/src/lib/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./nest-file-storage.module"), exports);
+tslib_1.__exportStar(require("./types"), exports);
+tslib_1.__exportStar(require("./storage.factory"), exports);
+tslib_1.__exportStar(require("./interceptor/file-storage.interceptor"), exports);
+tslib_1.__exportStar(require("./file-storage.service"), exports);
+//# sourceMappingURL=index.js.map

package/src/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/nest-file-storage/src/lib/index.ts"],"names":[],"mappings":";;;AAAA,qEAA2C;AAC3C,kDAAwB;AACxB,4DAAkC;AAClC,iFAAuD;AACvD,iEAAuC"}

package/src/lib/interceptor/file-storage.interceptor.d.ts

@@ -0,0 +1,21 @@
+import { NestInterceptor } from '@nestjs/common';
+import { Request } from 'express';
+import { FileStorageEnum, StorageOptions } from '../types';
+export type FileUploadConfig = {
+    type: 'single' | 'array' | 'fields';
+    fieldName?: string;
+    maxCount?: number;
+    fields?: {
+        name: string;
+        maxCount?: number;
+    }[];
+};
+export type FileStorageInterceptorOptions = {
+    fileName?: (file: any, req?: Request) => string;
+    fileDist?: (file: any, req?: Request) => string;
+    prefix?: string;
+    storageType?: FileStorageEnum;
+    storageOptions?: StorageOptions;
+    mapToRequestBody?: (file: any, fieldName: string, req?: Request) => any;
+};
+export declare function FileStorageInterceptor(fileConfig: FileUploadConfig | string, interceptorOptions?: FileStorageInterceptorOptions): NestInterceptor;