@shirudo/ddd-kit 0.9.1 → 0.9.3

package/README.md

@@ -62,19 +62,43 @@ Value Objects are immutable objects that are defined by their attributes rather
 
 ### Entities
 
-Entities are objects with unique identity that are defined by their ID rather than their attributes. The optional `Entity<TId>` interface can be used for nested entities within aggregates or entities that are not aggregate roots. Helper functions like `sameEntity()`, `findEntityById()`, and `hasEntityId()` provide utilities for working with entity collections.
+In Domain-Driven Design, there are two types of entities:
+
+1. **Aggregate Root Entity**: The parent Entity of an aggregate.
+   - Has identity (id) and version for optimistic concurrency control
+   - Represents the aggregate externally
+   - Loaded/saved through repositories
+   - Created by extending `AggregateBase` or `AggregateEventSourced`
+   - Implements `AggregateRoot<TId>`
+
+2. **Child Entities**: Entities within an aggregate.
+   - Have identity (id), but no own version
+   - Exist only within the aggregate boundary
+   - Versioned through the Aggregate Root
+   - Cannot be referenced directly from outside the aggregate
+   - Use the `Entity<TId>` interface for type safety
+
+The `Entity<TId>` interface is used for child entities within aggregates. Helper functions like `sameEntity()`, `findEntityById()`, `hasEntityId()`, `updateEntityById()`, and `removeEntityById()` provide utilities for working with child entity collections.
 
 ### Aggregates
 
-Aggregates are clusters of entities and value objects that form a consistency boundary. The library provides:
+Aggregates are clusters of entities and value objects that form a consistency boundary. An aggregate consists of:
+
+- **One Aggregate Root** (Entity with id + version)
+- **Optional child entities** (Entities with id, but no own version)
+- **Optional value objects** (immutable objects)
+
+The Aggregate Root is an Entity (the parent Entity of the aggregate) that represents the aggregate externally. All changes to child entities are versioned through the Aggregate Root. The version applies to the entire aggregate, including all child entities.
 
-- **`AggregateRoot<TId>`** - Marker interface for Aggregate Roots. Aggregate Roots are the entry points for modifying aggregates in DDD. They have identity (id) and version for optimistic concurrency control. All aggregate base classes implement this interface.
+The library provides:
 
-- **`AggregateBase<TState, TId>`** - Base class for aggregates without Event Sourcing. Implements `AggregateRoot<TId>`. Provides ID and version management, state management, and snapshot support. Use this when you don't need Event Sourcing but still want aggregate patterns with optimistic concurrency control.
+- **`AggregateRoot<TId>`** - Marker interface for Aggregate Root Entities. The Aggregate Root is an Entity with identity (id) and version for optimistic concurrency control. It represents the aggregate externally and is the only object that can be loaded/saved through repositories.
 
-- **`AggregateEventSourced<TState, TEvent, TId>`** - Base class for Event-Sourced aggregates. Extends `AggregateBase` (and thus implements `AggregateRoot<TId>`). Adds event tracking, event handlers, event validation, and history replay capabilities. Use this when you want full Event Sourcing with event tracking and replay.
+- **`AggregateBase<TState, TId>`** - Base class for creating Aggregate Root Entities without Event Sourcing. Implements `AggregateRoot<TId>`. The aggregate state (`TState`) contains child entities and value objects. Provides ID and version management, state management, and snapshot support. Use this when you don't need Event Sourcing but still want aggregate patterns with versioning and state management.
 
-Both classes support automatic versioning (configurable), snapshot creation/restoration, and optimistic concurrency control.
+- **`AggregateEventSourced<TState, TEvent, TId>`** - Base class for Event-Sourced Aggregate Root Entities. Extends `AggregateBase` (and thus implements `AggregateRoot<TId>`). Adds event tracking, event handlers, event validation, and history replay capabilities. Use this when you want full Event Sourcing with event tracking and replay.
+
+Both classes support automatic versioning (configurable), snapshot creation/restoration, and optimistic concurrency control. The version applies to the entire aggregate, including all child entities.
 
 ### CQRS (Command Query Responsibility Segregation)
 
