@shirudo/ddd-kit 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -8,256 +8,242 @@ interface IdGenerator {
     next: <T extends string>() => Id<T>;
 }
 
-type Version = number & {
-    readonly __v: true;
+/**
+ * Functional definition of an Entity via its capability.
+ * An object is identifiable if it has an id.
+ */
+type Identifiable<TId> = {
+    readonly id: TId;
 };
 /**
- * Metadata associated with a domain event for traceability and correlation.
- * Used in event-driven architectures to track event flow across services.
+ * Interface for Entities.
+ * Extends Identifiable and adds equality comparison behavior.
+ *
+ * @template TId - The type of the entity identifier
  */
-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;
+interface IEntity<TId> extends Identifiable<TId> {
     /**
-     * Source service or component that produced the event.
-     */
-    source?: string;
-    /**
-     * Additional custom metadata fields.
-     * Allows extensibility for domain-specific metadata.
+     * Checks if this entity is equal to another.
+     * Two entities are equal if they have the same ID.
+     *
+     * @param other - The other entity to compare
+     * @returns true if IDs are equal
      */
-    [key: string]: unknown;
+    equals(other: Identifiable<TId>): boolean;
 }
 /**
- * Domain Event represents something meaningful that happened in the domain.
- * Events are immutable and carry information about what occurred.
+ * Abstract base class for Entities.
+ * Provides identity equality and common behavior.
  *
- * @template T - The event type name (e.g., "OrderCreated")
- * @template P - The event payload type
+ * @template TId - The type of the entity identifier
  */
-interface DomainEvent<T extends string, P> {
-    /**
-     * The type of the event, used for routing and handling.
-     */
-    type: T;
+declare abstract class Entity<TId> implements IEntity<TId> {
+    readonly id: TId;
+    constructor(id: TId);
     /**
-     * The event payload containing the domain data.
+     * Optional validation hook that can be overridden by subclasses.
+     * Should throw an error if validation fails.
      */
-    payload: P;
+    protected validate(): void;
     /**
-     * Timestamp when the event occurred.
+     * Serializes the entity to a plain object.
+     * Default implementation returns the entity as is (since it's an object with properties).
+     * Subclasses can override this to control JSON serialization.
      */
-    occurredAt: Date;
+    toJSON(): unknown;
     /**
-     * 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.
+     * Checks if this entity is equal to another.
+     * Two entities are equal if they have the same ID.
+     *
+     * @param other - The other entity to compare
+     * @returns true if IDs are equal
      */
-    metadata?: EventMetadata;
+    equals(other: Identifiable<TId>): boolean;
 }
 /**
- * Marker interface for Aggregate Roots.
- *
- * In Domain-Driven Design, an Aggregate Root is an Entity (the parent Entity of the aggregate).
- * It represents the aggregate externally and is the only object that external code
- * is allowed to hold references to. All access to child entities within the aggregate
- * must go through the Aggregate Root.
- *
- * An Aggregate consists of:
- * - One Aggregate Root (Entity with id + version)
- * - Optional child entities (Entities with id, but no own version)
- * - Optional value objects
- *
- * The Aggregate Root has identity (id) and version for optimistic concurrency control.
- * Child entities exist only within the aggregate boundary and are versioned through
- * the Aggregate Root.
+ * Checks if two entities have the same ID.
+ * Works with any object that has an 'id' property.
  *
- * @template TId - The type of the aggregate root identifier
+ * @param a - First entity
+ * @param b - Second entity
+ * @returns true if both entities have the same ID, false otherwise
  *
  * @example
  * ```typescript
- * class Order extends AggregateBase<OrderState, OrderId> implements AggregateRoot<OrderId> {
- *   // Order is an Aggregate Root (an Entity)
- *   // OrderState contains child entities (e.g., OrderItem) and value objects
- * }
- * ```
- */
-interface AggregateRoot<TId extends Id<string>> {
-    /**
-     * Unique identifier of the aggregate root entity.
-     */
-    readonly id: TId;
-    /**
-     * Version number for optimistic concurrency control.
-     * Incremented on each state change to detect concurrent modifications.
-     * This version applies to the entire aggregate, including all child entities.
-     */
-    readonly version: Version;
-}
-/**
- * Structural interface representing an aggregate with state and events.
- * Used for type constraints in repositories and other infrastructure code.
+ * const item1: OrderItem = { id: itemId1, productId: "prod-1", quantity: 2 };
+ * const item2: OrderItem = { id: itemId2, productId: "prod-2", quantity: 1 };
  *
- * @template State - The type of the aggregate state
- * @template Evt - The union type of all domain events
+ * sameEntity(item1, item2); // false
+ * sameEntity(item1, item1); // true
+ * ```
  */
-interface Aggregate<State, Evt extends DomainEvent<string, unknown>> {
-    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>;
+declare function sameEntity<TId>(a: Identifiable<TId>, b: Identifiable<TId>): boolean;
 /**
- * Creates a domain event with default values.
- * Sets occurredAt to current date and version to 1 if not provided.
+ * Finds an entity by ID in a collection.
+ * Returns undefined if not found.
  *
- * @param type - The event type
- * @param payload - The event payload
- * @param options - Optional event configuration
- * @returns A domain event
+ * @param entities - Array of entities to search
+ * @param id - The ID to search for
+ * @returns The entity if found, undefined otherwise
  *
  * @example
  * ```typescript
- * const event = createDomainEvent("OrderCreated", { orderId: "123" });
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 },
+ *   { id: itemId2, productId: "prod-2", quantity: 1 }
+ * ];
+ *
+ * const item = findEntityById(items, itemId1);
+ * // item is { id: itemId1, productId: "prod-1", quantity: 2 }
  * ```
  */
-declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: {
-    occurredAt?: Date;
-    version?: number;
-    metadata?: EventMetadata;
-}): DomainEvent<T, P>;
+declare function findEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId): T | undefined;
 /**
- * Creates a domain event with metadata for traceability.
- * Convenience function for creating events with correlation and causation IDs.
+ * Checks if an entity with the given ID exists in the collection.
  *
- * @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
+ * @param entities - Array of entities to search
+ * @param id - The ID to check for
+ * @returns true if an entity with the ID exists, false otherwise
  *
  * @example
  * ```typescript
- * const event = createDomainEventWithMetadata(
- *   "OrderCreated",
- *   { orderId: "123" },
- *   {
- *     correlationId: "corr-123",
- *     causationId: "cmd-456",
- *     userId: "user-789"
- *   }
- * );
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 }
+ * ];
+ *
+ * hasEntityId(items, itemId1); // true
+ * hasEntityId(items, itemId2); // false
  * ```
  */
-declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: {
-    occurredAt?: Date;
-    version?: number;
-}): DomainEvent<T, P>;
+declare function hasEntityId<TId, T extends Identifiable<TId>>(entities: T[], id: TId): boolean;
 /**
- * Copies metadata from a source event to a new event.
- * Useful for maintaining correlation chains in event-driven architectures.
+ * Removes an entity with the given ID from the collection.
+ * Returns a new array without the entity.
  *
- * @param sourceEvent - The source event to copy metadata from
- * @param additionalMetadata - Additional metadata to merge in
- * @returns Event metadata with copied and merged values
+ * @param entities - Array of entities
+ * @param id - The ID of the entity to remove
+ * @returns A new array without the entity with the given ID
  *
  * @example
  * ```typescript
- * const newEvent = createDomainEvent(
- *   "OrderShipped",
- *   { orderId: "123" },
- *   {
- *     metadata: copyMetadata(previousEvent, { causationId: previousEvent.type })
- *   }
- * );
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 },
+ *   { id: itemId2, productId: "prod-2", quantity: 1 }
+ * ];
+ *
+ * const updated = removeEntityById(items, itemId1);
+ * // updated is [{ id: itemId2, productId: "prod-2", quantity: 1 }]
  * ```
  */
