ts-class-to-openapi 1.0.3 → 1.0.5

package/README.md

@@ -4,12 +4,16 @@
 
 A powerful library that automatically converts your TypeScript classes into OpenAPI-compatible schemas. Works with **pure TypeScript classes** and **class-validator decorated classes**, with zero runtime dependencies.
 
-> **🎯 New Feature**: Now supports **pure TypeScript classes** without requiring any decorators or external dependencies! Perfect for transforming existing codebases instantly.
+> **🎯 Latest Features**:
+>
+> - **Pure TypeScript classes** without requiring any decorators or external dependencies!
+> - **Full enum support** with `@IsEnum` decorator for string, numeric, and object enums
 
 ## 🚀 Key Features
 
 - ✅ **Pure TypeScript Support** - Transform any TypeScript class without decorators
 - ✅ **class-validator Compatible** - Enhanced schemas with validation decorators
+- ✅ **Enum Support** - Full support for TypeScript enums and object enums with @IsEnum
 - ✅ **CommonJS & ESM Compatible** - Works in any Node.js project
 - ✅ **Zero Runtime Dependencies** - No `reflect-metadata` or `emitDecoratorMetadata` required
 - ✅ **OpenAPI 3.1.0** - Industry-standard schema generation
@@ -81,7 +85,12 @@ This library is **100% compatible with both CommonJS and ESM**, allowing you to
 ```typescript
 // ESM import
 import { transform } from 'ts-class-to-openapi'
-import { IsString, IsEmail, IsNotEmpty } from 'class-validator'
+import { IsString, IsEmail, IsNotEmpty, IsEnum } from 'class-validator'
+
+enum UserType {
+  ADMIN = 'admin',
+  USER = 'user',
+}
 
 class User {
   @IsString()
@@ -90,6 +99,9 @@ class User {
 
   @IsEmail()
   email: string
+
+  @IsEnum(UserType)
+  type: UserType
 }
 
 const schema = transform(User)
@@ -101,7 +113,12 @@ console.log(JSON.stringify(schema, null, 2))
 ```typescript
 // TypeScript with CommonJS configuration
 import { transform } from 'ts-class-to-openapi'
-import { IsString, IsEmail, IsNotEmpty } from 'class-validator'
+import { IsString, IsEmail, IsNotEmpty, IsEnum } from 'class-validator'
+
+enum UserType {
+  ADMIN = 'admin',
+  USER = 'user',
+}
 
 class User {
   @IsString()
@@ -110,6 +127,9 @@ class User {
 
   @IsEmail()
   email: string
+
+  @IsEnum(UserType)
+  type: UserType
 }
 
 const schema = transform(User)
@@ -173,8 +193,22 @@ import {
   IsPositive,
   IsArray,
   IsNotEmpty,
+  IsEnum,
 } from 'class-validator'
 
+// Define enums for better API contracts
+enum ProductStatus {
+  DRAFT = 'draft',
+  PUBLISHED = 'published',
+  ARCHIVED = 'archived',
+}
+
+enum Priority {
+  LOW = 1,
+  MEDIUM = 2,
+  HIGH = 3,
+}
+
 // Enhanced with validation decorators
 class Product {
   @IsNumber()
@@ -189,6 +223,13 @@ class Product {
   @IsPositive()
   price: number
 
+  @IsEnum(ProductStatus)
+  @IsNotEmpty()
+  status: ProductStatus
+
+  @IsEnum(Priority)
+  priority?: Priority
+
   @IsArray()
   categories: string[]
 }
@@ -204,6 +245,7 @@ const schema = transform(Product)
 - ✅ String length constraints
 - ✅ Number range validation
 - ✅ Array size validation
+- ✅ Enum value constraints with automatic type detection
 
 ## 🚀 Quick Start
 
@@ -264,7 +306,7 @@ console.log(JSON.stringify(result, null, 2))
         "format": "date-time"
       }
     },
