ts-class-to-openapi 1.0.4 → 1.0.5

package/dist/transformer.d.ts

@@ -1,13 +1,4 @@
-import { type SchemaType } from './types.js';
-/**
- * Configuration options for SchemaTransformer memory management
- */
-interface TransformerOptions {
-    /** Maximum number of schemas to cache before cleanup (default: 100) */
-    maxCacheSize?: number;
-    /** Whether to automatically clean up cache (default: true) */
-    autoCleanup?: boolean;
-}
+import { type SchemaType, type TransformerOptions } from './types.js';
 /**
  * Transforms class-validator decorated classes into OpenAPI schema objects.
  * Analyzes TypeScript source files directly using the TypeScript compiler API.
@@ -59,6 +50,12 @@ declare class SchemaTransformer {
      * @private
      */
     private loadedFiles;
+    /**
+     * Set of class names currently being processed to prevent circular references
+     * Key format: "fileName:className" for uniqueness across different files
+     * @private
+     */
+    private processingClasses;
     /**
      * Private constructor for singleton pattern.
      *
@@ -83,22 +80,13 @@ declare class SchemaTransformer {
      * @private
      */
     private cleanupCache;
-    /**
-     * Gets relevant source files for a class, filtering out unnecessary files to save memory.
-     *
-     * @param className - The name of the class to find files for
-     * @param filePath - Optional specific file path
-     * @returns Array of relevant source files
-     * @private
-     */
-    private getRelevantSourceFiles;
     /**
      * Transforms a class by its name into an OpenAPI schema object.
-     * Now considers the context of the calling file to resolve ambiguous class names.
+     * 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 transform
-     * @param filePath - Optional path to the file containing the class
-     * @param contextFile - Optional context file for resolving class ambiguity
+     * @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
@@ -109,7 +97,7 @@ declare 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
      */
@@ -140,9 +128,50 @@ declare class SchemaTransformer {
     /**
      * Clears the current singleton instance. Useful for testing or when you need
      * to create a new instance with different configuration.
+     * @private
+     */
+    private static clearInstance;
+    /**
+     * Flag to prevent recursive disposal calls
+     * @private
+     */
+    private static disposingInProgress;
+    /**
+     * 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(): void;
+    /**
+     * @deprecated Use disposeInstance() instead for better clarity
+     * @private
      */
-    static clearInstance(): void;
+    private static dispose;
     static getInstance(tsConfigPath?: string, options?: TransformerOptions): SchemaTransformer;
+    /**
+     * Internal method to check if current instance is disposed
+     * @private
+     */
+    private static isInstanceDisposed;
+    /**
+     * 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<T>(cls: new (...args: any[]) => T, options?: TransformerOptions): {
+        name: string;
+        schema: SchemaType;
+    };
     /**
      * Transforms a class constructor function into an OpenAPI schema object.
      *
@@ -176,24 +205,92 @@ declare class SchemaTransformer {
      * @public
      */
     clearCache(): void;
+    /**
+     * 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
+     */
+    private dispose;
+    /**
+     * 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
+     */
+    private reset;
     /**
      * 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(): {
-        cacheSize: number;
-        loadedFiles: number;
-    };
+    private getMemoryStats;
+    /**
+     * 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
+     */
+    private isDisposed;
+    /**
+     * 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
+     */
+    private static hasActiveInstance;
     /**
      * Finds a class declaration by name within a source file.
      *
@@ -340,7 +437,7 @@ declare 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
      */
@@ -350,11 +447,19 @@ declare 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
      */
     private mapTypeToSchema;
+    /**
+     * 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
+     */
+    private isRefSchema;
     /**
      * Applies class-validator decorators to schema properties.
      * Maps validation decorators to their corresponding OpenAPI schema constraints.
@@ -471,5 +576,4 @@ export declare function transform<T>(cls: new (...args: any[]) => T, options?: T
     name: string;
     schema: SchemaType;
 };
-export type { TransformerOptions };
 export { SchemaTransformer };

package/dist/types.d.ts

@@ -3,7 +3,7 @@ type Property = {
 } & {
     type: string;
 };
-type SchemaType = {
+type SchemaType = ({
     [key: string]: any;
 } & {
     properties: {
@@ -13,7 +13,11 @@ type SchemaType = {
     required: string[];
 } & {
     type: string;
-};
+}) | ({
+    [key: string]: any;
+} & {
+    $ref: string;
+});
 /**
  * Information about a class-validator decorator found on a property.
  * @interface DecoratorInfo
@@ -38,4 +42,14 @@ interface PropertyInfo {
     /** Whether the property is optional (has ? operator) */
     isOptional: boolean;
 }
-export { type SchemaType, type Property, type DecoratorInfo, type PropertyInfo };
+/**
+ * Configuration options for SchemaTransformer memory management
+ * @interface TransformerOptions
+ */
+interface TransformerOptions {
+    /** Maximum number of schemas to cache before cleanup (default: 100) */
+    maxCacheSize?: number;
+    /** Whether to automatically clean up cache (default: true) */
+    autoCleanup?: boolean;
+}
+export { type SchemaType, type Property, type DecoratorInfo, type PropertyInfo, type TransformerOptions, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-class-to-openapi",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Transform TypeScript classes into OpenAPI 3.1.0 schema objects, which support class-validator decorators",
   "main": "./dist/index.js",
   "module": "./dist/index.esm.js",