Feature Typeorm support

Author: Mishhub

README.md

@@ -27,11 +27,13 @@ A powerful and flexible NestJS module for integrating MinIO object storage into
   - `@FileUpload()` - Handles multiple file uploads with built-in validation
   - `@FileField()` - Swagger-ready DTO field decorator
   - `@FileSchemaField()` - Mongoose schema integration for file fields
+- 🗃️ `@FileColumn()` decorator for TypeORM or any class-based model
 - 📁 Complete MinIO operations support (upload, download, delete, etc.)
 - 🔧 Configurable module options
 - 🎯 TypeScript support
 - 📝 Swagger documentation support
 - 🔄 RxJS integration
+- 🤖 Automatic presigned URL detection even for raw QueryBuilder results
 
 ## Installation
 
@@ -176,7 +178,26 @@ export class UserController {
 }
 ```
 
-4. (Optional) Add file fields to your Mongoose schema:
+4. (Optional) Add file fields to your persistence models:
+
+### TypeORM example
+
+```typescript
+import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
+import { FileColumn } from 'nestjs-minio-backend';
+
+@Entity()
+export class User {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @FileColumn({ bucketName: 'profiles' })
+  @Column({ nullable: true })
+  avatar?: string; // Stores the MinIO object path (bucket/objectName)
+}
+```
+
+### Mongoose example
 
 ```typescript
 import { FileSchemaField } from 'nestjs-minio-backend';
@@ -196,6 +217,7 @@ These decorators provide:
 - 📝 Automatic Swagger documentation
 - ✅ Built-in validation
 - 🔄 Seamless MongoDB integration
+- 🤖 Automatic presigned URL generation even for raw QueryBuilder objects (bucket names are auto-detected from your MinIO config)
 - 🎯 Type safety with TypeScript
 
 ## Configuration