-    "required": []
+    "required": ["id", "name", "email", "age", "isActive", "tags", "createdAt"]
   }
 }
 ```
@@ -319,7 +361,7 @@ console.log(JSON.stringify(result, null, 2))
         "maximum": 100
       }
     },
-    "required": ["name"]
+    "required": ["name", "email", "age"]
   }
 }
 ```
@@ -750,7 +792,16 @@ const schema = transform(User)
         "format": "binary"
       }
     },
-    "required": ["id", "tags", "role", "avatar"]
+    "required": [
+      "id",
+      "name",
+      "email",
+      "tags",
+      "createdAt",
+      "role",
+      "files",
+      "avatar"
+    ]
   }
 }
 ```
@@ -759,19 +810,19 @@ const schema = transform(User)
 
 ## 📊 Pure TypeScript vs Enhanced Mode Comparison
 
-| Feature                | Pure TypeScript                       | Enhanced (class-validator)           |
-| ---------------------- | ------------------------------------- | ------------------------------------ |
-| **Dependencies**       | Zero                                  | Requires `class-validator`           |
-| **Configuration**      | None                                  | `experimentalDecorators: true`       |
-| **Type Detection**     | Automatic                             | Automatic + Decorators               |
-| **Validation Rules**   | Basic types only                      | Rich validation constraints          |
-| **Required Fields**    | None (all optional)                   | Specified by decorators              |
-| **String Constraints** | None                                  | Min/max length, patterns             |
-| **Number Constraints** | None                                  | Min/max values, positive             |
-| **Array Constraints**  | None                                  | Min/max items, non-empty             |
-| **Email Validation**   | None                                  | Email format validation              |
-| **Date Handling**      | `date-time` format                    | `date-time` format                   |
-| **Use Case**           | Existing codebases, rapid prototyping | APIs with validation, robust schemas |
+| Feature                | Pure TypeScript                             | Enhanced (class-validator)                |
+| ---------------------- | ------------------------------------------- | ----------------------------------------- |
+| **Dependencies**       | Zero                                        | Requires `class-validator`                |
+| **Configuration**      | None                                        | `experimentalDecorators: true`            |
+| **Type Detection**     | Automatic                                   | Automatic + Decorators                    |
+| **Validation Rules**   | Basic types only                            | Rich validation constraints               |
+| **Required Fields**    | Based on TypeScript optional operator (`?`) | TypeScript optional operator + decorators |
+| **String Constraints** | None                                        | Min/max length, patterns                  |
+| **Number Constraints** | None                                        | Min/max values, positive                  |
+| **Array Constraints**  | None                                        | Min/max items, non-empty                  |
+| **Email Validation**   | None                                        | Email format validation                   |
+| **Date Handling**      | `date-time` format                          | `date-time` format                        |
+| **Use Case**           | Existing codebases, rapid prototyping       | APIs with validation, robust schemas      |
 
 ### Example Comparison
 
@@ -779,11 +830,11 @@ const schema = transform(User)
 
 ```typescript
 class User {
-  name: string
-  email: string
-  age: number
+  name: string // Required (no ? operator)
+  email: string // Required (no ? operator)
+  age: number // Required (no ? operator)
 }
-// Generates: All properties optional, basic types
+// Generates: All properties required (no ? operator), basic types
 ```
 
 **Enhanced Class:**
@@ -801,21 +852,126 @@ class User {
   @Min(18)
   age: number
 }
-// Generates: name required, email format validation, age minimum 18
+// Generates: All properties required, email format validation, age minimum 18
 ```
 
 ## 🎨 Supported Decorators Reference
 
 ### Type Validation Decorators
 
