ts-class-to-openapi 1.0.3 → 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,25 +80,28 @@ 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.
+     * 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 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
      */
     private transformByName;
+    /**
+     * 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
+     */
+    private prioritizeSourceFiles;
     /**
      * Gets the singleton instance of SchemaTransformer.
      *
@@ -128,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
      */
-    static clearInstance(): void;
+    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
+     */
+    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.
      *
@@ -164,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.
      *
@@ -195,6 +304,7 @@ declare 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
      */
@@ -215,6 +325,82 @@ declare class SchemaTransformer {
      * @private
      */
     private getPropertyType;
+    /**
+     * 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
+     */
+    private resolveGenericType;
+    /**
+     * 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
+     */
+    private isResolvedGenericType;
+    /**
+     * 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
+     */
+    private isKnownType;
+    /**
+     * 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
+     */
+    private findClassInProject;
+    /**
+     * Checks if a type is a primitive type.
+     *
+     * @param typeName - The type name to check
+     * @returns True if it's a primitive type
+     * @private
+     */
+    private isPrimitiveType;
+    /**
+     * 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
+     */
+    private resolveGenericTypeSchema;
+    /**
+     * Finds a type alias declaration by name.
+     *
+     * @param typeName - The type alias name to find
+     * @returns The type alias declaration node or null
+     * @private
+     */
+    private findTypeAliasDeclaration;
+    /**
+     * 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
+     */
+    private createSchemaFromTypeAlias;
+    /**
+     * 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
+     */
+    private resolveTypeParameterInTypeAlias;
     /**
      * Converts a TypeScript type node to its string representation.
      *
@@ -251,6 +437,7 @@ declare 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
      */
@@ -260,10 +447,19 @@ declare 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
      */
     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.
@@ -274,6 +470,52 @@ declare class SchemaTransformer {
      * @private
      */
     private applyDecorators;
+    /**
+     * 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
+     */
+    private applyEnumDecorator;
+    /**
+     * 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
+     */
+    private resolveEnumValues;
+    /**
+     * 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
+     */
+    private findEnumValues;
+    /**
+     * Extracts values from a TypeScript enum declaration.
+     *
+     * @param enumNode - The enum declaration node
+     * @returns Array of enum values
+     * @private
+     */
+    private extractEnumValues;
+    /**
+     * Extracts values from object literal enum (const object as const).
+     *
+     * @param initializer - The object literal initializer
+     * @returns Array of enum values
+     * @private
+     */
+    private extractObjectEnumValues;
     /**
      * Applies sensible default behaviors for properties without class-validator decorators.
      * This allows the schema generator to work with plain TypeScript classes.
@@ -334,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/transformer.fixtures.d.ts

@@ -140,6 +140,10 @@ declare const constants: {
         ArrayMinSize: {
             name: string;
         };
+        IsEnum: {
+            name: string;
+            type: string;
+        };
     };
 };
 export { messages, constants };

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.3",
+  "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",