@rineex/ddd 0.1.0 → 1.1.0

package/dist/index.d.mts

@@ -27,47 +27,6 @@ interface ApplicationServicePort<I, O> {
     execute: (args: I) => Promise<O>;
 }
 
-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);
-}
-
 declare abstract class ValueObject<T> {
     get value(): T;
     protected readonly props: Readonly<T>;
@@ -91,17 +50,6 @@ declare abstract class ValueObject<T> {
     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);
-}
-
 /**
  * AggregateId is a ValueObject that represents a unique identifier for an aggregate.
  */
@@ -143,6 +91,15 @@ declare class AggregateId extends ValueObject<string> {
     protected validate(value: string): void;
 }
 
+/**
+ * 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.
  *
@@ -153,6 +110,17 @@ declare class AggregateId extends ValueObject<string> {
  * - Values are numeric status codes.
  * - Frozen to prevent runtime mutation.
  * - Exporting `HttpStatus` ensures type-safe usage across the codebase.
+ * Usage:
+ * ```ts
+ * import { HttpStatus } from 'path-to-this-file';
+ *
+ * function handleRequest() {
+ *   return {
+ *     statusCode: HttpStatus.OK,
+ *     body: 'Success',
+ *   };
+ * }
+ * ```
  */
 declare const HttpStatus: Readonly<{
     readonly REQUEST_HEADER_FIELDS_TOO_LARGE: 431;
@@ -291,15 +259,6 @@ declare const HttpStatusMessage: {
 };
 type HttpStatusMessage = (typeof HttpStatusMessage)[keyof typeof HttpStatusMessage];
 
-/**
- * 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;
@@ -352,4 +311,245 @@ type UnwrapValueObject<T> = T extends ValueObject<infer V> ? UnwrapValueObject<V
 declare function unwrapValueObject<T>(input: T, seen?: WeakSet<object>): UnwrapValueObject<T>;
 declare function ensureObject<T>(input: UnwrapValueObject<T>): object;
 
-export { AggregateId, ApplicationError, type ApplicationServicePort, DomainError, type DomainErrorMetadata, EntityValidationError, HttpStatus, type HttpStatusCode, HttpStatusMessage, InvalidValueObjectError, type UnwrapValueObject, ValueObject, deepFreeze, ensureObject, unwrapValueObject };
+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: string;
+    }>;
+    /**
+     * 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({ createdAt, props, id, }: 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<EntityProps>): 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.
+     */
+    isPersisted(): boolean;
+    toJSON(): Record<string, unknown>;
+    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.
+     * @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, type UnwrapValueObject, ValueObject, deepFreeze, ensureObject, unwrapValueObject };