-| Decorator      | Generated Schema Property             | Description                 |
-| -------------- | ------------------------------------- | --------------------------- |
-| `@IsString()`  | `type: "string"`                      | String type validation      |
-| `@IsInt()`     | `type: "integer", format: "int32"`    | Integer type validation     |
-| `@IsNumber()`  | `type: "number", format: "double"`    | Number type validation      |
-| `@IsBoolean()` | `type: "boolean"`                     | Boolean type validation     |
-| `@IsEmail()`   | `type: "string", format: "email"`     | Email format validation     |
-| `@IsDate()`    | `type: "string", format: "date-time"` | Date-time format validation |
+| Decorator             | Generated Schema Property                       | Description                 |
+| --------------------- | ----------------------------------------------- | --------------------------- |
+| `@IsString()`         | `type: "string"`                                | String type validation      |
+| `@IsInt()`            | `type: "integer", format: "int32"`              | Integer type validation     |
+| `@IsNumber()`         | `type: "number", format: "double"`              | Number type validation      |
+| `@IsBoolean()`        | `type: "boolean"`                               | Boolean type validation     |
+| `@IsEmail()`          | `type: "string", format: "email"`               | Email format validation     |
+| `@IsDate()`           | `type: "string", format: "date-time"`           | Date-time format validation |
+| `@IsEnum(enumObject)` | `type: "string/number/boolean", enum: [values]` | Enum constraint validation  |
+
+### Enum Validation with @IsEnum
+
+The `@IsEnum()` decorator provides powerful enum validation with automatic type detection and value extraction:
+
+```typescript
+import { transform } from 'ts-class-to-openapi'
+import { IsEnum, IsNotEmpty, IsArray } from 'class-validator'
+
+// String enum
+enum UserRole {
+  ADMIN = 'admin',
+  USER = 'user',
+  MODERATOR = 'moderator',
+}
+
+// Numeric enum
+enum Priority {
+  LOW = 1,
+  MEDIUM = 2,
+  HIGH = 3,
+}
+
+// Auto-incremented enum
+enum Size {
+  SMALL, // 0
+  MEDIUM, // 1
+  LARGE, // 2
+}
+
+// Object enum with 'as const'
+const Status = {
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+  PENDING: 'pending',
+} as const
+
+class TaskEntity {
+  @IsEnum(UserRole)
+  @IsNotEmpty()
+  assignedRole: UserRole // Required enum
+
+  @IsEnum(Priority)
+  priority?: Priority // Optional enum
+
+  @IsEnum(Size)
+  size?: Size // Auto-incremented enum
+
+  @IsEnum(Status)
+  status?: keyof typeof Status // Object enum
+
+  @IsEnum(UserRole)
+  @IsArray()
+  allowedRoles?: UserRole[] // Array of enums
+}
+
+const result = transform(TaskEntity)
+```
+
+**Generated Output:**
+
+```json
+{
+  "name": "TaskEntity",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "assignedRole": {
+        "type": "string",
+        "enum": ["admin", "user", "moderator"]
+      },
+      "priority": {
+        "type": "number",
+        "enum": [1, 2, 3]
+      },
+      "size": {
+        "type": "number",
+        "enum": [0, 1, 2]
+      },
+      "status": {
+        "type": "string",
+        "enum": ["active", "inactive", "pending"]
+      },
+      "allowedRoles": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["admin", "user", "moderator"]
+        }
+      }
+    },
+    "required": ["assignedRole"]
+  }
+}
+```
+
+**Supported Enum Types:**
+
+- ✅ **String enums**: `enum Color { RED = 'red' }`
+- ✅ **Numeric enums**: `enum Status { ACTIVE = 1 }`
+- ✅ **Auto-incremented enums**: `enum Size { SMALL, MEDIUM }`
+- ✅ **Object enums**: `const Colors = { RED: 'red' } as const`
+- ✅ **Mixed enums**: `enum Mixed { NUM = 1, STR = 'text' }`
+- ✅ **Array of enums**: `roles: UserRole[]`
 
 ### String Validation Decorators
 
@@ -933,7 +1089,7 @@ console.log(JSON.stringify(schema, null, 2))
         "format": "binary"
       }
     },
-    "required": ["document"]
+    "required": ["document", "attachments"]
   }
 }
 ```
@@ -981,6 +1137,75 @@ console.log(result.name) // "User"
 console.log(result.schema) // OpenAPI schema object
 ```
 
