nestjs-ddd-cli 2.0.1 → 2.0.2

package/README.md

@@ -1,6 +1,10 @@
 # NestJS DDD CLI
 
-A CLI tool for generating NestJS boilerplate code following pragmatic DDD/CQRS patterns.
+🏗️ **An opinionated CLI for pragmatic Domain-Driven Design with NestJS**
+
+Stop writing boilerplate. Start building business logic.
+
+Generate production-ready NestJS code following proven DDD/CQRS patterns with consistent structure and immutable architecture principles.
 
 ## Installation
 
@@ -76,94 +80,380 @@ ddd generate all User -m user-management
 | **Complete CRUD** | `ddd scaffold <name> -m <module>` | All files for an entity |
 | **All Entity Files** | `ddd generate all <name> -m <module>` | Entity + related files |
 
-## Generated Structure
+## Quick Start
+
+### 🚀 **Generate Your First Feature**
+
+```bash
+# 1. Create complete scaffolding for a User management feature
+ddd scaffold User -m user-management
 
+# 2. Add business logic to the generated files
+# 3. Update index.ts exports
+# 4. Run migrations  
+# 5. Import module in app.module.ts
+```
+
+**What you get in seconds:**
+```
+📁 modules/user-management/
+├── 📄 user-management.module.ts      ✅ NestJS module configured
+├── 📁 application/
+│   ├── 📁 controllers/
+│   │   └── 📄 user.controller.ts     ✅ REST endpoints (GET, POST, PUT, DELETE)
+│   ├── 📁 domain/
+│   │   ├── 📁 entities/
+│   │   │   └── 📄 user.entity.ts     ✅ Domain entity with interfaces
+│   │   └── 📁 usecases/
+│   │       ├── 📄 create-user.usecase.ts ✅ Business logic for creation
+│   │       ├── 📄 update-user.usecase.ts ✅ Business logic for updates  
+│   │       └── 📄 delete-user.usecase.ts ✅ Business logic for deletion
+│   └── 📁 dto/
+│       ├── 📁 requests/
+│       │   ├── 📄 create-user.dto.ts ✅ Request validation schemas
+│       │   └── 📄 update-user.dto.ts ✅ Update validation schemas
+│       └── 📁 responses/
+│           └── 📄 user.response.ts   ✅ Response data contracts
+└── 📁 infrastructure/
+    ├── 📁 repositories/
+    │   └── 📄 user.repository.ts     ✅ CRUD operations + custom queries
+    ├── 📁 orm-entities/
+    │   └── 📄 user.orm-entity.ts     ✅ Database schema (TypeORM)
+    └── 📁 mappers/
+        └── 📄 user.mapper.ts         ✅ Domain ↔ Database mapping
 ```
-modules/
-└── [module-name]/
-    ├── application/
-    │   ├── commands/           # CQRS command handlers
-    │   ├── controllers/        # REST controllers
-    │   ├── domain/
-    │   │   ├── entities/       # Domain entities
-    │   │   ├── events/         # Domain events
-    │   │   ├── services/       # Domain services
-    │   │   └── usecases/       # Use cases/command handlers
-    │   ├── dto/
-    │   │   ├── requests/       # Request DTOs
-    │   │   └── responses/      # Response DTOs
-    │   └── queries/            # CQRS query handlers
-    ├── infrastructure/
-    │   ├── mappers/            # Domain ↔ ORM mappers
-    │   ├── orm-entities/       # Database entities
-    │   └── repositories/       # Repository implementations
-    └── [module-name].module.ts # NestJS module
-```
-
-## Examples
-
-### Create a new feature from scratch
+
+> **🚀 From zero to production-ready in under 30 seconds**
+
+## Real-World Examples
+
+### 🏢 **E-commerce Platform**
 
 ```bash
-# 1. Generate complete scaffolding for a Policy entity
-ddd scaffold Policy -m policies
+# Generate order management
+ddd scaffold Order -m orders
 