-declare function copyMetadata(sourceEvent: DomainEvent<string, unknown>, additionalMetadata?: Partial<EventMetadata>): EventMetadata;
+declare function removeEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId): T[];
 /**
- * Merges multiple metadata objects into one.
- * Later metadata objects override earlier ones for the same keys.
+ * Updates an entity with the given ID in the collection.
+ * Returns a new array with the updated entity.
+ * If the entity is not found, returns the original array unchanged.
  *
- * @param metadataObjects - Array of metadata objects to merge
- * @returns Merged event metadata
+ * @param entities - Array of entities
+ * @param id - The ID of the entity to update
+ * @param updater - Function that takes the entity and returns the updated entity
+ * @returns A new array with the updated entity
  *
  * @example
  * ```typescript
- * const metadata = mergeMetadata(
- *   { correlationId: "corr-123" },
- *   { userId: "user-456" },
- *   { source: "order-service" }
- * );
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 }
+ * ];
+ *
+ * const updated = updateEntityById(items, itemId1, (item) => ({
+ *   ...item,
+ *   quantity: item.quantity + 1
+ * }));
+ * // updated is [{ id: itemId1, productId: "prod-1", quantity: 3 }]
  * ```
  */
-declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
+declare function updateEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId, updater: (entity: T) => T): T[];
 /**
- * Snapshot of an aggregate state at a specific point in time.
- * Used for optimizing event replay by starting from a snapshot
- * instead of replaying all events from the beginning.
+ * Replaces an entity with the given ID in the collection.
+ * Returns a new array with the replaced entity.
+ * If the entity is not found, returns the original array unchanged.
  *
- * @template TState - The type of the aggregate state
+ * @param entities - Array of entities
+ * @param id - The ID of the entity to replace
+ * @param replacement - The replacement entity
+ * @returns A new array with the replaced entity
+ *
+ * @example
+ * ```typescript
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 }
+ * ];
+ *
+ * const updated = replaceEntityById(items, itemId1, {
+ *   id: itemId1,
+ *   productId: "prod-1",
+ *   quantity: 5
+ * });
+ * ```
  */
