@rineex/ddd 1.5.0 → 1.6.0

package/dist/index.d.mts

@@ -27,6 +27,190 @@ interface ApplicationServicePort<I, O> {
     execute: (args: I) => Promise<O>;
 }
 
+/**
+ * Interface for Identity Value Objects.
+ * Enables the Entity to remain agnostic of the underlying ID implementation
+ * (e.g., UUID, ULID, or Database Sequence).
+ * @template T - The underlying primitive type of the ID (usually string or number).
+ */
+interface EntityId<T = string> {
+    equals: (other?: EntityId<T> | null | undefined) => boolean;
+    toString: () => string;
+}
+
+/**
+ * Configuration for the base Entity constructor.
+ * Forces a single-object argument pattern to avoid positional argument errors.
+ * @template ID - A type satisfying the EntityId interface.
+ */
+interface EntityProps<ID extends EntityId, Props> {
+    /** The unique identity of the entity */
+    readonly id: ID;
+    /** Optional creation timestamp; defaults to 'now' if not provided */
+    readonly createdAt?: Date;
+    readonly props: Props;
+}
+/**
+ * Abstract Base Entity for Domain-Driven Design (DDD).
+ * This class provides the standard contract for entity equality and identity.
+ * It intentionally avoids "magic" property bags to ensure V8 engine optimization
+ * and better IDE intellisense.
+ * @template ID - The specific Identity Value Object type.
+ */
+declare abstract class Entity<ID extends EntityId, Props> {
+    /** The immutable unique identifier for this entity */
+    readonly id: ID;
+    /** The timestamp when this entity was first instantiated/created */
+    readonly createdAt: Date;
+    /**
+     * Protected constructor to be called by subclasses.
+     * @param props - Initial identity and metadata.
+     */
+    protected constructor(props: EntityProps<ID, Props>);
+    /**
+     * Compares entities by identity.
+     * In DDD, two entities are considered equal if their IDs match,
+     * regardless of their other properties.
+     * @param other - The entity to compare against.
+     * @returns True if IDs are equal.
+     */
+    equals(other?: Entity<ID, Props>): boolean;
+    /**
+     * Validates the current state of the entity against domain invariants.
+     * This method should be called after construction and any mutation.
+     * @throws {Error} Should throw a specific DomainError if validation fails.
+     */
+    abstract validate(): void;
+    /**
+     * Converts the Entity into a plain Javascript object.
+     * Subclasses must implement this to explicitly control serialization,
+     * @returns A plain object representation of the entity.
+     */
+    abstract toObject(): Record<string, unknown>;
+}
+
+type Primitive$1 = boolean | number | string | null;
+type Serializable = Primitive$1 | Serializable[] | {
+    [key: string]: Serializable;
+};
+type DomainEventPayload = Record<string, Serializable>;
+type UnixTimestampMillis = number;
+type DomainEventProps<AggregateId extends EntityId, Payload> = {
+    id?: string;
+    aggregateId: AggregateId;
+    schemaVersion: number;
+    occurredAt: UnixTimestampMillis;
+    payload: Payload;
+};
+declare abstract class DomainEvent<AggregateId extends EntityId = EntityId, T extends DomainEventPayload = DomainEventPayload> {
+    abstract readonly eventName: string;
+    readonly id: string;
+    readonly aggregateId: AggregateId;
+    readonly schemaVersion: number;
+    readonly occurredAt: number;
+    readonly payload: Readonly<T>;
+    protected constructor(props: DomainEventProps<AggregateId, T>);
+    toPrimitives(): Readonly<{
+        id: string;
+        eventName: string;
+        aggregateId: string;
+        schemaVersion: number;
+        occurredAt: UnixTimestampMillis;
+        payload: T;
+    }>;
+}
+
+/**
+ * Interface for AggregateRoot to ensure type safety and extensibility.
+ */
+interface Props<P> extends EntityProps<EntityId, P> {
+    readonly domainEvents: readonly DomainEvent[];
+    /**
+     * Adds a domain event to the aggregate.
+     * @param event The domain event to add.
+     */
+    addEvent: (event: DomainEvent) => void;
+    /**
+     * Retrieves and clears all domain events recorded by this aggregate.
+     *
+     * Domain events represent facts that occurred as a result of state changes
+     * within the aggregate. This method transfers ownership of those events
+     * to the application layer for further processing (e.g. publishing).
+     *
+     * Calling this method has the side effect of clearing the aggregate's
+     * internal event collection to prevent duplicate handling.
+     *
+     * This method is intended to be invoked by application services
+     * after the aggregate has been successfully persisted.
+     *
+     * @returns A read-only list of domain events raised by this aggregate.
+     */
+    pullDomainEvents: () => readonly DomainEvent[];
+}
+/**
+ * Base class for aggregate roots in DDD, encapsulating domain events and validation.
+ * @template EntityProps The type of the entity's properties.
+ */
+declare abstract class AggregateRoot<ID extends EntityId, P> extends Entity<ID, P> {
+    /**
+     * Gets a read-only copy of the domain events.
+     */
+    get domainEvents(): readonly DomainEvent[];
+    /**
+     * Internal list of domain events.
+     */
+    private readonly _domainEvents;
+    /**
+     * Adds a domain event to the aggregate after validating invariants.
+     * @param domainEvent The domain event to add.
+     * @throws {EntityValidationError} If invariants are not met.
+     */
+    addEvent(domainEvent: DomainEvent): void;
+    pullDomainEvents(): readonly DomainEvent[];
+}
+
+interface DomainErrorMetadata {
+    cause?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Base class for all Domain Errors in the application.
+ *
+ * This class ensures:
+ * 1. Serializable and structured for logs or API responses.
+ * 2. Identifiable via stable error codes (not just class names).
+ * 3. Contextual with optional structured metadata.
+ * 4. Supports error chaining (cause) and stack trace preservation.
+ *
+ * @example
+ * export class InsufficientFundsError extends DomainError {
+ *   constructor(accountId: string, currentBalance: number) {
+ *     super(
+ *       `Account ${accountId} has insufficient funds.`,
+ *       'INSUFFICIENT_FUNDS',
+ *       { accountId, currentBalance }
+ *     );
+ *   }
+ * }
+ */
+declare abstract class DomainError extends Error {
+    /** Stable, machine-readable error code */
+    readonly code: string;
+    /** Structured, immutable domain metadata */
+    readonly metadata: Readonly<DomainErrorMetadata>;
+    /**
+     * @param message - Human-readable error message
+     * @param code - Stable error code
+     * @param metadata - Domain-specific structured data; optional `cause` can be included
+     */
+    protected constructor(message: string, code: string, metadata?: DomainErrorMetadata);
+}
+
+type Primitive = boolean | number | string;
 /**
  * Base class for primitive-based Value Objects.
  *
@@ -45,7 +229,7 @@ interface ApplicationServicePort<I, O> {
  * - Username
  * - Slug
  */
-declare abstract class PrimitiveValueObject<T extends boolean | number | string> {
+declare abstract class PrimitiveValueObject<T extends Primitive> implements EntityId {
     /**
      * The underlying primitive value.
      * Guaranteed to be valid after construction.
@@ -72,7 +256,7 @@ declare abstract class PrimitiveValueObject<T extends boolean | number | string>
      *
      * @param other - Another Value Object
      */
-    equals(other?: PrimitiveValueObject<T>): boolean;
+    equals(other?: PrimitiveValueObject<T> | null | undefined): boolean;
     /**
      * JSON serialization hook.
      * Produces the raw primitive value.
@@ -92,6 +276,48 @@ declare abstract class PrimitiveValueObject<T extends boolean | number | string>
     protected abstract validate(value: T): void;
 }
 
+declare abstract class ValueObject<T> {
+    get value(): T;
+    protected readonly props: Readonly<T>;
+    protected constructor(props: T);
+    /**
+     * Standard for clean API integration and logging.
+     */
+    toJSON(): T;
+    /**
+     * Useful for debugging and string-based indexing.
+     */
+    toString(): string;
+    /**
+     * Type guard to check if an unknown object is an instance of ValueObject.
+     * This is useful for runtime type checking.
+     *
+     * @param vo The object to check.
+     * @returns True if the object is a ValueObject instance, false otherwise.
+     */
+    static is(vo: unknown): vo is ValueObject<unknown>;
+    /**
+     * Deep equality comparison of ValueObjects
+     */
+    equals(other?: ValueObject<T>): boolean;
+    /**
+     * Validates the value object props
+     * @throws InvalidValueObjectError if validation fails
+     */
+    protected abstract validate(props: T): void;
+}
+
+/**
+ * Custom error class for entity validation failures.
+ */
+declare class EntityValidationError extends DomainError {
+    constructor(message: string, cause?: Error);
+}
+
+declare class InvalidValueObjectError extends DomainError {
+    constructor(message: string);
+}
+
 /**
  * Represents a UUID (Universally Unique Identifier) value object.
  *
@@ -136,15 +362,6 @@ declare class UUID extends PrimitiveValueObject<string> {
 declare class AggregateId extends UUID {
 }
 
-/**
- * Utility to deeply freeze objects to ensure immutability - handles nested objects and arrays.
- *
- * @param obj - The object to be deeply frozen.
- * @param seen - A WeakSet to track already processed objects (for circular references).
- * @returns A deeply frozen version of the input object.
- */
-declare function deepFreeze<T>(obj: T, seen?: WeakSet<object>): Readonly<T>;
-
 /**
  * HTTP status code catalog.
  *
@@ -304,6 +521,150 @@ declare const HttpStatusMessage: {
 };
 type HttpStatusMessage = (typeof HttpStatusMessage)[keyof typeof HttpStatusMessage];
 
+/**
+ * Base class for Domain violations.
+ * Purposely does NOT extend native Error to avoid stack trace overhead in the domain.
+ */
+declare abstract class DomainViolation {
+    abstract readonly code: string;
+    abstract readonly message: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    protected constructor(metadata?: Record<string, unknown>);
+}
+
+/**
+ * Represents the outcome of an operation that can either succeed or fail,
+ * without relying on exceptions for control flow.
+ *
+ * This pattern is commonly used in domain and application layers to make
+ * success and failure states explicit, predictable, and type-safe.
+ *
+ * ## Design guarantees
+ * - A `Result` is **immutable** once created.
+ * - A `Result` is **exactly one of**:
+ *   - Success → contains a value
+ *   - Failure → contains an error
+ * - Accessing the wrong side throws immediately (fail-fast).
+ *
+ * @typeParam T - Type of the success value
+ * @typeParam E - Type of the failure error
+ *
+ * @example
+ * ```ts
+ * function parseNumber(input: string): Result<number, string> {
+ *   const value = Number(input);
+ *
+ *   if (Number.isNaN(value)) {
+ *     return Result.fail('Invalid number');
+ *   }
+ *
+ *   return Result.ok(value);
+ * }
+ *
+ * const result = parseNumber('42');
+ *
+ * if (result.isSuccess) {
+ *   console.log(result.getValue()); // 42
+ * } else {
+ *   console.error(result.getError());
+ * }
+ * ```
+ */
+declare class Result<T, E> {
+    private readonly _value?;
+    private readonly _error?;
+    /**
+     * Indicates whether the result represents a successful outcome.
+     *
+     * This flag is mutually exclusive with {@link isFailure}.
+     */
+    readonly isSuccess: boolean;
+    /**
+     * Indicates whether the result represents a failed outcome.
+     *
+     * This flag is mutually exclusive with {@link isSuccess}.
+     */
+    readonly isFailure: boolean;
+    /**
+     * Creates a new {@link Result} instance.
+     *
+     * This constructor is private to enforce the use of
+     * {@link Result.ok} and {@link Result.fail} factory methods,
+     * preserving the success/failure invariants.
+     *
+     * @param _value - Success value (defined only for success results)
+     * @param _error - Failure error (defined only for failure results)
+     */
+    private constructor();
+    /**
+     * Creates a successful {@link Result}.
+     *
+     * @param value - Value representing a successful outcome
+     * @returns A success {@link Result} containing the provided value
+     *
+     * @example
+     * ```ts
+     * return Result.ok(user);
+     * ```
+     */
+    static ok<T, E>(value: T): Result<T, E>;
+    /**
+     * Creates a failed {@link Result}.
+     *
+     * @param error - Error describing the failure
+     * @returns A failure {@link Result} containing the provided error
+     *
+     * @example
+     * ```ts
+     * return Result.fail(new ValidationError('Email is invalid'));
+     * ```
+     */
+    static fail<T, E>(error: E): Result<T, E>;
+    /**
+     * Returns the success value.
+     *
+     * @returns The value associated with a successful result
+     *
+     * @throws {Error}
+     * Thrown if this result represents a failure.
+     * This is a fail-fast guard against incorrect usage.
+     *
+     * @example
+     * ```ts
+     * if (result.isSuccess) {
+     *   const value = result.getValue();
+     * }
+     * ```
+     */
+    getValue(): T;
+    /**
+     * Returns the failure error.
+     *
+     * @returns The error associated with a failed result
+     *
+     * @throws {Error}
+     * Thrown if this result represents a success.
+     * This is a fail-fast guard against incorrect usage.
+     *
+     * @example
+     * ```ts
+     * if (result.isFailure) {
+     *   const error = result.getError();
+     * }
+     * ```
+     */
+    getError(): E;
+}
+
+/**
+ * Utility to deeply freeze objects to ensure immutability - handles nested objects and arrays.
+ *
+ * @param obj - The object to be deeply frozen.
+ * @param seen - A WeakSet to track already processed objects (for circular references).
+ * @returns A deeply frozen version of the input object.
+ */
+declare function deepFreeze<T>(obj: T, seen?: WeakSet<object>): Readonly<T>;
+
 interface ErrorParams {
     message: string;
     code: HttpStatusMessage;
@@ -350,287 +711,10 @@ declare abstract class ApplicationError extends Error {
     constructor({ code, isOperational, status, metadata, message, cause, }: ErrorParams);
 }
 
-declare abstract class ValueObject<T> {
-    get value(): T;
-    protected readonly props: Readonly<T>;
-    protected constructor(props: T);
-    /**
-     * Standard for clean API integration and logging.
-     */
-    toJSON(): T;
-    /**
-     * Useful for debugging and string-based indexing.
-     */
-    toString(): string;
-    /**
-     * Type guard to check if an unknown object is an instance of ValueObject.
-     * This is useful for runtime type checking.
-     *
-     * @param vo The object to check.
-     * @returns True if the object is a ValueObject instance, false otherwise.
-     */
-    static is(vo: unknown): vo is ValueObject<unknown>;
-    /**
-     * Deep equality comparison of ValueObjects
-     */
-    equals(other?: ValueObject<T>): boolean;
-    /**
-     * Validates the value object props
-     * @throws InvalidValueObjectError if validation fails
-     */
-    protected abstract validate(props: T): void;
-}
-
 type UnwrapValueObject<T> = T extends ValueObject<infer V> ? UnwrapValueObject<V> : T extends (infer U)[] ? UnwrapValueObject<U>[] : T extends Map<infer K, infer V> ? Map<K, UnwrapValueObject<V>> : T extends Set<infer V> ? Set<UnwrapValueObject<V>> : T extends Date ? string : T extends object ? {
     [K in keyof T]: UnwrapValueObject<T[K]>;
 } : T;
 declare function unwrapValueObject<T>(input: T, seen?: WeakSet<object>): UnwrapValueObject<T>;
 declare function ensureObject<T>(input: UnwrapValueObject<T>): object;
 
-interface EntityBaseInterface {
-    id: AggregateId;
-    equals: (entity: unknown) => boolean;
-}
-/**
- * Base properties common to all entities, including ID and timestamps.
- */
-interface BaseEntityProps {
-    /** Unique identifier for the entity */
-    id?: AggregateId;
-    /** Date when the entity was created */
-    createdAt: Date;
-}
-/**
- * Interface for constructing an entity with optional timestamps.
- * @template Props - The specific props type for the entity
- */
-type CreateEntityProps<T> = BaseEntityProps & {
-    props: T;
-};
-/**
- * Abstract base class for domain entities in a Domain-Driven Design (DDD) context.
- * Provides common functionality for entity identification, equality comparison,
- * immutability, and validation. Entities extending this class must implement
- * the `validate` method to enforce domain invariants.
- * @template EntityProps - The specific props type for the entity
- */
-declare abstract class Entity<EntityProps> {
-    #private;
-    /**
-     * Returns the creation timestamp.
-     * A new Date instance is returned to preserve immutability.
-     *
-     * @returns {Date} The creation date of the entity.
-     */
-    get createdAt(): Date;
-    /**
-     * Gets the entity's unique identifier.
-     * @returns The entity's ID
-     */
-    get id(): AggregateId;
-    get metadata(): Readonly<{
-        createdAt: string;
-        id: AggregateId;
-    }>;
-    /**
-     * Returns an immutable shallow copy of the entity's properties.
-     *
-     * @returns {Readonly<EntityProps>} The entity domain properties.
-     */
-    get props(): Readonly<EntityProps>;
-    /**
-     * Constructs an entity with the provided properties and timestamps.
-     * Ensures immutability by cloning props and validates the entity.
-     * @param params - Entity creation parameters
-     * @throws EntityValidationError if the ID is empty or validation fails
-     */
-    protected constructor(args: CreateEntityProps<EntityProps>);
-    /**
-     * Checks if the provided value is an instance of Entity.
-     * @param entity - The value to check
-     * @returns True if the value is an Entity instance
-     */
-    static isEntity(entity: unknown): entity is EntityBaseInterface;
-    /**
-     * Compares this entity with another to determine if they are the same.
-     * Equality is based on the entity ID.
-     * @param other - The entity to compare with
-     * @returns True if the entities have the same ID
-     */
-    equals(other?: Entity<unknown>): boolean;
-    /**
-     * Returns a frozen copy of the entity's properties, including base properties.
-     * Ensures immutability by returning a new object.
-     * @returns A frozen copy of the entity's properties
-     */
-    getPropsCopy(): Readonly<EntityProps>;
-    /**
-     * Determines if the entity is transient, i.e., it has not been persisted yet.
-     * By convention, an entity is considered transient if it lacks a valid identifier.
-     * This can be useful when performing logic that depends on persistence state,
-     * such as conditional inserts or validations that only apply to new entities.
-     *
-     * @returns True if the entity is transient (not persisted), otherwise false.
-     */
-    toJSON(): Record<string, unknown>;
-    /**
-     * Internal mutation hook.
-     * Must be followed by validation by caller.
-     */
-    protected updateProps(updater: (current: EntityProps) => EntityProps): void;
-    toObject(): Readonly<UnwrapValueObject<EntityProps> & {
-        createdAt: string;
-        id: string;
-    }>;
-    /**
-     * Validates the entity's state to enforce domain invariants.
-     * Must be implemented by subclasses to define specific validation rules.
-     * @implements Must be called by concrete factories and mutators.
-     * @throws EntityValidationError if validation fails
-     */
-    abstract validate(): void;
-}
-
-type Primitive = boolean | number | string | null;
-type Serializable = Primitive | Serializable[] | {
-    [key: string]: Serializable;
-};
-type DomainEventPayload = Record<string, Serializable>;
-type DomainEventProps<T> = {
-    id: string;
-    aggregateId: string;
-    schemaVersion: number;
-    occurredAt: number;
-    payload: T;
-};
-declare abstract class DomainEvent<T extends DomainEventPayload = DomainEventPayload> {
-    abstract readonly eventName: string;
-    readonly id: string;
-    readonly aggregateId: string;
-    readonly schemaVersion: number;
-    readonly occurredAt: number;
-    readonly payload: Readonly<T>;
-    protected constructor(props: DomainEventProps<T>);
-    toPrimitives(): {
-        schemaVersion: number;
-        aggregateId: string;
-        occurredAt: number;
-        eventName: string;
-        payload: Readonly<T>;
-        id: string;
-    };
-}
-
-/**
- * Interface for AggregateRoot to ensure type safety and extensibility.
- */
-interface AggregateRootInterface {
-    readonly id: AggregateId;
-    readonly domainEvents: readonly DomainEvent[];
-    /**
-     * Validates the aggregate's invariants.
-     * @throws {EntityValidationError} If validation fails.
-     */
-    validate: () => void;
-    /**
-     * Adds a domain event to the aggregate.
-     * @param event The domain event to add.
-     */
-    addEvent: (event: DomainEvent) => void;
-    /**
-     * Retrieves and clears all domain events recorded by this aggregate.
-     *
-     * Domain events represent facts that occurred as a result of state changes
-     * within the aggregate. This method transfers ownership of those events
-     * to the application layer for further processing (e.g. publishing).
-     *
-     * Calling this method has the side effect of clearing the aggregate's
-     * internal event collection to prevent duplicate handling.
-     *
-     * This method is intended to be invoked by application services
-     * after the aggregate has been successfully persisted.
-     *
-     * @returns A read-only list of domain events raised by this aggregate.
-     */
-    pullDomainEvents: () => readonly DomainEvent[];
-}
-/**
- * Base class for aggregate roots in DDD, encapsulating domain events and validation.
- * @template EntityProps The type of the entity's properties.
- */
-declare abstract class AggregateRoot<EntityProps> extends Entity<EntityProps> implements AggregateRootInterface {
-    /**
-     * Gets a read-only copy of the domain events.
-     */
-    get domainEvents(): readonly DomainEvent[];
-    /**
-     * Internal list of domain events.
-     */
-    private readonly _domainEvents;
-    /**
-     * Adds a domain event to the aggregate after validating invariants.
-     * @param domainEvent The domain event to add.
-     * @throws {EntityValidationError} If invariants are not met.
-     */
-    addEvent(domainEvent: DomainEvent): void;
-    pullDomainEvents(): readonly DomainEvent[];
-    /**
-     * Validates the entity's invariants.
-     * @throws {EntityValidationError} If validation fails.
-     */
-    abstract validate(): void;
-}
-
-interface DomainErrorMetadata {
-    cause?: {
-        name: string;
-        message: string;
-        stack?: string;
-    };
-    [key: string]: unknown;
-}
-/**
- * Base class for all Domain Errors in the application.
- *
- * This class ensures:
- * 1. Serializable and structured for logs or API responses.
- * 2. Identifiable via stable error codes (not just class names).
- * 3. Contextual with optional structured metadata.
- * 4. Supports error chaining (cause) and stack trace preservation.
- *
- * @example
- * export class InsufficientFundsError extends DomainError {
- *   constructor(accountId: string, currentBalance: number) {
- *     super(
- *       `Account ${accountId} has insufficient funds.`,
- *       'INSUFFICIENT_FUNDS',
- *       { accountId, currentBalance }
- *     );
- *   }
- * }
- */
-declare abstract class DomainError extends Error {
-    /** Stable, machine-readable error code */
-    readonly code: string;
-    /** Structured, immutable domain metadata */
-    readonly metadata: Readonly<DomainErrorMetadata>;
-    /**
-     * @param message - Human-readable error message
-     * @param code - Stable error code
-     * @param metadata - Domain-specific structured data; optional `cause` can be included
-     */
-    protected constructor(message: string, code: string, metadata?: DomainErrorMetadata);
-}
-
-/**
- * Custom error class for entity validation failures.
- */
-declare class EntityValidationError extends DomainError {
-    constructor(message: string, cause?: Error);
-}
-
-declare class InvalidValueObjectError extends DomainError {
-    constructor(message: string);
-}
-
-export { AggregateId, AggregateRoot, type AggregateRootInterface, ApplicationError, type ApplicationServicePort, type BaseEntityProps, type CreateEntityProps, DomainError, type DomainErrorMetadata, DomainEvent, type DomainEventPayload, Entity, type EntityBaseInterface, EntityValidationError, HttpStatus, type HttpStatusCode, HttpStatusMessage, InvalidValueObjectError, PrimitiveValueObject, type UnwrapValueObject, ValueObject, deepFreeze, ensureObject, unwrapValueObject };
+export { AggregateId, AggregateRoot, ApplicationError, type ApplicationServicePort, DomainError, type DomainErrorMetadata, DomainEvent, type DomainEventPayload, DomainViolation, Entity, type EntityId, type EntityProps, EntityValidationError, HttpStatus, type HttpStatusCode, HttpStatusMessage, InvalidValueObjectError, PrimitiveValueObject, type Props, Result, UUID, type UnixTimestampMillis, type UnwrapValueObject, ValueObject, deepFreeze, ensureObject, unwrapValueObject };