-# 2. Update the generated files with business logic
-# 3. Update index.ts files to export new classes
-# 4. Run the generated migration
-# 5. Import PoliciesModule in app.module.ts
+# Add payment processing
+ddd generate service PaymentProcessor -m orders
+ddd generate event OrderPaid -m orders
+
+# Add inventory checking  
+ddd generate query CheckStock -m inventory
+ddd generate service StockValidator -m inventory
 ```
 
-### Add a new entity to existing module
+**Result:** Complete order system with payment processing and inventory management
+```
+📁 modules/orders/
+├── 📄 orders.module.ts
+├── 📁 application/domain/services/
+│   └── 📄 payment-processor.service.ts  🆕 Payment business logic
+├── 📁 application/domain/events/  
+│   └── 📄 order-paid.event.ts          🆕 Order payment event
+└── ... (all CRUD operations)
+
+📁 modules/inventory/
+├── 📁 application/queries/
+│   └── 📄 check-stock.handler.ts       🆕 Stock checking query
+├── 📁 application/domain/services/
+│   └── 📄 stock-validator.service.ts   🆕 Stock validation logic
+└── ... (all CRUD operations)
+```
+
+### 🏥 **Healthcare System**
 
 ```bash
-# Generate entity with all related files
-ddd generate all Coverage -m policies
+# Patient management
+ddd scaffold Patient -m patients
+
+# Medical records with events
+ddd scaffold MedicalRecord -m medical-records
+ddd generate event RecordCreated -m medical-records
+ddd generate event RecordUpdated -m medical-records
+
+# Appointment scheduling
+ddd generate query FindAvailableSlots -m appointments
+ddd generate service AppointmentScheduler -m appointments
 ```
 
-### Add individual DDD components
+### 🎓 **Learning Management System**
 
 ```bash
-# Generate a new use case
-ddd generate usecase ApproveCoverage -m policies
+# Course management
+ddd scaffold Course -m courses
+ddd generate service CourseEnrollment -m courses
+ddd generate event StudentEnrolled -m courses
+
+# Progress tracking
+ddd generate query GetStudentProgress -m progress
+ddd generate service ProgressCalculator -m progress
+```
 
-# Generate a domain service for business logic
-ddd generate service PolicyValidation -m policies
+> **🎯 Each example follows identical patterns** - Learn once, apply everywhere.
 
-# Generate a domain event
-ddd generate event PolicyApproved -m policies
+## Philosophy & Principles
+
+This CLI embodies **pragmatic Domain-Driven Design** with unwavering consistency:
+
+### 🔒 **Immutable Architecture**
+- **"Code once, never touch"** - Each generated component remains unchanged after creation
+- **Evolution over modification** - New requirements create new use cases, never modify existing ones
+- **Predictable structure** - Every project follows identical patterns, enabling instant developer onboarding
+
+### 🎯 **Opinionated by Design**
+- **Zero configuration fatigue** - One way to do things, the right way
+- **Consistent naming** - PascalCase entities, kebab-case modules, predictable file names
+- **Proven patterns** - Battle-tested DDD/CQRS structure from real-world enterprise applications
+
+### 🚀 **Developer Experience First**
+- **No bikeshedding** - Spend time on business logic, not folder structure debates
+- **IDE-friendly** - Barrel exports, clear interfaces, TypeScript-first approach
+- **Team consistency** - Every developer generates identical code structure
+
+### 🏗️ **Enterprise Ready**
+- **Separation of concerns** - Domain logic isolated from infrastructure
+- **CQRS compliance** - Commands for writes, queries for reads
+- **Testable by default** - Clean interfaces enable easy unit testing
+
+## What Makes This Different?
+
+### 🎨 **Structure That Scales**
+
+Every module follows this **identical, battle-tested structure**:
 
-# Generate a query handler
-ddd generate query GetPolicyDetails -m policies
 ```
