npm package: @hatung/nx-nest-ddd
Description: A comprehensive Nx plugin for generating Domain-Driven Design (DDD) architecture with NestJS
Author: NWS-AI-Codex
Latest version: 1.1.2

# nx-nest-ddd

A comprehensive Nx plugin for generating Domain-Driven Design (DDD) architecture with NestJS. This plugin provides powerful generators for building scalable, maintainable applications following DDD principles, Clean Architecture, and CQRS patterns.

## 🚀 Features

- **🏗️ Complete DDD Architecture**: Generate domain, application, infrastructure, and UI layers with a single command
- **⚡ CQRS Support**: Built-in command and query generators with proper separation
- **🧹 Clean Architecture**: Proper separation of concerns across architectural layers
- **🪶 NestJS Integration**: Seamless integration with NestJS framework and ecosystem
- **🔌 Multiple UI Options**: Support for both REST and GraphQL API interfaces
- **🛡️ Type Safety**: Full TypeScript support with proper typing and interfaces
- **📦 Modular Design**: Generate individual components or complete bounded contexts
- **🧪 Testing Ready**: Includes test structure and e2e test applications
- **📖 Best Practices**: Follows industry standards and DDD patterns

## 📦 Installation

Install the plugin in your Nx workspace:

```bash
npm install --save-dev @hatung/nx-nest-ddd
# or
yarn add --dev @hatung/nx-nest-ddd
# or
pnpm add --save-dev @hatung/nx-nest-ddd
```

## 🎯 Quick Start

Generate a complete DDD bounded context in seconds:

```bash
nx g @hatung/nx-nest-ddd:sub-domain my-feature
```

This creates a fully functional DDD architecture with API, libraries, and tests ready to use!

## ⚙️ Generator Options

Most generators accept common options to customize the generated code:

### Common Options
- `--subDomain` - The sub-domain that contains the component (required for most generators)
- `--sourceRoot` - Override the default directory location
- `--templatePath` - Use custom templates for generation

### Sub-Domain Generator Options
- `--directory` - Directory where the application is placed
- `--tags` - Add tags for linting (e.g., "domain:users,layer:api")  
- `--strict` - Enable TypeScript strict mode (default: true)
- `--target` - ES target version (default: es2021)
- `--testEnvironment` - Jest test environment: "node" or "jsdom"
- `--skipFormat` - Skip formatting files
- `--skipPackageJson` - Don't add dependencies to package.json

### Properties Support

Many generators support defining properties for entities and value objects:

#### String Format (recommended for CLI)
```bash
--propertiesString="name:string,email:string,isActive:boolean:true"
```

#### JSON Array Format
```bash
--properties='[{"name":"title","type":"string"},{"name":"price","type":"number"},{"name":"available","type":"boolean","optional":true}]'
```

#### Property Format
- `name:type` - Required property
- `name:type:true` - Optional property (third parameter indicates optional)
- Supported types: `string`, `number`, `boolean`, `Date`, custom types

## 📚 Usage

### 🏛️ Generate a Complete Sub-Domain

Create a complete bounded context with all layers:

```bash
# Basic sub-domain
nx g @hatung/nx-nest-ddd:sub-domain my-feature

# Sub-domain with custom options
nx g @hatung/nx-nest-ddd:sub-domain users --tags="domain:users,layer:api" --directory=business

# Sub-domain with TypeScript strict mode disabled
nx g @hatung/nx-nest-ddd:sub-domain orders --strict=false --target=es2020
```

This command creates a complete Domain-Driven Design structure with the following components and folders:

#### Applications Generated:
- **`apps/<domain-name>/api/`** - NestJS API application
- **`apps/<domain-name>/api-e2e/`** - End-to-end tests for the API

#### Libraries Generated:
- **`libs/<domain-name>/domain/`** - Domain layer with:
  - `src/aggregates/` - Domain aggregates and root entities
  - `src/entities/` - Domain entities
  - `src/events/` - Domain events
  - `src/exceptions/` - Domain-specific exceptions
  - `src/repositories/` - Repository interfaces
  - `src/services/` - Domain services

- **`libs/<domain-name>/application/`** - Application layer with:
  - `src/commands/` - CQRS command handlers
  - `src/queries/` - CQRS query handlers  
  - `src/events/` - Application event handlers
  - `src/modules/` - Application modules

- **`libs/<domain-name>/infrastructure/`** - Infrastructure layer with:
  - `src/repositories/` - Repository implementations
  - `src/orm-entities/` - Database entities
  - `src/orm-mappers/` - Domain-to-ORM mappers
  - `src/modules/` - Infrastructure modules

- **`libs/<domain-name>/graphql-ui/`** - GraphQL API layer with:
  - `src/modules/` - GraphQL modules
  - `src/queries/` - GraphQL query resolvers
  - `src/mutations/` - GraphQL mutation resolvers
  - `src/types/` - GraphQL type definitions

- **`libs/<domain-name>/rest-ui/`** - REST API layer with:
  - `src/controllers/` - REST controllers
  - `src/dto/` - Data Transfer Objects
  - `src/modules/` - REST modules

### 🏗️ Generate Domain Layer Components

Build your domain layer with core business logic:

