ts-class-to-openapi 1.0.5 → 1.1.0

package/README.md

@@ -1,50 +1,34 @@
 # 🔄 ts-class-to-openapi
 
-✨ **Transform TypeScript classes into OpenAPI 3.1.0 schema objects**
+✨ **Transform TypeScript classes into OpenAPI 3.1.0 schemas**
 
-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.
+A robust and efficient library that automatically transforms TypeScript classes into OpenAPI-compatible schemas. Compatible with **pure TypeScript classes** and **class-validator decorated classes**.
 
-> **🎯 Latest Features**:
->
-> - **Pure TypeScript classes** without requiring any decorators or external dependencies!
-> - **Full enum support** with `@IsEnum` decorator for string, numeric, and object enums
+> **What is OpenAPI?** OpenAPI (formerly Swagger) is the industry standard for describing REST APIs. This library generates OpenAPI 3.1.0 compatible schemas that can be used for API documentation, client SDK generation, and validation.
 
 ## 🚀 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
-- ✅ **TypeScript Native** - Full type support and safety
-- ✅ **High Performance** - Singleton pattern with built-in caching
-- ✅ **Nested Objects** - Handles complex relationships automatically
-- ✅ **Typed Arrays** - Full support for arrays with validation
-- ✅ **File Uploads** - Binary file upload support
+- ✅ **Direct transformation** - Convert any TypeScript class without additional configuration
+- ✅ **Zero runtime dependencies** - No `reflect-metadata` or complex configurations required
+- ✅ **class-validator integration** - Enrich schemas using validation decorators
+- ✅ **Automatic documentation generation** - Generate Swagger documentation from existing classes
+- ✅ **Native TypeScript support** - Full compatibility with enums, arrays, and nested objects
 
-## 🎯 Why Use This Library?
+## 🎯 Quick Example
 
-Perfect for projects where you need to:
-
-- 🌐 **REST APIs**: Generate Swagger documentation from your existing TypeScript classes
-- 📚 **Auto Documentation**: Maintain consistency between TypeScript types and API contracts
-- 🧪 **API Testing**: Create mock data structures for testing
-- 🔧 **Microservices**: Ensure schema consistency across services
-- ⚡ **Legacy Projects**: Works without enabling `emitDecoratorMetadata`
-- 🎯 **Pure TypeScript**: Transform classes without any decorators
-- 🔍 **Enhanced Validation**: Add class-validator decorators for richer schemas
-
-### 📋 About OpenAPI
-
-**OpenAPI** (formerly Swagger) is the industry standard specification for describing REST APIs in a structured, machine-readable format. This library generates **OpenAPI 3.1.0** compatible schemas from your TypeScript classes.
+```typescript
+import { transform } from 'ts-class-to-openapi'
 
-**Benefits:**
+class User {
+  id: number
+  name: string
+  email: string
+  age?: number
+}
 
-- Automatic documentation generation
-- Client SDK generation
-- API testing automation
-- Consistency across your API ecosystem
+const schema = transform(User)
+// Returns complete OpenAPI schema ready for Swagger/API documentation
+```
 
 ## 📦 Installation
 
@@ -59,67 +43,77 @@ yarn add ts-class-to-openapi
 pnpm add ts-class-to-openapi
 ```
 
-### For class-validator Enhanced Features
+### Additional Dependencies for class-validator
 
-If you want to use class-validator decorators for enhanced validation schemas:
+To use validation decorators and generate more detailed schemas:
 
 ```bash
-# Using npm
 npm install ts-class-to-openapi class-validator
-
-# Using yarn
-yarn add ts-class-to-openapi class-validator
-
-# Using pnpm
-pnpm add ts-class-to-openapi class-validator
 ```
 
-> **Note**: `class-validator` is only required if you want to use validation decorators. Pure TypeScript classes work without it.
+> **Note**: The `class-validator` dependency is optional and only required when using validation decorators.
 
-## 🔧 Module Compatibility
+## 🎨 Class Transformation Examples
 
-This library is **100% compatible with both CommonJS and ESM**, allowing you to use it in any modern Node.js project.
+### 1. Basic TypeScript Class
 
-### ESM (ES Modules) - Recommended
+Fundamental method: transform any TypeScript class without decorators:
 
 ```typescript
-// ESM import
 import { transform } from 'ts-class-to-openapi'
-import { IsString, IsEmail, IsNotEmpty, IsEnum } from 'class-validator'
-
-enum UserType {
-  ADMIN = 'admin',
-  USER = 'user',
-}
 
+// Basic TypeScript class - no decorators required
 class User {
-  @IsString()
-  @IsNotEmpty()
+  id: number
   name: string
-
-  @IsEmail()
   email: string
-
-  @IsEnum(UserType)
-  type: UserType
+  age: number
+  active: boolean
+  tags: string[]
+  createdAt: Date
 }
 
