ts-class-to-openapi 1.0.5 → 1.0.6

package/dist/transformer.d.ts

@@ -1,579 +1,5 @@
-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.
- * Implemented as a singleton for performance optimization.
- *
- * @example
- * ```typescript
- * const transformer = SchemaTransformer.getInstance();
- * const schema = transformer.transform(User);
- * console.log(schema);
- * ```
- *
- * @public
- */
-declare class SchemaTransformer {
-    /**
-     * Singleton instance
-     * @private
-     */
-    private static instance;
-    /**
-     * TypeScript program instance for analyzing source files.
-     * @private
-     */
-    private program;
-    /**
-     * TypeScript type checker for resolving types.
-     * @private
-     */
-    private checker;
-    /**
-     * Cache for storing transformed class schemas to avoid reprocessing.
-     * Key format: "fileName:className" for uniqueness across different files.
-     * @private
-     */
-    private classCache;
-    /**
-     * Maximum number of entries to keep in cache before cleanup
-     * @private
-     */
-    private readonly maxCacheSize;
-    /**
-     * Whether to automatically clean up cache
-     * @private
-     */
-    private readonly autoCleanup;
-    /**
-     * Set of file paths that have been loaded to avoid redundant processing
-     * @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.
-     *
-     * @param tsConfigPath - Optional path to a specific TypeScript config file
-     * @param options - Configuration options for memory management
-     * @throws {Error} When TypeScript configuration cannot be loaded
-     * @private
-     */
-    private constructor();
-    /**
-     * Generates a unique cache key using file name and class name.
-     *
-     * @param fileName - The source file name
-     * @param className - The class name
-     * @returns Unique cache key in format "fileName:className"
-     * @private
-     */
-    private getCacheKey;
-    /**
-     * Cleans up cache when it exceeds maximum size to prevent memory leaks.
-     * Removes oldest entries using LRU strategy.
-     * @private
-     */
-    private cleanupCache;
-    /**
-     * 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 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.
-     *
-     * @param tsConfigPath - Optional path to a specific TypeScript config file (only used on first call)
-     * @param options - Configuration options for memory management (only used on first call)
-     * @returns The singleton instance
-     *
-     * @example
-     * ```typescript
-     * const transformer = SchemaTransformer.getInstance();
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // With memory optimization options
-     * const transformer = SchemaTransformer.getInstance('./tsconfig.json', {
-     *   maxCacheSize: 50,
-     *   autoCleanup: true
-     * });
-     * ```
-     *
-     * @public
-     */
-    /**
-     * 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
-     */
-    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.
-     *
-     * @param cls - The class constructor function to transform
-     * @returns Object containing the class name and its corresponding JSON schema
-     *
-     * @example
-     * ```typescript
-     * import { User } from './entities/user.js';
-     * const transformer = SchemaTransformer.getInstance();
-     * const schema = transformer.transform(User);
-     * ```
-     *
-     * @public
-     */
-    transform(cls: Function): {
-        name: string;
-        schema: SchemaType;
-    };
-    /**
-     * Clears all cached schemas and loaded file references to free memory.
-     * Useful for long-running applications or when processing many different classes.
-     *
-     * @example
-     * ```typescript
-     * const transformer = SchemaTransformer.getInstance();
-     * // After processing many classes...
-     * transformer.clearCache();
-     * ```
-     *
-     * @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, 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`);
-     * ```
-     *
-     * @private
-     */
-    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.
-     *
-     * @param sourceFile - The TypeScript source file to search in
-     * @param className - The name of the class to find
-     * @returns The class declaration node if found, undefined otherwise
-     * @private
-     */
-    private findClassByName;
-    /**
-     * 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
-     */
-    private transformClass;
-    /**
-     * Extracts property information from a class declaration.
-     *
-     * @param classNode - The TypeScript class declaration node
-     * @returns Array of property information including names, types, decorators, and optional status
-     * @private
-     */
-    private extractProperties;
-    /**
-     * Gets the TypeScript type of a property as a string.
-     *
-     * @param property - The property declaration to analyze
-     * @returns String representation of the property's type
-     * @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.
-     *
-     * @param typeNode - The TypeScript type node to convert
-     * @returns String representation of the type
-     * @private
-     */
-    private getTypeNodeToString;
-    /**
-     * Extracts decorator information from a property declaration.
-     *
-     * @param member - The property declaration to analyze
-     * @returns Array of decorator information including names and arguments
-     * @private
-     */
-    private extractDecorators;
-    /**
-     * Gets the name of a decorator from a call expression.
-     *
-     * @param callExpression - The decorator call expression
-     * @returns The decorator name or "unknown" if not identifiable
-     * @private
-     */
-    private getDecoratorName;
-    /**
-     * Extracts arguments from a decorator call expression.
-     *
-     * @param callExpression - The decorator call expression
-     * @returns Array of parsed decorator arguments
-     * @private
-     */
-    private getDecoratorArguments;
-    /**
-     * 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
-     */
-    private generateSchema;
-    /**
-     * Maps TypeScript types to OpenAPI schema types and formats.
-     * 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.
-     *
-     * @param decorators - Array of decorator information to apply
-     * @param schema - The schema object to modify
-     * @param propertyName - Name of the property being processed
-     * @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.
-     *
-     * @param property - The property information
-     * @param schema - The schema object to modify
-     * @private
-     */
-    /**
-     * Applies OpenAPI format specifications based on TypeScript types.
-     * This method is called when no decorators are present to set appropriate
-     * format values for primitive types according to OpenAPI specification.
-     *
-     * @param property - The property information containing type details
-     * @param schema - The schema object to modify
-     * @private
-     */
-    private applyTypeBasedFormats;
-    /**
-     * Determines if a property should be required based on decorators and optional status.
-     *
-     * Logic:
-     * - If property has IsNotEmpty or ArrayNotEmpty decorator, it's required (handled in applyDecorators)
-     * - Otherwise, the property is not required (preserving original behavior)
-     * - The isOptional information is stored for future use and documentation
-     *
-     * @param property - The property information
-     * @param schema - The schema object to modify
-     * @private
-     */
-    private determineRequiredStatus;
-}
-/**
- * Convenience function to transform a class using the singleton instance.
- *
- * @param cls - The class constructor function to transform
- * @param options - Optional configuration for memory management
- * @returns Object containing the class name and its corresponding JSON schema
- *
- * @example
- * ```typescript
- * import { transform } from 'class-validator-to-open-api'
- * import { User } from './entities/user.js'
- *
- * const schema = transform(User)
- * console.log(schema)
- * ```
- *
- * @example
- * ```typescript
- * // With memory optimization
- * const schema = transform(User, { maxCacheSize: 50, autoCleanup: true })
- * ```
- *
- * @public
- */
+import { SchemaType, TransformerOptions } from './types';
 export declare function transform<T>(cls: new (...args: any[]) => T, options?: TransformerOptions): {
     name: string;
     schema: SchemaType;
 };