```bash
# Domain entity - Core business objects with properties
nx g @hatung/nx-nest-ddd:domain-entity user users --propertiesString="name:string,email:string,isActive:boolean:true"

# Domain entity with individual properties array
nx g @hatung/nx-nest-ddd:domain-entity product catalog --properties='[{"name":"title","type":"string"},{"name":"price","type":"number"},{"name":"available","type":"boolean","optional":true}]'

# Value object - Immutable domain concepts with properties
nx g @hatung/nx-nest-ddd:domain-value-object email users --propertiesString="value:string"

# Domain aggregate - Consistency boundaries
nx g @hatung/nx-nest-ddd:domain-aggregate order orders --propertiesString="customerId:string,totalAmount:number,status:OrderStatus"

# Domain service - Business logic that doesn't fit in entities
nx g @hatung/nx-nest-ddd:domain-service user-service users

# Domain event - Business events for decoupling
nx g @hatung/nx-nest-ddd:domain-event user-created users

# Domain repository interface - Data access contracts
nx g @hatung/nx-nest-ddd:domain-repository user-repository users
```

### ⚡ Generate Application Layer Components

Implement use cases and CQRS patterns:

```bash
# Application layer - Complete application services
nx g @hatung/nx-nest-ddd:application user

# CQRS Commands - Write operations with sub-domain
nx g @hatung/nx-nest-ddd:application-command create-user users
nx g @hatung/nx-nest-ddd:application-command update-user users --sourceRoot=libs/users/application

# CQRS Queries - Read operations with sub-domain
nx g @hatung/nx-nest-ddd:application-query get-user users
nx g @hatung/nx-nest-ddd:application-query find-users users --sourceRoot=libs/users/application

# Application events - Cross-cutting concerns
nx g @hatung/nx-nest-ddd:application-event user-processed users
```

### 🔧 Generate Infrastructure Layer Components

Handle persistence and external concerns:

```bash
# Infrastructure layer - Complete infrastructure setup
nx g @hatung/nx-nest-ddd:infrastructure user

# ORM entities - Database representations
nx g @hatung/nx-nest-ddd:infrastructure-orm-entity user

# ORM mappers - Domain to database mapping
nx g @hatung/nx-nest-ddd:infrastructure-orm-mapper user

# Repository implementations - Data access implementations
nx g @hatung/nx-nest-ddd:infrastructure-repository user-repository
```

### 🌐 Generate UI Layer Components

Create API interfaces for external communication:

```bash
# REST API - HTTP endpoints
nx g @hatung/nx-nest-ddd:rest-ui user
nx g @hatung/nx-nest-ddd:rest-controller user

# GraphQL API - GraphQL schema and resolvers
nx g @hatung/nx-nest-ddd:graphql-ui user
nx g @hatung/nx-nest-ddd:graphql-query get-user
nx g @hatung/nx-nest-ddd:graphql-mutation create-user
```

## 🏛️ Architecture Overview

This plugin implements a clean, layered architecture following DDD principles:

```
┌─────────────────────────────────────────────────────────────┐
│                        🌐 UI Layer                           │
│              REST Controllers | GraphQL Resolvers          │
├─────────────────────────────────────────────────────────────┤
│                   ⚡ Application Layer                       │
│        Commands | Queries | Event Handlers | Use Cases     │
├─────────────────────────────────────────────────────────────┤
│                     🏗️ Domain Layer                          │
│    Entities | Aggregates | Value Objects | Domain Services │
├─────────────────────────────────────────────────────────────┤
│                  🔧 Infrastructure Layer                     │
│     Repositories | ORM Entities | External Services        │
└─────────────────────────────────────────────────────────────┘
```

### Layer Responsibilities

- **🌐 UI Layer**: API contracts, request/response handling, authentication
- **⚡ Application Layer**: Business workflows, CQRS implementation, transaction boundaries
- **🏗️ Domain Layer**: Core business rules, domain logic, business invariants
- **🔧 Infrastructure Layer**: Data persistence, external integrations, technical concerns

## 📋 Requirements

- **Node.js** >= 18
- **Nx** >= 21.0.0  
- **NestJS** project structure
- **TypeScript** enabled

## 🛠️ Development

### Building
```bash
nx build nx-nest-ddd
```

### Running Tests
```bash
nx test nx-nest-ddd
```

### Local Development
```bash
# Link for local development
npm link

# Use in another project
npm link @hatung/nx-nest-ddd
```

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. **🍴 Fork** the repository
2. **🌿 Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **💾 Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **📤 Push** to the branch (`git push origin feature/amazing-feature`)
5. **🔄 Open** a Pull Request

### Development Guidelines

- Follow existing code patterns and conventions
- Add tests for new generators
- Update documentation for new features
- Ensure all tests pass before submitting

## 📝 Changelog

### v1.1.0
- 📚 Enhanced README with comprehensive generator options and properties documentation
- ⚙️ Added detailed examples for using properties in entity and value object generation
- 🎯 Improved architectural diagrams and visual explanations
- 🛠️ Added development guidelines and contribution instructions
- ✨ Better CLI examples with real-world usage patterns
- 📖 Documented all available generator options and their usage

### v1.0.0
- Initial release with complete DDD generators
- Support for Domain, Application, Infrastructure, and UI layers
- CQRS command and query generators
- REST and GraphQL API generators

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with ❤️ by the [NWS-AI-Codex](https://github.com/NWS-AI-Codex) team
- Inspired by Domain-Driven Design principles by Eric Evans
- Powered by [Nx](https://nx.dev) and [NestJS](https://nestjs.com)