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

package/README.md

@@ -2,6 +2,8 @@
 
 Composable TypeScript toolkit for tactical Domain-Driven Design.
 
+📚 **[Full documentation site](https://shi-rudo.github.io/ddd-kit-ts/)** — guides, API reference, design decisions.
+
 > **Release Candidate**
 >
 > 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.
@@ -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
 
@@ -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({
@@ -308,6 +307,48 @@ 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
@@ -350,28 +391,22 @@ class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
   }
 
   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 = {
@@ -490,19 +525,24 @@ class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
 
 ### 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 & {
@@ -541,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);
@@ -600,7 +640,7 @@ const result = await queryBus.execute({
   orderId: "order-123",
 });
 
-if (result.ok) {
+if (result.isOk()) {
   const orderFromBus = result.value;
   // Use orderFromBus...
 } else {
@@ -714,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
@@ -1063,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;
 
@@ -1090,101 +1111,35 @@ 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
 - `EventSourcedAggregate<TState, TEvent, TId>` - Base class for Event-Sourced Aggregate Roots (extends `Entity`, implements `IEventSourcedAggregate<TId, TEvent>`)
@@ -1210,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
+- `Id<Tag>` - Branded ID type (Result type and operators come from the `@shirudo/result` peer dep)
 - `IRepository<TAgg, TId>` - Repository interface
-- `ISpecification<T>` - Specification interface
-- `UnitOfWork` - Unit of Work interface
-- `guard()` - Guard/validation helper
+- `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