-interface AggregateSnapshot<TState> {
-    /**
-     * The state of the aggregate at the time of the snapshot.
-     */
-    state: TState;
-    /**
-     * The version of the aggregate when the snapshot was taken.
-     */
-    version: Version;
-    /**
-     * Timestamp when the snapshot was created.
-     */
-    snapshotAt: Date;
-}
+declare function replaceEntityById<TId, T extends Identifiable<TId>>(entities: T[], id: TId, replacement: T): T[];
 /**
- * Checks if two aggregates are the same (same ID and version).
- * Useful for optimistic concurrency control checks.
+ * Extracts all IDs from a collection of entities.
  *
- * @param a - First aggregate
- * @param b - Second aggregate
- * @returns true if both aggregates have the same ID and version
+ * @param entities - Array of entities
+ * @returns Array of entity IDs
  *
  * @example
  * ```typescript
- * const aggregate1 = await repository.getById(id);
- * // ... some operations ...
- * const aggregate2 = await repository.getById(id);
+ * const items: OrderItem[] = [
+ *   { id: itemId1, productId: "prod-1", quantity: 2 },
+ *   { id: itemId2, productId: "prod-2", quantity: 1 }
+ * ];
  *
- * if (!sameAggregate(aggregate1, aggregate2)) {
- *   throw new Error("Aggregate was modified by another process");
- * }
+ * const ids = entityIds(items);
+ * // ids is [itemId1, itemId2]
  * ```
  */
