@shirudo/ddd-kit 0.16.0 → 1.0.0-rc.2

package/README.md

@@ -2,9 +2,11 @@
 
 Composable TypeScript toolkit for tactical Domain-Driven Design.
 
-> **⚠️ BETA WARNING**
+📚 **[Full documentation site](https://shi-rudo.github.io/ddd-kit-ts/)** — guides, API reference, design decisions.
+
+> **Release Candidate**
 >
-> This library is currently in beta. The API is subject to change until a stable 1.0.0 release. Breaking changes may occur in minor versions during the beta phase. Please pin your dependencies to specific versions.
+> This library is in Release Candidate phase. The API is considered stable and ready for production evaluation. Please report any issues before the final 1.0.0 release.
 
 ## Badges
 
@@ -20,7 +22,7 @@ Composable TypeScript toolkit for tactical Domain-Driven Design.
 - **Repositories** - Persistence abstraction layer for aggregates with specification pattern support
 - **Specifications** - Reusable query specifications for complex domain queries
 - **Unit of Work** - Transaction management for maintaining consistency across operations
-- **Result Type** - Functional error handling with `Result<T, E>` type for explicit success/failure states
+- **Result Type** - Functional error handling with `Result<T, E>` type for explicit success/failure states. For advanced error handling with typed error hierarchies, see [`@shirudo/base-error`](https://www.npmjs.com/package/@shirudo/base-error)
 
 ## Installation
 
@@ -62,7 +64,7 @@ const email = createEmail("user@example.com");
 
 ### Value Objects
 
-Value Objects are immutable objects that are defined by their attributes rather than identity. They ensure data integrity by preventing modification after creation. Use the `vo()` helper function to create deeply frozen value objects that cannot be mutated, even nested objects and arrays. The library provides `voEquals()` for value-based equality comparison, `voEqualsExcept()` for comparing while ignoring specified keys (useful for metadata), `voWithValidation()` for creating validated value objects (returns Result), and `voWithValidationUnsafe()` for the exception-throwing variant.
+Value Objects are immutable objects that are defined by their attributes rather than identity. They ensure data integrity by preventing modification after creation. Use the `vo()` helper function to create deeply frozen value objects that cannot be mutated, even nested objects and arrays. The library provides `voEquals()` for value-based equality comparison, `voEqualsExcept()` for comparing while ignoring specified keys (useful for metadata), and `voWithValidation()` for creating validated value objects at the App-Service boundary (returns Result). For Domain construction, prefer the `ValueObject` base class — its constructor throws on invariant violation via the `validate()` hook.
 
 ### Entities
 
@@ -72,7 +74,7 @@ In Domain-Driven Design, Entities are objects with identity and state. Unlike Va
    - Has identity (id), state, and version for optimistic concurrency control
    - Represents the aggregate externally
    - Loaded/saved through repositories
-   - Created by extending `AggregateRoot` or `AggregateEventSourced`
+   - Created by extending `AggregateRoot` (state-based) or `EventSourcedAggregate` (event-sourced)
    - Implements `IAggregateRoot<TId>`
 
 2. **Child Entities**: Entities within an aggregate.
@@ -107,7 +109,7 @@ The library provides:
 
 - **`AggregateRoot<TState, TId, TEvent?>`** - Base class for creating Aggregate Root Entities without Event Sourcing. Implements `IAggregateRoot<TId>`. The optional `TEvent` parameter (defaults to `unknown`) enables type-safe domain events — only aggregates that specify it get compile-time event validation. Provides ID and version management, state management, domain event tracking, and snapshot support. Use this when you don't need Event Sourcing but still want aggregate patterns with versioning and state management.
 
-- **`AggregateEventSourced<TState, TEvent, TId>`** - Base class for Event-Sourced Aggregate Root Entities. Extends `AggregateRoot` (and thus implements `IAggregateRoot<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.
+- **`EventSourcedAggregate<TState, TEvent, TId>`** - Base class for Event-Sourced Aggregate Roots. Extends `Entity` directly (not `AggregateRoot`) so that state changes can only happen through event handlers via `apply()`. Provides event tracking, event validation, history replay, and snapshot support.
 
 Both classes support automatic versioning (configurable), snapshot creation/restoration, and optimistic concurrency control. The version applies to the entire aggregate, including all child entities.
 
@@ -117,7 +119,7 @@ CQRS separates read operations (Queries) from write operations (Commands), provi
 
 ### Domain Events
 
-Domain Events represent something meaningful that happened in your domain. They are immutable records with a type, payload, timestamp, optional version for schema evolution, and metadata for traceability. Events support versioning for handling schema changes over time and include metadata fields like `correlationId`, `causationId`, `userId`, and `source` for tracking event flow in distributed systems. Events are automatically tracked by aggregates and can be published to event buses or stored in outboxes for eventual consistency.
+Domain Events represent something meaningful that happened in your domain. They are immutable records with a type, payload, timestamp, version for schema evolution, and optional metadata for traceability. Events support versioning for handling schema changes over time and include metadata fields like `correlationId`, `causationId`, `userId`, and `source` for tracking event flow in distributed systems. Events are automatically tracked by aggregates and can be published to event buses or stored in outboxes for eventual consistency.
 
 ### Repositories
 
@@ -170,19 +172,16 @@ const result = voWithValidation(
   "Amount must be non-negative and currency must be 3 characters"
 );
 
-if (result.ok) {
+if (result.isOk()) {
   const validMoney = result.value;
   // Use validMoney...
 } else {
   console.error(result.error);
 }
 
-// Or use unsafe variant (throws exception)
-const validMoneyUnsafe = voWithValidationUnsafe(
-  { amount: 100, currency: "USD" },
-  (m) => m.amount >= 0 && m.currency.length === 3,
-  "Amount must be non-negative and currency must be 3 characters"
-);
+// For Domain construction, use the `ValueObject` base class — its constructor
+// throws via the `validate()` hook, so Domain code keeps a throw-based contract.
+// Reserve `voWithValidation` for parsing untrusted input at the App boundary.
 
 // Value object with nested structures (deep freeze)
 const address = vo({
@@ -247,32 +246,29 @@ class Order extends AggregateRoot<OrderState, OrderId> {
   }
 
   addItem(productId: string, quantity: number, price: number): void {
-    if (this._state.status !== "pending") {
+    if (this.state.status !== "pending") {
       throw new Error("Cannot add items to a non-pending order");
     }
 
-    this._state = {
-      ...this._state,
-      items: [...this._state.items, { productId, quantity, price }],
-      total: this._state.total + quantity * price,
-    };
-    this.bumpVersion(); // Manual version bump for optimistic concurrency control
+    this.setState({
+      ...this.state,
+      items: [...this.state.items, { productId, quantity, price }],
+      total: this.state.total + quantity * price,
+    }, true); // true = bump version for optimistic concurrency control
   }
 
   confirm(): void {
-    if (this._state.status !== "pending") {
+    if (this.state.status !== "pending") {
       throw new Error("Only pending orders can be confirmed");
     }
-    this._state = { ...this._state, status: "confirmed" };
-    this.bumpVersion();
+    this.setState({ ...this.state, status: "confirmed" }, true);
   }
 
   ship(): void {
-    if (this._state.status !== "confirmed") {
+    if (this.state.status !== "confirmed") {
       throw new Error("Only confirmed orders can be shipped");
     }
-    this._state = { ...this._state, status: "shipped" };
-    this.bumpVersion();
+    this.setState({ ...this.state, status: "shipped" }, true);
   }
 }
 
@@ -297,15 +293,13 @@ type OrderDomainEvent =
 
 class Order extends AggregateRoot<OrderState, OrderId, OrderDomainEvent> {
   confirm(): void {
-    this._state = { ...this._state, status: "confirmed" };
+    this.setState({ ...this.state, status: "confirmed" }, true);
     this.addDomainEvent({ type: "OrderConfirmed" }); // type-safe
-    this.bumpVersion();
   }
 
   ship(trackingNumber: string): void {
-    this._state = { ...this._state, status: "shipped" };
+    this.setState({ ...this.state, status: "shipped" }, true);
     this.addDomainEvent({ type: "OrderShipped", trackingNumber }); // type-safe
-    this.bumpVersion();
   }
 }
 
@@ -313,11 +307,53 @@ class Order extends AggregateRoot<OrderState, OrderId, OrderDomainEvent> {
 // order.addDomainEvent({ type: "WrongEvent" }) → compile error
 ```
 
+> **Domain-event ordering: record AFTER mutation.** A domain event represents something that has *just happened* to the aggregate. Always mutate state first (`setState`, invariant checks), then `addDomainEvent`. Recording before mutation is a footgun: if a subsequent invariant throws, the event has been queued for a fact that never actually happened.
+>
+> Two paths give you that ordering for free, so you don't have to remember the rule:
+>
+> - **`EventSourcedAggregate.apply(event)`** — `validateEvent` runs, then the handler computes the next state, then state + event + version commit atomically. State is never mutated without the event, and the event is never recorded without the state.
+> - **`AggregateRoot.commit(newState, event)`** — opt-in helper that runs `setState(newState)` first (which throws on `validateState` failure) and only then appends the event(s). Use this instead of calling `setState` + `addDomainEvent` separately:
+>
+>   ```ts
+>   confirm(): void {
+>     if (this.state.status === "confirmed") throw new OrderAlreadyConfirmedError(this.id);
+>     this.commit(
+>       { ...this.state, status: "confirmed" },
+>       { type: "OrderConfirmed", orderId: this.id },
+>     );
+>   }
+>   ```
+>
+> `commit()` accepts a single event, an array of events, or none. Direct `setState`/`addDomainEvent` calls remain available for cases that don't fit the helper (state-only mutations, audit-only events, multi-step transactions).
+
+> **Aggregate methods own the behaviour, not the consumer.** Subclasses of `AggregateRoot` and `EventSourcedAggregate` expose state via the `state` getter (DDD requires invariant checks to read it), but the canonical Pattern is *Tell, Don't Ask*: write business methods on the aggregate that mutate via `commit()` / `setState()` / `apply()` and emit events; do not write `if (order.state.status === "draft") order.state.status = "confirmed"` from outside the aggregate. The state getter is for the aggregate's own methods and for read-only projections — not as a public mutation handle.
+
+### Event-Sourcing Schema Evolution (Upcasting)
+
+`DomainEvent.version` is intentionally a plain integer rather than a library-managed migration chain. Schema evolution is **the consumer's responsibility** — every event store handles it differently (sync upcasters in the load path, async upcasters in a projection rebuild, schema-registry coupling, etc.). The recommended pattern is to wrap your event-store read path:
+
+```ts
+// At the infrastructure boundary, before passing events to loadFromHistory:
+function upcast(event: PersistedEvent): DomainEvent {
+  if (event.type === "OrderCreated" && event.version === 1) {
+    // v1 → v2 migration; produce a new DomainEvent
+    return { ...event, version: 2, payload: { ...event.payload, currency: "EUR" } };
+  }
+  return event;
+}
+
+const history = await eventStore.read(aggregateId);
+const upcasted = history.map(upcast);
+aggregate.loadFromHistory(upcasted);
+```
+
+The library deliberately ships no `EventUpcaster` port. Real upcasting strategies vary too much (chained vs schema-registry vs lazy) to commit to one shape pre-1.0 without concrete usage data.
+
 ### Creating an Aggregate WITH Event Sourcing
 
 ```typescript
 import {
-  AggregateEventSourced,
+  EventSourcedAggregate,
   createDomainEvent,
   type AggregateRoot,
   type Id,
@@ -339,7 +375,7 @@ type OrderShipped = DomainEvent<"OrderShipped", { trackingNumber: string }>;
 
 type OrderEvent = OrderCreated | OrderConfirmed | OrderShipped;
 
-class Order extends AggregateEventSourced<OrderState, OrderEvent, OrderId> implements AggregateRoot<OrderId> {
+class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
   static create(id: OrderId, customerId: string): Order {
     const initialState: OrderState = {
       id,
@@ -355,28 +391,22 @@ class Order extends AggregateEventSourced<OrderState, OrderEvent, OrderId> imple
   }
 
   confirm(): void {
-    const result = this.apply(
-      createDomainEvent("OrderConfirmed") as OrderConfirmed
-    );
-    if (!result.ok) {
-      throw new Error(result.error);
-    }
+    this.apply(createDomainEvent("OrderConfirmed") as OrderConfirmed);
   }
 
   ship(trackingNumber: string): void {
-    const result = this.apply(
+    this.apply(
       createDomainEvent("OrderShipped", { trackingNumber }) as OrderShipped
     );
-    if (!result.ok) {
-      throw new Error(result.error);
-    }
   }
 
-  // Or use unsafe variant (throws exception directly)
-  confirmUnsafe(): void {
-    this.applyUnsafe(
-      createDomainEvent("OrderConfirmed") as OrderConfirmed
-    );
+  // Override `validateEvent` to throw a DomainError subclass when an invariant
+  // is violated (e.g. confirming an already-confirmed order). `apply()` itself
+  // throws `MissingHandlerError` when no handler is registered for the event.
+  protected validateEvent(event: OrderEvent): void {
+    if (event.type === "OrderConfirmed" && this.state.status === "confirmed") {
+      throw new OrderAlreadyConfirmedError(this.id);
+    }
   }
 
   protected readonly handlers = {
@@ -417,8 +447,8 @@ console.log(order.version); // 3 (automatically bumped)
 ```typescript
 import {
   AggregateRoot,
-  AggregateEventSourced,
-  sameAggregate,
+  EventSourcedAggregate,
+  sameVersion,
   type Id,
 } from "@shirudo/ddd-kit";
 
@@ -441,11 +471,11 @@ const eventSourcedOrder = EventSourcedOrder.create("order-123" as OrderId, "cust
 const eventsAfterSnapshot = [/* events that occurred after snapshot */];
 eventSourcedOrder.restoreFromSnapshotWithEvents(snapshot, eventsAfterSnapshot);
 
-// Aggregate equality check
+// Optimistic concurrency check
 const order1 = await repository.getById(id);
 // ... some operations ...
 const order2 = await repository.getById(id);
-if (!sameAggregate(order1, order2)) {
+if (!sameVersion(order1, order2)) {
   throw new Error("Aggregate was modified by another process");
 }
 ```
@@ -454,7 +484,7 @@ if (!sameAggregate(order1, order2)) {
 
 ```typescript
 import {
-  AggregateEventSourced,
+  EventSourcedAggregate,
   createDomainEvent,
   err,
   ok,
@@ -469,7 +499,7 @@ type OrderState = { id: OrderId; status: "pending" | "confirmed" | "shipped" };
 type OrderShipped = DomainEvent<"OrderShipped", { trackingNumber: string }>;
 type OrderEvent = OrderShipped;
 
-class Order extends AggregateEventSourced<OrderState, OrderEvent, OrderId> implements AggregateRoot<OrderId> {
+class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
   // Event validation
   protected validateEvent(event: OrderEvent): Result<true, string> {
     if (event.type === "OrderShipped" && this.state.status !== "confirmed") {
@@ -495,19 +525,24 @@ class Order extends AggregateEventSourced<OrderState, OrderEvent, OrderId> imple
 
 ### Using CQRS: Commands and Queries
 
+The library ships an in-memory `CommandBus` and `QueryBus`. These are zero-config in-process dispatchers — they fit:
+
+- **Edge runtimes** (Cloudflare Workers, Vercel Edge, Deno Deploy, Bun): each worker invocation handles one command in-process; external brokers would defeat edge latency.
+- **Modular monoliths**: a single Node process with several bounded contexts; the bus routes commands between modules. Domain events still leave the process via outbox/external bus when other services need them.
+- **Tests and local development**: stand-in for production buses without infrastructure.
+- **Small CLIs and scripts**: CQRS structure without infrastructure.
+
+For **cross-process messaging** (RabbitMQ, NATS, Kafka, AWS SQS, etc.), don't use the in-memory bus — keep the `CommandHandler<C, R>` / `QueryHandler<Q, R>` types as the contract and wire them to your transport of choice. The handlers stay portable; only the dispatcher changes.
+
+The included buses intentionally have no middleware/pipeline machinery — wrap handlers with decorator functions when you need logging, auth, metrics. Anything more elaborate is "in-house framework" territory and lives outside the kit.
+
 #### Commands (Write Operations)
 
 Commands represent write operations that change system state. They return `Result` for explicit error handling.
 
 ```typescript
-import {
-  Command,
-  CommandHandler,
-  CommandBus,
-  ok,
-  err,
-  type Result,
-} from "@shirudo/ddd-kit";
+import { Command, CommandHandler, CommandBus } from "@shirudo/ddd-kit";
+import { ok, err, type Result } from "@shirudo/result";
 
 // Define a command
 type CreateOrderCommand = Command & {
@@ -546,7 +581,7 @@ const result = await createOrderHandler({
   items: [{ productId: "product-1", quantity: 2, price: 10.0 }],
 });
 
-if (result.ok) {
+if (result.isOk()) {
   console.log("Order created:", result.value);
 } else {
   console.error("Error:", result.error);
@@ -605,7 +640,7 @@ const result = await queryBus.execute({
   orderId: "order-123",
 });
 
-if (result.ok) {
+if (result.isOk()) {
   const orderFromBus = result.value;
   // Use orderFromBus...
 } else {
@@ -719,7 +754,7 @@ channel.consume("order.commands", async (message) => {
   const command = JSON.parse(message.content.toString()) as CreateOrderCommand;
   const result = await createOrderHandler(command);
 
-  if (result.ok) {
+  if (result.isOk()) {
     channel.ack(message);
   } else {
     channel.nack(message, false, true); // Requeue on error
@@ -892,49 +927,42 @@ class Order extends AggregateRoot<OrderState, OrderId>
       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)
+    this.setState({
+      ...this.state,
+      items: [...this.state.items, item],
+      total: this.state.total + price * quantity,
+    }, true); // true = bump version (versions the entire aggregate including child entities)
     return itemId;
   }
 
   updateItemQuantity(itemId: ItemId, newQuantity: number): void {
-    const item = findEntityById(this._state.items, itemId);
+    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
+    this.setState({
+      ...this.state,
+      items: updateEntityById(this.state.items, itemId, (i) => ({ ...i, quantity: newQuantity })),
+      total: this.state.total - item.price * item.quantity + item.price * newQuantity,
+    }, true);
   }
 
   removeItem(itemId: ItemId): void {
-    const item = findEntityById(this._state.items, itemId);
+    const item = findEntityById(this.state.items, itemId);
     if (!item) {
       throw new Error("Item not found");
     }
 
-    this._state = {
-      ...this._state,
-      items: removeEntityById(this._state.items, itemId),
-      total: this._state.total - item.price * item.quantity,
-    };
-    this.bumpVersion(); // Versions the entire aggregate
+    this.setState({
+      ...this.state,
+      items: removeEntityById(this.state.items, itemId),
+      total: this.state.total - item.price * item.quantity,
+    }, true);
   }
 
   getItem(itemId: ItemId): OrderItem | undefined {
-    return findEntityById(this._state.items, itemId);
+    return findEntityById(this.state.items, itemId);
   }
 }
 
@@ -983,15 +1011,15 @@ class OrderItem extends Entity<OrderItemState, ItemId> {
     if (newQuantity <= 0) {
       throw new Error("Quantity must be greater than 0");
     }
-    this._state = { ...this._state, quantity: newQuantity };
+    this.setState({ ...this.state, quantity: newQuantity });
   }
 
   calculateSubtotal(): number {
-    return this._state.price * this._state.quantity;
+    return this.state.price * this.state.quantity;
   }
 
   isForProduct(productId: string): boolean {
-    return this._state.productId === productId;
+    return this.state.productId === productId;
   }
 
   protected validateState(state: OrderItemState): void {
@@ -1028,17 +1056,16 @@ class Order extends AggregateRoot<OrderState, OrderId>
     const itemId = `item-${++this.itemCounter}` as ItemId;
     const item = new OrderItem(itemId, productId, quantity, price);
 
-    this._state = {
-      ...this._state,
-      items: [...this._state.items, item],
-    };
-    this.bumpVersion();
+    this.setState({
+      ...this.state,
+      items: [...this.state.items, item],
+    }, true);
     return itemId;
   }
 
   // Delegate to entity's business logic
   updateItemQuantity(itemId: ItemId, newQuantity: number): void {
-    const item = findEntityById(this._state.items, itemId);
+    const item = findEntityById(this.state.items, itemId);
     if (!item) throw new Error("Item not found");
 
     item.updateQuantity(newQuantity); // Uses entity's logic
@@ -1047,18 +1074,17 @@ class Order extends AggregateRoot<OrderState, OrderId>
 
   // Use entity's business logic
   calculateTotal(): number {
-    return this._state.items.reduce(
+    return this.state.items.reduce(
       (total, item) => total + item.calculateSubtotal(),
       0
     );
   }
 
   confirm(): void {
-    if (this._state.items.length === 0) {
+    if (this.state.items.length === 0) {
       throw new Error("Cannot confirm an order without items");
     }
-    this._state = { ...this._state, status: "confirmed" };
-    this.bumpVersion();
+    this.setState({ ...this.state, status: "confirmed" }, true);
   }
 }
 
@@ -1077,26 +1103,7 @@ The `Result<T, E>` type provides composition utilities to avoid repetitive `if (
 **Import Result utilities from the dedicated export path:**
 
 ```typescript
-import { 
-  ok, 
-  err, 
-  isOk, 
-  isErr, 
-  andThen, 
-  map, 
-  mapErr, 
-  unwrapOr, 
-  unwrapOrElse, 
-  match,
-  matchAsync,
-  pipe,
-  tryCatch,
-  tryCatchAsync,
-  type Result,
-  Outcome,
-  Success,
-  Erroneous
-} from "@shirudo/ddd-kit/result";
+import { ok, err, type Result } from "@shirudo/result";
 
 type UserId = string;
 
@@ -1104,107 +1111,41 @@ function validateUserId(id: string): Result<UserId, string> {
   return id.length > 0 ? ok(id as UserId) : err("User ID cannot be empty");
 }
 
-function validateEmail(email: string): Result<string, string> {
-  return email.includes("@") ? ok(email) : err("Invalid email");
-}
-
-// 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,
-    }))
-  );
-}
-
-// 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);
+const result = validateUserId("user-123");
+if (result.isOk()) {
+  console.log("Valid:", result.value);
 } else {
-  console.error("Error:", result2.error);
+  console.error("Invalid:", result.error);
 }
+```
 
-// Using tryCatch to wrap functions that throw exceptions
-function riskyOperation(): string {
-  if (Math.random() > 0.5) {
-    throw new Error("Something went wrong");
-  }
-  return "success";
-}
+`ddd-kit` declares `@shirudo/result` as a `peerDependency`, so install it once in your app:
 
-const result3 = tryCatch(() => riskyOperation());
-if (result3.ok) {
-  console.log(result3.value); // "success"
-} else {
-  console.error(result3.error.message); // "Something went wrong"
-}
+```bash
+pnpm add @shirudo/result
+```
 
-// Using tryCatchAsync for async operations
-async function riskyAsyncOperation(): Promise<string> {
-  if (Math.random() > 0.5) {
-    throw new Error("Async error");
-  }
-  return "async success";
-}
+For composition utilities (`map`, `flatMap`, `mapErr`, `match`, `unwrapOr`, `pipe`, `tryCatch`, async variants, etc.), refer to the [`@shirudo/result` documentation](https://www.npmjs.com/package/@shirudo/result).
 
-const result4 = await tryCatchAsync(() => riskyAsyncOperation());
-match(result4,
-  (value) => console.log("Success:", value),
-  (error) => console.error("Error:", error.message)
-);
-```
+**Where `ddd-kit` uses `Result` vs `throw`:**
 
-**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. Supports both function and object syntax.
-- `matchAsync<T, E, R>(result, onOk, onErr)` - Asynchronous pattern matching. Applies async functions for Ok/Err cases. Supports both function and object syntax.
-- `pipe<T, E>(initial, ...fns)` - Pipes a Result through multiple operations. Stops on first error. Cleaner alternative to nested `andThen` calls.
-- `tryCatch<T, E>(fn, errorMapper?)` - Wraps a function that may throw exceptions into a Result type. Catches exceptions and converts them to Err results.
-- `tryCatchAsync<T, E>(fn, errorMapper?)` - Wraps an async function that may throw exceptions into a Promise<Result>. Catches exceptions and Promise rejections.
-
-**Class-based API (for method chaining):**
-- `Outcome<T, E>` - Wrapper class for Result with method chaining support
-- `Success<T>` - Class representing successful results (created via `Ok()` factory)
-- `Erroneous<E>` - Class representing error results (created via `Err()` factory)
+- **Domain layer throws** `DomainError`-derived exceptions. `EventSourcedAggregate.apply()`, the `validateEvent()` hook, and the `ValueObject` constructor all throw. Subclass `DomainError` for your aggregate-specific errors (e.g. `OrderAlreadyShippedError`) and catch via `instanceof`.
+- **Infrastructure boundary returns `Result`** where corruption is an expected recoverable failure: `EventSourcedAggregate.loadFromHistory()`, `restoreFromSnapshotWithEvents()`.
+- **App-Service boundary returns `Result`**: `CommandBus.execute()`, `QueryBus.execute()`, `CommandHandler<C,R>`, `QueryHandler<Q,R>`, `withCommit()`. This is where you map errors to HTTP statuses, logs, etc.
+- **`voWithValidation`** is the explicit Result variant for parsing untrusted input at the App boundary. For Domain construction, use the `ValueObject` base class (constructor throws via `validate()`).
 
 ## 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()`, `voEqualsExcept()`, `voWithValidation()`, `voWithValidationUnsafe()` - Value Object utilities
+- `vo()`, `voEquals()`, `voEqualsExcept()`, `voWithValidation()` - Value Object utilities (`voWithValidation` is for the App-Service boundary; Domain construction goes through the `ValueObject` base class which throws via `validate()`)
 - `IAggregateRoot<TId>` - Marker interface for Aggregate Root Entities
 - `AggregateRoot<TState, TId, TEvent?>` - Base class for creating Aggregate Root Entities without Event Sourcing (extends `Entity`, implements `IAggregateRoot<TId>`). Optional `TEvent` parameter enables type-safe domain events
-- `AggregateEventSourced<TState, TEvent, TId>` - Base class for Event-Sourced Aggregate Root Entities (extends `AggregateRoot`, implements `IAggregateEventSourced<TId, TEvent>`)
-- `AggregateConfig`, `AggregateEventSourcedConfig` - Configuration interfaces
+- `EventSourcedAggregate<TState, TEvent, TId>` - Base class for Event-Sourced Aggregate Roots (extends `Entity`, implements `IEventSourcedAggregate<TId, TEvent>`)
+- `AggregateConfig`, `EventSourcedAggregateConfig` - Configuration interfaces
 - `AggregateSnapshot<TState>` - Snapshot interface for performance optimization
-- `sameAggregate()` - Aggregate equality helper
+- `sameVersion()` - Optimistic concurrency check (same ID and version)
 - `Entity<TState, TId>` - Base class for entities with state and business logic
 - `IEntity<TId, TState>` - Entity interface
 - `Identifiable<TId>` - Minimal interface for objects with id
@@ -1224,14 +1165,12 @@ Key exports include:
 - `EventBus.subscribe()` - Subscribe handlers to event types
 - `EventBus.publish()` - Publish events to all subscribers (uses `Promise.allSettled` — all handlers run even if one fails)
 - `EventBus.once()` - Wait for the next event of a given type (returns Promise, auto-unsubscribes)
-- `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
-- `UnitOfWork` - Unit of Work interface
-- `guard()` - Guard/validation helper
+- `Id<Tag>` - Branded ID type (Result type and operators come from the `@shirudo/result` peer dep)
+- `IRepository<TAgg, TId>` - Repository interface
+- `IQueryableRepository<TAgg, TId, TFilter>` - Repository extension that adds filter-based querying. `TFilter` is the persistence layer's native filter shape (Drizzle SQL, Prisma WhereInput, Mongo filter doc, in-memory predicate, …). Repositories that are only accessed by id should implement `IRepository` directly and skip this extension.
+- `TransactionScope` - Transaction-scope abstraction (wraps a block of work in the persistence layer's native transaction). Intentionally minimal — not Fowler's full UoW with change tracking.
+- `DomainError` - Abstract base for domain exceptions (Consumer subclasses for their aggregate-specific errors)
+- `MissingHandlerError`, `AggregateNotFoundError` - Concrete library-internal `DomainError` subclasses
 
 ## Concurrency & Thread Safety
 
@@ -1349,7 +1288,7 @@ class CreateOrderHandler implements CommandHandler<CreateOrderCommand, OrderId>
 
     // 3. Save
     await this.repository.save(order);
-    await this.eventBus.publish(order.pendingEvents);
+    await this.eventBus.publish(order.domainEvents);
 
     return ok(order.id);
     // 4. Aggregate is garbage collected when method returns
@@ -1556,7 +1495,7 @@ class OrderService {
     }
 
     await this.repository.save(order);
-    await this.eventBus.publish(order.pendingEvents);
+    await this.eventBus.publish(order.domainEvents);
 
     return ok(order.id);
     // order is garbage collected here