ts-class-to-openapi 1.2.1 → 1.2.3

package/README.md

@@ -231,7 +231,7 @@ const schema = transform(User)
 
 ### 4. Enumerations and Special Types
 
-Full compatibility with TypeScript enumerations:
+Full compatibility with TypeScript enumerations (both decorated and pure):
 
 ```typescript
 import { transform } from 'ts-class-to-openapi'
@@ -253,6 +253,9 @@ class Task {
   @IsEnum(UserType)
   assignedTo: UserType
 
+  // Pure TypeScript enum (automatically detected without decorator)
+  status: UserType
+
   @IsEnum(Priority)
   priority?: Priority
 
@@ -276,6 +279,10 @@ const schema = transform(Task)
         "type": "string",
         "enum": ["admin", "user", "moderator"]
       },
+      "status": {
+        "type": "string",
+        "enum": ["admin", "user", "moderator"]
+      },
       "priority": {
         "type": "number",
         "enum": [1, 2, 3]
@@ -287,7 +294,7 @@ const schema = transform(Task)
         "format": "date-time"
       }
     },
-    "required": ["assignedTo", "title", "completed", "dueDate"]
+    "required": ["assignedTo", "status", "title", "completed", "dueDate"]
   }
 }
 ```

package/dist/__test__/entities/collision/arrays/number-array.d.ts

@@ -0,0 +1,3 @@
+export declare class ArrayCollision {
+    tags: number[];
+}

package/dist/__test__/entities/collision/arrays/string-array.d.ts

@@ -0,0 +1,3 @@
+export declare class ArrayCollision {
+    tags: string[];
+}

package/dist/__test__/entities/collision/number-props/same-name.d.ts

@@ -0,0 +1,5 @@
+export declare class SameNameClass {
+    prop1: number;
+    prop2: number;
+    prop3: number;
+}

package/dist/__test__/entities/collision/string-props/same-name.d.ts

@@ -0,0 +1,5 @@
+export declare class SameNameClass {
+    prop1: string;
+    prop2: string;
+    prop3: string;
+}

package/dist/__test__/entities/collision/throwing/class-a.d.ts

@@ -0,0 +1,4 @@
+export declare class ThrowingClass {
+    uniqueA: string;
+    constructor();
+}

package/dist/__test__/entities/collision/throwing/class-b.d.ts

@@ -0,0 +1,4 @@
+export declare class ThrowingClass {
+    uniqueB: boolean;
+    constructor();
+}

package/dist/__test__/entities/enum-classes.d.ts

@@ -0,0 +1,30 @@
+export declare enum UserRole {
+    ADMIN = "admin",
+    USER = "user",
+    GUEST = "guest"
+}
+export declare enum OrderStatus {
+    PENDING = 0,
+    PROCESSING = 1,
+    SHIPPED = 2,
+    DELIVERED = 3,
+    CANCELLED = 4
+}
+export declare enum MixedEnum {
+    YES = "yes",
+    NO = 0
+}
+export declare class EnumTestEntity {
+    role: UserRole;
+    status: OrderStatus;
+    mixed: MixedEnum;
+}
+export declare class ArrayEnumTestEntity {
+    roles: UserRole[];
+    statuses: OrderStatus[];
+}
+export declare class PureEnumTestEntity {
+    role: UserRole;
+    status: OrderStatus;
+    mixed: MixedEnum;
+}

package/dist/__test__/entities/evaluation/generics.d.ts

@@ -0,0 +1,6 @@
+export declare class Base<T> {
+    data: T;
+}
+export declare class ConcreteString extends Base<string> {
+    other: number;
+}

package/dist/__test__/entities/evaluation/modifiers.d.ts

@@ -0,0 +1,7 @@
+export declare class AccessorAndModifiers {
+    publicProp: string;
+    private privateProp;
+    protected protectedProp: string;
+    static staticProp: string;
+    get computedProp(): string;
+}

package/dist/__test__/index.d.ts

@@ -1,3 +1,7 @@
 import './testCases/pure-classes.test';
 import './testCases/decorated-classes.test';
 import './testCases/nested-classes.test';