-declare function sameAggregate<TId extends Id<string>>(a: {
-    id: TId;
-    version: Version;
-}, b: {
-    id: TId;
-    version: Version;
-}): boolean;
+declare function entityIds<TId, T extends Identifiable<TId>>(entities: T[]): TId[];
 
 /**
- * Configuration options for AggregateBase behavior.
+ * Marker interface for Aggregate Roots.
+ *
+ * In Domain-Driven Design, an Aggregate Root is an Entity (the parent Entity of the aggregate).
+ * It represents the aggregate externally and is the only object that external code
+ * is allowed to hold references to. All access to child entities within the aggregate
+ * must go through the Aggregate Root.
+ *
+ * An Aggregate consists of:
+ * - One Aggregate Root (Entity with id + version)
+ * - Optional child entities (Entities with id, but no own version)
+ * - Optional value objects
+ *
+ * The Aggregate Root has identity (id) and version for optimistic concurrency control.
+ * Child entities exist only within the aggregate boundary and are versioned through
+ * the Aggregate Root.
+ *
+ * @template TId - The type of the aggregate root identifier
+ *
+ * @example
+ * ```typescript
+ * class Order extends AggregateRoot<OrderState, OrderId> implements IAggregateRoot<OrderId> {
+ *   // Order is an Aggregate Root (an Entity)
+ *   // OrderState contains child entities (e.g., OrderItem) and value objects
+ * }
+ * ```
+ */
+interface IAggregateRoot<TId extends Id<string>> extends Identifiable<TId> {
+    /**
+     * Unique identifier of the aggregate root entity.
+     */
+    readonly id: TId;
+    /**
+     * Version number for optimistic concurrency control.
+     * Incremented on each state change to detect concurrent modifications.
+     * This version applies to the entire aggregate, including all child entities.
+     */
+    readonly version: Version;
+}
+/**
+ * Configuration options for AggregateRoot behavior.
  */
 interface AggregateConfig {
     /**
@@ -285,7 +271,7 @@ interface AggregateConfig {
  * - State management (containing child entities and value objects)
  * - Snapshot support for performance optimization
  *
- * Implements `AggregateRoot<TId>` to mark this as an Aggregate Root Entity.
+ * 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.
@@ -296,7 +282,7 @@ interface AggregateConfig {
  * @example
  * ```typescript
  * // Order is an Aggregate Root (an Entity)
- * class Order extends AggregateBase<OrderState, OrderId> implements AggregateRoot<OrderId> {
+ * class Order extends AggregateRoot<OrderState, OrderId> {
  *   constructor(id: OrderId, initialState: OrderState) {
  *     super(id, initialState);
  *   }
@@ -308,18 +294,45 @@ interface AggregateConfig {
  * }
  * ```
  */
-declare abstract class AggregateBase<TState, TId extends Id<string>> implements AggregateRoot<TId> {
+declare abstract class AggregateRoot<TState, TId extends Id<string>> implements IAggregateRoot<TId> {
     readonly id: TId;
     version: Version;
     private readonly _config;
     private readonly _autoVersionBump;
+    private _domainEvents;
     get state(): TState;
+    /**
+     * Returns a read-only list of domain events recorded by this aggregate.
+     * These events are side-effects of state changes.
+     */
+    get domainEvents(): ReadonlyArray<unknown>;
+    /**
+     * Clears the list of recorded domain events.
+     * Call this after dispatching the events.
+     */
+    clearDomainEvents(): void;
     /**
      * The state is 'protected' so that only the subclass can change it.
      * Subclasses can mutate this directly or use helper methods.
      */
     protected _state: TState;
     protected constructor(id: TId, initialState: TState, config?: AggregateConfig);
+    /**
+     * Optional validation hook to ensure state invariants.
+     * Called during construction, setState, and snapshot restoration.
+     * Override this method to implement validation logic.
+     *
+     * @param state - The state to validate
+     * @throws Error if validation fails
+     */
+    protected validateState(_state: TState): void;
+    /**
+     * Adds a domain event to the aggregate's list of changes.
+     * Use this to record side-effects that should be published.
+     *
+     * @param event - The domain event to add
+     */
+    protected addDomainEvent(event: unknown): void;
     /**
      * Manually bumps the aggregate version.
      * Call this after state changes for Optimistic Concurrency Control.
@@ -331,6 +344,7 @@ declare abstract class AggregateBase<TState, TId extends Id<string>> implements
     /**
      * Sets the state and optionally bumps the version automatically.
      * This is a convenience method for state mutations.
+     * Automatically validates the newState using `validateState()`.
      *
      * @param newState - The new state
      * @param bumpVersion - Whether to bump the version (defaults to autoVersionBump config)
@@ -353,6 +367,7 @@ declare abstract class AggregateBase<TState, TId extends Id<string>> implements
      * Restores the aggregate from a snapshot.
      * This is useful for loading aggregates from snapshots instead of
      * rebuilding them from scratch.
+     * Validates the restored state.
      *
      * @param snapshot - The snapshot to restore from
      *
@@ -365,6 +380,41 @@ declare abstract class AggregateBase<TState, TId extends Id<string>> implements
     restoreFromSnapshot(snapshot: AggregateSnapshot<TState>): void;
 }
 
+/**
+ * Interface for Event-Sourced Aggregate Roots.
+ * Defines the contract for aggregates that manage state changes via event sourcing.
+ *
+ * @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> {
+    /**
+     * Returns a read-only list of new, not-yet-persisted events.
+     */
+    readonly pendingEvents: ReadonlyArray<TEvent>;
+    /**
+     * Reconstitutes the aggregate from an event history.
+     *
+     * @param history - An ordered list of past events
+     */
+    loadFromHistory(history: TEvent[]): Result<void, string>;
+    /**
+     * Clears the list of pending events.
+     */
+    clearPendingEvents(): void;
+    /**
+     * Checks if the aggregate has any pending events.
+     */
+    hasPendingEvents(): boolean;
+    /**
+     * Returns the number of pending events.
+     */
+    getEventCount(): number;
+    /**
+     * Returns the latest pending event, if any.
+     */
+    getLatestEvent(): TEvent | undefined;
+}
 type Handler<TState, TEvent> = (state: TState, event: TEvent) => TState;
 /**
  * Extended configuration options for AggregateEventSourced behavior.
@@ -379,7 +429,7 @@ interface AggregateEventSourcedConfig extends AggregateConfig {
 /**
  * Base class for Event-Sourced Aggregate Roots (Entities).
  *
- * Extends `AggregateBase` to create an Aggregate Root Entity with Event Sourcing capabilities.
+ * 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.
  *
  * The aggregate state (`TState`) contains:
@@ -389,7 +439,7 @@ interface AggregateEventSourcedConfig extends AggregateConfig {
  * All changes to child entities are versioned through the Aggregate Root. The version
  * applies to the entire aggregate, including all child entities.
  *
- * Extends `AggregateBase` with Event Sourcing capabilities:
+ * Extends `AggregateRoot` with Event Sourcing capabilities:
  * - Event tracking (pendingEvents)
  * - Event handlers for state transitions
  * - Event validation
@@ -419,10 +469,9 @@ interface AggregateEventSourcedConfig extends AggregateConfig {
  * }
  * ```
  */
-declare abstract class AggregateEventSourced<TState, TEvent extends DomainEvent<string, unknown>, TId extends Id<string>> extends AggregateBase<TState, TId> {
+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;
-    private readonly _pendingEvents;
     protected constructor(id: TId, initialState: TState, config?: AggregateEventSourcedConfig);
     /**
      * Returns a read-only list of new, not-yet-persisted events.
@@ -499,36 +548,246 @@ declare abstract class AggregateEventSourced<TState, TEvent extends DomainEvent<
      */
     getEventCount(): number;
     /**
-     * Returns the latest pending event, if any.
-     *
-     * @returns The most recent event or undefined if no events exist
+     * Returns the latest pending event, if any.
+     *
+     * @returns The most recent event or undefined if no events exist
+     */
+    getLatestEvent(): TEvent | undefined;
+    /**
+     * 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);
+     * ```
+     */
+    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: TEvent[]): Result<void, string>;
+    /**
+     * A map of event types to their corresponding handlers.
+     * Subclasses MUST implement this property.
+     */
+    protected abstract readonly handlers: {
+        [K in TEvent["type"]]: Handler<TState, Extract<TEvent, {
+            type: K;
+        }>>;
+    };
+}
+
+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.
+ *
+ * @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.
+ *
+ * @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>> {
+    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
+ *
+ * @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.
+ *
+ * @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" }
+ * );
+ * ```
+ */
+declare function mergeMetadata(...metadataObjects: Array<EventMetadata | undefined>): EventMetadata;
+/**
+ * Snapshot of an aggregate state at a specific point in time.
+ * Used for optimizing event replay by starting from a snapshot
+ * instead of replaying all events from the beginning.
+ *
+ * @template TState - The type of the aggregate state
+ */
+interface AggregateSnapshot<TState> {
+    /**
+     * The state of the aggregate at the time of the snapshot.
      */
-    getLatestEvent(): TEvent | undefined;
+    state: 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);
-     * ```
+     * The version of the aggregate when the snapshot was taken.
      */
-    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: TEvent[]): Result<void, string>;
+    version: Version;
     /**
-     * A map of event types to their corresponding handlers.
-     * Subclasses MUST implement this property.
+     * Timestamp when the snapshot was created.
      */