-export { SchemaTransformer };

package/dist/transformer.fixtures.d.ts

@@ -12,6 +12,14 @@ declare const constants: {
             type: string;
             value: string;
         };
+        Any: {
+            type: string;
+            value: string;
+        };
+        Unknown: {
+            type: string;
+            value: string;
+        };
         Number: {
             type: string;
             value: string;
@@ -117,6 +125,9 @@ declare const constants: {
         IsNotEmpty: {
             name: string;
         };
+        IsOptional: {
+            name: string;
+        };
         IsBoolean: {
             name: string;
             type: string;
@@ -145,5 +156,15 @@ declare const constants: {
             type: string;
         };
     };
+    tsUtilityTypes: {
+        Partial: {
+            type: string;
+            value: string;
+        };
+        Required: {
+            type: string;
+            value: string;
+        };
+    };
 };
 export { messages, constants };

package/dist/types.d.ts

@@ -1,22 +1,31 @@
-type Property = {
+import ts from 'typescript';
+type Property = ({
     [key: string]: any;
 } & {
     type: string;
-};
+}) | SchemaType;
 type SchemaType = ({
     [key: string]: any;
 } & {
     properties: {
         [key: string]: any;
+    } & {
+        additionalProperties?: boolean;
     };
 } & {
-    required: string[];
+    required?: string[];
 } & {
     type: string;
 }) | ({
     [key: string]: any;
 } & {
     $ref: string;
+}) | ({
+    [key: string]: any;
+} & {
+    type: 'array';
+} & {
+    items: SchemaType;
 });
 /**
  * Information about a class-validator decorator found on a property.
@@ -41,6 +50,16 @@ interface PropertyInfo {
     decorators: DecoratorInfo[];
     /** Whether the property is optional (has ? operator) */
     isOptional: boolean;
+    /** Whether the property type is a generic type */
+    isGeneric: boolean;
+    /** Whether the property type is a primitive type */
+    isPrimitive: boolean;
+    /** Whether the property type is a class type */
+    isClassType?: boolean;
+    /** Whether the property type is an array type */
+    isArray?: boolean;
+    /** The original TypeScript property declaration (optional) */
+    originalProperty: ts.PropertyDeclaration;
 }
 /**
  * Configuration options for SchemaTransformer memory management
@@ -51,5 +70,21 @@ interface TransformerOptions {
     maxCacheSize?: number;
     /** Whether to automatically clean up cache (default: true) */
     autoCleanup?: boolean;
+    /** Options related to the source of the class being transformed */
+    sourceOptions?: {
+        /** Whether the class is from an external module */
+        isExternal: true;
+        /** The package name (required when isExternal is true) */
+        packageName: string;
+        /** The file path of the class being transformed */
+        filePath?: string;
+    } | {
+        /** Whether the class is from an external module */
+        isExternal: false;
+        /** The package name (optional when isExternal is false) */
+        packageName: never;
+        /** The file path of the class being transformed */
+        filePath?: string;
+    };
 }
 export { type SchemaType, type Property, type DecoratorInfo, type PropertyInfo, type TransformerOptions, };