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

package/dist/index.d.ts

@@ -8,6 +8,138 @@ interface IdGenerator {
     next: <T extends string>() => Id<T>;
 }
 
+/**
+ * Metadata associated with a domain event for traceability and correlation.
+ * Used in event-driven architectures to track event flow across services.
+ */
+interface EventMetadata {
+    /**
+     * Correlation ID for tracing events across multiple services/components.
+     * Typically used to group related events in a distributed system.
+     */
+    correlationId?: string;
+    /**
+     * Causation ID referencing the event or command that caused this event.
+     * Used to build event chains and understand causality.
+     */
+    causationId?: string;
+    /**
+     * User ID of the person or system that triggered the event.
+     */
+    userId?: string;
+    /**
+     * Source service or component that produced the event.
+     */
+    source?: string;
+    /**
+     * Additional custom metadata fields.
+     * Allows extensibility for domain-specific metadata.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Domain Event represents something meaningful that happened in the domain.
+ * Events are immutable and carry information about what occurred.
+ *
+ * @template T - The event type name (e.g., "OrderCreated")
+ * @template P - The event payload type
+ */
+interface DomainEvent<T extends string, P = void> {
+    /**
+     * The type of the event, used for routing and handling.
+     */
+    type: T;
+    /**
+     * The event payload containing the domain data.
+     * Omitted when P is void (events without payload).
+     */
+    payload: P;
+    /**
+     * Timestamp when the event occurred.
+     */
+    occurredAt: Date;
+    /**
+     * Event schema version for handling schema evolution.
+     * Required for safe schema migration in event-sourced systems.
+     * Use 1 for the initial schema version.
+     */
+    version: number;
+    /**
+     * Optional metadata for traceability, correlation, and auditing.
+     * Includes correlationId, causationId, userId, source, and custom fields.
+     */
+    metadata?: EventMetadata;
+}
+/**
+ * Creates a domain event with default values.
+ * Sets occurredAt to current date and version to 1 if not provided.
+ *
+ * @param type - The event type
+ * @param payload - The event payload
+ * @param options - Optional event configuration
+ * @returns A domain event
+ *
+ * @example
+ * ```typescript
+ * const event = createDomainEvent("OrderCreated", { orderId: "123" });
+ * ```
+ */
+declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: {
+    occurredAt?: Date;
+    version?: number;
+    metadata?: EventMetadata;
+}): DomainEvent<T, void>;
+declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: {
+    occurredAt?: Date;
+    version?: number;
+    metadata?: EventMetadata;
+}): DomainEvent<T, P>;
+/**
+ * Creates a domain event with metadata for traceability.
+ * Convenience function for creating events with correlation and causation IDs.
+ *
+ * @example
+ * ```typescript
+ * const event = createDomainEventWithMetadata(
+ *   "OrderCreated",
+ *   { orderId: "123" },
+ *   { correlationId: "corr-123", causationId: "cmd-456", userId: "user-789" }
+ * );
+ * ```
+ */
+declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: {
+    occurredAt?: Date;
+    version?: number;
+}): DomainEvent<T, P>;
+/**
+ * Copies metadata from a source event to a new event.
+ * Useful for maintaining correlation chains in event-driven architectures.
+ *
+ * @example
+ * ```typescript
+ * const newEvent = createDomainEvent(
+ *   "OrderShipped",
+ *   { orderId: "123" },
+ *   { metadata: copyMetadata(previousEvent, { causationId: previousEvent.type }) }
+ * );
+ * ```
+ */
+declare function copyMetadata(sourceEvent: DomainEvent<string, unknown>, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
+/**
+ * Merges multiple metadata objects into one.
+ * Later metadata objects override earlier ones for the same keys.
+ *
+ * @example
+ * ```typescript
+ * const metadata = mergeMetadata(
+ *   { correlationId: "corr-123" },
+ *   { userId: "user-456" },
+ *   { source: "order-service" }
+ * );
+ * ```
+ */
+declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
+
 /**
  * Functional definition of an Entity via its capability.
  * An object is identifiable if it has an id.
@@ -292,36 +424,28 @@ interface AggregateConfig {
     autoVersionBump?: boolean;
 }
 /**
- * Base class for creating Aggregate Roots (Entities) without Event Sourcing.
+ * Base class for Aggregate Roots without Event Sourcing.
  *
- * This class creates an Entity that serves as the Aggregate Root. The Aggregate Root
- * is the parent Entity of the aggregate and represents it externally. It has identity
- * (id), state, and version for optimistic concurrency control.
+ * In DDD (Evans), an Aggregate is a cluster of objects — root entity, child entities,
+ * and value objects — treated as a unit for consistency. The **Aggregate Root** is the
+ * root entity that represents the aggregate externally and is the only entry point
+ * for external code. This class serves as both: it IS the root entity and it contains
+ * the aggregate state (`TState`) which holds child entities and value objects.
  *
- * Extends `Entity<TState, TId>` to inherit:
- * - Identity (id)
- * - State management
- * - State validation
- *
- * Adds Aggregate Root specific functionality:
- * - Version management (for Optimistic Concurrency Control)
- * - Domain events tracking
+ * Provides:
+ * - Identity (id) and state management (via `Entity`)
+ * - Version management for optimistic concurrency control
+ * - Domain event tracking for side-effects
  * - Snapshot support for performance optimization
  *
- * The aggregate state (`TState`) contains:
- * - Child entities (Entities with id + state, but no own version)
- * - Value objects (immutable objects)
+ * All changes to child entities within `TState` are versioned through this root.
+ * Use `setState()` for state mutations to ensure invariant validation.
  *
- * All changes to child entities are versioned through the Aggregate Root. The version
- * applies to the entire aggregate, including all child entities.
- *
- * Implements `IAggregateRoot<TId>` to mark this as an Aggregate Root Entity.
- *
- * Use this class when you don't need Event Sourcing but still want
- * aggregate patterns with versioning and state management.
+ * For event sourcing, use `EventSourcedAggregate` instead.
  *
  * @template TState - The type of the aggregate state (contains child entities and value objects)
  * @template TId - The type of the aggregate root identifier
+ * @template TEvent - The type of domain events recorded by this aggregate (defaults to unknown)
  *
  * @example
  * ```typescript
@@ -332,14 +456,15 @@ interface AggregateConfig {
  *   }
  *
  *   confirm(): void {
- *     this._state = { ...this._state, status: "confirmed" };
- *     this.bumpVersion(); // Versions the entire aggregate
+ *     this.setState({ ...this.state, status: "confirmed" }, true);
  *   }
  * }
  * ```
  */
-declare abstract class AggregateRoot<TState, TId extends Id<string>> extends Entity<TState, TId> implements IAggregateRoot<TId> {
-    version: Version;
+declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent = unknown> extends Entity<TState, TId> implements IAggregateRoot<TId> {
+    private _version;
+    get version(): Version;
+    protected setVersion(version: Version): void;
     private readonly _config;
     private readonly _autoVersionBump;
     private _domainEvents;
@@ -347,7 +472,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>> extends Ent
      * Returns a read-only list of domain events recorded by this aggregate.
      * These events are side-effects of state changes.
      */
-    get domainEvents(): ReadonlyArray<unknown>;
+    get domainEvents(): ReadonlyArray<TEvent>;
     /**
      * Clears the list of recorded domain events.
      * Call this after dispatching the events.
@@ -360,7 +485,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>> extends Ent
      *
      * @param event - The domain event to add
      */
-    protected addDomainEvent(event: unknown): void;
+    protected addDomainEvent(event: TEvent): void;
     /**
      * Manually bumps the aggregate version.
      * Call this after state changes for Optimistic Concurrency Control.
@@ -416,7 +541,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>> extends Ent
  * @template TId - The type of the aggregate root identifier
  * @template TEvent - The union type of all domain events
  */
-interface IAggregateEventSourced<TId extends Id<string>, TEvent extends DomainEvent<string, unknown>> extends IAggregateRoot<TId> {
+interface IEventSourcedAggregate<TId extends Id<string>, TEvent extends DomainEvent<string, unknown>> extends IAggregateRoot<TId> {
     /**
      * Returns a read-only list of new, not-yet-persisted events.
      */
@@ -446,9 +571,9 @@ interface IAggregateEventSourced<TId extends Id<string>, TEvent extends DomainEv
 }
 type Handler<TState, TEvent> = (state: TState, event: TEvent) => TState;
 /**
- * Extended configuration options for AggregateEventSourced behavior.
+ * Configuration options for EventSourcedAggregate behavior.
  */
-interface AggregateEventSourcedConfig extends AggregateConfig {
+interface EventSourcedAggregateConfig {
     /**
      * Whether to automatically bump the version when applying new events.
      * Defaults to true. Set to false to manually control versioning.
@@ -456,26 +581,15 @@ interface AggregateEventSourcedConfig extends AggregateConfig {
     autoVersionBump?: boolean;
 }
 /**
- * Base class for Event-Sourced Aggregate Roots (Entities).
+ * Base class for Event-Sourced Aggregate Roots (Vernon, IDDD Chapter 8).
  *
- * Extends `AggregateRoot` to create an Aggregate Root Entity with Event Sourcing capabilities.
- * The Aggregate Root is the parent Entity of the aggregate and represents it externally.
+ * Like `AggregateRoot`, this is both the root entity and the aggregate boundary.
+ * The difference is persistence: state is derived from events, not stored directly.
+ * Events are the single source of truth — all state changes go through `apply()` → handler.
  *
- * The aggregate state (`TState`) contains:
- * - Child entities (Entities with id, but no own version)
- * - Value objects (immutable objects)
- *
- * All changes to child entities are versioned through the Aggregate Root. The version
- * applies to the entire aggregate, including all child entities.
- *
- * Extends `AggregateRoot` with Event Sourcing capabilities:
- * - Event tracking (pendingEvents)
- * - Event handlers for state transitions
- * - Event validation
- * - History replay
- *
- * Use this class when you want Event Sourcing with full event tracking
- * and replay capabilities.
+ * Extends `Entity` directly (not `AggregateRoot`) so that `setState()` and
+ * `addDomainEvent()` are not available. This enforces the event sourcing pattern
+ * at the type level — there is no way to mutate state without going through an event handler.
  *
  * @template TState - The type of the aggregate state (contains child entities and value objects)
  * @template TEvent - The union type of all domain events
@@ -483,8 +597,7 @@ interface AggregateEventSourcedConfig extends AggregateConfig {
  *
  * @example
  * ```typescript
- * // Order is an Aggregate Root (an Entity) with Event Sourcing
- * class Order extends AggregateEventSourced<OrderState, OrderEvent, OrderId> {
+ * class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
  *   confirm(): void {
  *     this.apply(createDomainEvent("OrderConfirmed", {}));
  *   }
@@ -498,58 +611,32 @@ interface AggregateEventSourcedConfig extends AggregateConfig {
  * }
  * ```
  */
-declare abstract class AggregateEventSourced<TState, TEvent extends DomainEvent<string, unknown>, TId extends Id<string>> extends AggregateRoot<TState, TId> implements IAggregateEventSourced<TId, TEvent> {
-    private readonly _eventConfig;
-    private readonly _eventAutoVersionBump;
-    protected constructor(id: TId, initialState: TState, config?: AggregateEventSourcedConfig);
-    /**
-     * Returns a read-only list of new, not-yet-persisted events.
-     */
+declare abstract class EventSourcedAggregate<TState, TEvent extends DomainEvent<string, unknown>, TId extends Id<string>> extends Entity<TState, TId> implements IEventSourcedAggregate<TId, TEvent> {
+    private _version;
+    get version(): Version;
+    private setVersion;
+    private _pendingEvents;
+    private readonly _autoVersionBump;
     get pendingEvents(): ReadonlyArray<TEvent>;
-    /**
-     * Clears the list of pending events.
-     * Typically called after the events have been persisted.
-     */
     clearPendingEvents(): void;
+    protected constructor(id: TId, initialState: TState, config?: EventSourcedAggregateConfig);
     /**
      * Validates an event before it is applied.
      * Override this method to add custom validation logic.
      * Return `ok(true)` if the event is valid, `err(message)` otherwise.
-     *
-     * @param event - The event to validate
-     * @returns Result indicating if the event is valid
-     *
-     * @example
-     * ```typescript
-     * protected validateEvent(event: OrderEvent): Result<true, string> {
-     *   if (event.type === "OrderShipped" && this.state.status !== "confirmed") {
-     *     return err("Order must be confirmed before shipping");
-     *   }
-     *   return ok(true);
-     * }
-     * ```
      */
     protected validateEvent(_event: TEvent): Result<true, string>;
     /**
-     * Applies an event to change the state and adds it
-     * to the list of pending events.
+     * Applies an event to change the state and adds it to pending events.
      * Returns a Result type instead of throwing an error.
      *
      * @param event - The domain event to apply
-     * @param isNew - Indicates whether the event is new (and needs to be persisted)
-     *                or if it is being loaded from history
-     * @returns Result<void, string> - ok if successful, err with error message if validation fails or handler is missing
+     * @param isNew - Whether the event is new (needs persisting) or from history replay
      */
     protected apply(event: TEvent, isNew?: boolean): Result<void, string>;
     /**
-     * Applies an event to change the state and adds it
-     * to the list of pending events.
+     * Applies an event to change the state and adds it to pending events.
      * Throws an error if validation fails or handler is missing.
-     *
-     * @param event - The domain event to apply
-     * @param isNew - Indicates whether the event is new (and needs to be persisted)
-     *                or if it is being loaded from history
-     * @throws Error if event validation fails or handler is missing
      */
     protected applyUnsafe(event: TEvent, isNew?: boolean): void;
     /**
@@ -560,41 +647,17 @@ declare abstract class AggregateEventSourced<TState, TEvent extends DomainEvent<
     /**
      * Reconstitutes the aggregate from an event history.
      * Sets the version to the number of events in the history.
-     *
-     * @param history - An ordered list of past events
      */
     loadFromHistory(history: TEvent[]): Result<void, string>;
-    /**
-     * Checks if the aggregate has any pending events.
-     *
-     * @returns true if there are pending events, false otherwise
-     */
     hasPendingEvents(): boolean;
-    /**
-     * Returns the number of pending events.
-     *
-     * @returns The count of pending events
-     */
     getEventCount(): number;
+    getLatestEvent(): TEvent | undefined;
     /**
-     * Returns the latest pending event, if any.
-     *
-     * @returns The most recent event or undefined if no events exist
+     * Creates a snapshot of the current aggregate state.
      */
-    getLatestEvent(): TEvent | undefined;
+    createSnapshot(): AggregateSnapshot<TState>;
     /**
-     * Restores the aggregate from a snapshot and applies events that occurred after the snapshot.
-     * This is more efficient than replaying all events from the beginning.
-     *
-     * @param snapshot - The snapshot to restore from
-     * @param eventsAfterSnapshot - Events that occurred after the snapshot was taken
-     *
-     * @example
-     * ```typescript
-     * const snapshot = await snapshotRepository.getLatest(aggregateId);
-     * const eventsAfter = await eventStore.getEventsAfter(aggregateId, snapshot.version);
-     * aggregate.restoreFromSnapshotWithEvents(snapshot, eventsAfter);
-     * ```
+     * Restores the aggregate from a snapshot and applies events that occurred after.
      */
     restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: TEvent[]): Result<void, string>;
     /**
@@ -612,164 +675,32 @@ type Version = number & {
     readonly __v: true;
 };
 /**
- * Metadata associated with a domain event for traceability and correlation.
- * Used in event-driven architectures to track event flow across services.
- */
-interface EventMetadata {
-    /**
-     * Correlation ID for tracing events across multiple services/components.
-     * Typically used to group related events in a distributed system.
-     */
-    correlationId?: string;
-    /**
-     * Causation ID referencing the event or command that caused this event.
-     * Used to build event chains and understand causality.
-     */
-    causationId?: string;
-    /**
-     * User ID of the person or system that triggered the event.
-     */
-    userId?: string;
-    /**
-     * Source service or component that produced the event.
-     */
-    source?: string;
-    /**
-     * Additional custom metadata fields.
-     * Allows extensibility for domain-specific metadata.
-     */
-    [key: string]: unknown;
-}
-/**
- * Domain Event represents something meaningful that happened in the domain.
- * Events are immutable and carry information about what occurred.
+ * Lightweight functional aggregate state — state + version, no event sourcing.
+ * This is a data projection, not a full Aggregate (which requires identity via IAggregateRoot).
  *
- * @template T - The event type name (e.g., "OrderCreated")
- * @template P - The event payload type
- */
-interface DomainEvent<T extends string, P> {
-    /**
-     * The type of the event, used for routing and handling.
-     */
-    type: T;
-    /**
-     * The event payload containing the domain data.
-     */
-    payload: P;
-    /**
-     * Timestamp when the event occurred.
-     */
-    occurredAt: Date;
-    /**
-     * Event schema version for handling schema evolution.
-     * Defaults to 1 if not specified. Higher versions indicate schema changes.
-     */
-    version?: number;
-    /**
-     * Optional metadata for traceability, correlation, and auditing.
-     * Includes correlationId, causationId, userId, source, and custom fields.
-     */
-    metadata?: EventMetadata;
-}
-
-/**
- * Structural interface representing an aggregate with state and events.
- * Used for type constraints in repositories and other infrastructure code.
+ * For event sourcing, use the class-based `EventSourcedAggregate` which enforces
+ * that state changes happen through event handlers.
  *
  * @template State - The type of the aggregate state
- * @template Evt - The union type of all domain events
  */
-interface Aggregate<State, Evt extends DomainEvent<string, unknown>> {
+interface AggregateState<State> {
     state: Readonly<State>;
     version: Version;
-    pendingEvents: ReadonlyArray<Evt>;
 }
-declare function aggregate<State, Evt extends DomainEvent<string, unknown>>(state: State, version?: Version): Aggregate<State, Evt>;
-declare function withEvent<S, E extends DomainEvent<string, unknown>>(agg: Aggregate<S, E>, evt: E): Aggregate<S, E>;
-declare function bump<S, E extends DomainEvent<string, unknown>>(agg: Aggregate<S, E>): Aggregate<S, E>;
-/**
- * Creates a domain event with default values.
- * Sets occurredAt to current date and version to 1 if not provided.
- *
- * @param type - The event type
- * @param payload - The event payload
- * @param options - Optional event configuration
- * @returns A domain event
- *
- * @example
- * ```typescript
- * const event = createDomainEvent("OrderCreated", { orderId: "123" });
- * ```
- */
-declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: {
-    occurredAt?: Date;
-    version?: number;
-    metadata?: EventMetadata;
-}): DomainEvent<T, P>;
-/**
- * Creates a domain event with metadata for traceability.
- * Convenience function for creating events with correlation and causation IDs.
- *
- * @param type - The event type
- * @param payload - The event payload
- * @param metadata - Event metadata for traceability
- * @param options - Optional event configuration
- * @returns A domain event with metadata
- *
- * @example
- * ```typescript
- * const event = createDomainEventWithMetadata(
- *   "OrderCreated",
- *   { orderId: "123" },
- *   {
- *     correlationId: "corr-123",
- *     causationId: "cmd-456",
- *     userId: "user-789"
- *   }
- * );
- * ```
- */
-declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: {
-    occurredAt?: Date;
-    version?: number;
-}): DomainEvent<T, P>;
 /**
- * Copies metadata from a source event to a new event.
- * Useful for maintaining correlation chains in event-driven architectures.
- *
- * @param sourceEvent - The source event to copy metadata from
- * @param additionalMetadata - Additional metadata to merge in
- * @returns Event metadata with copied and merged values
+ * Creates a lightweight functional aggregate state.
  *
  * @example
  * ```typescript
- * const newEvent = createDomainEvent(
- *   "OrderShipped",
- *   { orderId: "123" },
- *   {
- *     metadata: copyMetadata(previousEvent, { causationId: previousEvent.type })
- *   }
- * );
+ * const order = aggregate<OrderState>({ status: "draft", items: [] });
  * ```
  */
-declare function copyMetadata(sourceEvent: DomainEvent<string, unknown>, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
+declare function aggregate<State>(state: State, version?: Version): AggregateState<State>;
 /**
- * Merges multiple metadata objects into one.
- * Later metadata objects override earlier ones for the same keys.
- *
- * @param metadataObjects - Array of metadata objects to merge
- * @returns Merged event metadata
- *
- * @example
- * ```typescript
- * const metadata = mergeMetadata(
- *   { correlationId: "corr-123" },
- *   { userId: "user-456" },
- *   { source: "order-service" }
- * );
- * ```
+ * Bumps the version of a functional aggregate state.
+ * Returns a new aggregate state with incremented version.
  */
-declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
+declare function bump<S>(agg: AggregateState<S>): AggregateState<S>;
 /**
  * Snapshot of an aggregate state at a specific point in time.
  * Used for optimizing event replay by starting from a snapshot
@@ -792,25 +723,24 @@ interface AggregateSnapshot<TState> {
     snapshotAt: Date;
 }
 /**
- * Checks if two aggregates are the same (same ID and version).
+ * Checks if two aggregates are at the same version (same ID and version).
  * Useful for optimistic concurrency control checks.
  *
- * @param a - First aggregate
- * @param b - Second aggregate
- * @returns true if both aggregates have the same ID and version
+ * Note: Two aggregates with the same ID ARE the same aggregate (identity).
+ * This function checks if they are at the same version — i.e., no concurrent modification.
  *
  * @example
  * ```typescript
- * const aggregate1 = await repository.getById(id);
+ * const before = await repository.getById(id);
  * // ... some operations ...
- * const aggregate2 = await repository.getById(id);
+ * const after = await repository.getById(id);
  *
- * if (!sameAggregate(aggregate1, aggregate2)) {
+ * if (!sameVersion(before, after)) {
  *   throw new Error("Aggregate was modified by another process");
  * }
  * ```
  */
-declare function sameAggregate<TId extends Id<string>>(a: {
+declare function sameVersion<TId extends Id<string>>(a: {
     id: TId;
     version: Version;
 }, b: {
@@ -906,29 +836,58 @@ interface Command {
  */
 type CommandHandler<C extends Command, R> = (cmd: C) => Promise<Result<R, string>>;
 
+/**
+ * Type map for command types to their return types.
+ * Used to improve type inference in CommandBus.
+ *
+ * @example
+ * ```typescript
+ * type MyCommandMap = {
+ *   CreateOrder: OrderId;
+ *   CancelOrder: void;
+ * };
+ *
+ * const bus = new CommandBus<MyCommandMap>();
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<OrderId, string>  ← automatically inferred
+ * ```
+ */
+type CommandTypeMap = Record<string, unknown>;
 /**
  * Command Bus interface for dispatching commands to their handlers.
  * Provides a centralized way to execute commands with handler registration.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * Without a type map, the return type must be specified manually or defaults to `unknown`.
+ *
+ * @template TMap - Optional mapping from command type strings to return types
+ *
  * @example
  * ```typescript
+ * // With type map (recommended) – return type is inferred
+ * type MyCommands = { CreateOrder: OrderId; CancelOrder: void };
+ * const bus = new CommandBus<MyCommands>();
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<OrderId, string>
+ *
+ * // Without type map – works like before
  * const bus = new CommandBus();
  * bus.register("CreateOrder", createOrderHandler);
- *
- * const result = await bus.execute({
- *   type: "CreateOrder",
- *   customerId: "123",
- *   items: [...]
- * });
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<unknown, string>
  * ```
  */
-interface ICommandBus {
+interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
     /**
      * Executes a command by dispatching it to the registered handler.
+     * When a type map is provided, the return type is inferred from the command type.
      *
      * @param command - The command to execute
      * @returns Result containing the success value or error message
      */
+    execute<C extends Command & {
+        type: keyof TMap & string;
+    }>(command: C): Promise<Result<TMap[C["type"]], string>>;
     execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
     /**
      * Registers a handler for a specific command type.
@@ -942,6 +901,10 @@ interface ICommandBus {
  * Simple in-memory command bus implementation.
  * Handlers are stored in a Map and dispatched based on command type.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * When `TMap` is provided, `execute()` infers the result type from the command type.
+ * Without `TMap`, it works like before (return type defaults to `unknown` or can be specified manually).
+ *
  * **Note:** This is a basic implementation suitable for development and simple use cases.
  * For production environments, consider implementing or using a more feature-rich bus that includes:
  * - Middleware/Pipeline support (logging, validation, authorization)
@@ -954,20 +917,28 @@ interface ICommandBus {
  * The `CommandHandler` type can still be used with external production-grade buses
  * (e.g., RabbitMQ, AWS SQS) while maintaining type safety.
  *
+ * @template TMap - Optional mapping from command type strings to return types
+ *
  * @example
  * ```typescript
- * const bus = new CommandBus();
- * bus.register("CreateOrder", async (cmd) => {
- *   // ... handler logic
- *   return ok(orderId);
- * });
+ * // With type map – full inference
+ * type Commands = { CreateOrder: OrderId; CancelOrder: void };
+ * const bus = new CommandBus<Commands>();
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * // result: Result<OrderId, string>
  *
+ * // Without type map – same as before
+ * const bus = new CommandBus();
+ * bus.register("CreateOrder", async (cmd) => ok(orderId));
  * const result = await bus.execute({ type: "CreateOrder", ... });
  * ```
  */
-declare class CommandBus implements ICommandBus {
+declare class CommandBus<TMap extends CommandTypeMap = CommandTypeMap> implements ICommandBus<TMap> {
     private readonly handlers;
     register<C extends Command, R>(commandType: C["type"], handler: CommandHandler<C, R>): void;
+    execute<C extends Command & {
+        type: keyof TMap & string;
+    }>(command: C): Promise<Result<TMap[C["type"]], string>>;
     execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
 }
 
@@ -1000,7 +971,9 @@ type EventHandler<Evt> = (event: Evt) => Promise<void> | void;
  * await bus.publish([orderCreatedEvent, orderShippedEvent]);
  * ```
  */
-interface EventBus<Evt> {
+interface EventBus<Evt extends {
+    type: string;
+}> {
     /**
      * Publishes events to all subscribed handlers.
      * All handlers for each event type will be called.
@@ -1026,14 +999,26 @@ interface EventBus<Evt> {
      * unsubscribe();
      * ```
      */
-    subscribe: <T extends Evt>(eventType: string, handler: EventHandler<T>) => () => void;
+    subscribe: <T extends Evt>(eventType: Evt["type"], handler: EventHandler<T>) => () => void;
+    /**
+     * Subscribes to the next occurrence of an event type.
+     * Returns a Promise that resolves with the event data.
+     * Automatically unsubscribes after the first event.
+     *
+     * @param eventType - The event type to wait for
+     * @returns A Promise that resolves with the event
+     *
+     * @example
+     * ```typescript
+     * const event = await bus.once("OrderCreated");
+     * console.log("Order created:", event.payload.orderId);
+     * ```
+     */
+    once: <T extends Evt>(eventType: Evt["type"]) => Promise<T>;
 }
 interface Outbox<Evt> {
     add: (events: ReadonlyArray<Evt>) => Promise<void>;
 }
-interface Clock {
-    now: () => Date;
-}
 
 interface UnitOfWork {
     transactional<T>(fn: () => Promise<T>): Promise<T>;
@@ -1063,7 +1048,9 @@ type RepoProvider<R> = (uow: UnitOfWork) => R;
  * );
  * ```
  */
-declare function withCommit<Evt, R>(deps: {
+declare function withCommit<Evt extends {
+    type: string;
+}, R>(deps: {
     outbox: Outbox<Evt>;
     bus?: EventBus<Evt>;
     uow: UnitOfWork;
@@ -1147,29 +1134,57 @@ interface Query {
  */
 type QueryHandler<Q extends Query, R> = (query: Q) => Promise<R>;
 
+/**
+ * Type map for query types to their return types.
+ * Used to improve type inference in QueryBus.
+ *
+ * @example
+ * ```typescript
+ * type MyQueryMap = {
+ *   GetOrder: Order | null;
+ *   ListOrders: Order[];
+ * };
+ *
+ * const bus = new QueryBus<MyQueryMap>();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<Order | null, string>  ← automatically inferred
+ * ```
+ */
+type QueryTypeMap = Record<string, unknown>;
 /**
  * Query Bus interface for dispatching queries to their handlers.
  * Provides a centralized way to execute queries with handler registration.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * Without a type map, the return type must be specified manually or defaults to `unknown`.
+ *
+ * @template TMap - Optional mapping from query type strings to return types
+ *
  * @example
  * ```typescript
- * const bus = new QueryBus();
- * bus.register("GetOrder", getOrderHandler);
+ * // With type map (recommended) – return type is inferred
+ * type MyQueries = { GetOrder: Order | null; ListOrders: Order[] };
+ * const bus = new QueryBus<MyQueries>();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<Order | null, string>
  *
- * const order = await bus.execute({
- *   type: "GetOrder",
- *   orderId: "123"
- * });
+ * // Without type map – works like before
+ * const bus = new QueryBus();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<unknown, string>
  * ```
  */
-interface IQueryBus {
+interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
     /**
      * Executes a query by dispatching it to the registered handler.
-     * Returns a Result type instead of throwing an error.
+     * When a type map is provided, the return type is inferred from the query type.
      *
      * @param query - The query to execute
-     * @returns Result containing the query result if successful, or an error message if no handler is registered
+     * @returns Result containing the query result if successful, or an error message
      */
+    execute<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
     execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
     /**
      * Executes a query by dispatching it to the registered handler.
@@ -1179,6 +1194,9 @@ interface IQueryBus {
      * @returns The query result
      * @throws Error if no handler is registered for the query type
      */
+    executeUnsafe<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<TMap[Q["type"]]>;
     executeUnsafe<Q extends Query, R>(query: Q): Promise<R>;
     /**
      * Registers a handler for a specific query type.
@@ -1188,15 +1206,14 @@ interface IQueryBus {
      */
     register<Q extends Query, R>(queryType: Q["type"], handler: QueryHandler<Q, R>): void;
 }
-/**
- * Type map for query types to their return types.
- * Used to improve type inference in QueryBus.
- */
-type QueryTypeMap = Record<string, unknown>;
 /**
  * Simple in-memory query bus implementation.
  * Handlers are stored in a Map and dispatched based on query type.
  *
+ * Supports an optional type map (`TMap`) for automatic return type inference.
+ * When `TMap` is provided, `execute()` and `executeUnsafe()` infer the result type from the query type.
+ * Without `TMap`, it works like before (return type defaults to `unknown` or can be specified manually).
+ *
  * **Note:** This is a basic implementation suitable for development and simple use cases.
  * For production environments, consider implementing or using a more feature-rich bus that includes:
  * - Middleware/Pipeline support (logging, caching, rate limiting)
@@ -1209,23 +1226,32 @@ type QueryTypeMap = Record<string, unknown>;
  * The `QueryHandler` type can still be used with external production-grade buses
  * (e.g., RabbitMQ, AWS SQS) while maintaining type safety.
  *
+ * @template TMap - Optional mapping from query type strings to return types
+ *
  * @example
  * ```typescript
- * const bus = new QueryBus();
- * bus.register("GetOrder", async (query) => {
- *   return await repository.getById(query.orderId);
- * });
+ * // With type map – full inference
+ * type Queries = { GetOrder: Order | null; ListOrders: Order[] };
+ * const bus = new QueryBus<Queries>();
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // result: Result<Order | null, string>
  *
- * const order = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * // Without type map – same as before
+ * const bus = new QueryBus();
+ * bus.register("GetOrder", async (query) => repository.getById(query.orderId));
+ * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
  * ```
  */
-declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus {
+declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus<TMap> {
     private readonly handlers;
     register<Q extends Query, R>(queryType: Q["type"], handler: QueryHandler<Q, R>): void;
     execute<Q extends Query & {
-        type: keyof TMap;
+        type: keyof TMap & string;
     }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
     execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
+    executeUnsafe<Q extends Query & {
+        type: keyof TMap & string;
+    }>(query: Q): Promise<TMap[Q["type"]]>;
     executeUnsafe<Q extends Query, R>(query: Q): Promise<R>;
 }
 
@@ -1271,16 +1297,21 @@ declare function guard(cond: boolean, error: string): Result<true, string>;
  */
 declare class EventBusImpl<Evt extends DomainEvent<string, unknown>> implements EventBus<Evt> {
     private readonly handlers;
-    subscribe<T extends Evt>(eventType: string, handler: EventHandler<T>): () => void;
+    subscribe<T extends Evt>(eventType: Evt["type"], handler: EventHandler<T>): () => void;
+    once<T extends Evt>(eventType: Evt["type"]): Promise<T>;
     publish(events: ReadonlyArray<Evt>): Promise<void>;
 }
 
+declare const __specBrand: unique symbol;
 /**
  * A Specification is a named, standalone object that represents a business rule for a query.
  * It is "translatable" into a concrete database query.
+ *
+ * Uses a branded type to carry the generic parameter without requiring
+ * implementors to add a runtime field.
  */
 interface ISpecification<T> {
-    readonly _type: T;
+    readonly [__specBrand]?: T;
 }
 
 /**
@@ -1297,12 +1328,10 @@ interface ISpecification<T> {
  * Child entities cannot be loaded or saved independently - they exist only
  * within the aggregate boundary and are managed through the Aggregate Root.
  *
- * @template TState - The type of the aggregate state (contains child entities and value objects)
- * @template TEvent - The union type of all domain events
- * @template TAgg - The aggregate root type (must be an Aggregate Root Entity)
+ * @template TAgg - The aggregate root type (must implement IAggregateRoot)
  * @template TId - The type of the aggregate root identifier
  */
-interface IRepository<TState, TEvent extends DomainEvent<string, unknown>, TAgg extends IAggregateRoot<TId> & Aggregate<TState, TEvent>, TId extends Id<string>> {
+interface IRepository<TAgg extends IAggregateRoot<TId>, TId extends Id<string>> {
     getById(id: TId): Promise<TAgg | null>;
     findOne(spec: ISpecification<TAgg>): Promise<TAgg | null>;
     find(spec: ISpecification<TAgg>): Promise<TAgg[]>;
@@ -1541,4 +1570,4 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     toJSON(): Readonly<T>;
 }
 
-export { type Aggregate, type AggregateConfig, AggregateEventSourced, type AggregateEventSourcedConfig, AggregateRoot, type AggregateSnapshot, type Clock, type Command, CommandBus, type CommandHandler, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventMetadata, type IAggregateEventSourced, type IAggregateRoot, type ICommandBus, type IEntity, type IQueryBus, type IRepository, type ISpecification, type IValueObject, type Id, type IdGenerator, type Identifiable, type Outbox, type Query, QueryBus, type QueryHandler, type RepoProvider, type UnitOfWork, type VO, ValueObject, type Version, aggregate, bump, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, guard, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, sameAggregate, sameEntity, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, voWithValidationUnsafe, withCommit, withEvent };
+export { type AggregateConfig, AggregateRoot, type AggregateSnapshot, type AggregateState, type Command, CommandBus, type CommandHandler, type DomainEvent, Entity, type EventBus, EventBusImpl, type EventHandler, type EventMetadata, EventSourcedAggregate, type EventSourcedAggregateConfig, type IAggregateRoot, type ICommandBus, type IEntity, type IEventSourcedAggregate, type IQueryBus, type IRepository, type ISpecification, type IValueObject, type Id, type IdGenerator, type Identifiable, type Outbox, type Query, QueryBus, type QueryHandler, type RepoProvider, type UnitOfWork, type VO, ValueObject, type Version, aggregate, bump, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepFreeze, entityIds, findEntityById, guard, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, sameEntity, sameVersion, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, voWithValidationUnsafe, withCommit };