ts-class-to-openapi 1.0.3 → 1.0.5

package/dist/index.esm.js

@@ -36,6 +36,7 @@ const validatorDecorators = {
     ArrayNotEmpty: { name: 'ArrayNotEmpty' },
     ArrayMaxSize: { name: 'ArrayMaxSize' },
     ArrayMinSize: { name: 'ArrayMinSize' },
+    IsEnum: { name: 'IsEnum', type: 'string' },
 };
 const constants = {
     TS_CONFIG_DEFAULT_PATH,
@@ -94,6 +95,12 @@ class SchemaTransformer {
      * @private
      */
     loadedFiles = new Set();
+    /**
+     * Set of class names currently being processed to prevent circular references
+     * Key format: "fileName:className" for uniqueness across different files
+     * @private
+     */
+    processingClasses = new Set();
     /**
      * Private constructor for singleton pattern.
      *
@@ -146,20 +153,19 @@ class SchemaTransformer {
         }
     }
     /**
-     * Gets relevant source files for a class, filtering out unnecessary files to save memory.
+     * Transforms a class by its name into an OpenAPI schema object.
+     * Considers the context of the calling file to resolve ambiguous class names.
+     * Includes circular reference detection to prevent infinite recursion.
      *
-     * @param className - The name of the class to find files for
-     * @param filePath - Optional specific file path
-     * @returns Array of relevant source files
+     * @param className - The name of the class to transform
+     * @param contextFilePath - Optional path to context file for resolving class ambiguity
+     * @returns Object containing the class name and its corresponding JSON schema
+     * @throws {Error} When the specified class cannot be found
      * @private
      */
-    getRelevantSourceFiles(className, filePath) {
-        if (filePath) {
-            const sourceFile = this.program.getSourceFile(filePath);
-            return sourceFile ? [sourceFile] : [];
-        }
-        // Only get source files that are not declaration files and not in node_modules
-        return this.program.getSourceFiles().filter(sf => {
+    transformByName(className, contextFilePath) {
+        // Get all relevant source files (not declaration files and not in node_modules)
+        const sourceFiles = this.program.getSourceFiles().filter(sf => {
             if (sf.isDeclarationFile)
                 return false;
             if (sf.fileName.includes('.d.ts'))
@@ -170,19 +176,46 @@ class SchemaTransformer {
             this.loadedFiles.add(sf.fileName);
             return true;
         });
-    }
-    /**
-     * Transforms a class by its name into an OpenAPI schema object.
-     *
-     * @param className - The name of the class to transform
-     * @param filePath - Optional path to the file containing the class
-     * @returns Object containing the class name and its corresponding JSON schema
-     * @throws {Error} When the specified class cannot be found
-     * @private
-     */
-    transformByName(className, filePath) {
-        const sourceFiles = this.getRelevantSourceFiles(className, filePath);
-        for (const sourceFile of sourceFiles) {
+        // If we have a context file, try to find the class in that file first
+        if (contextFilePath) {
+            const contextSourceFile = this.program.getSourceFile(contextFilePath);
+            if (contextSourceFile) {
+                const classNode = this.findClassByName(contextSourceFile, className);
+                if (classNode) {
+                    const cacheKey = this.getCacheKey(contextSourceFile.fileName, className);
+                    // Check cache first
+                    if (this.classCache.has(cacheKey)) {
+                        return this.classCache.get(cacheKey);
+                    }
+                    // Check for circular reference before processing
+                    if (this.processingClasses.has(cacheKey)) {
+                        // Return a $ref reference to break circular dependency (OpenAPI 3.1 style)
+                        return {
+                            name: className,
+                            schema: {
+                                $ref: `#/components/schemas/${className}`,
+                                description: `Reference to ${className} (circular reference detected)`,
+                            },
+                        };
+                    }
+                    // Mark this class as being processed
+                    this.processingClasses.add(cacheKey);
+                    try {
+                        const result = this.transformClass(classNode, contextSourceFile);
+                        this.classCache.set(cacheKey, result);
+                        this.cleanupCache();
+                        return result;
+                    }
+                    finally {
+                        // Always remove from processing set when done
+                        this.processingClasses.delete(cacheKey);
+                    }
+                }
+            }
+        }
+        // Fallback to searching all files, but prioritize files that are more likely to be relevant
+        const prioritizedFiles = this.prioritizeSourceFiles(sourceFiles, contextFilePath);
+        for (const sourceFile of prioritizedFiles) {
             const classNode = this.findClassByName(sourceFile, className);
             if (classNode && sourceFile?.fileName) {
                 const cacheKey = this.getCacheKey(sourceFile.fileName, className);
@@ -190,16 +223,67 @@ class SchemaTransformer {
                 if (this.classCache.has(cacheKey)) {
                     return this.classCache.get(cacheKey);
                 }
-                const result = this.transformClass(classNode);
-                // Cache using fileName:className as key for uniqueness
-                this.classCache.set(cacheKey, result);
-                // Clean up cache if it gets too large
-                this.cleanupCache();
-                return result;
+                // Check for circular reference before processing
+                if (this.processingClasses.has(cacheKey)) {
+                    // Return a $ref reference to break circular dependency (OpenAPI 3.1 style)
+                    return {
+                        name: className,
+                        schema: {
+                            $ref: `#/components/schemas/${className}`,
+                            description: `Reference to ${className} (circular reference detected)`,
+                        },
+                    };
+                }
+                // Mark this class as being processed
+                this.processingClasses.add(cacheKey);
+                try {
+                    const result = this.transformClass(classNode, sourceFile);
+                    // Cache using fileName:className as key for uniqueness
+                    this.classCache.set(cacheKey, result);
+                    // Clean up cache if it gets too large
+                    this.cleanupCache();
+                    return result;
+                }
+                finally {
+                    // Always remove from processing set when done
+                    this.processingClasses.delete(cacheKey);
+                }
             }
         }
         throw new Error(`Class ${className} not found`);
     }
+    /**
+     * Prioritizes source files based on context to resolve class name conflicts.
+     * Gives priority to files in the same directory or with similar names.
+     *
+     * @param sourceFiles - Array of source files to prioritize
+     * @param contextFilePath - Optional path to context file for prioritization
+     * @returns Prioritized array of source files
+     * @private
+     */
+    prioritizeSourceFiles(sourceFiles, contextFilePath) {
+        if (!contextFilePath) {
+            return sourceFiles;
+        }
+        const contextDir = contextFilePath.substring(0, contextFilePath.lastIndexOf('/'));
+        return sourceFiles.sort((a, b) => {
+            const aDir = a.fileName.substring(0, a.fileName.lastIndexOf('/'));
+            const bDir = b.fileName.substring(0, b.fileName.lastIndexOf('/'));
+            // Prioritize files in the same directory as context
+            const aInSameDir = aDir === contextDir ? 1 : 0;
+            const bInSameDir = bDir === contextDir ? 1 : 0;
+            if (aInSameDir !== bInSameDir) {
+                return bInSameDir - aInSameDir; // Higher priority first
+            }
+            // Prioritize non-test files over test files
+            const aIsTest = a.fileName.includes('test') || a.fileName.includes('spec') ? 0 : 1;
+            const bIsTest = b.fileName.includes('test') || b.fileName.includes('spec') ? 0 : 1;
+            if (aIsTest !== bIsTest) {
+                return bIsTest - aIsTest; // Non-test files first
+            }
+            return 0;
+        });
+    }
     /**
      * Gets the singleton instance of SchemaTransformer.
      *
@@ -226,16 +310,88 @@ class SchemaTransformer {
     /**
      * Clears the current singleton instance. Useful for testing or when you need
      * to create a new instance with different configuration.
+     * @private
      */
     static clearInstance() {
-        SchemaTransformer.instance = null;
+        SchemaTransformer.instance = undefined;
+    }
+    /**
+     * Flag to prevent recursive disposal calls
+     * @private
+     */
+    static disposingInProgress = false;
+    /**
+     * Completely disposes of the current singleton instance and releases all resources.
+     * This is a static method that can be called without having an instance reference.
+     * Ensures complete memory cleanup regardless of the current state.
+     *
+     * @example
+     * ```typescript
+     * SchemaTransformer.disposeInstance();
+     * // All resources released, next getInstance() will create fresh instance
+     * ```
+     *
+     * @public
+     */
+    static disposeInstance() {
+        // Prevent recursive disposal calls
+        if (SchemaTransformer.disposingInProgress) {
+            return;
+        }
+        SchemaTransformer.disposingInProgress = true;
+        try {
+            if (SchemaTransformer.instance) {
+                SchemaTransformer.instance.dispose();
+            }
+        }
+        catch (error) {
+            // Log any disposal errors but continue with cleanup
+            console.warn('Warning during static disposal:', error);
+        }
+        finally {
+            // Always ensure the static instance is cleared
+            SchemaTransformer.instance = undefined;
+            SchemaTransformer.disposingInProgress = false;
+            // Force garbage collection for cleanup
+            if (global.gc) {
+                global.gc();
+            }
+        }
+    }
+    /**
+     * @deprecated Use disposeInstance() instead for better clarity
+     * @private
+     */
+    static dispose() {
+        SchemaTransformer.disposeInstance();
     }
     static getInstance(tsConfigPath, options) {
-        if (!SchemaTransformer.instance) {
+        if (!SchemaTransformer.instance || SchemaTransformer.isInstanceDisposed()) {
             SchemaTransformer.instance = new SchemaTransformer(tsConfigPath, options);
         }
         return SchemaTransformer.instance;
     }
+    /**
+     * Internal method to check if current instance is disposed
+     * @private
+     */
+    static isInstanceDisposed() {
+        return SchemaTransformer.instance
+            ? SchemaTransformer.instance.isDisposed()
+            : true;
+    }
+    /**
+     * Transforms a class using the singleton instance
+     * @param cls - The class constructor function to transform
+     * @param options - Optional configuration for memory management (only used if no instance exists)
+     * @returns Object containing the class name and its corresponding JSON schema
+     * @public
+     */
+    static transformClass(cls, options) {
+        // Use the singleton instance instead of creating a temporary one
+        const transformer = SchemaTransformer.getInstance(undefined, options);
+        return transformer.transform(cls);
+    }
     /**
      * Transforms a class constructor function into an OpenAPI schema object.
      *
@@ -270,31 +426,147 @@ class SchemaTransformer {
     clearCache() {
         this.classCache.clear();
         this.loadedFiles.clear();
+        this.processingClasses.clear();
         // Force garbage collection hint if available
         if (global.gc) {
             global.gc();
         }
     }
+    /**
+     * Completely disposes of the transformer instance and releases all resources.
+     * This includes clearing all caches, releasing TypeScript program resources,
+     * and resetting the singleton instance.
+     *
+     * After calling this method, you need to call getInstance() again to get a new instance.
+     *
+     * @example
+     * ```typescript
+     * const transformer = SchemaTransformer.getInstance();
+     * // ... use transformer
+     * transformer.dispose();
+     * // transformer is now unusable, need to get new instance
+     * const newTransformer = SchemaTransformer.getInstance();
+     * ```
+     *
+     * @private
+     */
+    dispose() {
+        try {
+            // Clear all caches and sets completely
+            this.classCache.clear();
+            this.loadedFiles.clear();
+            this.processingClasses.clear();
+            // Release TypeScript program resources
+            // While TypeScript doesn't provide explicit disposal methods,
+            // we can help garbage collection by clearing all references
+            // Clear all references to TypeScript objects
+            // @ts-ignore - We're intentionally setting these to null for cleanup
+            this.program = null;
+            // @ts-ignore - We're intentionally setting these to null for cleanup
+            this.checker = null;
+        }
+        catch (error) {
+            // If there's any error during disposal, log it but continue
+            console.warn('Warning during transformer disposal:', error);
+        }
+        finally {
+            // Force garbage collection for cleanup
+            if (global.gc) {
+                global.gc();
+            }
+        }
+    }
+    /**
+     * Completely resets the transformer by disposing current instance and creating a new one.
+     * This is useful when you need a fresh start with different TypeScript configuration
+     * or want to ensure all resources are properly released and recreated.
+     *
+     * @param tsConfigPath - Optional path to a specific TypeScript config file for the new instance
+     * @param options - Configuration options for memory management for the new instance
+     * @returns A fresh SchemaTransformer instance
+     *
+     * @example
+     * ```typescript
+     * const transformer = SchemaTransformer.getInstance();
+     * // ... use transformer
+     * const freshTransformer = transformer.reset('./new-tsconfig.json');
+     * ```
+     *
+     * @private
+     */
+    reset(tsConfigPath, options) {
+        // Dispose current instance using static method to properly clear instance reference
+        SchemaTransformer.disposeInstance();
+        // Create and return new instance
+        return SchemaTransformer.getInstance(tsConfigPath, options);
+    }
     /**
      * Gets memory usage statistics for monitoring and debugging.
      *
-     * @returns Object containing cache size and loaded files count
+     * @returns Object containing cache size, loaded files count, and processing status
      *
      * @example
      * ```typescript
      * const transformer = SchemaTransformer.getInstance();
      * const stats = transformer.getMemoryStats();
      * console.log(`Cache entries: ${stats.cacheSize}, Files loaded: ${stats.loadedFiles}`);
+     * console.log(`Currently processing: ${stats.currentlyProcessing} classes`);
      * ```
      *
-     * @public
+     * @private
      */
     getMemoryStats() {
         return {
-            cacheSize: this.classCache.size,
-            loadedFiles: this.loadedFiles.size,
+            cacheSize: this.classCache?.size || 0,
+            loadedFiles: this.loadedFiles?.size || 0,
+            currentlyProcessing: this.processingClasses?.size || 0,
+            maxCacheSize: this.maxCacheSize || 0,
+            autoCleanup: this.autoCleanup || false,
+            isDisposed: !this.program || !this.checker,
         };
     }
+    /**
+     * Checks if the transformer instance has been disposed and is no longer usable.
+     *
+     * @returns True if the instance has been disposed
+     *
+     * @example
+     * ```typescript
+     * const transformer = SchemaTransformer.getInstance();
+     * transformer.dispose();
+     * console.log(transformer.isDisposed()); // true
+     * ```
+     *
+     * @private
+     */
+    isDisposed() {
+        return (!this.program ||
+            !this.checker ||
+            !this.classCache ||
+            !this.loadedFiles ||
+            !this.processingClasses);
+    }
+    /**
+     * Static method to check if there's an active singleton instance.
+     *
+     * @returns True if there's an active instance, false if disposed or never created
+     *
+     * @example
+     * ```typescript
+     * console.log(SchemaTransformer.hasActiveInstance()); // false
+     * const transformer = SchemaTransformer.getInstance();
+     * console.log(SchemaTransformer.hasActiveInstance()); // true
+     * SchemaTransformer.dispose();
+     * console.log(SchemaTransformer.hasActiveInstance()); // false
+     * ```
+     *
+     * @private
+     */
+    static hasActiveInstance() {
+        return (SchemaTransformer.instance !== null &&
+            SchemaTransformer.instance !== undefined &&
+            !SchemaTransformer.isInstanceDisposed());
+    }
     /**
      * Finds a class declaration by name within a source file.
      *
@@ -319,13 +591,14 @@ class SchemaTransformer {
      * Transforms a TypeScript class declaration into a schema object.
      *
      * @param classNode - The TypeScript class declaration node
+     * @param sourceFile - The source file containing the class (for context)
      * @returns Object containing class name and generated schema
      * @private
      */
-    transformClass(classNode) {
+    transformClass(classNode, sourceFile) {
         const className = classNode.name?.text || 'Unknown';
         const properties = this.extractProperties(classNode);
-        const schema = this.generateSchema(properties);
+        const schema = this.generateSchema(properties, sourceFile?.fileName);
         return { name: className, schema };
     }
     /**
@@ -369,6 +642,237 @@ class SchemaTransformer {
         const type = this.checker.getTypeAtLocation(property);
         return this.checker.typeToString(type);
     }
+    /**
+     * Resolves generic types by analyzing the type alias and its arguments.
+     * For example, User<Role> where User is a type alias will be resolved to its structure.
+     *
+     * @param typeNode - The TypeScript type reference node with generic arguments
+     * @returns String representation of the resolved type or schema
+     * @private
+     */
+    resolveGenericType(typeNode) {
+        const typeName = typeNode.typeName.text;
+        const typeArguments = typeNode.typeArguments;
+        if (!typeArguments || typeArguments.length === 0) {
+            return typeName;
+        }
+        // Try to resolve the type using the TypeScript type checker
+        const type = this.checker.getTypeAtLocation(typeNode);
+        const resolvedType = this.checker.typeToString(type);
+        // If we can resolve it to a meaningful structure, use that
+        if (resolvedType &&
+            resolvedType !== typeName &&
+            !resolvedType.includes('any')) {
+            // For type aliases like User<Role>, we want to create a synthetic type name
+            // that represents the resolved structure
+            const typeArgNames = typeArguments.map(arg => {
+                if (ts.isTypeReferenceNode(arg) && ts.isIdentifier(arg.typeName)) {
+                    return arg.typeName.text;
+                }
+                return this.getTypeNodeToString(arg);
+            });
+            return `${typeName}_${typeArgNames.join('_')}`;
+        }
+        return typeName;
+    }
+    /**
+     * Checks if a type string represents a resolved generic type.
+     *
+     * @param type - The type string to check
+     * @returns True if it's a resolved generic type
+     * @private
+     */
+    isResolvedGenericType(type) {
+        // Simple heuristic: resolved generic types contain underscores and
+        // the parts after underscore should be known types
+        const parts = type.split('_');
+        return (parts.length > 1 &&
+            parts
+                .slice(1)
+                .every(part => this.isKnownType(part) || this.isPrimitiveType(part)));
+    }
+    /**
+     * Checks if a type is a known class or interface.
+     *
+     * @param typeName - The type name to check
+     * @returns True if it's a known type
+     * @private
+     */
+    isKnownType(typeName) {
+        // First check if it's a primitive type to avoid unnecessary lookups
+        if (this.isPrimitiveType(typeName)) {
+            return true;
+        }
+        try {
+            // Use a more conservative approach - check if we can find the class
+            // without actually transforming it to avoid side effects
+            const found = this.findClassInProject(typeName);
+            return found !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Finds a class by name in the project without transforming it.
+     *
+     * @param className - The class name to find
+     * @returns True if found, false otherwise
+     * @private
+     */
+    findClassInProject(className) {
+        const sourceFiles = this.program.getSourceFiles().filter(sf => {
+            if (sf.isDeclarationFile)
+                return false;
+            if (sf.fileName.includes('.d.ts'))
+                return false;
+            if (sf.fileName.includes('node_modules'))
+                return false;
+            return true;
+        });
+        for (const sourceFile of sourceFiles) {
+            const found = this.findClassByName(sourceFile, className);
+            if (found)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Checks if a type is a primitive type.
+     *
+     * @param typeName - The type name to check
+     * @returns True if it's a primitive type
+     * @private
+     */
+    isPrimitiveType(typeName) {
+        const lowerTypeName = typeName.toLowerCase();
+        // Check against all primitive types from constants
+        const primitiveTypes = [
+            constants.jsPrimitives.String.type.toLowerCase(),
+            constants.jsPrimitives.Number.type.toLowerCase(),
+            constants.jsPrimitives.Boolean.type.toLowerCase(),
+            constants.jsPrimitives.Date.type.toLowerCase(),
+            constants.jsPrimitives.Buffer.type.toLowerCase(),
+            constants.jsPrimitives.Uint8Array.type.toLowerCase(),
+            constants.jsPrimitives.File.type.toLowerCase(),
+            constants.jsPrimitives.UploadFile.type.toLowerCase(),
+            constants.jsPrimitives.BigInt.type.toLowerCase(),
+        ];
+        return primitiveTypes.includes(lowerTypeName);
+    }
+    /**
+     * Resolves a generic type schema by analyzing the type alias structure.
+     *
+     * @param resolvedTypeName - The resolved generic type name (e.g., User_Role)
+     * @returns OpenAPI schema for the resolved generic type
+     * @private
+     */
+    resolveGenericTypeSchema(resolvedTypeName) {
+        const parts = resolvedTypeName.split('_');
+        const baseTypeName = parts[0];
+        const typeArgNames = parts.slice(1);
+        if (!baseTypeName) {
+            return null;
+        }
+        // Find the original type alias declaration
+        const typeAliasSymbol = this.findTypeAliasDeclaration(baseTypeName);
+        if (!typeAliasSymbol) {
+            return null;
+        }
+        // Create a schema based on the type alias structure, substituting type parameters
+        return this.createSchemaFromTypeAlias(typeAliasSymbol, typeArgNames);
+    }
+    /**
+     * Finds a type alias declaration by name.
+     *
+     * @param typeName - The type alias name to find
+     * @returns The type alias declaration node or null
+     * @private
+     */
+    findTypeAliasDeclaration(typeName) {
+        for (const sourceFile of this.program.getSourceFiles()) {
+            if (sourceFile.isDeclarationFile)
+                continue;
+            const findTypeAlias = (node) => {
+                if (ts.isTypeAliasDeclaration(node) && node.name.text === typeName) {
+                    return node;
+                }
+                return ts.forEachChild(node, findTypeAlias) || null;
+            };
+            const result = findTypeAlias(sourceFile);
+            if (result)
+                return result;
+        }
+        return null;
+    }
+    /**
+     * Creates a schema from a type alias declaration, substituting type parameters.
+     *
+     * @param typeAlias - The type alias declaration
+     * @param typeArgNames - The concrete type arguments
+     * @returns OpenAPI schema for the type alias
+     * @private
+     */
+    createSchemaFromTypeAlias(typeAlias, typeArgNames) {
+        const typeNode = typeAlias.type;
+        if (ts.isTypeLiteralNode(typeNode)) {
+            const schema = {
+                type: 'object',
+                properties: {},
+                required: [],
+            };
+            for (const member of typeNode.members) {
+                if (ts.isPropertySignature(member) &&
+                    member.name &&
+                    ts.isIdentifier(member.name)) {
+                    const propertyName = member.name.text;
+                    const isOptional = !!member.questionToken;
+                    if (member.type) {
+                        const propertyType = this.resolveTypeParameterInTypeAlias(member.type, typeAlias.typeParameters, typeArgNames);
+                        const { type, format, nestedSchema } = this.mapTypeToSchema(propertyType);
+                        if (nestedSchema) {
+                            schema.properties[propertyName] = nestedSchema;
+                        }
+                        else {
+                            schema.properties[propertyName] = { type };
+                            if (format)
+                                schema.properties[propertyName].format = format;
+                        }
+                        if (!isOptional) {
+                            schema.required.push(propertyName);
+                        }
+                    }
+                }
+            }
+            return schema;
+        }
+        return null;
+    }
+    /**
+     * Resolves type parameters in a type alias to concrete types.
+     *
+     * @param typeNode - The type node to resolve
+     * @param typeParameters - The type parameters of the type alias
+     * @param typeArgNames - The concrete type arguments
+     * @returns The resolved type string
+     * @private
+     */
+    resolveTypeParameterInTypeAlias(typeNode, typeParameters, typeArgNames) {
+        if (ts.isTypeReferenceNode(typeNode) &&
+            ts.isIdentifier(typeNode.typeName)) {
+            const typeName = typeNode.typeName.text;
+            // Check if this is a type parameter
+            if (typeParameters) {
+                const paramIndex = typeParameters.findIndex(param => param.name.text === typeName);
+                if (paramIndex !== -1 && paramIndex < typeArgNames.length) {
+                    const resolvedType = typeArgNames[paramIndex];
+                    return resolvedType || typeName;
+                }
+            }
+            return typeName;
+        }
+        return this.getTypeNodeToString(typeNode);
+    }
     /**
      * Converts a TypeScript type node to its string representation.
      *
@@ -394,6 +898,7 @@ class SchemaTransformer {
                         return firstTypeArg.typeName.text;
                     }
                 }
+                return this.resolveGenericType(typeNode);
             }
             return typeNode.typeName.text;
         }
@@ -492,19 +997,24 @@ class SchemaTransformer {
      * Generates an OpenAPI schema from extracted property information.
      *
      * @param properties - Array of property information to process
+     * @param contextFilePath - Optional context file path for resolving class references
      * @returns Complete OpenAPI schema object with properties and validation rules
      * @private
      */
-    generateSchema(properties) {
+    generateSchema(properties, contextFilePath) {
         const schema = {
             type: 'object',
             properties: {},
             required: [],
         };
         for (const property of properties) {
-            const { type, format, nestedSchema } = this.mapTypeToSchema(property.type);
+            const { type, format, nestedSchema } = this.mapTypeToSchema(property.type, contextFilePath);
             if (nestedSchema) {
                 schema.properties[property.name] = nestedSchema;
+                // Skip decorator application for $ref schemas
+                if (this.isRefSchema(nestedSchema)) {
+                    continue;
+                }
             }
             else {
                 schema.properties[property.name] = { type };
@@ -527,14 +1037,15 @@ class SchemaTransformer {
      * Handles primitive types, arrays, and nested objects recursively.
      *
      * @param type - The TypeScript type string to map
+     * @param contextFilePath - Optional context file path for resolving class references
      * @returns Object containing OpenAPI type, optional format, and nested schema
      * @private
      */
-    mapTypeToSchema(type) {
+    mapTypeToSchema(type, contextFilePath) {
         // Handle arrays
         if (type.endsWith('[]')) {
             const elementType = type.slice(0, -2);
-            const elementSchema = this.mapTypeToSchema(elementType);
+            const elementSchema = this.mapTypeToSchema(elementType, contextFilePath);
             const items = elementSchema.nestedSchema || {
                 type: elementSchema.type,
             };
@@ -578,9 +1089,31 @@ class SchemaTransformer {
                     format: constants.jsPrimitives.UploadFile.format,
                 };
             default:
+                // Check if it's a resolved generic type (e.g., User_Role)
+                if (type.includes('_') && this.isResolvedGenericType(type)) {
+                    try {
+                        const genericSchema = this.resolveGenericTypeSchema(type);
+                        if (genericSchema) {
+                            return {
+                                type: constants.jsPrimitives.Object.value,
+                                nestedSchema: genericSchema,
+                            };
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Failed to resolve generic type ${type}:`, error);
+                    }
+                }
                 // Handle nested objects
                 try {
-                    const nestedResult = this.transformByName(type);
+                    const nestedResult = this.transformByName(type, contextFilePath);
+                    // Check if it's a $ref schema (circular reference)
+                    if (nestedResult.schema.$ref) {
+                        return {
+                            type: constants.jsPrimitives.Object.value,
+                            nestedSchema: nestedResult.schema,
+                        };
+                    }
                     return {
                         type: constants.jsPrimitives.Object.value,
                         nestedSchema: nestedResult.schema,
@@ -591,6 +1124,16 @@ class SchemaTransformer {
                 }
         }
     }
+    /**
+     * Checks if a schema is a $ref schema (circular reference).
+     *
+     * @param schema - The schema to check
+     * @returns True if it's a $ref schema
+     * @private
+     */
+    isRefSchema(schema) {
+        return '$ref' in schema;
+    }
     /**
      * Applies class-validator decorators to schema properties.
      * Maps validation decorators to their corresponding OpenAPI schema constraints.
@@ -601,6 +1144,10 @@ class SchemaTransformer {
      * @private
      */
     applyDecorators(decorators, schema, propertyName) {
+        // Skip applying decorators to $ref schemas
+        if (this.isRefSchema(schema)) {
+            return;
+        }
         const isArrayType = schema.properties[propertyName].type ===
             constants.jsPrimitives.Array.value;
         for (const decorator of decorators) {
@@ -716,8 +1263,193 @@ class SchemaTransformer {
                 case constants.validatorDecorators.ArrayMaxSize.name:
                     schema.properties[propertyName].maxItems = decorator.arguments[0];
                     break;
+                case constants.validatorDecorators.IsEnum.name:
+                    this.applyEnumDecorator(decorator, schema, propertyName, isArrayType);
+                    break;
+            }
+        }
+    }
+    /**
+     * Applies the @IsEnum decorator to a property, handling both primitive values and object enums.
+     * Supports arrays of enum values as well.
+     *
+     * @param decorator - The IsEnum decorator information
+     * @param schema - The schema object to modify
+     * @param propertyName - The name of the property
+     * @param isArrayType - Whether the property is an array type
+     * @private
+     */
+    applyEnumDecorator(decorator, schema, propertyName, isArrayType) {
+        if (!decorator.arguments || decorator.arguments.length === 0) {
+            return;
+        }
+        const enumArg = decorator.arguments[0];
+        let enumValues = [];
+        // Handle different enum argument types
+        if (typeof enumArg === 'string') {
+            // This is likely a reference to an enum type name
+            // We need to try to resolve this to actual enum values
+            enumValues = this.resolveEnumValues(enumArg);
+        }
+        else if (typeof enumArg === 'object' && enumArg !== null) {
+            // Object enum - extract values
+            if (Array.isArray(enumArg)) {
+                // Already an array of values
+                enumValues = enumArg;
+            }
+            else {
+                // Enum object - get all values
+                enumValues = Object.values(enumArg);
+            }
+        }
+        // If we couldn't resolve enum values, fall back to string type without enum constraint
+        if (enumValues.length === 0) {
+            if (!isArrayType) {
+                schema.properties[propertyName].type = 'string';
+            }
+            else if (schema.properties[propertyName].items) {
+                schema.properties[propertyName].items.type = 'string';
+            }
+            return;
+        }
+        // Determine the type based on enum values
+        let enumType = 'string';
+        if (enumValues.length > 0) {
+            const firstValue = enumValues[0];
+            if (typeof firstValue === 'number') {
+                enumType = 'number';
+            }
+            else if (typeof firstValue === 'boolean') {
+                enumType = 'boolean';
+            }
+        }
+        // Apply enum to schema
+        if (!isArrayType) {
+            schema.properties[propertyName].type = enumType;
+            schema.properties[propertyName].enum = enumValues;
+        }
+        else if (schema.properties[propertyName].items) {
+            schema.properties[propertyName].items.type = enumType;
+            schema.properties[propertyName].items.enum = enumValues;
+        }
+    }
+    /**
+     * Attempts to resolve enum values from an enum type name.
+     * This searches through the TypeScript AST to find the enum declaration
+     * and extract its values.
+     *
+     * @param enumTypeName - The name of the enum type
+     * @returns Array of enum values if found, empty array otherwise
+     * @private
+     */
+    resolveEnumValues(enumTypeName) {
+        // Search for enum declarations in source files
+        for (const sourceFile of this.program.getSourceFiles()) {
+            if (sourceFile.isDeclarationFile)
+                continue;
+            if (sourceFile.fileName.includes('node_modules'))
+                continue;
+            const enumValues = this.findEnumValues(sourceFile, enumTypeName);
+            if (enumValues.length > 0) {
+                return enumValues;
+            }
+        }
+        return [];
+    }
+    /**
+     * Finds enum values in a specific source file.
+     *
+     * @param sourceFile - The source file to search
+     * @param enumTypeName - The name of the enum to find
+     * @returns Array of enum values if found, empty array otherwise
+     * @private
+     */
+    findEnumValues(sourceFile, enumTypeName) {
+        let enumValues = [];
+        const visit = (node) => {
+            // Handle TypeScript enum declarations
+            if (ts.isEnumDeclaration(node) && node.name?.text === enumTypeName) {
+                enumValues = this.extractEnumValues(node);
+                return;
+            }
+            // Handle const object declarations (like const Status = { ... } as const)
+            if (ts.isVariableStatement(node)) {
+                for (const declaration of node.declarationList.declarations) {
+                    if (ts.isVariableDeclaration(declaration) &&
+                        ts.isIdentifier(declaration.name) &&
+                        declaration.name.text === enumTypeName &&
+                        declaration.initializer) {
+                        let initializer = declaration.initializer;
+                        // Handle "as const" assertions
+                        if (ts.isAsExpression(initializer) && initializer.expression) {
+                            initializer = initializer.expression;
+                        }
+                        enumValues = this.extractObjectEnumValues(initializer);
+                        return;
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        return enumValues;
+    }
+    /**
+     * Extracts values from a TypeScript enum declaration.
+     *
+     * @param enumNode - The enum declaration node
+     * @returns Array of enum values
+     * @private
+     */
+    extractEnumValues(enumNode) {
+        const values = [];
+        for (const member of enumNode.members) {
+            if (member.initializer) {
+                // Handle initialized enum members
+                if (ts.isStringLiteral(member.initializer)) {
+                    values.push(member.initializer.text);
+                }
+                else if (ts.isNumericLiteral(member.initializer)) {
+                    values.push(Number(member.initializer.text));
+                }
+            }
+            else {
+                // Handle auto-incremented numeric enums
+                if (values.length === 0) {
+                    values.push(0);
+                }
+                else {
+                    const lastValue = values[values.length - 1];
+                    if (typeof lastValue === 'number') {
+                        values.push(lastValue + 1);
+                    }
+                }
+            }
+        }
+        return values;
+    }
+    /**
+     * Extracts values from object literal enum (const object as const).
+     *
+     * @param initializer - The object literal initializer
+     * @returns Array of enum values
+     * @private
+     */
+    extractObjectEnumValues(initializer) {
+        const values = [];
+        if (ts.isObjectLiteralExpression(initializer)) {
+            for (const property of initializer.properties) {
+                if (ts.isPropertyAssignment(property) && property.initializer) {
+                    if (ts.isStringLiteral(property.initializer)) {
+                        values.push(property.initializer.text);
+                    }
+                    else if (ts.isNumericLiteral(property.initializer)) {
+                        values.push(Number(property.initializer.text));
+                    }
+                }
             }
         }
+        return values;
     }
     /**
      * Applies sensible default behaviors for properties without class-validator decorators.
@@ -737,6 +1469,10 @@ class SchemaTransformer {
      * @private
      */
     applyTypeBasedFormats(property, schema) {
+        // Skip applying type-based formats to $ref schemas
+        if (this.isRefSchema(schema)) {
+            return;
+        }
         const propertyName = property.name;
         const propertyType = property.type.toLowerCase();
         const propertySchema = schema.properties[propertyName];
@@ -771,6 +1507,10 @@ class SchemaTransformer {
      * @private
      */
     determineRequiredStatus(property, schema) {
+        // Skip determining required status for $ref schemas
+        if (this.isRefSchema(schema)) {
+            return;
+        }
         const propertyName = property.name;
         // Check if already marked as required by IsNotEmpty or ArrayNotEmpty decorator
         const isAlreadyRequired = schema.required.includes(propertyName);
@@ -811,7 +1551,7 @@ class SchemaTransformer {
  * @public
  */
 function transform(cls, options) {
-    return SchemaTransformer.getInstance(undefined, options).transform(cls);
+    return SchemaTransformer.transformClass(cls, options);
 }
 
-export { transform };
+export { SchemaTransformer, transform };