+## 🔍 Required Properties Rules
+
+Understanding how properties are marked as required is crucial for generating accurate schemas:
+
+### TypeScript Optional Operator (`?`)
+
+The presence or absence of the TypeScript optional operator (`?`) determines if a property is required:
+
+```typescript
+class User {
+  name: string // ✅ REQUIRED (no ? operator)
+  email: string // ✅ REQUIRED (no ? operator)
+  age?: number // ❌ OPTIONAL (has ? operator)
+  bio?: string // ❌ OPTIONAL (has ? operator)
+}
+
+// Generated schema:
+// "required": ["name", "email"]
+```
+
+### class-validator Decorators Override
+
+When using class-validator decorators, they can override the TypeScript optional behavior:
+
+```typescript
+import { IsNotEmpty, IsOptional } from 'class-validator'
+
+class User {
+  @IsNotEmpty()
+  requiredField?: string // ✅ REQUIRED (@IsNotEmpty overrides ?)
+
+  @IsOptional()
+  optionalField: string // ❌ OPTIONAL (@IsOptional overrides no ?)
+
+  normalField: string // ✅ REQUIRED (no ? operator)
+  normalOptional?: string // ❌ OPTIONAL (has ? operator)
+}
+
+// Generated schema:
+// "required": ["requiredField", "normalField"]
+```
+
+### Array Properties
+
+Array properties follow the same rules, with additional decorators:
+
+```typescript
+import { ArrayNotEmpty } from 'class-validator'
+
+class User {
+  tags: string[] // ✅ REQUIRED (no ? operator)
+
+  @ArrayNotEmpty()
+  categories?: string[] // ✅ REQUIRED (@ArrayNotEmpty overrides ?)
+
+  optionalTags?: string[] // ❌ OPTIONAL (has ? operator)
+}
+
+// Generated schema:
+// "required": ["tags", "categories"]
+```
+
+### Summary of Rules
+
+1. **No `?` operator** → Property is **REQUIRED**
+2. **Has `?` operator** → Property is **OPTIONAL**
+3. **`@IsNotEmpty()` or `@ArrayNotEmpty()`** → Forces **REQUIRED** (overrides `?`)
+4. **`@IsOptional()`** → Forces **OPTIONAL** (overrides no `?`)
+
 ## 🌟 Advanced Features
 
 - ✅ **Pure TypeScript Support** - Works with any TypeScript class, no decorators required

package/dist/__test__/circular-reference.test.d.ts

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

package/dist/__test__/entities/circular.entity.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Example entity demonstrating circular reference issue
+ * User -> Role -> User (circular)
+ */
+export declare class CircularUser {
+    id: string;
+    name: string;
+    role: CircularRole;
+    organization: CircularOrganization;
+    organizations: CircularOrganization[];
+}
+export declare class CircularRole {
+    id: string;
+    name: string;
+    assignedBy: CircularUser;
+    organization: CircularOrganization;
+    usersWithRole: CircularUser[];
+}
+/**
+ * Example entity demonstrating complex circular references
+ * Organization -> User, Role, Organization (multiple circular references)
+ */
+export declare class CircularOrganization {
+    id: string;
+    name: string;
+    owner: CircularUser;
+    defaultRole: CircularRole;
+    members: CircularUser[];
+    availableRoles: CircularRole[];
+    parentOrganization?: CircularOrganization;
+    childOrganizations: CircularOrganization[];
+}
+/**
+ * Example demonstrating deep circular reference chain
+ * A -> B -> C -> D -> A (complex chain)
+ */
+export declare class DeepCircularA {
+    id: string;
+    reference: DeepCircularB;
+}
+export declare class DeepCircularB {
+    id: string;
+    reference: DeepCircularC;
+}
+export declare class DeepCircularC {
+    id: string;
+    reference: DeepCircularD;
+}
+export declare class DeepCircularD {
+    id: string;
+    reference: DeepCircularA;
+    allReferences: {
+        a: DeepCircularA;
+        b: DeepCircularB;
+        c: DeepCircularC;
+        selfRef: DeepCircularD;
+    };
+    arrayReferences: (DeepCircularA | DeepCircularB | DeepCircularC | DeepCircularD)[];
+}

