@libs-for-dev/nestjs-ddd-library 1.1.1 → 1.2.0

package/README.md

@@ -10,6 +10,9 @@ A comprehensive library providing Domain-Driven Design (DDD) building blocks for
 - **Value Objects**: Immutable objects that contain attributes but have no conceptual identity with examples:
   - **UUID**: Built-in UUID v7 generation and validation
   - **Email**: Email value object with validation
+  - **Money**: Money value object with amount and currency (ISO 4217) validation
+  - **PhoneNumber**: Phone number value object with mobile phone validation
+  - **Url**: URL value object with protocol validation
 
 ## Installation
 
@@ -74,8 +77,65 @@ if (emailResult.isOk()) {
 }
 ```
 
+#### Money
+
+```typescript
+import { Money } from '@libs-for-dev/nestjs-ddd-library';
+
+// Create a Money value object
+const moneyResult = Money.create(100.50, 'USD');
+
+if (moneyResult.isOk()) {
+  const money = moneyResult.unwrap();
+  console.log(money.amount); // 100.50
+  console.log(money.currency); // USD
+  console.log(money.value); // { amount: 100.50, currency: 'USD' }
+} else {
+  // Handle error
+  console.error(moneyResult.unwrapErr());
+}
+```
+
+#### PhoneNumber
+
+```typescript
+import { PhoneNumber } from '@libs-for-dev/nestjs-ddd-library';
+
+// Create a PhoneNumber value object
+const phoneResult = PhoneNumber.create('+1234567890');
+
+if (phoneResult.isOk()) {
+  const phone = phoneResult.unwrap();
+  console.log(phone.value); // +1234567890
+} else {
+  // Handle error
+  console.error(phoneResult.unwrapErr());
+}
+```
+
+#### Url
+
+```typescript
+import { Url } from '@libs-for-dev/nestjs-ddd-library';
+
+// Create a Url value object
+const urlResult = Url.create('https://example.com');
+
+if (urlResult.isOk()) {
+  const url = urlResult.unwrap();
+  console.log(url.value); // https://example.com
+} else {
+  // Handle error
+  console.error(urlResult.unwrapErr());
+}
+```
+
 ### Entities
 
+`AbstractEntity` provides immutable properties through `DeepReadonly`. All properties, including nested objects, are readonly and cannot be modified directly. Changes must be made through entity domain methods.
+
+#### Basic Usage
+
 ```typescript
 import { AbstractEntity, Uuid } from '@libs-for-dev/nestjs-ddd-library';
 
@@ -118,6 +178,70 @@ user.updateName('Jane Doe');
 console.log(user.props.name); // Jane Doe
 ```
 
+#### Readonly Properties with Nested Objects
+
+Properties returned by `props` getter are deeply readonly, including nested objects. This ensures immutability and prevents accidental modifications:
+
+```typescript
+import { AbstractEntity, Uuid } from '@libs-for-dev/nestjs-ddd-library';
+
+interface UserProfileProps {
+  personal: {
+    firstName: string;
+    lastName: string;
+  };
+  settings: {
+    theme: string;
+  };
+}
+
+class UserProfile extends AbstractEntity<Uuid, UserProfileProps> {
+  public static create(id: Uuid, props: UserProfileProps): UserProfile {
+    return new UserProfile(id, props);
+  }
+
+  public updateFirstName(firstName: string): void {
+    this.propsData = {
+      props: {
+        ...this.props,
+        personal: {
+          ...this.props.personal,
+          firstName
+        }
+      }
+    };
+  }
+}
+
+// Usage
+const profile = UserProfile.create(Uuid.generate(), {
+  personal: {
+    firstName: 'John',
+    lastName: 'Doe'
+  },
+  settings: {
+    theme: 'dark'
+  }
+});
+
+// All properties are readonly, including nested objects
+// This will throw an error at runtime:
+// profile.props.personal.firstName = 'Jane'; // ❌ Error: Cannot assign to read-only property
+
+// This will also throw an error:
+// profile.props.settings.theme = 'light'; // ❌ Error: Cannot assign to read-only property
+
+// Changes must be made through domain methods
+profile.updateFirstName('Jane');
+console.log(profile.props.personal.firstName); // Jane
+
+// Previous references remain unchanged (immutability)
+const oldProps = profile.props;
+profile.updateFirstName('Bob');
+console.log(oldProps.personal.firstName); // Jane (unchanged)
+console.log(profile.props.personal.firstName); // Bob (updated)
+```
+
 ## Domain Events
 
 The library integrates with NestJS CQRS to support domain events:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libs-for-dev/nestjs-ddd-library",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "NestJS DDD library",
   "keywords": [
     "ddd-library",