+modules/
+└── [feature-name]/                           # 🏠 Feature boundary
+    ├── [feature-name].module.ts              # 🔧 NestJS module wiring
+    ├── application/                          # 📋 Application layer
+    │   ├── commands/                         # ✍️  CQRS commands (writes)
+    │   │   ├── create-[entity].command.ts    #    └─ Create operations
+    │   │   ├── update-[entity].command.ts    #    └─ Update operations  
+    │   │   ├── delete-[entity].command.ts    #    └─ Delete operations
+    │   │   └── index.ts                      #    └─ Barrel exports
+    │   ├── controllers/                      # 🌐 HTTP/GraphQL endpoints
+    │   │   ├── [entity].controller.ts        #    └─ REST API endpoints
+    │   │   └── index.ts                      #    └─ Barrel exports
+    │   ├── domain/                           # 🧠 Pure business logic
+    │   │   ├── entities/                     # 📦 Business objects
+    │   │   │   ├── [entity].entity.ts        #    └─ Domain entity
+    │   │   │   └── index.ts                  #    └─ Barrel exports
+    │   │   ├── events/                       # 🎯 Domain events
+    │   │   │   ├── [entity]-created.event.ts #    └─ Event definitions
+    │   │   │   └── index.ts                  #    └─ Barrel exports
+    │   │   ├── services/                     # ⚙️  Domain services
+    │   │   │   ├── [entity].service.ts       #    └─ Business rules
+    │   │   │   └── index.ts                  #    └─ Barrel exports
+    │   │   └── usecases/                     # 🎬 Use case operations
+    │   │       ├── create-[entity].usecase.ts#    └─ Create business logic
+    │   │       ├── update-[entity].usecase.ts#    └─ Update business logic
+    │   │       ├── delete-[entity].usecase.ts#    └─ Delete business logic
+    │   │       └── index.ts                  #    └─ Barrel exports
+    │   ├── dto/                              # 📄 Data contracts
+    │   │   ├── requests/                     # 📤 Inbound data
+    │   │   │   ├── create-[entity].dto.ts    #    └─ Create request
+    │   │   │   ├── update-[entity].dto.ts    #    └─ Update request
+    │   │   │   └── index.ts                  #    └─ Barrel exports
+    │   │   ├── responses/                    # 📥 Outbound data
+    │   │   │   ├── [entity].response.ts      #    └─ Entity response
+    │   │   │   └── index.ts                  #    └─ Barrel exports
+    │   │   └── index.ts                      #    └─ Barrel exports
+    │   └── queries/                          # 🔍 CQRS queries (reads)
+    │       ├── get-[entity].handler.ts       #    └─ Single entity query
+    │       ├── list-[entities].handler.ts    #    └─ Multiple entities query
+    │       └── index.ts                      #    └─ Barrel exports
+    └── infrastructure/                       # 🏗️  Infrastructure layer
+        ├── mappers/                          # 🔄 Data transformation
+        │   ├── [entity].mapper.ts            #    └─ Domain ↔ ORM mapping
+        │   └── index.ts                      #    └─ Barrel exports
+        ├── orm-entities/                     # 🗄️  Database schema
+        │   ├── [entity].orm-entity.ts        #    └─ TypeORM entity
+        │   └── index.ts                      #    └─ Barrel exports
+        └── repositories/                     # 💾 Data access
+            ├── [entity].repository.ts        #    └─ Repository implementation
+            └── index.ts                      #    └─ Barrel exports
+```
+
+> **🎯 Every feature looks identical** - No surprises, no confusion, just consistency.
 
-## Philosophy
+### 🧠 **Smart Defaults & Conventions**
 
-This CLI follows the "code once, never touch" philosophy:
-- Each feature is immutable once written
-- Changes create new use cases, not modify existing ones
-- Boilerplate is predictable and consistent
-- Focus on business logic, not structure
+```bash
+# Naming follows strict patterns
+ddd generate entity UserProfile    # → user-profile.entity.ts
+ddd generate service OrderValidator # → order-validator.service.ts  
+ddd generate event PaymentProcessed # → payment-processed.event.ts
+```
+
+**Built-in Intelligence:**
+- **🔄 Barrel exports** - Automatic `index.ts` files for clean imports
+- **🔒 TypeScript strict** - Zero `any` types, full type safety  
+- **💉 DI ready** - Injectable decorators configured
+- **📋 Interface first** - Clear contracts between layers
+- **📁 Predictable paths** - Same location every time
+
+### 💡 **Enterprise Patterns**
+
+```typescript
+// ✅ Commands (writes) - Tell, don't ask
+@CommandHandler(CreateUserCommand)
+export class CreateUserHandler {
+  async execute(command: CreateUserCommand): Promise<void> {
+    // Returns nothing - just does the work
+  }
+}
+
+// ✅ Queries (reads) - Ask, don't tell  
+@QueryHandler(GetUserQuery)
+export class GetUserHandler {
+  async execute(query: GetUserQuery): Promise<UserResponse> {
+    // Returns data - no side effects
+  }
+}
+
+// ✅ Domain Events - Loose coupling
+export class UserCreatedEvent implements IEvent {
+  constructor(public readonly userId: string) {}
+}
+```
+
+**Battle-tested principles:**
+- **Command/Query Separation** - Writes vs reads clearly separated
+- **Domain Events** - Decoupled communication between bounded contexts
+- **Repository Pattern** - Abstract data access from business logic
+- **Clean Architecture** - Dependencies point inward to domain
 
 ## After Generation
 
-1. **Update index.ts files**: Add new classes to the barrel exports
-2. **Add entity properties**: Define domain properties in entities and DTOs
-3. **Update mappers**: Add field mappings between domain and ORM entities
-4. **Run migrations**: Execute the generated migration files
-5. **Import module**: Add module to app.module.ts imports
+### 🔧 **Your 5-Minute Setup Checklist:**
+
+```bash
+# ✅ 1. Generated files are ready - Review structure
+ls -la modules/your-feature/
+
+# ✅ 2. Add business properties to entities
+# Edit: application/domain/entities/[entity].entity.ts
+#   Add: name: string; email: string; etc.
+
+# ✅ 3. Update DTOs with validation rules  
+# Edit: application/dto/requests/create-[entity].dto.ts
+#   Add: @IsEmail() email: string; @IsNotEmpty() name: string;
+
+# ✅ 4. Configure database mappings
+# Edit: infrastructure/orm-entities/[entity].orm-entity.ts  
+#   Add: @Column() name: string; @Column() email: string;
+
+# ✅ 5. Wire up the module
+# Edit: app.module.ts
+#   Add: YourFeatureModule to imports array
+```
+
+### 🎯 **Focus on Business Value:**
+```typescript
+// ✅ Write business rules in domain services
+export class OrderValidator {
+  validateBusinessRules(order: Order): ValidationResult {
+    // Your domain logic here - not infrastructure concerns
+  }
+}
+
+// ✅ Add complex queries for reporting
+@QueryHandler(GetMonthlyRevenueQuery) 
+export class GetMonthlyRevenueHandler {
+  async execute(query: GetMonthlyRevenueQuery) {
+    // Complex business queries - not CRUD
+  }
+}
+
+// ✅ Handle domain events for integration
+@EventsHandler(OrderCreatedEvent)
+export class OrderCreatedHandler {
+  async handle(event: OrderCreatedEvent) {
+    // Send emails, update analytics, etc.
+  }
+}
+```
+
+> **🚀 From scaffolding to production in minutes, not days**
+
+## Why This CLI Exists
+
+### 😤 **The Problem**
+- Endless debates about folder structure
+- Inconsistent naming across team members
+- Copy-pasting boilerplate between features  
+- Mixed patterns in the same codebase
+- New developers spending weeks learning "our way"
+
+### 🎯 **The Solution**
+- **One structure** that works for all features
+- **Zero configuration** - works out of the box
+- **Battle-tested patterns** from real enterprise apps
+- **Instant onboarding** - same structure everywhere
+- **Focus on business logic** instead of architecture decisions
 
-## Development
+### 🏆 **The Result**
+- 10x faster feature development
+- Consistent codebase architecture
+- Easy code reviews and maintenance
+- New developers productive from day one
+- No more "where does this file go?" questions
 
-To modify the CLI:
+---
+
+## Contributing & Development
+
+### 🔧 **Local Development**
 
 ```bash
