ts-class-to-openapi 1.0.4 → 1.0.5

package/dist/index.esm.js

@@ -95,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.
      *
@@ -147,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'))
@@ -171,23 +176,9 @@ class SchemaTransformer {
             this.loadedFiles.add(sf.fileName);
             return true;
         });
-    }
-    /**
-     * Transforms a class by its name into an OpenAPI schema object.
-     * Now considers the context of the calling file to resolve ambiguous class names.
-     *
-     * @param className - The name of the class to transform
-     * @param filePath - Optional path to the file containing the class
-     * @param contextFile - Optional 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
-     */
-    transformByName(className, filePath, contextFile) {
-        const sourceFiles = this.getRelevantSourceFiles(className, filePath);
         // If we have a context file, try to find the class in that file first
-        if (contextFile) {
-            const contextSourceFile = this.program.getSourceFile(contextFile);
+        if (contextFilePath) {
+            const contextSourceFile = this.program.getSourceFile(contextFilePath);
             if (contextSourceFile) {
                 const classNode = this.findClassByName(contextSourceFile, className);
                 if (classNode) {
@@ -196,15 +187,34 @@ class SchemaTransformer {
                     if (this.classCache.has(cacheKey)) {
                         return this.classCache.get(cacheKey);
                     }
-                    const result = this.transformClass(classNode, contextSourceFile);
-                    this.classCache.set(cacheKey, result);
-                    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, 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, contextFile);
+        const prioritizedFiles = this.prioritizeSourceFiles(sourceFiles, contextFilePath);
         for (const sourceFile of prioritizedFiles) {
             const classNode = this.findClassByName(sourceFile, className);
             if (classNode && sourceFile?.fileName) {
@@ -213,12 +223,31 @@ class SchemaTransformer {
                 if (this.classCache.has(cacheKey)) {
                     return this.classCache.get(cacheKey);
                 }
-                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;
+                // 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`);
@@ -228,15 +257,15 @@ class SchemaTransformer {
      * Gives priority to files in the same directory or with similar names.
      *
      * @param sourceFiles - Array of source files to prioritize
-     * @param contextFile - Optional context file for prioritization
+     * @param contextFilePath - Optional path to context file for prioritization
      * @returns Prioritized array of source files
      * @private
      */
-    prioritizeSourceFiles(sourceFiles, contextFile) {
-        if (!contextFile) {
+    prioritizeSourceFiles(sourceFiles, contextFilePath) {
+        if (!contextFilePath) {
             return sourceFiles;
         }
-        const contextDir = contextFile.substring(0, contextFile.lastIndexOf('/'));
+        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('/'));
@@ -281,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.
      *
@@ -325,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.
      *
@@ -780,20 +997,24 @@ class SchemaTransformer {
      * Generates an OpenAPI schema from extracted property information.
      *
      * @param properties - Array of property information to process
-     * @param contextFile - Optional context file path for resolving class references
+     * @param contextFilePath - Optional context file path for resolving class references
      * @returns Complete OpenAPI schema object with properties and validation rules
      * @private
      */
-    generateSchema(properties, contextFile) {
+    generateSchema(properties, contextFilePath) {
         const schema = {
             type: 'object',
             properties: {},
             required: [],
         };
         for (const property of properties) {
-            const { type, format, nestedSchema } = this.mapTypeToSchema(property.type, contextFile);
+            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 };
@@ -816,15 +1037,15 @@ class SchemaTransformer {
      * Handles primitive types, arrays, and nested objects recursively.
      *
      * @param type - The TypeScript type string to map
-     * @param contextFile - Optional context file path for resolving class references
+     * @param contextFilePath - Optional context file path for resolving class references
      * @returns Object containing OpenAPI type, optional format, and nested schema
      * @private
      */
-    mapTypeToSchema(type, contextFile) {
+    mapTypeToSchema(type, contextFilePath) {
         // Handle arrays
         if (type.endsWith('[]')) {
             const elementType = type.slice(0, -2);
-            const elementSchema = this.mapTypeToSchema(elementType, contextFile);
+            const elementSchema = this.mapTypeToSchema(elementType, contextFilePath);
             const items = elementSchema.nestedSchema || {
                 type: elementSchema.type,
             };
@@ -885,7 +1106,14 @@ class SchemaTransformer {
                 }
                 // Handle nested objects
                 try {
-                    const nestedResult = this.transformByName(type, undefined, contextFile);
+                    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,
@@ -896,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.
@@ -906,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) {
@@ -1227,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];
@@ -1261,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);
@@ -1301,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 };