Herbal Peppermint - DDD NestJS Library

A comprehensive Domain-Driven Design (DDD) library for NestJS applications, providing a robust foundation for building scalable and maintainable applications.

Overview

Herbal Peppermint is designed to help developers implement DDD principles in their NestJS applications. It provides a structured approach to organizing code, handling errors, and implementing common patterns like CQRS and Event Sourcing.

Architecture

The library follows a clean architecture approach with clear separation of concerns:

src/
├── adapters/                 # External interface adapters
│   ├── http/                # HTTP-related adapters
│   │   └── rest/           # REST-specific implementations
│   │       └── decorators/ # REST-specific decorators
│   ├── graphql/            # GraphQL adapters
│   ├── messaging/          # Message queue adapters
│   └── persistence/        # Database adapters
├── core/                    # Core business logic
│   ├── application/        # Application services
│   ├── domain/            # Domain models and logic
│   ├── common/            # Shared utilities
│   └── infrastructure/    # Core infrastructure
├── errors/                 # Error handling
│   ├── application/       # Application-level errors
│   ├── domain/           # Domain-level errors
│   ├── infrastructure/   # Infrastructure-level errors
│   └── filters/         # Error filters
├── modules/               # Feature modules
├── patterns/             # Design patterns
│   ├── cqrs/            # CQRS implementation
│   ├── event-sourcing/  # Event sourcing
│   ├── messaging/       # Messaging patterns
│   └── repository/      # Repository pattern
└── testing/             # Testing utilities

Features

Domain Layer

• Rich domain models
• Value objects
• Domain events
• Domain services
• Aggregates
• Repositories

Application Layer

• Application services
• DTOs
• Command/Query handlers
• Event handlers
• Use cases

Infrastructure Layer

• Database adapters (TypeORM, Knex)
• HTTP adapters (REST, GraphQL)
• Message queue adapters
• External service integrations

Error Handling

• Hierarchical error system
  • Domain errors
  • Application errors
  • Infrastructure errors
• Error filters and parsers
• Metadata support for debugging
• Custom error types for different layers

REST Decorators

• Validation decorators
  • @IsTimeString()
  • @IsIsoDate()
  • @IsLessThan()
  • @IsMoreThan()
  • @IsLessThanOrEqual()
  • @IsMoreThanOrEqual()
  • @NotEqualTo()
• Utility decorators
  • @EnsureArray()

Installation

npm install herbal-peppermint
# or
yarn add herbal-peppermint

Usage

Basic Setup

import { Module } from '@nestjs/common';
import { HerbalPeppermintModule } from 'herbal-peppermint';

@Module({
  imports: [HerbalPeppermintModule],
})
export class AppModule {}

Using Decorators

import { IsTimeString, IsLessThan, EnsureArray } from 'herbal-peppermint/adapters/http/rest/decorators';

export class CreateEventDto {
  @IsTimeString()
  startTime: string;

  @IsLessThan('startTime')
  endTime: string;

  @EnsureArray()
  tags: string[];
}

Error Handling

import { DomainError, ApplicationError, InfrastructureError } from 'herbal-peppermint/errors';

// Domain error
throw new DomainError('InvalidOperation', 'Cannot perform this operation');

// Application error
throw new ApplicationError('ValidationFailed', 'Invalid input data');

// Infrastructure error
throw new InfrastructureError('DatabaseConnectionFailed', 'Failed to connect to database');

Testing

The library includes comprehensive testing utilities:

import { TestUtils } from 'herbal-peppermint/testing';

describe('MyService', () => {
  let service: MyService;

  beforeEach(() => {
    service = TestUtils.createService(MyService);
  });

  it('should handle domain events', () => {
    // Test implementation
  });
});

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.