-    protected abstract readonly handlers: {
-        [K in TEvent["type"]]: Handler<TState, Extract<TEvent, {
-            type: K;
-        }>>;
-    };
+    snapshotAt: Date;
 }
+/**
+ * Checks if two aggregates are the same (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
+ *
+ * @example
+ * ```typescript
+ * const aggregate1 = await repository.getById(id);
+ * // ... some operations ...
+ * const aggregate2 = await repository.getById(id);
+ *
+ * if (!sameAggregate(aggregate1, aggregate2)) {
+ *   throw new Error("Aggregate was modified by another process");
+ * }
+ * ```
+ */
+declare function sameAggregate<TId extends Id<string>>(a: {
+    id: TId;
+    version: Version;
+}, b: {
+    id: TId;
+    version: Version;
+}): boolean;
 
 /**
  * Marker interface for Commands.
@@ -959,207 +1218,6 @@ declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQue
  */
 declare function guard(cond: boolean, error: string): Result<true, string>;
 
-/**
- * Interface for entities with identity.
- *
- * In Domain-Driven Design, there are two types of entities:
- *
- * 1. **Aggregate Root Entity**: The parent Entity of an aggregate.
- *    - Has identity (id) and version
- *    - Implemented by classes extending `AggregateBase` or `AggregateEventSourced`
- *    - Represents the aggregate externally
- *    - Loaded/saved through repositories
- *
- * 2. **Child Entities**: Entities within an aggregate.
- *    - Have identity (id), but no own version
- *    - Exist only within the aggregate boundary
- *    - Versioned through the Aggregate Root
- *    - Cannot be referenced directly from outside the aggregate
- *
- * This interface is used for child entities within aggregates. The Aggregate Root
- * also implements this interface (through `AggregateRoot<TId>`), but additionally
- * has version management.
- *
- * @template TId - The type of the entity identifier
- *
- * @example
- * ```typescript
- * // Child Entity within an aggregate
- * type OrderItem = Entity<ItemId> & {
- *   productId: string;
- *   quantity: number;
- * };
- *
- * // Aggregate Root (also an Entity, but with version)
- * class Order extends AggregateBase<OrderState, OrderId>
- *   implements AggregateRoot<OrderId> {
- *   // Order is an Entity (the Aggregate Root)
- *   // OrderState contains OrderItem (child entities)
- * }
- * ```
- */
-interface Entity<TId> {
-    readonly id: TId;
-}
-/**
- * Checks if two entities have the same ID.
- * Works with any object that has an 'id' property.
- *
- * @param a - First entity
- * @param b - Second entity
- * @returns true if both entities have the same ID, false otherwise
- *
- * @example
- * ```typescript
- * const item1: OrderItem = { id: itemId1, productId: "prod-1", quantity: 2 };
- * const item2: OrderItem = { id: itemId2, productId: "prod-2", quantity: 1 };
- *
- * sameEntity(item1, item2); // false
- * sameEntity(item1, item1); // true
- * ```
- */
-declare function sameEntity<TId>(a: {
-    id: TId;
-}, b: {
-    id: TId;
-}): boolean;
-/**
- * Finds an entity by ID in a collection.
- * Returns undefined if not found.
- *
- * @param entities - Array of entities to search
- * @param id - The ID to search for
- * @returns The entity if found, undefined otherwise
- *
- * @example
- * ```typescript
- * const items: OrderItem[] = [
- *   { id: itemId1, productId: "prod-1", quantity: 2 },
- *   { id: itemId2, productId: "prod-2", quantity: 1 }
- * ];
- *
- * const item = findEntityById(items, itemId1);
- * // item is { id: itemId1, productId: "prod-1", quantity: 2 }
- * ```
- */
-declare function findEntityById<TId, T extends {
-    id: TId;
-}>(entities: T[], id: TId): T | undefined;
-/**
- * Checks if an entity with the given ID exists in the collection.
- *
- * @param entities - Array of entities to search
- * @param id - The ID to check for
- * @returns true if an entity with the ID exists, false otherwise
- *
- * @example
- * ```typescript
- * const items: OrderItem[] = [
- *   { id: itemId1, productId: "prod-1", quantity: 2 }
- * ];
- *
- * hasEntityId(items, itemId1); // true
- * hasEntityId(items, itemId2); // false
- * ```
- */
-declare function hasEntityId<TId, T extends {
-    id: TId;
-}>(entities: T[], id: TId): boolean;
-/**
- * Removes an entity with the given ID from the collection.
- * Returns a new array without the entity.
- *
- * @param entities - Array of entities
- * @param id - The ID of the entity to remove
- * @returns A new array without the entity with the given ID
- *
- * @example
- * ```typescript
- * const items: OrderItem[] = [
- *   { id: itemId1, productId: "prod-1", quantity: 2 },
- *   { id: itemId2, productId: "prod-2", quantity: 1 }
- * ];
- *
- * const updated = removeEntityById(items, itemId1);
- * // updated is [{ id: itemId2, productId: "prod-2", quantity: 1 }]
- * ```
- */
-declare function removeEntityById<TId, T extends {
-    id: TId;
-}>(entities: T[], id: TId): T[];
-/**
- * Updates an entity with the given ID in the collection.
- * Returns a new array with the updated entity.
- * If the entity is not found, returns the original array unchanged.
- *
- * @param entities - Array of entities
- * @param id - The ID of the entity to update
- * @param updater - Function that takes the entity and returns the updated entity
- * @returns A new array with the updated entity
- *
- * @example
- * ```typescript
- * const items: OrderItem[] = [
- *   { id: itemId1, productId: "prod-1", quantity: 2 }
- * ];
- *
- * const updated = updateEntityById(items, itemId1, (item) => ({
- *   ...item,
- *   quantity: item.quantity + 1
- * }));
- * // updated is [{ id: itemId1, productId: "prod-1", quantity: 3 }]
- * ```
- */
-declare function updateEntityById<TId, T extends {
-    id: TId;
-}>(entities: T[], id: TId, updater: (entity: T) => T): T[];
-/**
- * Replaces an entity with the given ID in the collection.
- * Returns a new array with the replaced entity.
- * If the entity is not found, returns the original array unchanged.
- *
- * @param entities - Array of entities
- * @param id - The ID of the entity to replace
- * @param replacement - The replacement entity
- * @returns A new array with the replaced entity
- *
- * @example
- * ```typescript
- * const items: OrderItem[] = [
- *   { id: itemId1, productId: "prod-1", quantity: 2 }
- * ];
- *
- * const updated = replaceEntityById(items, itemId1, {
- *   id: itemId1,
- *   productId: "prod-1",
- *   quantity: 5
- * });
- * ```
- */
-declare function replaceEntityById<TId, T extends {
-    id: TId;
-}>(entities: T[], id: TId, replacement: T): T[];
-/**
- * Extracts all IDs from a collection of entities.
- *
- * @param entities - Array of entities
- * @returns Array of entity IDs
- *
- * @example
- * ```typescript
- * const items: OrderItem[] = [
- *   { id: itemId1, productId: "prod-1", quantity: 2 },
- *   { id: itemId2, productId: "prod-2", quantity: 1 }
- * ];
- *
- * const ids = entityIds(items);
- * // ids is [itemId1, itemId2]
- * ```
- */
-declare function entityIds<TId, T extends {
-    id: TId;
-}>(entities: T[]): TId[];
-
 /**
  * Simple in-memory event bus implementation.
  * Supports multiple subscribers per event type (pub/sub pattern).
@@ -1215,7 +1273,7 @@ interface ISpecification<T> {
  * @template TAgg - The aggregate root type (must be an Aggregate Root Entity)
  * @template TId - The type of the aggregate root identifier
  */
