@shirudo/ddd-kit 0.9.8 → 0.10.0

package/dist/index.d.ts

@@ -0,0 +1,1400 @@
+import { R as Result } from './result-jCwPSjFa.js';
+import { a as DeepEqualExceptOptions } from './deep-equal-except-C8yoSk4L.js';
+
+type Id<Tag extends string> = string & {
+    readonly __brand: Tag;
+};
+interface IdGenerator {
+    next: <T extends string>() => Id<T>;
+}
+
+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;
+}
+/**
+ * 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 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.
+ *
+ * @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.
+     */
+    state: TState;
+    /**
+     * The version of the aggregate when the snapshot was taken.
+     */
+    version: Version;
+    /**
+     * Timestamp when the snapshot was created.
+     */
+    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;
+
+/**
+ * Configuration options for AggregateBase behavior.
+ */
+interface AggregateConfig {
+    /**
+     * Whether to automatically bump the version when state changes.
+     * Defaults to false. Set to true for automatic versioning.
+     */
+    autoVersionBump?: boolean;
+}
+/**
+ * Base class for creating Aggregate Roots (Entities) 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) and version for optimistic concurrency control.
+ *
+ * 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.
+ *
+ * Provides core functionality:
+ * - ID and Version management (for Optimistic Concurrency Control)
+ * - State management (containing child entities and value objects)
+ * - Snapshot support for performance optimization
+ *
+ * Implements `AggregateRoot<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.
+ *
+ * @template TState - The type of the aggregate state (contains child entities and value objects)
+ * @template TId - The type of the aggregate root identifier
+ *
+ * @example
+ * ```typescript
+ * // Order is an Aggregate Root (an Entity)
+ * class Order extends AggregateBase<OrderState, OrderId> implements AggregateRoot<OrderId> {
+ *   constructor(id: OrderId, initialState: OrderState) {
+ *     super(id, initialState);
+ *   }
+ *
+ *   confirm(): void {
+ *     this._state = { ...this._state, status: "confirmed" };
+ *     this.bumpVersion(); // Versions the entire aggregate
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AggregateBase<TState, TId extends Id<string>> implements AggregateRoot<TId> {
+    readonly id: TId;
+    version: Version;
+    private readonly _config;
+    private readonly _autoVersionBump;
+    get state(): TState;
+    /**
+     * 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);
+    /**
+     * Manually bumps the aggregate version.
+     * Call this after state changes for Optimistic Concurrency Control.
+     *
+     * If `autoVersionBump` is enabled, this is called automatically
+     * when using `setState()`.
+     */
+    protected bumpVersion(): void;
+    /**
+     * Sets the state and optionally bumps the version automatically.
+     * This is a convenience method for state mutations.
+     *
+     * @param newState - The new state
+     * @param bumpVersion - Whether to bump the version (defaults to autoVersionBump config)
+     */
+    protected setState(newState: TState, bumpVersion?: boolean): void;
+    /**
+     * Creates a snapshot of the current aggregate state.
+     * Useful for performance optimization, backup/restore, and audit trails.
+     *
+     * @returns A snapshot containing the current state and version
+     *
+     * @example
+     * ```typescript
+     * const snapshot = aggregate.createSnapshot();
+     * await snapshotRepository.save(aggregate.id, snapshot);
+     * ```
+     */
+    createSnapshot(): AggregateSnapshot<TState>;
+    /**
+     * Restores the aggregate from a snapshot.
+     * This is useful for loading aggregates from snapshots instead of
+     * rebuilding them from scratch.
+     *
+     * @param snapshot - The snapshot to restore from
+     *
+     * @example
+     * ```typescript
+     * const snapshot = await snapshotRepository.getLatest(aggregateId);
+     * aggregate.restoreFromSnapshot(snapshot);
+     * ```
+     */
+    restoreFromSnapshot(snapshot: AggregateSnapshot<TState>): void;
+}
+
+type Handler<TState, TEvent> = (state: TState, event: TEvent) => TState;
+/**
+ * Extended configuration options for AggregateEventSourced behavior.
+ */
+interface AggregateEventSourcedConfig extends AggregateConfig {
+    /**
+     * Whether to automatically bump the version when applying new events.
+     * Defaults to true. Set to false to manually control versioning.
+     */
+    autoVersionBump?: boolean;
+}
+/**
+ * Base class for Event-Sourced Aggregate Roots (Entities).
+ *
+ * Extends `AggregateBase` 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:
+ * - 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 `AggregateBase` 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.
+ *
+ * @template TState - The type of the aggregate state (contains child entities and value objects)
+ * @template TEvent - The union type of all domain events
+ * @template TId - The type of the aggregate root identifier
+ *
+ * @example
+ * ```typescript
+ * // Order is an Aggregate Root (an Entity) with Event Sourcing
+ * class Order extends AggregateEventSourced<OrderState, OrderEvent, OrderId> {
+ *   confirm(): void {
+ *     this.apply(createDomainEvent("OrderConfirmed", {}));
+ *   }
+ *
+ *   protected readonly handlers = {
+ *     OrderConfirmed: (state: OrderState): OrderState => ({
+ *       ...state,
+ *       status: "confirmed",
+ *     }),
+ *   };
+ * }
+ * ```
+ */
+declare abstract class AggregateEventSourced<TState, TEvent extends DomainEvent<string, unknown>, TId extends Id<string>> extends AggregateBase<TState, TId> {
+    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.
+     */
+    get pendingEvents(): ReadonlyArray<TEvent>;
+    /**
+     * Clears the list of pending events.
+     * Typically called after the events have been persisted.
+     */
+    clearPendingEvents(): void;
+    /**
+     * 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.
+     * 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
+     */
+    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.
+     * 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;
+    /**
+     * Manually bumps the aggregate version.
+     * Only needed if `autoVersionBump` is disabled.
+     */
+    protected bumpVersion(): void;
+    /**
+     * 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;
+    /**
+     * 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;
+        }>>;
+    };
+}
+
+/**
+ * Marker interface for Commands.
+ * Commands represent write operations that change system state.
+ * They should be immutable and contain all data needed to perform the operation.
+ *
+ * This interface can be used as a type marker even when using external frameworks
+ * (e.g., RabbitMQ, AWS SQS) to ensure type safety across different bus implementations.
+ *
+ * @example
+ * ```typescript
+ * type CreateOrderCommand = Command & {
+ *   type: "CreateOrder";
+ *   customerId: string;
+ *   items: OrderItem[];
+ * };
+ * ```
+ *
+ * @example Using with external frameworks (RabbitMQ, etc.)
+ * ```typescript
+ * // Define command using Command marker
+ * type CreateOrderCommand = Command & {
+ *   type: "CreateOrder";
+ *   customerId: string;
+ * };
+ *
+ * // Handler can be typed with CommandHandler even for external frameworks
+ * const handler: CommandHandler<CreateOrderCommand, OrderId> = async (cmd) => {
+ *   // ... handler logic
+ *   return ok(orderId);
+ * };
+ *
+ * // Register with RabbitMQ or other external bus
+ * rabbitMQChannel.consume("order.commands", async (message) => {
+ *   const command = JSON.parse(message.content) as CreateOrderCommand;
+ *   const result = await handler(command);
+ *   // ... handle result
+ * });
+ * ```
+ */
+interface Command {
+    readonly type: string;
+}
+/**
+ * Handler for executing commands.
+ * Commands return Result for explicit error handling.
+ * Commands may modify system state and should be idempotent when possible.
+ *
+ * This type can be used to mark handlers even when using external frameworks
+ * (e.g., RabbitMQ, AWS SQS, Kafka) to ensure type safety and consistency.
+ *
+ * @template C - The command type (must extend Command)
+ * @template R - The result type
+ *
+ * @example
+ * ```typescript
+ * const handler: CommandHandler<CreateOrderCommand, OrderId> = async (cmd) => {
+ *   const order = Order.create(cmd.customerId, cmd.items);
+ *   await repository.save(order);
+ *   return ok(order.id);
+ * };
+ * ```
+ *
+ * @example Using with external frameworks
+ * ```typescript
+ * // Handler typed with CommandHandler for type safety
+ * const createOrderHandler: CommandHandler<CreateOrderCommand, OrderId> = async (cmd) => {
+ *   // ... handler logic
+ *   return ok(orderId);
+ * };
+ *
+ * // Can be used with any external bus/framework
+ * // RabbitMQ example:
+ * rabbitMQChannel.consume("commands", async (msg) => {
+ *   const command = JSON.parse(msg.content) as CreateOrderCommand;
+ *   const result = await createOrderHandler(command);
+ *   // ... handle result
+ * });
+ *
+ * // AWS SQS example:
+ * sqs.receiveMessage({ QueueUrl: "..." }, async (err, data) => {
+ *   const command = JSON.parse(data.Messages[0].Body) as CreateOrderCommand;
+ *   const result = await createOrderHandler(command);
+ *   // ... handle result
+ * });
+ * ```
+ */
+type CommandHandler<C extends Command, R> = (cmd: C) => Promise<Result<R, string>>;
+
+/**
+ * Command Bus interface for dispatching commands to their handlers.
+ * Provides a centralized way to execute commands with handler registration.
+ *
+ * @example
+ * ```typescript
+ * const bus = new CommandBus();
+ * bus.register("CreateOrder", createOrderHandler);
+ *
+ * const result = await bus.execute({
+ *   type: "CreateOrder",
+ *   customerId: "123",
+ *   items: [...]
+ * });
+ * ```
+ */
+interface ICommandBus {
+    /**
+     * Executes a command by dispatching it to the registered handler.
+     *
+     * @param command - The command to execute
+     * @returns Result containing the success value or error message
+     */
+    execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
+    /**
+     * Registers a handler for a specific command type.
+     *
+     * @param commandType - The command type to register the handler for
+     * @param handler - The handler function for this command type
+     */
+    register<C extends Command, R>(commandType: C["type"], handler: CommandHandler<C, R>): void;
+}
+/**
+ * Simple in-memory command bus implementation.
+ * Handlers are stored in a Map and dispatched based on command type.
+ *
+ * **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)
+ * - Error handling and retry logic
+ * - Timeout handling
+ * - Metrics and observability
+ * - Transaction management
+ * - Dead letter queue support
+ *
+ * The `CommandHandler` type can still be used with external production-grade buses
+ * (e.g., RabbitMQ, AWS SQS) while maintaining type safety.
+ *
+ * @example
+ * ```typescript
+ * const bus = new CommandBus();
+ * bus.register("CreateOrder", async (cmd) => {
+ *   // ... handler logic
+ *   return ok(orderId);
+ * });
+ *
+ * const result = await bus.execute({ type: "CreateOrder", ... });
+ * ```
+ */
+declare class CommandBus implements ICommandBus {
+    private readonly handlers;
+    register<C extends Command, R>(commandType: C["type"], handler: CommandHandler<C, R>): void;
+    execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
+}
+
+/**
+ * Event handler function type for subscribing to domain events.
+ *
+ * @template Evt - The type of domain event
+ */
+type EventHandler<Evt> = (event: Evt) => Promise<void> | void;
+/**
+ * Event Bus interface for publishing and subscribing to domain events.
+ * Supports multiple subscribers per event type (pub/sub pattern).
+ *
+ * @template Evt - The type of domain events
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus<OrderEvent>();
+ *
+ * // Subscribe to specific event types
+ * bus.subscribe("OrderCreated", async (event) => {
+ *   await sendEmail(event.payload.customerId);
+ * });
+ *
+ * bus.subscribe("OrderShipped", async (event) => {
+ *   await updateInventory(event.payload.orderId);
+ * });
+ *
+ * // Publish events
+ * await bus.publish([orderCreatedEvent, orderShippedEvent]);
+ * ```
+ */
+interface EventBus<Evt> {
+    /**
+     * Publishes events to all subscribed handlers.
+     * All handlers for each event type will be called.
+     *
+     * @param events - Array of events to publish
+     */
+    publish: (events: ReadonlyArray<Evt>) => Promise<void>;
+    /**
+     * Subscribes a handler to a specific event type.
+     * Multiple handlers can subscribe to the same event type.
+     *
+     * @param eventType - The event type to subscribe to
+     * @param handler - The handler function to call when events of this type are published
+     * @returns A function to unsubscribe the handler
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = bus.subscribe("OrderCreated", async (event) => {
+     *   console.log("Order created:", event.payload.orderId);
+     * });
+     *
+     * // Later: unsubscribe
+     * unsubscribe();
+     * ```
+     */
+    subscribe: <T extends Evt>(eventType: string, handler: EventHandler<T>) => () => void;
+}
+interface Outbox<Evt> {
+    add: (events: ReadonlyArray<Evt>) => Promise<void>;
+}
+interface Clock {
+    now: () => Date;
+}
+
+interface UnitOfWork {
+    transactional<T>(fn: () => Promise<T>): Promise<T>;
+}
+type RepoProvider<R> = (uow: UnitOfWork) => R;
+
+/**
+ * Helper function for executing commands within a transaction.
+ * Handles event persistence via outbox and optional event bus publishing.
+ *
+ * @param deps - Dependencies including outbox, optional event bus, and unit of work
+ * @param fn - Function that returns result and events
+ * @returns The result wrapped in a transaction
+ *
+ * @example
+ * ```typescript
+ * const result = await withCommit(
+ *   { outbox, bus, uow },
+ *   async () => {
+ *     const order = Order.create(customerId, items);
+ *     await repository.save(order);
+ *     return {
+ *       result: order.id,
+ *       events: order.pendingEvents
+ *     };
+ *   }
+ * );
+ * ```
+ */
+declare function withCommit<Evt, R>(deps: {
+    outbox: Outbox<Evt>;
+    bus?: EventBus<Evt>;
+    uow: UnitOfWork;
+}, fn: () => Promise<{
+    result: R;
+    events: ReadonlyArray<Evt>;
+}>): Promise<R>;
+
+/**
+ * Marker interface for Queries.
+ * Queries represent read operations that don't change system state.
+ * They should be immutable and contain all data needed to perform the read.
+ *
+ * This interface can be used as a type marker even when using external frameworks
+ * (e.g., RabbitMQ, AWS SQS) to ensure type safety across different bus implementations.
+ *
+ * @example
+ * ```typescript
+ * type GetOrderQuery = Query & {
+ *   type: "GetOrder";
+ *   orderId: OrderId;
+ * };
+ * ```
+ *
+ * @example Using with external frameworks
+ * ```typescript
+ * type GetOrderQuery = Query & {
+ *   type: "GetOrder";
+ *   orderId: OrderId;
+ * };
+ *
+ * // Handler typed with QueryHandler for type safety
+ * const handler: QueryHandler<GetOrderQuery, Order | null> = async (query) => {
+ *   return await repository.getById(query.orderId);
+ * };
+ *
+ * // Can be used with any external framework
+ * rabbitMQChannel.consume("queries", async (message) => {
+ *   const query = JSON.parse(message.content) as GetOrderQuery;
+ *   const result = await handler(query);
+ *   // ... handle result
+ * });
+ * ```
+ */
+interface Query {
+    readonly type: string;
+}
+/**
+ * Handler for executing queries.
+ * Queries return data directly (no Result type) as read operations
+ * are not expected to fail in normal circumstances.
+ * Queries should not modify system state and can be cached.
+ *
+ * This type can be used to mark handlers even when using external frameworks
+ * (e.g., RabbitMQ, AWS SQS, Kafka) to ensure type safety and consistency.
+ *
+ * @template Q - The query type (must extend Query)
+ * @template R - The result type
+ *
+ * @example
+ * ```typescript
+ * const handler: QueryHandler<GetOrderQuery, Order | null> = async (query) => {
+ *   return await repository.getById(query.orderId);
+ * };
+ * ```
+ *
+ * @example Using with external frameworks
+ * ```typescript
+ * // Handler typed with QueryHandler for type safety
+ * const getOrderHandler: QueryHandler<GetOrderQuery, Order | null> = async (query) => {
+ *   return await repository.getById(query.orderId);
+ * };
+ *
+ * // Can be used with any external bus/framework
+ * rabbitMQChannel.consume("queries", async (msg) => {
+ *   const query = JSON.parse(msg.content) as GetOrderQuery;
+ *   const result = await getOrderHandler(query);
+ *   // ... handle result
+ * });
+ * ```
+ */
+type QueryHandler<Q extends Query, R> = (query: Q) => Promise<R>;
+
+/**
+ * Query Bus interface for dispatching queries to their handlers.
+ * Provides a centralized way to execute queries with handler registration.
+ *
+ * @example
+ * ```typescript
+ * const bus = new QueryBus();
+ * bus.register("GetOrder", getOrderHandler);
+ *
+ * const order = await bus.execute({
+ *   type: "GetOrder",
+ *   orderId: "123"
+ * });
+ * ```
+ */
+interface IQueryBus {
+    /**
+     * Executes a query by dispatching it to the registered handler.
+     * Returns a Result type instead of throwing an error.
+     *
+     * @param query - The query to execute
+     * @returns Result containing the query result if successful, or an error message if no handler is registered
+     */
+    execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
+    /**
+     * Executes a query by dispatching it to the registered handler.
+     * Throws an error if no handler is registered.
+     *
+     * @param query - The query to execute
+     * @returns The query result
+     * @throws Error if no handler is registered for the query type
+     */
+    executeUnsafe<Q extends Query, R>(query: Q): Promise<R>;
+    /**
+     * Registers a handler for a specific query type.
+     *
+     * @param queryType - The query type to register the handler for
+     * @param handler - The handler function for this query type
+     */
+    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.
+ *
+ * **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)
+ * - Error handling
+ * - Timeout handling
+ * - Metrics and observability
+ * - Query result caching
+ * - Rate limiting
+ *
+ * The `QueryHandler` type can still be used with external production-grade buses
+ * (e.g., RabbitMQ, AWS SQS) while maintaining type safety.
+ *
+ * @example
+ * ```typescript
+ * const bus = new QueryBus();
+ * bus.register("GetOrder", async (query) => {
+ *   return await repository.getById(query.orderId);
+ * });
+ *
+ * const order = await bus.execute({ type: "GetOrder", orderId: "123" });
+ * ```
+ */
+declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus {
+    private readonly handlers;
+    register<Q extends Query, R>(queryType: Q["type"], handler: QueryHandler<Q, R>): void;
+    execute<Q extends Query & {
+        type: keyof TMap;
+    }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
+    execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
+    executeUnsafe<Q extends Query, R>(query: Q): Promise<R>;
+}
+
+/**
+ * Guard function that validates a condition and returns a Result.
+ * Returns `ok(true)` if the condition is met, otherwise `err(error)`.
+ *
+ * @param cond - The condition to check
+ * @param error - Error message if condition fails
+ * @returns Result<true, string>
+ *
+ * @example
+ * ```typescript
+ * const result = guard(id.length > 0, "ID cannot be empty");
+ * if (!result.ok) {
+ *   return err(result.error);
+ * }
+ * ```
+ */
+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).
+ *
+ * @template Evt - The type of domain events (must extend DomainEvent)
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBusImpl<OrderEvent>();
+ *
+ * bus.subscribe("OrderCreated", async (event) => {
+ *   await sendEmail(event.payload.customerId);
+ * });
+ *
+ * bus.subscribe("OrderCreated", async (event) => {
+ *   await logEvent(event);
+ * });
+ *
+ * await bus.publish([orderCreatedEvent]);
+ * // Both handlers will be called
+ * ```
+ */
+declare class EventBusImpl<Evt extends DomainEvent<string, unknown>> implements EventBus<Evt> {
+    private readonly handlers;
+    subscribe<T extends Evt>(eventType: string, handler: EventHandler<T>): () => void;
+    publish(events: ReadonlyArray<Evt>): Promise<void>;
+}
+
+/**
+ * A Specification is a named, standalone object that represents a business rule for a query.
+ * It is "translatable" into a concrete database query.
+ */
+interface ISpecification<T> {
+    readonly _type: T;
+}
+
+/**
+ * Repository interface for Aggregate Roots (Entities).
+ *
+ * Repositories work exclusively with Aggregate Root Entities. The Aggregate Root
+ * is the Entity that represents the aggregate externally and is the only object
+ * that can be loaded/saved through repositories.
+ *
+ * When loading an Aggregate Root, all child entities and value objects within
+ * the aggregate state are loaded as well. When saving, the entire aggregate
+ * (including all child entities) is persisted as a unit.
+ *
+ * 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 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>> {
+    getById(id: TId): Promise<TAgg | null>;
+    findOne(spec: ISpecification<TAgg>): Promise<TAgg | null>;
+    find(spec: ISpecification<TAgg>): Promise<TAgg[]>;
+    save(aggregate: TAgg): Promise<void>;
+    delete(id: TId): Promise<void>;
+}
+
+type VO<T> = Readonly<T>;
+/**
+ * Deep freezes an object and all its nested properties recursively.
+ * This ensures true immutability for value objects with nested structures.
+ * Handles circular references by tracking visited objects.
+ */
+declare function deepFreeze<T>(obj: T, visited?: WeakSet<object>): Readonly<T>;
+/**
+ * Creates a deeply immutable value object from the given data.
+ * All nested objects and arrays are frozen recursively.
+ *
+ * @param t - The data to convert into a value object
+ * @returns A deeply frozen, immutable value object
+ *
+ * @example
+ * ```typescript
+ * const address = vo({
+ *   street: "Main St",
+ *   city: "Berlin",
+ *   coordinates: { lat: 52.5, lng: 13.4 }
+ * });
+ * // address.coordinates.lat = 99; // ❌ Error: Cannot assign to read-only property
+ * ```
+ */
+declare function vo<T>(t: T): VO<T>;
+/**
+ * Compares two value objects for equality based on their values.
+ * Uses deep equality comparison that handles:
+ * - Nested objects and arrays
+ * - Primitives (including NaN)
+ * - Dates, Maps, Sets, RegExp
+ * - TypedArrays and DataView
+ * - Symbol keys
+ * - Circular references
+ *
+ * @param a - First value object
+ * @param b - Second value object
+ * @returns true if both objects have the same values, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const money1 = vo({ amount: 100, currency: "USD" });
+ * const money2 = vo({ amount: 100, currency: "USD" });
+ * voEquals(money1, money2); // true
+ *
+ * const address1 = vo({
+ *   street: "Main St",
+ *   coordinates: { lat: 52.5, lng: 13.4 }
+ * });
+ * const address2 = vo({
+ *   street: "Main St",
+ *   coordinates: { lat: 52.5, lng: 13.4 }
+ * });
+ * voEquals(address1, address2); // true
+ * ```
+ */
+declare function voEquals<T>(a: VO<T>, b: VO<T>): boolean;
+/**
+ * Compares two value objects for equality while ignoring specified keys.
+ * Useful for comparing value objects that contain metadata or optional fields
+ * that should not affect equality comparison.
+ *
+ * @param a - First value object
+ * @param b - Second value object
+ * @param options - Options specifying which keys to ignore during comparison
+ * @returns true if both objects have the same values (after ignoring specified keys), false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Value object with metadata
+ * const address1 = vo({
+ *   street: "Main St",
+ *   city: "Berlin",
+ *   metadata: { createdAt: "2024-01-01", updatedAt: "2024-01-02" }
+ * });
+ *
+ * const address2 = vo({
+ *   street: "Main St",
+ *   city: "Berlin",
+ *   metadata: { createdAt: "2024-01-01", updatedAt: "2024-01-03" }
+ * });
+ *
+ * // Compare ignoring metadata timestamps
+ * voEqualsExcept(address1, address2, {
+ *   ignoreKeys: ["updatedAt"],
+ *   ignoreKeyPredicate: (key, path) => path.includes("metadata")
+ * }); // true
+ *
+ * // Compare ignoring all metadata
+ * voEqualsExcept(address1, address2, {
+ *   ignoreKeyPredicate: (key, path) => path.includes("metadata")
+ * }); // true
+ * ```
+ */
+declare function voEqualsExcept<T>(a: VO<T>, b: VO<T>, options: DeepEqualExceptOptions): boolean;
+/**
+ * Creates a value object with optional validation.
+ * Returns a Result type instead of throwing an error.
+ *
+ * @param t - The data to convert into a value object
+ * @param validate - Validation function that returns true if valid
+ * @param errorMessage - Optional custom error message if validation fails
+ * @returns Result containing the value object if valid, or an error message if validation fails
+ *
+ * @example
+ * ```typescript
+ * const result = voWithValidation(
+ *   { amount: 100, currency: "USD" },
+ *   (m) => m.amount >= 0 && m.currency.length === 3,
+ *   "Invalid money: amount must be non-negative and currency must be 3 characters"
+ * );
+ *
+ * if (result.ok) {
+ *   console.log(result.value); // Use the value object
+ * } else {
+ *   console.error(result.error); // Handle validation error
+ * }
+ * ```
+ */
+declare function voWithValidation<T>(t: T, validate: (value: T) => boolean, errorMessage?: string): Result<VO<T>, string>;
+/**
+ * Creates a value object with optional validation.
+ * Throws an error if validation fails.
+ *
+ * @param t - The data to convert into a value object
+ * @param validate - Validation function that returns true if valid
+ * @param errorMessage - Optional custom error message if validation fails
+ * @returns A deeply frozen, immutable value object
+ * @throws Error if validation fails
+ *
+ * @example
+ * ```typescript
+ * const money = voWithValidationUnsafe(
+ *   { amount: 100, currency: "USD" },
+ *   (m) => m.amount >= 0 && m.currency.length === 3,
+ *   "Invalid money: amount must be non-negative and currency must be 3 characters"
+ * );
+ * ```
+ */
+declare function voWithValidationUnsafe<T>(t: T, validate: (value: T) => boolean, errorMessage?: string): VO<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> {
+    readonly props: Readonly<T>;
+    /**
+     * Creates a new ValueObject.
+     * The properties are deeply frozen to ensure immutability.
+     *
+     * @param props - The properties of the value object
+     * @example
+     * ```ts
+     * class Money extends ValueObject<{ amount: number; currency: string }> {
+     *   constructor(props: { amount: number; currency: string }) {
+     *     super(props);
+     *   }
+     * }
+     * ```
+     */
+    constructor(props: 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: ValueObject<T>): boolean;
+}
+
+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 };