@@ -712,169 +736,206 @@ const eventV2 = createDomainEvent(
 );
 ```
 
-### Working with Nested Entities
+### Working with Child Entities
+
+An Aggregate Root Entity can contain multiple child entities. Child entities have identity (id) but no own version - they are versioned through the Aggregate Root.
 
 ```typescript
 import {
   AggregateBase,
-  createDomainEvent,
   Entity,
   findEntityById,
   hasEntityId,
   removeEntityById,
+  updateEntityById,
   sameEntity,
+  type AggregateRoot,
   type Id,
-  type DomainEvent,
 } from "@shirudo/ddd-kit";
 
 type OrderId = Id<"OrderId">;
 type ItemId = Id<"ItemId">;
 
-// Define nested entity
+// Child Entity within the aggregate (has id, but no own version)
 type OrderItem = Entity<ItemId> & {
   productId: string;
   quantity: number;
   price: number;
 };
 
+// Aggregate state contains child entities
 type OrderState = {
   id: OrderId;
   customerId: string;
-  items: OrderItem[];
+  items: OrderItem[]; // Child entities
   total: number;
 };
 
-type ItemAdded = DomainEvent<"ItemAdded", { item: OrderItem }>;
-type ItemRemoved = DomainEvent<"ItemRemoved", { itemId: ItemId }>;
-type OrderEvent = ItemAdded | ItemRemoved;
-
-class Order extends AggregateBase<OrderState, OrderEvent, OrderId> {
+// Order is the Aggregate Root (an Entity with id + version)
+class Order extends AggregateBase<OrderState, OrderId> 
+  implements AggregateRoot<OrderId> {
   static create(id: OrderId, customerId: string): Order {
     const initialState: OrderState = {
       id,
       customerId,
-      items: [],
+      items: [], // Child entities
       total: 0,
     };
-    const order = new Order(id, initialState);
-    const result = order.apply(createDomainEvent("OrderCreated", { customerId }) as any);
-    if (!result.ok) {
-      throw new Error(result.error);
-    }
-    return order;
+    return new Order(id, initialState);
   }
 
-  addItem(item: OrderItem): void {
-    if (hasEntityId(this.state.items, item.id)) {
-      throw new Error("Item already exists");
-    }
-    const result = this.apply(createDomainEvent("ItemAdded", { item }) as ItemAdded);
-    if (!result.ok) {
-      throw new Error(result.error);
+  // Operations on child entities are versioned through the Aggregate Root
+  addItem(productId: string, quantity: number, price: number): ItemId {
+    const itemId = `item-${Date.now()}` as ItemId;
+    const item: OrderItem = {
+      id: itemId,
+      productId,
+      quantity,
+      price,
+    };
+
+    this._state = {
+      ...this._state,
+      items: [...this._state.items, item],
+      total: this._state.total + price * quantity,
+    };
+    this.bumpVersion(); // Versions the entire aggregate (including child entities)
+    return itemId;
+  }
+
+  updateItemQuantity(itemId: ItemId, newQuantity: number): void {
+    const item = findEntityById(this._state.items, itemId);
+    if (!item) {
+      throw new Error("Item not found");
     }
+
+    this._state = {
+      ...this._state,
+      items: updateEntityById(
+        this._state.items,
+        itemId,
+        (i) => ({ ...i, quantity: newQuantity })
+      ),
+      total: this._state.total - item.price * item.quantity + item.price * newQuantity,
+    };
+    this.bumpVersion(); // Versions the entire aggregate
   }
 
   removeItem(itemId: ItemId): void {
-    if (!hasEntityId(this.state.items, itemId)) {
+    const item = findEntityById(this._state.items, itemId);
+    if (!item) {
       throw new Error("Item not found");
     }
-    const result = this.apply(createDomainEvent("ItemRemoved", { itemId }) as ItemRemoved);
-    if (!result.ok) {
-      throw new Error(result.error);
-    }
+
+    this._state = {
+      ...this._state,
+      items: removeEntityById(this._state.items, itemId),
+      total: this._state.total - item.price * item.quantity,
+    };
+    this.bumpVersion(); // Versions the entire aggregate
   }
 
   getItem(itemId: ItemId): OrderItem | undefined {
-    return findEntityById(this.state.items, itemId);
+    return findEntityById(this._state.items, itemId);
   }
-
-  protected readonly handlers = {
-    ItemAdded: (state: OrderState, event: ItemAdded): OrderState => ({
-      ...state,
-      items: [...state.items, event.payload.item],
-      total: state.total + event.payload.item.price * event.payload.item.quantity,
-    }),
-    ItemRemoved: (state: OrderState, event: ItemRemoved): OrderState => {
-      const item = findEntityById(state.items, event.payload.itemId);
-      if (!item) return state;
-      return {
-        ...state,
-        items: removeEntityById(state.items, event.payload.itemId),
-        total: state.total - item.price * item.quantity,
-      };
-    },
-  };
 }
 
 // Usage
-const orderId = "order-123" as OrderId;
-const order = Order.create(orderId, "customer-456");
-
-const item: OrderItem = {
-  id: "item-1" as ItemId,
-  productId: "prod-123",
-  quantity: 2,
-  price: 10.99,
-};
+const order = Order.create("order-123" as OrderId, "customer-456");
+const itemId = order.addItem("product-1", 2, 10.0); // Adds child entity
+order.updateItemQuantity(itemId, 3); // Updates child entity
+order.removeItem(itemId); // Removes child entity
 
-order.addItem(item);
-const foundItem = order.getItem(item.id);
-console.log(sameEntity(item, foundItem!)); // true
+// All changes version the Aggregate Root (order.version increments)
+console.log(order.version); // 3 (one for each operation)
 ```
 
 ### Using Result Type for Error Handling
 
+The `Result<T, E>` type provides composition utilities to avoid repetitive `if (isErr)` checks:
+
 ```typescript
-import { ok, err, isOk, isErr, type Result, guard } from "@shirudo/ddd-kit";
+import { 
+  ok, 
+  err, 
+  isOk, 
+  isErr, 
+  andThen, 
+  map, 
+  mapErr, 
+  unwrapOr, 
+  unwrapOrElse, 
+  match,
+  type Result, 
+  guard 
+} from "@shirudo/ddd-kit";
 
 type UserId = string;
 
 function validateUserId(id: string): Result<UserId, string> {
-  const validation = guard(id.length > 0, "User ID cannot be empty");
-  if (isErr(validation)) {
-    return err(validation.error);
-  }
-  return ok(id as UserId);
+  return id.length > 0 ? ok(id as UserId) : err("User ID cannot be empty");
 }
 
-function createUser(id: string): Result<{ id: UserId; name: string }, string> {
-  const userIdResult = validateUserId(id);
-  if (isErr(userIdResult)) {
-    return err(userIdResult.error);
-  }
-
-  return ok({
-    id: userIdResult.value,
-    name: "John Doe",
-  });
+function validateEmail(email: string): Result<string, string> {
+  return email.includes("@") ? ok(email) : err("Invalid email");
 }
 
-// Usage with type guards (recommended)
-const result = createUser("user-123");
-if (isOk(result)) {
-  console.log("User created:", result.value); // TypeScript knows result is Ok
-} else {
-  console.error("Error:", result.error); // TypeScript knows result is Err
+// Chaining operations with andThen (avoids if-checks)
+function createUser(id: string, email: string): Result<{ id: UserId; email: string }, string> {
+  return andThen(validateUserId(id), (userId) =>
+    map(validateEmail(email), (email) => ({
+      id: userId,
+      email,
+    }))
+  );
 }
 
-// Usage with ok property (also works)
-const result2 = createUser("user-123");
-if (result2.ok) {
+// Using map for transformations
+const result = ok(5);
+const doubled = map(result, x => x * 2); // Ok<10>
+
+// Using mapErr to transform errors
+const errorResult = err("not found");
+const mappedError = mapErr(errorResult, e => `Error: ${e}`); // Err<"Error: not found">
+
+// Using unwrapOr for defaults
+const userId = unwrapOr(validateUserId(""), "default-id");
+
+// Using unwrapOrElse for computed defaults
+const userId2 = unwrapOrElse(validateUserId(""), err => `fallback-${Date.now()}`);
+
+// Using match for pattern matching
+const message = match(createUser("user-123", "test@example.com"),
+  user => `User created: ${user.id}`,
+  error => `Error: ${error}`
+);
+
+// Usage with type guards (still works)
+const result2 = createUser("user-123", "test@example.com");
+if (isOk(result2)) {
   console.log("User created:", result2.value);
 } else {
   console.error("Error:", result2.error);
 }
 ```
 
+**Available Composition Utilities:**
+- `andThen<T, E, U>(result, fn)` - Chains Result operations (flatMap/bind). If Ok, applies function; if Err, returns error unchanged.
+- `map<T, E, U>(result, fn)` - Transforms Ok value. If Err, returns error unchanged.
+- `mapErr<T, E, F>(result, fn)` - Transforms Err value. If Ok, returns value unchanged.
+- `unwrapOr<T, E>(result, defaultValue)` - Returns value if Ok, otherwise returns default.
+- `unwrapOrElse<T, E>(result, fn)` - Returns value if Ok, otherwise computes default from error.
+- `match<T, E, R>(result, onOk, onErr)` - Pattern matching. Applies one function if Ok, another if Err.
+
 ## API Documentation
 
 This package is written in TypeScript and provides full type definitions. All types and functions are exported from the main entry point. You can explore the available APIs through your IDE's autocomplete or by examining the type definitions in `node_modules/@shirudo/ddd-kit/dist/index.d.ts`.
 
 Key exports include:
 - `vo()`, `voEquals()`, `voWithValidation()`, `voWithValidationUnsafe()` - Value Object utilities
-- `AggregateRoot<TId>` - Marker interface for Aggregate Roots
-- `AggregateBase<TState, TId>` - Base class for aggregates without Event Sourcing (implements `AggregateRoot<TId>`)
-- `AggregateEventSourced<TState, TEvent, TId>` - Base class for Event-Sourced aggregates (extends `AggregateBase`, implements `AggregateRoot<TId>`)
+- `AggregateRoot<TId>` - Marker interface for Aggregate Root Entities
+- `AggregateBase<TState, TId>` - Base class for creating Aggregate Root Entities without Event Sourcing (implements `AggregateRoot<TId>`)
+- `AggregateEventSourced<TState, TEvent, TId>` - Base class for Event-Sourced Aggregate Root Entities (extends `AggregateBase`, implements `AggregateRoot<TId>`)
 - `AggregateConfig`, `AggregateEventSourcedConfig` - Configuration interfaces
 - `AggregateSnapshot<TState>` - Snapshot interface for performance optimization
 - `sameAggregate()` - Aggregate equality helper
@@ -892,7 +953,9 @@ Key exports include:
 - `EventHandler<Evt>` - Event handler function type
 - `EventBus.subscribe()` - Subscribe handlers to event types
 - `EventBus.publish()` - Publish events to all subscribers
-- `Result<T, E>`, `ok()`, `err()`, `isOk()`, `isErr()` - Result type and helpers
+- `Result<T, E>`, `ok()`, `err()`, `isOk()`, `isErr()` - Result type and type guards
+- `andThen()`, `map()`, `mapErr()` - Result composition utilities
+- `unwrapOr()`, `unwrapOrElse()`, `match()` - Result unwrapping and pattern matching
 - `Id<Tag>` - Branded ID type
 - `IRepository<TState, TEvent, TAgg, TId>` - Repository interface
 - `ISpecification<T>` - Specification interface