-const schema = transform(User)
-console.log(JSON.stringify(schema, null, 2))
+// Transform class to OpenAPI schema
+const result = transform(User)
+console.log(JSON.stringify(result, null, 2))
+```
+
+**Generated output:**
+
+```json
+{
+  "name": "User",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "id": { "type": "number" },
+      "name": { "type": "string" },
+      "email": { "type": "string" },
+      "age": { "type": "number" },
+      "active": { "type": "boolean" },
+      "tags": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "createdAt": {
+        "type": "string",
+        "format": "date-time"
+      }
+    },
+    "required": ["id", "name", "email", "age", "active", "tags", "createdAt"]
+  }
+}
 ```
 
-### TypeScript with CommonJS
+### 2. Class with Advanced Validations
+
+For more detailed schemas, class-validator decorators can be incorporated:
 
 ```typescript
-// TypeScript with CommonJS configuration
 import { transform } from 'ts-class-to-openapi'
-import { IsString, IsEmail, IsNotEmpty, IsEnum } from 'class-validator'
-
-enum UserType {
-  ADMIN = 'admin',
-  USER = 'user',
-}
+import { IsString, IsEmail, IsNotEmpty, IsInt, Min, Max } from 'class-validator'
 
+// Class with validation decorators
 class User {
   @IsString()
   @IsNotEmpty()
@@ -128,79 +122,125 @@ class User {
   @IsEmail()
   email: string
 
-  @IsEnum(UserType)
-  type: UserType
+  @IsInt()
+  @Min(18)
+  @Max(100)
+  age: number
 }
 
-const schema = transform(User)
-console.log(JSON.stringify(schema, null, 2))
+const result = transform(User)
 ```
 
-## ⚙️ Requirements
+**Generated output:**
 
-- Node.js >= 14.0.0
-- TypeScript with minimal compiler options in `tsconfig.json`:
-  ```json
-  {
-    "compilerOptions": {
-      "experimentalDecorators": true
-    }
+```json
+{
+  "name": "User",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": { "type": "string" },
+      "email": {
+        "type": "string",
+        "format": "email"
+      },
+      "age": {
+        "type": "integer",
+        "format": "int32",
+        "minimum": 18,
+        "maximum": 100
+      }
+    },
+    "required": ["name", "email", "age"]
   }
-  ```
-
-> **Note**: The `experimentalDecorators` option is only required if you plan to use class-validator decorators. Pure TypeScript classes work without any special configuration.
-
-## 🎨 Two Transformation Modes
+}
+```
 
-### 1. Pure TypeScript Classes
+### 3. Nested Objects and Arrays
 
-Transform any TypeScript class without requiring any decorators or external dependencies:
+Automatic processing of complex relationships:
 
 ```typescript
 import { transform } from 'ts-class-to-openapi'
 
-// Pure TypeScript - no decorators needed
-class Product {
+class Address {
+  street: string
+  city: string
+  zipCode: string
+}
+
+class Role {
   id: number
   name: string
-  price: number
-  inStock: boolean
-  categories: string[]
-  metadata: Record<string, any>
-  createdAt: Date
+  permissions: string[]
+}
+
+class User {
+  id: number
+  name: string
+  email: string
+  address: Address // Nested object
+  roles: Role[] // Array of objects
+  phone?: string // Optional property
 }
 
-const schema = transform(Product)
+const schema = transform(User)
 ```
 
-**Benefits:**
+**Generated output:**
 
-- ✅ No external dependencies required
-- ✅ Works with existing TypeScript codebases
-- ✅ Zero configuration needed
-- ✅ Automatic type inference
-- ✅ Perfect for legacy projects
+```json
+{
+  "name": "User",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "id": { "type": "number" },
+      "name": { "type": "string" },
+      "email": { "type": "string" },
+      "address": {
+        "type": "object",
+        "properties": {
+          "street": { "type": "string" },
+          "city": { "type": "string" },
+          "zipCode": { "type": "string" }
+        },
+        "required": ["street", "city", "zipCode"]
+      },
+      "roles": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "number" },
+            "name": { "type": "string" },
+            "permissions": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "required": ["id", "name", "permissions"]
+        }
+      },
+      "phone": { "type": "string" }
+    },
+    "required": ["id", "name", "email", "address", "roles"]
+  }
+}
+```
 
-### 2. Enhanced with class-validator
+### 4. Enumerations and Special Types
 
-Add validation decorators for richer, more detailed schemas:
+Full compatibility with TypeScript enumerations:
 
 ```typescript
 import { transform } from 'ts-class-to-openapi'
-import {
-  IsString,
-  IsNumber,
-  IsPositive,
-  IsArray,
-  IsNotEmpty,
-  IsEnum,
-} from 'class-validator'
+import { IsEnum } from 'class-validator'
 