+import './testCases/enum-properties.test';
+import './testCases/collision.test';
+import './testCases/collision-advanced.test';
+import './testCases/generics-and-modifiers.test';

package/dist/__test__/testCases/collision.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__test__/testCases/enum-properties.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__test__/testCases/generics-and-modifiers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.esm.js

@@ -66,14 +66,14 @@ class SchemaTransformer {
         this.program = ts.createProgram(fileNames, tsOptions);
         this.checker = this.program.getTypeChecker();
     }
-    getPropertiesByClassDeclaration(classNode, visitedDeclarations = new Set()) {
+    getPropertiesByClassDeclaration(classNode, visitedDeclarations = new Set(), genericTypeMap = new Map()) {
         if (visitedDeclarations.has(classNode)) {
             return [];
         }
         visitedDeclarations.add(classNode);
         // if no heritage clauses, get properties directly from class
         if (!classNode.heritageClauses) {
-            return this.getPropertiesByClassMembers(classNode.members, classNode);
+            return this.getPropertiesByClassMembers(classNode.members, classNode, genericTypeMap);
         } // use heritage clauses to get properties from base classes
         else {
             const heritageClause = classNode.heritageClauses[0];
@@ -89,28 +89,47 @@ class SchemaTransformer {
                     return [];
                 const declaration = symbol.declarations?.[0];
                 if (declaration && ts.isClassDeclaration(declaration)) {
-                    baseProperties = this.getPropertiesByClassDeclaration(declaration, visitedDeclarations);
+                    const newGenericTypeMap = new Map();
+                    if (declaration.typeParameters && type.typeArguments) {
+                        declaration.typeParameters.forEach((param, index) => {
+                            const arg = type.typeArguments[index];
+                            if (arg) {
+                                const resolvedArg = this.getTypeNodeToString(arg, genericTypeMap);
+                                newGenericTypeMap.set(param.name.text, resolvedArg);
+                            }
+                        });
+                    }
+                    baseProperties = this.getPropertiesByClassDeclaration(declaration, visitedDeclarations, newGenericTypeMap);
                 }
-                properties = this.getPropertiesByClassMembers(classNode.members, classNode);
+                properties = this.getPropertiesByClassMembers(classNode.members, classNode, genericTypeMap);
                 return baseProperties.concat(properties);
             }
             else {
-                return this.getPropertiesByClassMembers(classNode.members, classNode);
+                return this.getPropertiesByClassMembers(classNode.members, classNode, genericTypeMap);
             }
         }
     }
-    getPropertiesByClassMembers(members, parentClassNode) {
+    getPropertiesByClassMembers(members, parentClassNode, genericTypeMap = new Map()) {
         const properties = [];
         for (const member of members) {
             if (ts.isPropertyDeclaration(member) &&
                 member.name &&
                 ts.isIdentifier(member.name)) {
+                // Skip static, private, and protected properties
+                if (member.modifiers) {
+                    const hasExcludedModifier = member.modifiers.some(m => m.kind === ts.SyntaxKind.StaticKeyword ||
+                        m.kind === ts.SyntaxKind.PrivateKeyword ||
+                        m.kind === ts.SyntaxKind.ProtectedKeyword);
+                    if (hasExcludedModifier)
+                        continue;
+                }
                 const propertyName = member.name.text;
-                const type = this.getPropertyType(member);
+                const type = this.getPropertyType(member, genericTypeMap);
                 const decorators = this.extractDecorators(member);
                 const isOptional = !!member.questionToken;
                 const isGeneric = this.isPropertyTypeGeneric(member);
-                const isPrimitive = this.isPrimitiveType(type);
+                const isEnum = this.isEnum(member);
+                const isPrimitive = this.isPrimitiveType(type) || isEnum;
                 const isClassType = this.isClassType(member);
                 const isArray = this.isArrayProperty(member);
                 const isTypeLiteral = this.isTypeLiteral(member);
@@ -124,6 +143,7 @@ class SchemaTransformer {
                     isPrimitive,
                     isClassType,
                     isArray,
+                    isEnum,
                     isRef: false,
                     isTypeLiteral: isTypeLiteral,
                 };
@@ -164,17 +184,21 @@ class SchemaTransformer {
         }
         return properties;
     }
-    getPropertyType(property) {
+    getPropertyType(property, genericTypeMap = new Map()) {
         if (property.type) {
-            return this.getTypeNodeToString(property.type);
+            return this.getTypeNodeToString(property.type, genericTypeMap);
         }
         const type = this.checker.getTypeAtLocation(property);
         return this.getStringFromType(type);
     }
-    getTypeNodeToString(typeNode) {
+    getTypeNodeToString(typeNode, genericTypeMap = new Map()) {
         if (ts.isTypeReferenceNode(typeNode) &&
             ts.isIdentifier(typeNode.typeName)) {
-            if (typeNode.typeName.text.toLowerCase() === 'uploadfile') {
+            const typeName = typeNode.typeName.text;
+            if (genericTypeMap.has(typeName)) {
+                return genericTypeMap.get(typeName);
+            }
+            if (typeName.toLowerCase() === 'uploadfile') {
                 return 'UploadFile';
             }
             if (typeNode.typeArguments && typeNode.typeArguments.length > 0) {
@@ -199,11 +223,11 @@ class SchemaTransformer {
                 return constants.jsPrimitives.Boolean.type;
             case ts.SyntaxKind.ArrayType:
                 const arrayType = typeNode;
-                return `${this.getTypeNodeToString(arrayType.elementType)}[]`;
+                return `${this.getTypeNodeToString(arrayType.elementType, genericTypeMap)}[]`;
             case ts.SyntaxKind.UnionType:
                 // Handle union types like string | null
                 const unionType = typeNode;
-                const types = unionType.types.map(t => this.getTypeNodeToString(t));
+                const types = unionType.types.map(t => this.getTypeNodeToString(t, genericTypeMap));
                 // Filter out null and undefined, return the first meaningful type
                 const meaningfulTypes = types.filter(t => t !== 'null' && t !== 'undefined');
                 if (meaningfulTypes.length > 0 && meaningfulTypes[0]) {
@@ -215,6 +239,10 @@ class SchemaTransformer {
                 return 'object';
             default:
                 const typeText = typeNode.getText();
+                // Check if this is a generic type parameter we can resolve
+                if (genericTypeMap && genericTypeMap.has(typeText)) {
+                    return genericTypeMap.get(typeText);
+                }
                 // Handle some common TypeScript utility types
                 if (typeText.startsWith('Date'))
                     return constants.jsPrimitives.Date.type;
@@ -275,9 +303,15 @@ class SchemaTransformer {
                 return true;
             if (arg.kind === ts.SyntaxKind.FalseKeyword)
                 return false;
-            return arg.getText();
+            return arg;
         });
     }
+    getSafeDecoratorArgument(arg) {
+        if (arg && typeof arg === 'object' && 'kind' in arg) {
+            return arg.getText();
+        }
+        return arg;
+    }
     isPropertyTypeGeneric(property) {
         if (property.type && this.isGenericTypeFromNode(property.type)) {
             return true;
@@ -443,37 +477,175 @@ class SchemaTransformer {
         }
         return SchemaTransformer.instance;
     }
-    getSourceFileByClassName(className, sourceOptions) {
-        let sourceFiles = [];
-        if (sourceOptions?.isExternal) {
-            sourceFiles = this.program.getSourceFiles().filter(sf => {
-                return (sf.fileName.includes(sourceOptions.packageName) &&
-                    (!sourceOptions.filePath || sf.fileName === sourceOptions.filePath));
-            });
+    getSourceFileByClass(cls, sourceOptions) {
+        const className = cls.name;
+        const sourceFiles = this.getFilteredSourceFiles(sourceOptions);
+        const matches = [];
+        for (const sourceFile of sourceFiles) {
+            const node = sourceFile.statements.find(stmt => ts.isClassDeclaration(stmt) &&
+                stmt.name &&
+                stmt.name.text === className);
+            if (node) {
+                matches.push({ sourceFile, node });
+            }
         }
-        else {
-            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;
+        if (matches.length === 0) {
+            return undefined;
+        }
+        if (matches.length === 1) {
+            return matches[0];
+        }
+        if (matches.length > 1 && !sourceOptions?.filePath) {
+            const bestMatch = this.findBestMatch(cls, matches);
+            if (bestMatch) {
+                return bestMatch;
+            }
+            const firstMatch = matches[0];
+            if (firstMatch) {
+                console.warn(`[ts-class-to-openapi] Warning: Found multiple classes with name '${className}'. Using the first one found in '${firstMatch.sourceFile.fileName}'. To resolve this collision, provide 'sourceOptions.filePath'.`);
+            }
+        }
+        return matches[0];
+    }
+    checkTypeMatch(value, typeNode) {
+        const runtimeType = typeof value;
+        if (runtimeType === 'string' &&
+            typeNode.kind === ts.SyntaxKind.StringKeyword)
+            return true;
+        if (runtimeType === 'number' &&
+            typeNode.kind === ts.SyntaxKind.NumberKeyword)
+            return true;
+        if (runtimeType === 'boolean' &&
+            typeNode.kind === ts.SyntaxKind.BooleanKeyword)
+            return true;
+        if (Array.isArray(value) && ts.isArrayTypeNode(typeNode)) {
+            if (value.length === 0)
                 return true;
+            const firstItem = value[0];
+            const elementType = typeNode.elementType;
+            return this.checkTypeMatch(firstItem, elementType);
+        }
+        if (runtimeType === 'object' && value !== null && !Array.isArray(value)) {
+            if (ts.isTypeReferenceNode(typeNode) ||
+                typeNode.kind === ts.SyntaxKind.ObjectKeyword) {
+                return true;
+            }
+        }
+        return false;
+    }
+    findBestMatch(cls, matches) {
+        const runtimeSource = cls.toString();
+        const runtimeProperties = new Map();
+        const regexProperties = new Set();
+        // Try to extract properties from runtime source (assignments in constructor)
+        try {
+            const regex = /this\.([a-zA-Z0-9_$]+)\s*=/g;
+            let match;
+            while ((match = regex.exec(runtimeSource)) !== null) {
+                regexProperties.add(match[1]);
+            }
+        }
+        catch (e) {
+            // Ignore regex errors
+        }
+        // Try to instantiate the class to find properties
+        try {
+            const instance = new cls();
+            Object.keys(instance).forEach(key => {
+                runtimeProperties.set(key, instance[key]);
             });
         }
-        for (const sourceFile of sourceFiles) {
-            let node;
-            const found = sourceFile.statements.some(stmt => {
-                node = stmt;
-                return (ts.isClassDeclaration(stmt) &&
-                    stmt.name &&
-                    stmt.name.text === className);
+        catch (e) {
+            // Ignore instantiation errors (e.g. required constructor arguments)
+        }
+        // Try to get properties from class-validator metadata
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { getMetadataStorage } = require('class-validator');
+            const metadata = getMetadataStorage();
+            const targetMetadata = metadata.getTargetValidationMetadatas(cls, null, false, false);
+            targetMetadata.forEach((m) => {
+                if (m.propertyName && !runtimeProperties.has(m.propertyName)) {
+                    runtimeProperties.set(m.propertyName, undefined);
+                }
             });
-            if (found) {
-                return { sourceFile, node: node };
+        }
+        catch (e) {
+            // Ignore if class-validator is not available or fails
+        }
+        // console.log(`[findBestMatch] Class: ${cls.name}, Runtime Props: ${Array.from(runtimeProperties.keys()).join(', ')}`)
+        const scores = matches.map(match => {
+            let score = 0;
+            for (const member of match.node.members) {
+                if (ts.isMethodDeclaration(member) && ts.isIdentifier(member.name)) {
+                    if (runtimeSource.includes(member.name.text)) {
+                        score += 2;
+                    }
+                }
+                else if (ts.isPropertyDeclaration(member) &&
+                    ts.isIdentifier(member.name)) {
+                    const propName = member.name.text;
+                    if (runtimeProperties.has(propName)) {
+                        score += 1;
+                        const value = runtimeProperties.get(propName);
+                        if (member.type && this.checkTypeMatch(value, member.type)) {
+                            score += 5;
+                        }
+                    }
+                    else if (regexProperties.has(propName)) {
+                        score += 1;
+                    }
+                }
+            }
+            return { match, score };
+        });
+        scores.sort((a, b) => b.score - a.score);
+        const firstScore = scores[0];
+        const secondScore = scores[1];
+        if (firstScore && firstScore.score > 0) {
+            if (scores.length === 1 ||
+                (secondScore && firstScore.score > secondScore.score)) {
+                return firstScore.match;
             }
         }
+        return undefined;
+    }
+    getFilteredSourceFiles(sourceOptions) {
+        if (sourceOptions?.isExternal) {
+            return this.program.getSourceFiles().filter(sf => {
+                return (sf.fileName.includes(sourceOptions.packageName) &&
+                    (!sourceOptions.filePath || sf.fileName === sourceOptions.filePath));
+            });
+        }
+        return 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;
+            if (sourceOptions?.filePath &&
+                !sf.fileName.includes(sourceOptions.filePath)) {
+                return false;
+            }
+            return true;
+        });
+    }
+    isEnum(propertyDeclaration) {
+        if (!propertyDeclaration.type) {
+            return false;
+        }
+        let typeNode = propertyDeclaration.type;
+        if (ts.isArrayTypeNode(typeNode)) {
+            typeNode = typeNode.elementType;
+        }
+        if (ts.isTypeReferenceNode(typeNode)) {
+            const type = this.checker.getTypeAtLocation(typeNode);
+            // console.log('isEnum check:', typeNode.getText(), type.flags)
+            return (!!(type.flags & ts.TypeFlags.Enum) ||
+                !!(type.flags & ts.TypeFlags.EnumLiteral));
+        }
+        return false;
     }
     isClassType(propertyDeclaration) {
         // If there's no explicit type annotation, we can't determine reliably
@@ -724,7 +896,58 @@ class SchemaTransformer {
         transformedSchema.set(declaration.name.text, schema);
         return schema;
     }
+    getSchemaFromEnum(property) {
+        let typeNode = property.originalProperty.type;
+        if (ts.isArrayTypeNode(typeNode)) {
+            typeNode = typeNode.elementType;
+        }
+        const type = this.checker.getTypeAtLocation(typeNode);
+        if (type.symbol && type.symbol.exports) {
+            const values = [];
+            type.symbol.exports.forEach(member => {
+                const declaration = member.valueDeclaration;
+                if (declaration && ts.isEnumMember(declaration)) {
+                    const value = this.checker.getConstantValue(declaration);
+                    if (value !== undefined) {
+                        values.push(value);
+                    }
+                }
+            });
+            if (values.length > 0) {
+                const propertySchema = { type: 'object' };
+                propertySchema.enum = values;
+                const isString = values.every(v => typeof v === 'string');
+                const isNumber = values.every(v => typeof v === 'number');
+                if (isString) {
+                    propertySchema.type = 'string';
+                }
+                else if (isNumber) {
+                    propertySchema.type = 'number';
+                }
+                else {
+                    propertySchema.type = 'string';
+                }
+                if (property.isArray) {
+                    const itemsSchema = { ...propertySchema };
+                    propertySchema.type = 'array';
+                    propertySchema.items = itemsSchema;
+                    delete propertySchema.enum;
+                    return propertySchema;
+                }
+                else {
+                    return propertySchema;
+                }
+            }
+        }
+        return undefined;
+    }
     getSchemaFromPrimitive(property) {
+        if (property.isEnum) {
+            const enumSchema = this.getSchemaFromEnum(property);
+            if (enumSchema) {
+                return enumSchema;
+            }
+        }
         const propertySchema = { type: 'object' };
         const propertyType = property.type.toLowerCase().replace('[]', '').trim();
         let isFile = false;
@@ -812,8 +1035,40 @@ class SchemaTransformer {
             ts.isTypeReferenceNode(typeNode) // Omit, Pick, Partial, etc.
         );
     }
-    //Todo: implement properly
-    applyEnumDecorator(decorator, schema) { }
+    applyEnumDecorator(decorator, schema) {
+        if (decorator.arguments.length === 0)
+            return;
+        const arg = decorator.arguments[0];
+        if (arg && typeof arg === 'object' && 'kind' in arg) {
+            const type = this.checker.getTypeAtLocation(arg);
+            if (type.symbol && type.symbol.exports) {
+                const values = [];
+                type.symbol.exports.forEach(member => {
+                    const declaration = member.valueDeclaration;
+                    if (declaration && ts.isEnumMember(declaration)) {
+                        const value = this.checker.getConstantValue(declaration);
+                        if (value !== undefined) {
+                            values.push(value);
+                        }
+                    }
+                });
+                if (values.length > 0) {
+                    schema.enum = values;
+                    const isString = values.every(v => typeof v === 'string');
+                    const isNumber = values.every(v => typeof v === 'number');
+                    if (isString) {
+                        schema.type = 'string';
+                    }
+                    else if (isNumber) {
+                        schema.type = 'number';
+                    }
+                    else {
+                        schema.type = 'string';
+                    }
+                }
+            }
+        }
+    }
     applyDecorators(property, schema) {
         for (const decorator of property.decorators) {
             const decoratorName = decorator.name;
@@ -877,22 +1132,22 @@ class SchemaTransformer {
                     property.isOptional = true;
                     break;
                 case constants.validatorDecorators.MinLength.name:
-                    schema.minLength = decorator.arguments[0];
+                    schema.minLength = this.getSafeDecoratorArgument(decorator.arguments[0]);
                     break;
                 case constants.validatorDecorators.MaxLength.name:
-                    schema.maxLength = decorator.arguments[0];
+                    schema.maxLength = this.getSafeDecoratorArgument(decorator.arguments[0]);
                     break;
                 case constants.validatorDecorators.Length.name:
-                    schema.minLength = decorator.arguments[0];
+                    schema.minLength = this.getSafeDecoratorArgument(decorator.arguments[0]);
                     if (decorator.arguments[1]) {
-                        schema.maxLength = decorator.arguments[1];
+                        schema.maxLength = this.getSafeDecoratorArgument(decorator.arguments[1]);
                     }
                     break;
                 case constants.validatorDecorators.Min.name:
-                    schema.minimum = decorator.arguments[0];
+                    schema.minimum = this.getSafeDecoratorArgument(decorator.arguments[0]);
                     break;
                 case constants.validatorDecorators.Max.name:
-                    schema.maximum = decorator.arguments[0];
+                    schema.maximum = this.getSafeDecoratorArgument(decorator.arguments[0]);
                     break;
                 case constants.validatorDecorators.IsPositive.name:
                     schema.minimum = 0;
@@ -905,20 +1160,25 @@ class SchemaTransformer {
                     property.isOptional = false;
                     break;
                 case constants.validatorDecorators.ArrayMinSize.name:
-                    schema.minItems = decorator.arguments[0];
+                    schema.minItems = this.getSafeDecoratorArgument(decorator.arguments[0]);
                     break;
                 case constants.validatorDecorators.ArrayMaxSize.name:
-                    schema.maxItems = decorator.arguments[0];
+                    schema.maxItems = this.getSafeDecoratorArgument(decorator.arguments[0]);
                     break;
                 case constants.validatorDecorators.IsEnum.name:
-                    this.applyEnumDecorator(decorator, schema);
+                    if (!property.isArray) {
+                        this.applyEnumDecorator(decorator, schema);
+                    }
+                    else if (schema.items) {
+                        this.applyEnumDecorator(decorator, schema.items);
+                    }
                     break;
             }
         }
     }
     transform(cls, sourceOptions) {
         let schema = { type: 'object', properties: {} };
-        const result = this.getSourceFileByClassName(cls.name, sourceOptions);
+        const result = this.getSourceFileByClass(cls, sourceOptions);
         if (!result?.sourceFile) {
             console.warn(`Class ${cls.name} not found in any source file.`);
             return { name: cls.name, schema: {} };