@nestjslatam/ddd-lib 1.0.56 → 2.0.0

package/README.md

@@ -1,30 +1,408 @@
-# Ddd Library
+# @nestjslatam/ddd-lib
 
-Welcome to DDD Library for NESTJS, an innovative open-source library crafted to seamlessly integrate Domain-Driven Design (DDD) principles into your NESTJS applications. This powerful library is meticulously developed with a focus on TypeScript, leveraging the robust capabilities of NESTJS and ensuring seamless compatibility with Node.js.
+A comprehensive Domain-Driven Design (DDD) library for NestJS applications, providing building blocks and patterns to implement clean, maintainable, and scalable enterprise applications.
 
-Domain-Driven Design has proven to be a game-changer in building scalable and maintainable applications by placing the domain at the heart of the software design process. With [Library Name], we aim to simplify the application of DDD concepts within the NESTJS framework, empowering developers to create well-architected, domain-centric solutions.
+[![npm version](https://badge.fury.io/js/%40nestjslatam%2Fddd-lib.svg)](https://www.npmjs.com/package/@nestjslatam/ddd-lib)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## DISCLAIMER: This library is not ready to be used in production environments
+## ⚠️ Development Status
 
-# Key Features:
+**Version 2.0.0** - This library is actively developed and NOT recommended for production use. Breaking changes may occur between minor versions.
 
-- NESTJS Integration: DDD Library for NESTJS is designed from the ground up to seamlessly integrate with NESTJS, a leading framework for building efficient and scalable server-side applications with TypeScript.
-- TypeScript Support: Take advantage of the static typing and modern features of TypeScript, enhancing the development experience and catching errors early in the development process.
-- Node.js Compatibility: DDD Library for NESTJS is built to support Node.js, allowing you to harness the full power of JavaScript on the server side.
-- Domain-Driven Design Principles: Embrace the core principles of DDD effortlessly. DDD Library for NESTJS provides abstractions and utilities that align with DDD concepts, allowing you to model your domain in a clear and expressive manner.
-- Modularity and Extensibility: Enjoy a modular and extensible architecture that adapts to the complexity of your application. DDD Library for NESTJS empowers you to build scalable systems by encapsulating domain logic in a modular fashion.
-- Community-Driven: As an open-source project, DDD Library for NESTJS thrives on community collaboration. Contribute, share your insights, and join the growing community of developers dedicated to enhancing DDD practices within NESTJS.
+## 🎯 What is Domain-Driven Design?
 
-# Getting Started:
+Domain-Driven Design has proven to be a game-changer in building scalable and maintainable applications by placing the domain at the heart of the software design process. This library simplifies the application of DDD concepts within the NestJS framework, empowering developers to create well-architected, domain-centric solutions.
 
-To start incorporating DDD principles into your NESTJS projects, DDD Library for NESTJS offers comprehensive documentation, examples, and tutorials to guide you through the implementation process. Whether you are a seasoned developer or new to DDD, our library provides the tools you need to create robust, maintainable, and scalable applications.
+## ✨ Key Features
 
-Explore the potential of DDD Library for NESTJS today and elevate your NESTJS projects to new heights by seamlessly integrating Domain-Driven Design into your development workflow. Together, let's build software that truly reflects the intricacies of your business domain.
+### 🏗️ Core DDD Building Blocks
 
-### Install
+- **Aggregate Roots**: Base class `DddAggregateRoot` with built-in validation and state tracking
+- **Value Objects**: `StringValueObject`, `NumberValueObject` with immutability
+- **Entities**: Rich domain entities with identity
+- **Domain Events**: Event-driven architecture support
+- **Repositories**: Read/Write repository pattern interfaces
 
-`npm install @nestjslatam/ddd-lib`
+### 🔍 Advanced Features
 
-### Use library
+- **Automatic State Tracking**: Track entity state (new, modified, deleted)
+- **Validation Framework**: `AbstractRuleValidator` for custom business rules
+- **Business Rules Management**: Broken rules collection and validation orchestration
+- **Property Change Tracking**: Detect and react to property changes
+- **Type Safety**: Full TypeScript support with complete type definitions
 
-This source code include a defaultr sample where we can see in detail how use this library.
+### 🚀 Framework Integration
+
+- **NestJS Native**: Built specifically for NestJS framework
+- **TypeScript First**: Leverages TypeScript's type system
+- **Node.js Compatible**: Works seamlessly with Node.js ecosystem
+- **Modular Architecture**: Import only what you need
+
+## 📦 Installation
+
+```bash
+npm install @nestjslatam/ddd-lib
+```
+
+### Peer Dependencies
+
+```bash
+npm install @nestjs/common @nestjs/core rxjs uuid
+```
+
+## 🚀 Quick Start
+
+### 1. Create a Value Object
+
+```typescript
+import { StringValueObject, AbstractRuleValidator } from '@nestjslatam/ddd-lib';
+
+// Custom validator
+class EmailValidator extends AbstractRuleValidator<Email> {
+  constructor(subject: Email) {
+    super(subject);
+  }
+
+  public addRules(): void {
+    const value = this.subject.getValue();
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+    if (!emailRegex.test(value)) {
+      this.addBrokenRule('value', 'Invalid email format');
+    }
+  }
+}
+
+// Value Object
+export class Email extends StringValueObject {
+  private constructor(value: string) {
+    super(value);
+  }
+
+  static create(value: string): Email {
+    const email = new Email(value);
+
+    if (!email.isValid) {
+      const errors = email.brokenRules.getBrokenRules();
+      throw new Error(
+        `Invalid email: ${errors.map((e) => e.message).join(', ')}`,
+      );
+    }
+
+    return email;
+  }
+
+  protected override addValidators(): void {
+    super.addValidators();
+    this.validatorRules.add(new EmailValidator(this));
+  }
+}
+```
+
+### 2. Create an Aggregate Root
+
+```typescript
+import { DddAggregateRoot, IdValueObject } from '@nestjslatam/ddd-lib';
+import { Email } from './value-objects/email';
+
+interface UserProps {
+  email: Email;
+  name: string;
+  isActive: boolean;
+}
+
+export class User extends DddAggregateRoot<UserProps> {
+  private constructor(
+    id: IdValueObject,
+    props: UserProps,
+    createdAt?: Date,
+    updatedAt?: Date,
+  ) {
+    super(id, props, createdAt, updatedAt);
+  }
+
+  static create(email: Email, name: string): User {
+    const id = IdValueObject.create();
+    const user = new User(id, {
+      email,
+      name,
+      isActive: false,
+    });
+
+    user.validate();
+    return user;
+  }
+
+  // Business methods
+  activate(): void {
+    if (this.props.isActive) {
+      throw new Error('User is already active');
+    }
+
+    this.props.isActive = true;
+    this.trackingState.markAsDirty();
+  }
+
+  deactivate(): void {
+    if (!this.props.isActive) {
+      throw new Error('User is already inactive');
+    }
+
+    this.props.isActive = false;
+    this.trackingState.markAsDirty();
+  }
+
+  // Getters
+  get email(): Email {
+    return this.props.email;
+  }
+
+  get name(): string {
+    return this.props.name;
+  }
+
+  get isActive(): boolean {
+    return this.props.isActive;
+  }
+}
+```
+
+### 3. Use in Your Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { User } from './domain/user';
+import { Email } from './domain/value-objects/email';
+
+@Injectable()
+export class UserService {
+  async createUser(emailStr: string, name: string): Promise<User> {
+    const email = Email.create(emailStr);
+    const user = User.create(email, name);
+
+    // Check state
+    console.log(user.trackingState.isNew); // true
+    console.log(user.trackingState.isDirty); // false
+    console.log(user.isValid()); // true
+
+    // Business logic
+    user.activate();
+    console.log(user.trackingState.isDirty); // true
+
+    return user;
+  }
+}
+```
+
+## 📚 Core Concepts
+
+### Aggregate Roots
+
+Aggregate roots are the entry points to your domain model. They enforce consistency boundaries and business rules.
+
+```typescript
+import { DddAggregateRoot } from '@nestjslatam/ddd-lib';
+
+export class Order extends DddAggregateRoot<OrderProps> {
+  // Your domain logic
+}
+```
+
+**Features:**
+
+- ✅ Automatic state tracking (new, dirty, deleted)
+- ✅ Built-in validation orchestration
+- ✅ Domain event support
+- ✅ Broken rules management
+
+### Value Objects
+
+Value objects are immutable and represent domain concepts without identity.
+
+```typescript
+import { StringValueObject, NumberValueObject } from '@nestjslatam/ddd-lib';
+
+export class Money extends NumberValueObject {
+  // Your value object logic
+}
+```
+
+**Built-in Validators:**
+
+- `StringNotNullOrEmptyValidator` - Ensures string is not null or empty
+- `NumberNotNullValidator` - Ensures number is not null
+- `NumberPositiveValidator` - Ensures number is positive
+
+### Custom Validators
+
+Create business rule validators by extending `AbstractRuleValidator`.
+
+```typescript
+import { AbstractRuleValidator } from '@nestjslatam/ddd-lib';
+
+export class PriceRangeValidator extends AbstractRuleValidator<Price> {
+  public addRules(): void {
+    const value = this.subject.getValue();
+
+    if (value < 0) {
+      this.addBrokenRule('value', 'Price cannot be negative');
+    }
+
+    if (value > 999999.99) {
+      this.addBrokenRule('value', 'Price exceeds maximum');
+    }
+  }
+}
+```
+
+### State Tracking
+
+Every aggregate automatically tracks its state:
+
+```typescript
+const product = Product.create(name, price);
+
+product.trackingState.isNew; // true
+product.trackingState.isDirty; // false
+product.trackingState.isDeleted; // false
+
+product.changePrice(newPrice);
+product.trackingState.isDirty; // true
+
+product.trackingState.markAsDeleted();
+product.trackingState.isDeleted; // true
+```
+
+## 🏗️ Architecture Example
+
+```
+src/
+├── domain/
+│   ├── aggregates/
+│   │   └── product.ts          # Extends DddAggregateRoot
+│   ├── value-objects/
+│   │   ├── price.ts            # Extends NumberValueObject
+│   │   └── product-name.ts     # Extends StringValueObject
+│   └── validators/
+│       └── price-range.validator.ts  # Extends AbstractRuleValidator
+├── application/
+│   ├── commands/
+│   └── queries/
+└── infrastructure/
+    └── repositories/
+```
+
+## 🔄 Version 2.0.0 Changes
+
+### What's New
+
+**NPM Package Distribution**
+
+- Library is now published as a standalone NPM package
+- No need for monorepo or path mappings
+- Standard Node.js module resolution
+
+**Eliminated Circular Dependencies**
+
+- Refactored internal imports to eliminate circular references
+- Direct imports from specific modules
+- Reliable runtime behavior
+
+**Pre-compiled Distribution**
+
+- Published as compiled JavaScript with TypeScript declarations
+- Faster application startup
+- Better tree-shaking support
+
+**Improved Type Definitions**
+
+- Complete `.d.ts` files for all exports
+- Better IDE support and autocomplete
+- Source maps for debugging
+
+### Breaking Changes from 1.x.x
+
+1. **Installation Method**
+
+   ```bash
+   # Before (1.x.x) - Local library
+   # Used path mappings in tsconfig.json
+
+   # After (2.0.0) - NPM package
+   npm install @nestjslatam/ddd-lib
+   ```
+
+2. **Import Paths**
+
+   ```typescript
+   // Before (1.x.x)
+   import { DddAggregateRoot } from '@nestjslatam/ddd-lib/aggregate-root';
+
+   // After (2.0.0)
+   import { DddAggregateRoot } from '@nestjslatam/ddd-lib';
+   ```
+
+3. **No Path Mappings Required**
+   ```json
+   // tsconfig.json - NO LONGER NEEDED
+   {
+     "paths": {
+       "@nestjslatam/ddd-lib": ["libs/ddd/src"]
+     }
+   }
+   ```
+
+## 📖 API Reference
+
+### Exported Classes
+
+**Base Classes:**
+
+- `DddAggregateRoot<T>` - Base class for aggregate roots
+- `StringValueObject` - Base class for string value objects
+- `NumberValueObject` - Base class for number value objects
+- `IdValueObject` - UUID-based identity value object
+
+**Validators:**
+
+- `AbstractRuleValidator<T>` - Base class for custom validators
+- `StringNotNullOrEmptyValidator` - Built-in string validator
+- `NumberNotNullValidator` - Built-in number validator
+- `NumberPositiveValidator` - Built-in positive number validator
+
+**Managers:**
+
+- `BrokenRulesManager` - Manages validation errors
+- `ValidatorRuleManager` - Manages validator rules
+- `TrackingStateManager` - Manages entity state
+
+**Interfaces:**
+
+- `IDomainReadRepository<T>` - Read repository interface
+- `IDomainWriteRepository<T>` - Write repository interface
+
+## 🤝 Contributing
+
+We welcome contributions! This is an open-source project maintained by the NestJS LATAM community.
+
+## 📄 License
+
+This library is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- [NPM Package](https://www.npmjs.com/package/@nestjslatam/ddd-lib)
+- [GitHub Repository](https://github.com/nestjslatam/ddd)
+- [Sample Application](https://github.com/nestjslatam/ddd/tree/main/src)
+- [NestJS LATAM](http://nestjslatam.org/)
+
+## 👥 Author
+
+**Alberto Arroyo Raygada**
+
+- Email: beyondnet.peru@gmail.com
+- Website: [http://nestjslatam.org/](http://nestjslatam.org/)
+
+## 🙏 Acknowledgments
+
+This library is inspired by Domain-Driven Design principles and built specifically for the NestJS ecosystem. Special thanks to the NestJS and DDD communities for their invaluable insights and contributions.

package/{dist/aggregate-root.d.ts → aggregate-root.d.ts}

@@ -1,6 +1,7 @@
 import { AggregateRoot } from '@nestjs/cqrs';
 import { BrokenRulesManager } from './broken-rules.manager';
-import { AbstractRuleValidator, TrackingProps } from './core';
+import { AbstractRuleValidator } from './core/validator-rules';
+import { TrackingProps } from './core/tracking-state';
 import { TrackingStateManager } from './tracking-state-manager';
 import { ValidatorRuleManager } from './validator-rule.manager';
 import { IdValueObject } from './valueobjects';

package/{dist/broken-rules.manager.d.ts → broken-rules.manager.d.ts}

@@ -1,4 +1,4 @@
-import { BrokenRule } from './core';
+import { BrokenRule } from './core/business-rules';
 export interface IBrokenRulesManager {
     getBrokenRules(): ReadonlyArray<BrokenRule>;
 }

package/package.json

@@ -1,52 +1,41 @@
-{
-  "name": "@nestjslatam/ddd-lib",
-  "version": "1.0.56",
-  "description": "A simple Domain-Driven Library for NESTJS",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "private": false,
-  "scripts": {
-    "build": "tsc -p tsconfig.lib.json",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "nestjs",
-    "nestjslatam",
-    "ddd",
-    "domain-driven-design",
-    "aggregate",
-    "value-object",
-    "entity"
-  ],
-  "author": {
-    "name": "Alberto Arroyo Raygada",
-    "email": "beyondnet.peru@gmail.com",
-    "url": "http://nestjslatam.org/"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nestjslatam/ddd"
-  },
-  "files": [
-    "**/*.js",
-    "**/*.d.ts",
-    "!**/*.spec.js",
-    "!**/*.spec.d.ts"
-  ],
-  "dependencies": {
-    "@nestjs/common": "^10.0.0 || ^11.0.0",
-    "@nestjs/core": "^10.0.0 || ^11.0.0",
-    "@nestjslatam/ddd-lib": "^1.0.52",
-    "rxjs": "^7.8.2",
-    "uuid": "^11.1.0"
-  },
-  "peerDependencies": {
-    "@nestjs/common": "^10.0.0 || ^11.0.0",
-    "@nestjs/core": "^10.0.0 || ^11.0.0"
-  },
-  "devDependencies": {
-    "@nestjs/cli": "^11.0.6",
-    "@nestjs/config": "^4.0.2"
-  }
-}
+{
+  "name": "@nestjslatam/ddd-lib",
+  "version": "2.0.0",
+  "description": "A comprehensive Domain-Driven Design library for NestJS - Build scalable, maintainable enterprise applications",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "private": false,
+  "keywords": [
+    "nestjs",
+    "nestjslatam",
+    "ddd",
+    "domain-driven-design",
+    "aggregate",
+    "value-object",
+    "entity"
+  ],
+  "author": {
+    "name": "Alberto Arroyo Raygada",
+    "email": "beyondnet.peru@gmail.com",
+    "url": "http://nestjslatam.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nestjslatam/ddd"
+  },
+  "files": [
+    "**/*.js",
+    "**/*.d.ts",
+    "!**/*.spec.js",
+    "!**/*.spec.d.ts"
+  ],
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0"
+  },
+  "dependencies": {
+    "rxjs": "^7.8.2",
+    "uuid": "^11.1.0"
+  }
+}

package/{dist/tracking-state-manager.d.ts → tracking-state-manager.d.ts}

@@ -1,4 +1,4 @@
-import { IChangeDetector, IProps, ITrackingProps, ITrackingStateManager, ITrackingStateTransitions } from './core';
+import { IChangeDetector, IProps, ITrackingProps, ITrackingStateManager, ITrackingStateTransitions } from './core/tracking-state';
 export declare class TrackingStateManager implements ITrackingStateManager, ITrackingStateTransitions {
     private _isNew;
     private _isDirty;

package/{dist/tracking-state-manager.js → tracking-state-manager.js}

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TrackingStateManager = void 0;
-const core_1 = require("./core");
+const impl_1 = require("./core/tracking-state/impl");
 class TrackingStateManager {
     get isNew() {
         return this._isNew;
@@ -20,7 +20,7 @@ class TrackingStateManager {
         this._isDirty = false;
         this._isSelfDeleted = false;
         this._isDeleted = false;
-        this.changeDetector = changeDetector || new core_1.NestedPropertyChangeDetector();
+        this.changeDetector = changeDetector || new impl_1.NestedPropertyChangeDetector();
         this.markAsClean();
     }
     get trackingProps() {
@@ -36,16 +36,16 @@ class TrackingStateManager {
         return this;
     }
     markAsDirty() {
-        core_1.TrackingStateTransition.toDirty(this);
+        impl_1.TrackingStateTransition.toDirty(this);
     }
     markAsNew() {
-        core_1.TrackingStateTransition.toNew(this);
+        impl_1.TrackingStateTransition.toNew(this);
     }
     markAsSelfDeleted() {
-        core_1.TrackingStateTransition.toSelfDeleted(this);
+        impl_1.TrackingStateTransition.toSelfDeleted(this);
     }
     markAsDeleted() {
-        core_1.TrackingStateTransition.toDeleted(this);
+        impl_1.TrackingStateTransition.toDeleted(this);
     }
     markAsClean() {
         this._isDirty = false;

package/{dist/validator-rule.manager.d.ts → validator-rule.manager.d.ts}

@@ -1,4 +1,5 @@
-import { BrokenRule, ClassType, IRuleValidator } from './core';
+import { BrokenRule } from './core/business-rules';
+import { ClassType, IRuleValidator } from './core/validator-rules';
 export declare class ValidatorRuleManager<TValidator extends IRuleValidator> {
     private readonly _validators;
     add(rule: TValidator): void;

package/{dist/valueobjects → valueobjects}/number-notnull.validator.d.ts

@@ -1,4 +1,4 @@
-import { AbstractRuleValidator } from '../core';
+import { AbstractRuleValidator } from '../core/validator-rules/impl/abstract-rule-validator';
 import { DddValueObject } from '../valueobject';
 export declare class NumberNotNullValidator extends AbstractRuleValidator<DddValueObject<number>> {
     private readonly options;

package/{dist/valueobjects → valueobjects}/number-notnull.validator.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NumberNotNullValidator = void 0;
-const core_1 = require("../core");
-class NumberNotNullValidator extends core_1.AbstractRuleValidator {
+const abstract_rule_validator_1 = require("../core/validator-rules/impl/abstract-rule-validator");
+class NumberNotNullValidator extends abstract_rule_validator_1.AbstractRuleValidator {
     constructor(subject, options) {
         super(subject);
         this.options = {

package/{dist/valueobjects → valueobjects}/number-positive.validator.d.ts

@@ -1,4 +1,4 @@
-import { AbstractRuleValidator } from '../core';
+import { AbstractRuleValidator } from '../core/validator-rules/impl/abstract-rule-validator';
 import { DddValueObject } from '../valueobject';
 export declare class NumberPositiveValidator extends AbstractRuleValidator<DddValueObject<number>> {
     private readonly options;

package/{dist/valueobjects → valueobjects}/number-positive.validator.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NumberPositiveValidator = void 0;
-const core_1 = require("../core");
-class NumberPositiveValidator extends core_1.AbstractRuleValidator {
+const abstract_rule_validator_1 = require("../core/validator-rules/impl/abstract-rule-validator");
+class NumberPositiveValidator extends abstract_rule_validator_1.AbstractRuleValidator {
     constructor(subject, options) {
         super(subject);
         this.options = {

package/{dist/valueobjects → valueobjects}/string-notnullorempty.validator.d.ts

@@ -1,4 +1,4 @@
-import { AbstractRuleValidator } from '../core';
+import { AbstractRuleValidator } from '../core/validator-rules/impl/abstract-rule-validator';
 import { DddValueObject } from '../valueobject';
 export declare class StringNotNullOrEmptyValidator extends AbstractRuleValidator<DddValueObject<string>> {
     private readonly options;

package/{dist/valueobjects → valueobjects}/string-notnullorempty.validator.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StringNotNullOrEmptyValidator = void 0;
-const core_1 = require("../core");
-class StringNotNullOrEmptyValidator extends core_1.AbstractRuleValidator {
+const abstract_rule_validator_1 = require("../core/validator-rules/impl/abstract-rule-validator");
+class StringNotNullOrEmptyValidator extends abstract_rule_validator_1.AbstractRuleValidator {
     constructor(subject, options) {
         super(subject);
         this.options = {

package/src/types.d.ts

@@ -1,7 +0,0 @@
-/* eslint-disable @typescript-eslint/ban-types */
-/**
- * Type of a class.
- */
-export interface Type<T = any> extends Function {
-  new (...args: any[]): T;
-}