-interface IRepository<TState, TEvent extends DomainEvent<string, unknown>, TAgg extends AggregateRoot<TId> & Aggregate<TState, TEvent>, TId extends Id<string>> {
+interface IRepository<TState, TEvent extends DomainEvent<string, unknown>, TAgg extends IAggregateRoot<TId> & Aggregate<TState, TEvent>, TId extends Id<string>> {
     getById(id: TId): Promise<TAgg | null>;
     findOne(spec: ISpecification<TAgg>): Promise<TAgg | null>;
     find(spec: ISpecification<TAgg>): Promise<TAgg[]>;
@@ -1364,13 +1422,46 @@ declare function voWithValidation<T>(t: T, validate: (value: T) => boolean, erro
  */
 declare function voWithValidationUnsafe<T>(t: T, validate: (value: T) => boolean, errorMessage?: string): VO<T>;
 
+/**
+ * Interface for Value Objects.
+ * Value Objects are immutable and defined by their properties.
+ *
+ * @template T - The shape of the value object's properties
+ */
+interface IValueObject<T extends object> {
+    /**
+     * The immutable properties of the value object.
+     */
+    readonly props: Readonly<T>;
+    /**
+     * Checks if this value object is equal to another.
+     * Uses deep equality comparison on the properties.
+     *
+     * @param other - The other value object to compare
+     * @returns true if the properties are deeply equal
+     */
+    equals(other: IValueObject<T>): boolean;
+    /**
+     * Creates a clone of the value object with optional property overrides.
+     *
+     * @param props - Optional properties to override
+     * @returns A new instance of the value object
+     */
+    clone(props?: Partial<T>): IValueObject<T>;
+    /**
+     * Serializes the value object to its raw properties for JSON operations.
+     *
+     * @returns The raw properties object
+     */
+    toJSON(): Readonly<T>;
+}
 /**
  * Abstract base class for creating Value Objects.
  * Value Objects are immutable and defined by their properties.
  *
  * @template T - The shape of the value object's properties
  */
-declare abstract class ValueObject<T extends object> {
+declare abstract class ValueObject<T extends object> implements IValueObject<T> {
     readonly props: Readonly<T>;
     /**
      * Creates a new ValueObject.
@@ -1383,18 +1474,43 @@ declare abstract class ValueObject<T extends object> {
      *   constructor(props: { amount: number; currency: string }) {
      *     super(props);
      *   }
+     *
+     *   protected validate(props: { amount: number; currency: string }): void {
+     *     if (props.amount < 0) throw new Error("Amount cannot be negative");
+     *   }
      * }
      * ```
      */
     constructor(props: T);
+    /**
+     * Optional validation hook that can be overridden by subclasses.
+     * Should throw an error if validation fails.
+     *
+     * @param props - The properties to validate
+     * @throws Error if validation fails
+     */
+    protected validate(props: T): void;
     /**
      * Checks if this value object is equal to another.
-     * Uses deep equality comparison on the properties.
+     * Uses deep equality comparison on the properties and checks for constructor equality.
      *
      * @param other - The other value object to compare
-     * @returns true if the properties are deeply equal
+     * @returns true if the properties are deeply equal and constructors match
      */
     equals(other: ValueObject<T>): boolean;
+    /**
+     * Creates a clone of the value object with optional property overrides.
+     *
+     * @param props - Optional properties to override
+     * @returns A new instance of the value object
+     */
+    clone(props?: Partial<T>): this;
+    /**
+     * Serializes the value object to its raw properties for JSON operations.
+     *
+     * @returns The raw properties object
+     */
+    toJSON(): Readonly<T>;
 }
 
-export { type Aggregate, AggregateBase, type AggregateConfig, AggregateEventSourced, type AggregateEventSourcedConfig, type AggregateRoot, type AggregateSnapshot, type Clock, type Command, CommandBus, type CommandHandler, type DomainEvent, type Entity, type EventBus, EventBusImpl, type EventHandler, type EventMetadata, type ICommandBus, type IQueryBus, type IRepository, type ISpecification, type Id, type IdGenerator, 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 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 };