package/dist/__test__/entities/complex-generics.entity.d.ts

@@ -0,0 +1,33 @@
+export type ApiResponse<T> = {
+    data: T;
+    message: string;
+    success: boolean;
+};
+export type PaginatedResponse<T> = {
+    items: T[];
+    total: number;
+    page: number;
+};
+export declare class Product {
+    id: number;
+    name: string;
+    price: number;
+}
+export declare class UserEntity {
+    id: number;
+    username: string;
+    email: string;
+}
+export declare class ProductResponseDto {
+    response: ApiResponse<Product>;
+}
+export declare class UserListDto {
+    users: PaginatedResponse<UserEntity>;
+}
+export type KeyValuePair<K, V> = {
+    key: K;
+    value: V;
+};
+export declare class ConfigDto {
+    setting: KeyValuePair<string, number>;
+}

package/dist/__test__/entities/comprehensive-enum.entity.d.ts

@@ -0,0 +1,23 @@
+declare enum Color {
+    RED = "red",
+    GREEN = "green",
+    BLUE = "blue"
+}
+declare enum Size {
+    SMALL = 0,
+    MEDIUM = 1,
+    LARGE = 2
+}
+declare enum HttpStatus {
+    OK = 200,
+    NOT_FOUND = 404,
+    ERROR = "server_error"
+}
+export declare class ComprehensiveEnumEntity {
+    primaryColor: Color;
+    size?: Size;
+    status?: HttpStatus;
+    availableColors?: Color[];
+    supportedSizes: Size[];
+}
+export { Color, Size, HttpStatus };

package/dist/__test__/entities/enum.entity.d.ts

@@ -0,0 +1,29 @@
+declare enum UserRole {
+    ADMIN = "admin",
+    USER = "user",
+    MODERATOR = "moderator"
+}
+declare enum Priority {
+    LOW = 1,
+    MEDIUM = 2,
+    HIGH = 3
+}
+declare const Status: {
+    readonly ACTIVE: "active";
+    readonly INACTIVE: "inactive";
+    readonly PENDING: "pending";
+};
+declare enum BooleanEnum {
+    TRUE = "true",
+    FALSE = "false"
+}
+export declare class EnumTestEntity {
+    role: UserRole;
+    priority?: Priority;
+    status?: keyof typeof Status;
+    flag?: BooleanEnum;
+    roles?: UserRole[];
+    priorities?: Priority[];
+    optionalRole?: UserRole;
+}
+export { UserRole, Priority, Status, BooleanEnum };

package/dist/__test__/entities/user-role-generic.entity.d.ts

@@ -0,0 +1,13 @@
+export type User<T> = {
+    _id: number;
+    fullName: string;
+    role: T;
+};
+export declare class Role {
+    _id: number;
+    name: string;
+}
+export declare class QuoteDto {
+    _id: number;
+    user: User<Role>;
+}

package/dist/__test__/enum.test.d.ts

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

package/dist/__test__/generic-types.test.d.ts

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

package/dist/__test__/index.d.ts

@@ -2,3 +2,8 @@ import './main.test';
 import './integration.test';
 import './plain.test';
 import './optional-properties.test';
+import './generic-types.test';
+import './enum.test';
+import './circular-reference.test';
+import './ref-pattern.test';
+import './singleton-behavior.test';

package/dist/__test__/ref-pattern.test.d.ts

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

package/dist/__test__/singleton-behavior.test.d.ts

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

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { transform } from './transformer';
-import { SchemaType } from './types';
-export { transform, type SchemaType };
+import { transform, SchemaTransformer } from './transformer';
+import { SchemaType, TransformerOptions } from './types';
+export { transform, SchemaTransformer, type SchemaType, type TransformerOptions, };