@@ -368,7 +390,7 @@ Swagger-ready DTO field decorator for file uploads.
 ```
 
 #### @FileSchemaField()
-Mongoose schema integration for file fields.
+Mongoose schema integration for file fields (wraps `@Prop` plus `@FileColumn` metadata).
 
 ```typescript
 @FileSchemaField({
@@ -377,6 +399,15 @@ Mongoose schema integration for file fields.
 })
 ```
 
+#### @FileColumn()
+Database-agnostic decorator for marking entity properties that store MinIO object references. Works with TypeORM, Mongoose, or any class-based model.
+
+```typescript
+@FileColumn({
+  bucketName?: string        // Optionally enforce a specific bucket
+})
+```
+
 ## Contributing
 
 1. Fork it ([https://github.com/UtilKit/nestjs-minio-backend/fork](https://github.com/UtilKit/nestjs-minio-backend/fork))

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-minio-backend",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "NestJS module for MinIO integration",
   "author": "Mishhub",
   "license": "MIT",
@@ -60,10 +60,10 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "@nestjs/common": "^10.0.0",
-    "@nestjs/core": "^10.0.0",
-    "@nestjs/mongoose": "^10.0.0",
-    "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/mongoose": "^10.0.0 || ^11.0.0",
+    "@nestjs/platform-express": "^10.0.0 || ^11.0.0",
     "@nestjs/swagger": "^8.0.0",
     "class-validator": "^0.14.1",
     "minio": "^8.0.5",

package.json

@@ -1 +1,2 @@
 export const MINIO_CONFIG = 'MINIO_CONFIG';
+export const MINIO_FILE_FIELD_METADATA = 'MINIO_FILE_FIELD_METADATA';

src/constants.ts

@@ -0,0 +1,20 @@
+import { applyDecorators } from '@nestjs/common';
+import { MINIO_FILE_FIELD_METADATA } from '../constants';
+
+export interface FileColumnOptions {
+  bucketName?: string;
+}
+
+export function FileColumn(options: FileColumnOptions = {}): PropertyDecorator {
+  return applyDecorators((target: object, propertyKey: string | symbol) => {
+    Reflect.defineMetadata(
+      MINIO_FILE_FIELD_METADATA,
+      {
+        bucketName: options.bucketName,
+      },
+      target,
+      propertyKey,
+    );
+  });
+}
+

src/decorators/file-column.decorator.ts

@@ -1,6 +1,7 @@
 import { applyDecorators } from '@nestjs/common';
 import { ApiProperty } from '@nestjs/swagger';
 import { IsOptional } from 'class-validator';
+import { FileColumn } from './file-column.decorator';
 
 export interface FileFieldOptions {
   bucketName: string;
@@ -13,6 +14,7 @@ export function FileField(options: FileFieldOptions): PropertyDecorator {
 
   // Store metadata on the property
   return applyDecorators(
+    FileColumn({ bucketName }),
     ApiProperty({
       type: 'string',
       format: 'binary',

src/decorators/file-field.decorator.ts

@@ -1,17 +1,15 @@
+import { applyDecorators } from '@nestjs/common';
 import { Prop, PropOptions } from '@nestjs/mongoose';
+import { FileColumn, FileColumnOptions } from './file-column.decorator';
 
-export type FileSchemaFieldOptions = PropOptions & {
-  bucketName?: string;
-};
+export type FileSchemaFieldOptions = PropOptions & FileColumnOptions;
 
 export function FileSchemaField(options: FileSchemaFieldOptions = {}): PropertyDecorator {
-  // Add a metadata marker to identify this as a file field
   const fileOptions = {
     ...(options as object),
     isFileField: true,
     bucketName: options.bucketName || 'media-files-bucket',
   };
 
-  // Use the standard Prop decorator with our custom metadata
-  return Prop(fileOptions);
+  return applyDecorators(FileColumn(options), Prop(fileOptions));
 }

src/decorators/file-schema-field.decorator.ts

@@ -1,7 +1,7 @@
 import { applyDecorators, UseInterceptors } from '@nestjs/common';
 import { FileFieldsInterceptor } from '@nestjs/platform-express';
 import { ApiConsumes } from '@nestjs/swagger';
-import { FileFieldConfig } from 'src/interfaces/file-field.interface';
+import { FileFieldConfig } from '../interfaces/file-field.interface';
 import { MinioFileInterceptor } from '../interceptors/file.interceptor';
 
 export function FileUpload(fileFields: FileFieldConfig[]): PropertyDecorator {

src/decorators/file-upload.decorator.ts

@@ -1,6 +1,7 @@
 export * from './decorators/file-field.decorator';
 export * from './decorators/file-upload.decorator';
 export * from './decorators/file-schema-field.decorator';
+export * from './decorators/file-column.decorator';
 export * from './minio.service';
 export * from './minio.module';
 export * from './interfaces/file.interface';

src/index.ts

@@ -4,6 +4,7 @@ import { map } from 'rxjs/operators';
 import { MinioService } from '../minio.service';
 import { Socket } from 'net';
 import { IncomingMessage, ServerResponse } from 'http';
+import { MINIO_FILE_FIELD_METADATA } from '../constants';
 
 @Injectable()
 export class FileUrlTransformInterceptor implements NestInterceptor {
@@ -34,7 +35,7 @@ export class FileUrlTransformInterceptor implements NestInterceptor {
    * @returns The transformed data with URLs replaced by presigned URLs.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private async transformUrls(data: any): Promise<any> {
+  private async transformUrls(data: any, visited = new WeakSet<object>()): Promise<any> {
     if (!data) return data;
 
     // Skip processing for Node.js internal objects (HTTP, Socket, etc.)
@@ -47,6 +48,13 @@ export class FileUrlTransformInterceptor implements NestInterceptor {
       return data;
     }
 
+    if (typeof data === 'object' && data !== null) {
+      if (visited.has(data)) {
+        return data;
+      }
+      visited.add(data);
+    }
+
     // If it's a mongoose document, convert to plain object
     const obj = data.toJSON ? data.toJSON() : data;
 
@@ -60,14 +68,19 @@ export class FileUrlTransformInterceptor implements NestInterceptor {
 
     // Process each property recursively
     for (const [key, value] of Object.entries(obj)) {
-      // Check if this field is decorated with FileSchemaField
-      const isFileField = schema?.paths?.[key]?.options?.isFileField;
+      // Check if this field is decorated with FileSchemaField or FileColumn
+      const isFileField =
+        schema?.paths?.[key]?.options?.isFileField ||
+        this.hasFileFieldMetadata(data, key) ||
+        this.hasFileFieldMetadata(obj, key);
 
-      if (isFileField && typeof value === 'string' && value.includes('/')) {
-        const [bucketName, ...pathParts] = value.split('/');
-        if (pathParts.length > 0) {
+      const inferredPath = !isFileField ? this.extractMinioPath(value) : null;
+
+      if ((isFileField || inferredPath) && typeof value === 'string') {
+        const split = inferredPath ?? this.splitBucketAndObject(value);
+        if (split) {
           try {
-            obj[key] = await this.minioService.getPresignedUrl(bucketName, pathParts.join('/'));
+            obj[key] = await this.minioService.getPresignedUrl(split.bucketName, split.objectName);
           } catch (error) {
             this.logger.error(`Error generating presigned URL for ${key}:`, error);
           }
@@ -77,21 +90,59 @@ export class FileUrlTransformInterceptor implements NestInterceptor {
       else if (
         value &&
         typeof value === 'object' &&
-        !Array.isArray(value) &&
-        Object.getPrototypeOf(value) === Object.prototype
+        !Array.isArray(value)
       ) {
-        obj[key] = await this.transformUrls(value);
+        obj[key] = await this.transformUrls(value, visited);
       }
       // Handle arrays of objects recursively
       else if (Array.isArray(value)) {
         obj[key] = await Promise.all(
           value.map((item) =>
-            typeof item === 'object' && item !== null ? this.transformUrls(item) : item,
+            typeof item === 'object' && item !== null ? this.transformUrls(item, visited) : item,
           ),
         );
       }
     }
 
     return obj;
   }
+
+  private hasFileFieldMetadata(target: unknown, propertyKey: string): boolean {
+    if (!target) return false;
+
+    const directMetadata = Reflect.getMetadata(MINIO_FILE_FIELD_METADATA, target, propertyKey);
+    if (directMetadata) {
+      return true;
+    }
+
+    const prototype = typeof target === 'object' ? Object.getPrototypeOf(target) : undefined;
+    if (!prototype) {
+      return false;
+    }
+
+    return Boolean(Reflect.getMetadata(MINIO_FILE_FIELD_METADATA, prototype, propertyKey));
+  }
+
+  private extractMinioPath(value: unknown): { bucketName: string; objectName: string } | null {
+    if (typeof value !== 'string') {
+      return null;
+    }
+
+    const split = this.splitBucketAndObject(value);
+    return split;
+  }
+
+  private splitBucketAndObject(value: string): { bucketName: string; objectName: string } | null {
+    if (!value.includes('/')) {
+      return null;
+    }
+    const [bucketName, ...pathParts] = value.split('/');
+    if (!bucketName || pathParts.length === 0) {
+      return null;
+    }
+    return {
+      bucketName,
+      objectName: pathParts.join('/'),
+    };
+  }
 }