-// Define enums for better API contracts
-enum ProductStatus {
-  DRAFT = 'draft',
-  PUBLISHED = 'published',
-  ARCHIVED = 'archived',
+enum UserType {
+  ADMIN = 'admin',
+  USER = 'user',
+  MODERATOR = 'moderator',
 }
 
 enum Priority {
@@ -209,164 +249,105 @@ enum Priority {
   HIGH = 3,
 }
 
-// Enhanced with validation decorators
-class Product {
-  @IsNumber()
-  @IsPositive()
-  id: number
-
-  @IsString()
-  @IsNotEmpty()
-  name: string
-
-  @IsNumber()
-  @IsPositive()
-  price: number
-
-  @IsEnum(ProductStatus)
-  @IsNotEmpty()
-  status: ProductStatus
+class Task {
+  @IsEnum(UserType)
+  assignedTo: UserType
 
   @IsEnum(Priority)
   priority?: Priority
 
-  @IsArray()
-  categories: string[]
-}
-
-const schema = transform(Product)
-```
-
-**Benefits:**
-
-- ✅ Rich validation constraints
-- ✅ Required field specification
-- ✅ Format validation (email, date, etc.)
-- ✅ String length constraints
-- ✅ Number range validation
-- ✅ Array size validation
-- ✅ Enum value constraints with automatic type detection
-
-## 🚀 Quick Start
-
-### Pure TypeScript Classes
-
-Transform any TypeScript class without requiring decorators:
-
-```typescript
-import { transform } from 'ts-class-to-openapi'
-
-// Pure TypeScript class - no decorators needed!
-class User {
-  id: number
-  name: string
-  email: string
-  age: number
-  isActive: boolean
-  tags: string[]
-  createdAt: Date
+  title: string
+  completed: boolean
+  dueDate: Date
 }
 
-// Transform the class to OpenAPI schema
-const result = transform(User)
-console.log(JSON.stringify(result, null, 2))
+const schema = transform(Task)
 ```
 
-**Generated Output:**
+**Generated output:**
 
 ```json
 {
-  "name": "User",
+  "name": "Task",
   "schema": {
     "type": "object",
     "properties": {
-      "id": {
-        "type": "number"
-      },
-      "name": {
-        "type": "string"
-      },
-      "email": {
-        "type": "string"
-      },
-      "age": {
-        "type": "number"
-      },
-      "isActive": {
-        "type": "boolean"
+      "assignedTo": {
+        "type": "string",
+        "enum": ["admin", "user", "moderator"]
       },
-      "tags": {
-        "type": "array",
-        "items": {
-          "type": "string"
-        }
+      "priority": {
+        "type": "number",
+        "enum": [1, 2, 3]
       },
-      "createdAt": {
+      "title": { "type": "string" },
+      "completed": { "type": "boolean" },
+      "dueDate": {
         "type": "string",
         "format": "date-time"
       }
     },
-    "required": ["id", "name", "email", "age", "isActive", "tags", "createdAt"]
+    "required": ["assignedTo", "title", "completed", "dueDate"]
   }
 }
 ```
 
-### Enhanced with class-validator Decorators
+### 5. File Upload
 
-For more detailed validation schemas, add class-validator decorators:
+Integrated support for binary file handling:
 
 ```typescript
 import { transform } from 'ts-class-to-openapi'
-import { IsString, IsEmail, IsNotEmpty, IsInt, Min, Max } from 'class-validator'
+import { IsNotEmpty, IsOptional } from 'class-validator'
 
-// Define your class with validation decorators
-class User {
-  @IsString()
+// Custom file type definition
+class UploadFile {}
+
+class UserProfile {
   @IsNotEmpty()
-  name: string
+  profilePicture: UploadFile
 
-  @IsEmail()
-  email: string
+  @IsOptional()
+  resume: UploadFile
 
-  @IsInt()
-  @Min(18)
-  @Max(100)
-  age: number
+  documents: UploadFile[] // Multiple files
 }
 
-// Transform the class to OpenAPI schema
-const result = transform(User)
-console.log(JSON.stringify(result, null, 2))
+const schema = transform(UserProfile)
 ```
 
-**Generated Output:**
+**Generated output:**
 
 ```json
 {
-  "name": "User",
+  "name": "UserProfile",
   "schema": {
     "type": "object",
     "properties": {
-      "name": {
-        "type": "string"
+      "profilePicture": {
+        "type": "string",
+        "format": "binary"
       },
-      "email": {
+      "resume": {
         "type": "string",
-        "format": "email"
+        "format": "binary"
       },
-      "age": {
-        "type": "integer",
-        "format": "int32",
-        "minimum": 18,
-        "maximum": 100
+      "documents": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "format": "binary"
+        }
       }
     },
-    "required": ["name", "email", "age"]
+    "required": ["profilePicture", "documents"]
   }
 }
 ```
 
-### Express.js + Swagger UI Example
+## 🌐 REST API Integration
+
+### Implementation with Express.js and Swagger UI
 
 ```typescript
 import express from 'express'
@@ -374,7 +355,7 @@ import swaggerUi from 'swagger-ui-express'
 import { transform } from 'ts-class-to-openapi'
 import { IsString, IsEmail, IsNotEmpty, IsInt, Min, Max } from 'class-validator'
 
-// Define your DTOs with validation decorators
+// DTO definition with validation decorators
 class User {
   @IsString()
   @IsNotEmpty()
@@ -400,14 +381,14 @@ class CreateUserDto {
 
 const app = express()
 
-// Generate schemas from your classes
+// Schema generation from classes
 const userSchema = transform(User)
 const createUserSchema = transform(CreateUserDto)
 
-// Create OpenAPI specification
-const swaggerSpec = {
+// OpenAPI specification configuration
+const swaggerSpecification = {
   openapi: '3.1.0',
-  info: { title: 'My API', version: '1.0.0' },
+  info: { title: 'Management API', version: '1.0.0' },
   components: {
     schemas: {
       [userSchema.name]: userSchema.schema,
@@ -416,17 +397,15 @@ const swaggerSpec = {
   },
 }
 
-// Setup Swagger UI at /api-docs
-app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))
+// Swagger UI configuration
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecification))
 
 app.listen(3000, () => {
-  console.log('API docs available at http://localhost:3000/api-docs')
+  console.log('API documentation available at http://localhost:3000/api-docs')
 })
 ```
 
-#### Complete POST API Example with Schema Validation
-
-Here's a complete example of a POST endpoint that uses the generated schemas for both request validation and response structure:
+### Complete POST endpoint implementation with schema validation
 
 ```typescript
 import express from 'express'
@@ -442,7 +421,7 @@ import {
   IsOptional,
 } from 'class-validator'
 
-// Define your entities
+// Domain entity definition
 class User {
   @IsInt()
   @Min(1)
@@ -465,7 +444,7 @@ class User {
   phone?: string
 }
 
-// DTO for creating a user
+// DTO for user creation
 class CreateUserDto {
   @IsString()
   @IsNotEmpty()
@@ -484,29 +463,22 @@ class CreateUserDto {
   phone?: string
 }
 
-// Response wrapper (not transformed, defined manually in OpenAPI spec)
-interface ApiResponse<T> {
-  data: T
-  success: boolean
-}
-
 const app = express()
 app.use(express.json())
 
-// Generate schemas only for your entities
+// Schema generation from classes
 const userSchema = transform(User)
 const createUserSchema = transform(CreateUserDto)
 
-// Create OpenAPI specification with POST endpoint
-const swaggerSpec = {
+// Complete OpenAPI specification with POST endpoint
+const swaggerSpecification = {
   openapi: '3.1.0',
   info: { title: 'User Management API', version: '1.0.0' },
   components: {
     schemas: {
       [userSchema.name]: userSchema.schema,
       [createUserSchema.name]: createUserSchema.schema,
-      // ApiResponse schema defined manually
-      UserApiResponse: {
+      UserResponse: {
         type: 'object',
         properties: {
           data: { $ref: `#/components/schemas/${userSchema.name}` },
@@ -524,7 +496,9 @@ const swaggerSpec = {
           required: true,
           content: {
             'application/json': {
-              schema: { $ref: `#/components/schemas/${createUserSchema.name}` },
+              schema: {
+                $ref: `#/components/schemas/${createUserSchema.name}`,
+              },
             },
           },
         },
@@ -533,7 +507,7 @@ const swaggerSpec = {
             description: 'User created successfully',
             content: {
               'application/json': {
-                schema: { $ref: '#/components/schemas/UserApiResponse' },
+                schema: { $ref: '#/components/schemas/UserResponse' },
               },
             },
           },
@@ -546,21 +520,19 @@ const swaggerSpec = {
   },
 }
 
-// Implement the POST endpoint
+// POST endpoint implementation
 app.post('/users', (req, res) => {
   try {
-    // In a real application, you would validate the request body
-    // and save to database
     const userData = req.body as CreateUserDto
 
-    // Mock user creation (replace with actual database logic)
+    // User creation simulation (replace with database logic)
     const newUser: User = {
       id: Math.floor(Math.random() * 1000) + 1,
       ...userData,
     }
 
-    // Return response matching the schema
-    const response: ApiResponse<User> = {
+    // Response that complies with the defined schema
+    const response = {
       data: newUser,
       success: true,
     }
@@ -575,409 +547,107 @@ app.post('/users', (req, res) => {
   }
 })
 
-// Setup Swagger UI
-app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))
+// Swagger UI configuration
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecification))
 
 app.listen(3000, () => {
-  console.log('API docs available at http://localhost:3000/api-docs')
+  console.log('API documentation available at http://localhost:3000/api-docs')
 })
 ```
 
-This example demonstrates:
+## 📖 API Reference
 
-- **Request Schema**: Uses `CreateUserDto` schema for POST body validation
-- **Response Schema**: Returns data in `{ data: User, success: boolean }` format
-- **OpenAPI Documentation**: Complete Swagger specification with request/response schemas
-- **Type Safety**: Full TypeScript support for request and response types
+### `transform(class: Function)`
 
-### File Upload Example
+Transforms a class constructor function into an OpenAPI schema object.
 
-```typescript
-import { transform } from 'ts-class-to-openapi'
-import { IsNotEmpty, IsOptional } from 'class-validator'
+**Parameters:**
 
-// Define custom file type
-class UploadFile {}
+- `class: Function` - The class constructor function to transform
 
-// Create your upload DTO
-class ProfileUpload {
-  @IsNotEmpty()
-  profilePicture: UploadFile
+**Returns:**
 
-  @IsOptional()
-  resume: UploadFile
+```typescript
+{
+  name: string;        // Class name
+  schema: {
+    type: "object";
+    properties: Record<string, any>;
+    required: string[];
+  }
 }
-
-// Generate schema
-const schema = transform(ProfileUpload)
-console.log(JSON.stringify(schema, null, 2))
 ```
 
-**Generated Output:**
-
-```json
-{
-  "name": "ProfileUpload",
-  "schema": {
-    "type": "object",
-    "properties": {
-      "profilePicture": {
-        "type": "string",
-        "format": "binary"
-      },
-      "resume": {
-        "type": "string",
-        "format": "binary"
-      }
-    },
-    "required": ["profilePicture"]
-  }
-}
-```
-
-### Advanced Example with Nested Objects and Arrays
-
-#### Pure TypeScript Classes
+**Example:**
 
 ```typescript
 import { transform } from 'ts-class-to-openapi'
+import { User } from './entities/user.js'
 
-class Role {
-  id: number
-  name: string
-  permissions: string[]
-}
-
-class Address {
-  street: string
-  city: string
-  country: string
-  zipCode: string
-}
-
-class User {
-  id: number
-  name: string
-  email: string
-  age: number
-  isActive: boolean
-  tags: string[]
-  createdAt: Date
-  role: Role // Nested object
-  addresses: Address[] // Array of objects
-  files: Buffer[] // Binary files
-}
-
-const schema = transform(User)
-```
-
-#### Enhanced with class-validator
-
-```typescript
-import {
-  IsString,
-  IsInt,
-  IsEmail,
-  IsDate,
-  IsArray,
-  IsNotEmpty,
-  MinLength,
-  MaxLength,
-  Min,
-  Max,
-  ArrayNotEmpty,
-} from 'class-validator'
-
-class Role {
-  @IsInt()
-  @IsNotEmpty()
-  id: number
-
-  @IsString()
-  @MinLength(1)
-  @MaxLength(50)
-  name: string
-}
-
-class User {
-  @IsInt()
-  @IsNotEmpty()
-  @Min(1)
-  id: number
-
-  @IsString()
-  @MinLength(2)
-  @MaxLength(100)
-  name: string
-
-  @IsEmail()
-  email: string
-
-  @IsArray()
-  @ArrayNotEmpty()
-  tags: string[]
-
-  @IsDate()
-  createdAt: Date
-
-  @IsNotEmpty()
-  role: Role // Nested object
-
-  files: Buffer[] // Binary files
-
-  @IsNotEmpty()
-  avatar: UploadFile // Custom file upload type
-}
-
-const schema = transform(User)
-```
-
-**Generated Output:**
-
-```json
-{
-  "name": "User",
-  "schema": {
-    "type": "object",
-    "properties": {
-      "id": {
-        "type": "integer",
-        "format": "int32",
-        "minimum": 1
-      },
-      "name": {
-        "type": "string",
-        "minLength": 2,
-        "maxLength": 100
-      },
-      "email": {
-        "type": "string",
-        "format": "email"
-      },
-      "tags": {
-        "type": "array",
-        "items": {
-          "type": "string"
-        },
-        "minItems": 1
-      },
-      "createdAt": {
-        "type": "string",
-        "format": "date-time"
-      },
-      "role": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "integer",
-            "format": "int32"
-          },
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 50
-          }
-        },
-        "required": ["id"]
-      },
-      "files": {
-        "type": "array",
-        "items": {
-          "type": "string",
-          "format": "binary"
-        }
-      },
-      "avatar": {
-        "type": "string",
-        "format": "binary"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "email",
-      "tags",
-      "createdAt",
-      "role",
-      "files",
-      "avatar"
-    ]
-  }
-}
+const result = transform(User)
+console.log(result.name) // "User"
+console.log(result.schema) // OpenAPI schema object
 ```
 
-> **Note**: Unlike other solutions, this package does **NOT** require `emitDecoratorMetadata: true` or `reflect-metadata`.
-
-## 📊 Pure TypeScript vs Enhanced Mode Comparison
+## 🎯 Required Properties Rules
 
-| 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
+### TypeScript Optional Operator (`?`)
 
-**Pure TypeScript Class:**
+The presence or absence of the TypeScript optional operator (`?`) determines whether a property is required:
 
 ```typescript
 class User {
-  name: string // Required (no ? operator)
-  email: string // Required (no ? operator)
-  age: number // Required (no ? operator)
+  name: string // ✅ REQUIRED (no ? operator)
+  email: string // ✅ REQUIRED (no ? operator)
+  age?: number // ❌ OPTIONAL (has ? operator)
+  bio?: string // ❌ OPTIONAL (has ? operator)
 }
-// Generates: All properties required (no ? operator), basic types
-```
-
-**Enhanced Class:**
-
-```typescript
-class User {
-  @IsString()
-  @IsNotEmpty()
-  name: string
-
-  @IsEmail()
-  email: string
 
-  @IsInt()
-  @Min(18)
-  age: number
-}
-// Generates: All properties required, email format validation, age minimum 18
+// Generated schema:
+// "required": ["name", "email"]
 ```
 
-## 🎨 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 |
-| `@IsEnum(enumObject)` | `type: "string/number/boolean", enum: [values]` | Enum constraint validation  |
-
-### Enum Validation with @IsEnum
+### Override via class-validator Decorators
 
-The `@IsEnum()` decorator provides powerful enum validation with automatic type detection and value extraction:
+class-validator decorators can override the default behavior of the TypeScript optional operator:
 
 ```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
+import { IsNotEmpty, IsOptional } from 'class-validator'
 
-class TaskEntity {
-  @IsEnum(UserRole)
+class User {
   @IsNotEmpty()
-  assignedRole: UserRole // Required enum
-
-  @IsEnum(Priority)
-  priority?: Priority // Optional enum
-
-  @IsEnum(Size)
-  size?: Size // Auto-incremented enum
+  requiredField?: string // ✅ REQUIRED (@IsNotEmpty overrides ?)
 
-  @IsEnum(Status)
-  status?: keyof typeof Status // Object enum
+  @IsOptional()
+  optionalField: string // ❌ OPTIONAL (@IsOptional overrides absence of ?)
 
-  @IsEnum(UserRole)
-  @IsArray()
-  allowedRoles?: UserRole[] // Array of enums
+  normalField: string // ✅ REQUIRED (no ? operator)
+  normalOptional?: string // ❌ OPTIONAL (has ? operator)
 }
 
-const result = transform(TaskEntity)
+// Generated schema:
+// "required": ["requiredField", "normalField"]
 ```
 
-**Generated Output:**
+## 🎨 Supported Decorators
 
-```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:**
+### Type Validation Decorators
 
-- ✅ **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[]`
+| 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 format validation     |
+| `@IsEnum(enumObject)` | `type: "string/number/boolean", enum: [values]` | Enum constraint validation |
 
 ### String Validation Decorators
 
 | Decorator           | Generated Schema Property        | Description           |
 | ------------------- | -------------------------------- | --------------------- |
-| `@IsNotEmpty()`     | Adds to `required` array         | Field is required     |
+| `@IsNotEmpty()`     | Added to `required` array        | Field is required     |
 | `@MinLength(n)`     | `minLength: n`                   | Minimum string length |
 | `@MaxLength(n)`     | `maxLength: n`                   | Maximum string length |
 | `@Length(min, max)` | `minLength: min, maxLength: max` | String length range   |
@@ -999,259 +669,146 @@ const result = transform(TaskEntity)
 | `@ArrayMinSize(n)` | `minItems: n`             | Minimum array size          |
 | `@ArrayMaxSize(n)` | `maxItems: n`             | Maximum array size          |
 
-### Special Type Mappings
-
-| TypeScript Type | Generated OpenAPI Schema              | Description                    |
-| --------------- | ------------------------------------- | ------------------------------ |
-| `Date`          | `type: "string", format: "date-time"` | ISO date-time string           |
-| `Buffer`        | `type: "string", format: "binary"`    | Binary data                    |
-| `Uint8Array`    | `type: "string", format: "binary"`    | Binary array                   |
-| `UploadFile`    | `type: "string", format: "binary"`    | Custom file upload type        |
-| `CustomClass`   | Nested object schema                  | Recursive class transformation |
-| `Type[]`        | Array with typed items                | Array of specific type         |
-
-### Automatic TypeScript Type Detection
-
-The library automatically detects and converts TypeScript types:
-
-```typescript
-class AutoDetectionExample {
-  // Primitives
-  id: number // → type: "number"
-  name: string // → type: "string"
-  isActive: boolean // → type: "boolean"
-
-  // Special types
-  createdAt: Date // → type: "string", format: "date-time"
-  file: Buffer // → type: "string", format: "binary"
-
-  // Arrays
-  tags: string[] // → type: "array", items: { type: "string" }
-  scores: number[] // → type: "array", items: { type: "number" }
-
-  // Objects
-  metadata: object // → type: "object"
-  data: any // → No schema constraints
-
-  // Nested classes (automatically transformed)
-  profile: UserProfile // → Nested object schema
-}
-```
-
-## 📁 File Upload Support
-
-The library provides built-in support for file uploads with automatic binary format mapping:
-
-```typescript
-import { transform } from 'ts-class-to-openapi'
-import { IsNotEmpty, IsArray, IsOptional } from 'class-validator'
-
-// Define your custom file type
-class UploadFile {}
-
-class DocumentUpload {
-  @IsNotEmpty()
-  document: UploadFile // Single file upload (required)
+## 📊 Comparison: Pure TypeScript vs Enhanced Mode
 
-  @IsArray()
-  attachments: UploadFile[] // Multiple file uploads
+| 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 optional operator (`?`)      | 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             |
+| **Use Case**           | Existing codebases, rapid prototyping | APIs with validation, robust schemas |
 
-  @IsOptional()
-  avatar: UploadFile // Optional file upload
-}
-
-// Transform to OpenAPI schema
-const schema = transform(DocumentUpload)
-console.log(JSON.stringify(schema, null, 2))
-```
+## ⚙️ Configuration
 
-**Generated Schema:**
+### Requirements
 
-```json
-{
-  "name": "DocumentUpload",
-  "schema": {
-    "type": "object",
-    "properties": {
-      "document": {
-        "type": "string",
-        "format": "binary"
-      },
-      "attachments": {
-        "type": "array",
-        "items": {
-          "type": "string",
-          "format": "binary"
-        }
-      },
-      "avatar": {
-        "type": "string",
-        "format": "binary"
-      }
-    },
-    "required": ["document", "attachments"]
+- Node.js >= 14.0.0
+- TypeScript with minimal compiler options in `tsconfig.json`:
+  ```json
+  {
+    "compilerOptions": {
+      "experimentalDecorators": true
+    }
   }
-}
-```
-
-### Supported File Types
-
-The following types are automatically converted to binary format:
-
-- `Buffer` - Node.js Buffer objects
-- `Uint8Array` - Typed arrays
-- `UploadFile` - Custom file upload classes
-- Any class ending with "File" suffix (e.g., `ImageFile`, `VideoFile`)
-
-## 📖 API Reference
-
-### `transform(cls: Function)`
+  ```
 
-Transforms a class constructor function into an OpenAPI schema object.
+> **Note**: The `experimentalDecorators` option is only required if you plan to use class-validator decorators. Pure TypeScript classes work without special configuration.
 
-**Parameters:**
+### TypeScript Support
 
-- `cls: Function` - The class constructor function to transform
+This library works with:
 
-**Returns:**
+- ✅ Pure TypeScript classes (no decorators needed)
+- ✅ class-validator decorated classes
+- ✅ Mixed usage (some classes with decorators, some without)
+- ✅ All TypeScript types: primitives, arrays, enums, nested objects
 
-```typescript
-{
-  name: string;        // Class name
-  schema: {
-    type: "object";
-    properties: Record<string, any>;
-    required: string[];
-  }
-}
-```
+### Module Compatibility
 
-**Example:**
+This library is **fully compatible with CommonJS and ESM**:
 
 ```typescript
+// ESM (recommended)
 import { transform } from 'ts-class-to-openapi'
-import { User } from './entities/user.js'
 
-const result = transform(User)
-console.log(result.name) // "User"
-console.log(result.schema) // OpenAPI schema object
+// CommonJS
+const { transform } = require('ts-class-to-openapi')
 ```
 
-## 🔍 Required Properties Rules
-
-Understanding how properties are marked as required is crucial for generating accurate schemas:
-
-### TypeScript Optional Operator (`?`)
+## 🔧 Troubleshooting
 
-The presence or absence of the TypeScript optional operator (`?`) determines if a property is required:
+### Common Issues
 
-```typescript
-class User {
-  name: string // ✅ REQUIRED (no ? operator)
-  email: string // ✅ REQUIRED (no ? operator)
-  age?: number // ❌ OPTIONAL (has ? operator)
-  bio?: string // ❌ OPTIONAL (has ? operator)
-}
+**Error: "Cannot find module 'ts-class-to-openapi'"**
 
-// Generated schema:
-// "required": ["name", "email"]
+```bash
+npm install ts-class-to-openapi
 ```
 
-### class-validator Decorators Override
+**Error: "Cannot find module 'class-validator'"**
 
-When using class-validator decorators, they can override the TypeScript optional behavior:
+This dependency is only necessary for using validation decorators:
 
-```typescript
-import { IsNotEmpty, IsOptional } from 'class-validator'
+```bash
+npm install class-validator
+```
 
-class User {
-  @IsNotEmpty()
-  requiredField?: string // ✅ REQUIRED (@IsNotEmpty overrides ?)
+**Error: "Experimental decorators warning"**
 
-  @IsOptional()
-  optionalField: string // ❌ OPTIONAL (@IsOptional overrides no ?)
+Add the following configuration to the `tsconfig.json` file:
 
-  normalField: string // ✅ REQUIRED (no ? operator)
-  normalOptional?: string // ❌ OPTIONAL (has ? operator)
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
 }
-
-// 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 ?)
+**Empty schema generated**
 
-  optionalTags?: string[] // ❌ OPTIONAL (has ? operator)
-}
+- For pure TypeScript classes: Verify that the class contains properties with correctly defined types
+- For classes with decorators: Confirm that the class includes class-validator decorators
+- Verify that the class is correctly exported and imported
+- Confirm that TypeScript compilation runs without errors
 
-// Generated schema:
-// "required": ["tags", "categories"]
-```
+**Works without decorators but wants validation?**
 
-### Summary of Rules
+Pure TypeScript classes work immediately, but if you want enhanced validation schemas:
 
-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 `?`)
+1. Install class-validator: `npm install class-validator`
+2. Add decorators to the corresponding properties
+3. Enable `experimentalDecorators: true` in the tsconfig.json file
 
 ## 🌟 Advanced Features
 
-- ✅ **Pure TypeScript Support** - Works with any TypeScript class, no decorators required
-- ✅ **Zero Runtime Dependencies** - Uses TypeScript Compiler API instead of reflect-metadata
-- ✅ **High Performance** - Singleton pattern with built-in caching for repeated transformations
-- ✅ **Nested Object Support** - Automatically handles complex object relationships
-- ✅ **Array Type Support** - Full support for typed arrays with validation constraints
-- ✅ **Built-in Caching** - Avoids reprocessing the same classes multiple times
-- ✅ **Type Safety** - Complete TypeScript support with proper type definitions
-- ✅ **Framework Agnostic** - Works with any TypeScript project configuration
-- ✅ **Comprehensive Coverage** - Supports all major class-validator decorators
-- ✅ **Flexible Usage** - Use with or without validation decorators
+- ✅ **Native pure TypeScript support** - Compatible with any TypeScript class without requiring decorators
+- ✅ **Zero runtime dependencies** - Uses TypeScript Compiler API instead of reflect-metadata
+- ✅ **Optimized performance** - Singleton pattern implementation with caching system for repeated transformations
+- ✅ **Nested object processing** - Automatic handling of complex relationships between objects
+- ✅ **Full typed array support** - Comprehensive compatibility with arrays and validation constraints
+- ✅ **Integrated caching system** - Avoids reprocessing the same classes
+- ✅ **Type safety** - Complete TypeScript support with precise type definitions
+- ✅ **Framework agnostic** - Compatible with any TypeScript project configuration
 
 ## 🔄 Migration Guide
 
-### From reflect-metadata Solutions
+### Migration from reflect-metadata Based Solutions
 
-If you're migrating from a solution that requires `reflect-metadata`:
+For projects using solutions that require `reflect-metadata`:
 
-**Before (with reflect-metadata):**
+**Previous implementation (with reflect-metadata):**
 
 ```typescript
 import 'reflect-metadata'
 import { getMetadataStorage } from 'class-validator'
 
-// Complex setup required
+// Complex configuration required
 const schema = transformClassToSchema(User)
 ```
 
-**After (with ts-class-to-openapi):**
+**New implementation (with ts-class-to-openapi):**
 
 ```typescript
 import { transform } from 'ts-class-to-openapi'
 
-// Simple, clean API
+// Simplified API
 const schema = transform(User)
 ```
 
-### New: Pure TypeScript Support
+### New Functionality: Pure TypeScript Support
 
-The biggest advantage is that you can now transform **any TypeScript class** without requiring decorators:
+The main advantage lies in the ability to transform **any TypeScript class** without requiring decorators:
 
-**Before (required decorators):**
+**Previous limitation (mandatory decorators):**
 
 ```typescript
-// This would NOT work with traditional solutions
+// This approach would NOT work with traditional solutions
 class LegacyUser {
   id: number
   name: string
@@ -1259,92 +816,21 @@ class LegacyUser {
 }
 ```
 
-**Now (works immediately):**
+**Current implementation (immediate functionality):**
 
 ```typescript
 import { transform } from 'ts-class-to-openapi'
 
-// This works out of the box!
+// Ready-to-use functionality
 class LegacyUser {
   id: number
   name: string
   email: string
 }
 
-const schema = transform(LegacyUser) // ✅ Works perfectly
+const schema = transform(LegacyUser) // ✅ Successful operation
 ```
 
-### Migration Steps
-
-1. **Remove reflect-metadata imports** from your entities
-2. **Remove `emitDecoratorMetadata: true`** from tsconfig.json (optional)
-3. **Update transformation code** to use the new API
-4. **Remove reflect-metadata dependency** from package.json
-5. **Optional**: Keep decorators for enhanced validation or remove them entirely
-
-### TypeScript Configuration
-
-You only need minimal TypeScript configuration:
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true
-    // emitDecoratorMetadata: true ← NOT REQUIRED!
-  }
-}
-```
-
-## 🔧 Troubleshooting
-
-### Common Issues
-
-**Error: "Cannot find module 'ts-class-to-openapi'"**
-
-```bash
-npm install ts-class-to-openapi
-```
-
-**Error: "Cannot find module 'class-validator'"**
-
-This is only needed if you want to use validation decorators:
-
-```bash
-npm install class-validator
-```
-
-**Error: "Experimental decorators warning"**
-Add to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true
-  }
-}
-```
-
-**Empty schema generated**
-
-- For pure TypeScript classes: Ensure your class has properly typed properties
-- For class-validator enhanced: Ensure your class has class-validator decorators
-- Check that the class is properly exported/imported
-- Verify TypeScript compilation is working
-
-**Works without decorators but want validation?**
-
-Pure TypeScript classes work immediately, but if you want enhanced validation schemas:
-
-1. Install class-validator: `npm install class-validator`
-2. Add decorators to your properties
-3. Enable `experimentalDecorators: true` in tsconfig.json
-
-**Nested objects not working**
-
-- Make sure nested classes are in the same project
-- Ensure nested classes have their own decorators
-- Check file paths and imports
-
 ## 📄 License
 
 MIT