-# Make changes
+# Clone and setup
+git clone https://github.com/eshe-huli/nestjs-ddd-cli
+cd nestjs-ddd-cli
+npm install
+
+# Test changes locally
 npm run dev -- generate entity Test -m test
 
-# Rebuild
+# Build for production  
 npm run build
 
-# Test globally
+# Test globally installed version
 ddd generate entity Test -m test
-```
+```
+
+### 🧪 **Testing Your Changes**
+
+```bash
+# Create a test project
+mkdir test-project && cd test-project
+
+# Test scaffolding
+ddd scaffold Product -m inventory
+
+# Verify structure matches expectations
+tree modules/inventory/
+
+# Test individual generators  
+ddd generate service ProductValidator -m inventory
+ddd generate event ProductCreated -m inventory
+ddd generate query GetProductsByCategory -m inventory
+```
+
+### 📋 **Template Structure**
+```
+src/templates/
+├── 📁 entity/           # Domain entity templates
+├── 📁 service/          # Domain service templates  
+├── 📁 event/            # Domain event templates
+├── 📁 query/            # Query handler templates
+├── 📁 usecase/          # Use case templates
+├── 📁 controller/       # Controller templates
+├── 📁 repository/       # Repository templates
+└── 📁 ... (more templates)
+```
+
+> **🤝 Pull requests welcome!** Help make DDD development even better.
+
+## License
+
+MIT - Build amazing things 🚀

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-ddd-cli",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "CLI for generating NestJS DDD boilerplate code",
   "main": "dist/index.js",
   "bin": {