@rineex/ddd 2.1.0 → 2.2.0

package/dist/index.d.mts

@@ -1,3 +1,211 @@
+import { Primitive as Primitive$2, Tagged } from 'type-fest';
+import z from 'zod';
+
+/**
+ * HTTP status code catalog.
+ *
+ * This object provides a typed, immutable map of standard HTTP status names
+ * to their numeric codes. Designed for server-side frameworks such as Fastify.
+ *
+ * - All identifiers use clear, canonical semantic names.
+ * - 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;
+    readonly NETWORK_AUTHENTICATION_REQUIRED: 511;
+    readonly NON_AUTHORITATIVE_INFORMATION: 203;
+    readonly PROXY_AUTHENTICATION_REQUIRED: 407;
+    readonly UNAVAILABLE_FOR_LEGAL_REASONS: 451;
+    readonly HTTP_VERSION_NOT_SUPPORTED: 505;
+    readonly BANDWIDTH_LIMIT_EXCEEDED: 509;
+    readonly VARIANT_ALSO_NEGOTIATES: 506;
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    readonly RANGE_NOT_SATISFIABLE: 416;
+    readonly PRECONDITION_REQUIRED: 428;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly INSUFFICIENT_STORAGE: 507;
+    readonly SWITCHING_PROTOCOLS: 101;
+    readonly PRECONDITION_FAILED: 412;
+    readonly MISDIRECTED_REQUEST: 421;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly EXPECTATION_FAILED: 417;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly FAILED_DEPENDENCY: 424;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly ALREADY_REPORTED: 208;
+    readonly MULTIPLE_CHOICES: 300;
+    readonly PAYMENT_REQUIRED: 402;
+    readonly UPGRADE_REQUIRED: 426;
+    readonly PARTIAL_CONTENT: 206;
+    readonly REQUEST_TIMEOUT: 408;
+    readonly LENGTH_REQUIRED: 411;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly GATEWAY_TIMEOUT: 504;
+    readonly NOT_ACCEPTABLE: 406;
+    readonly RESET_CONTENT: 205;
+    readonly LOOP_DETECTED: 508;
+    readonly MULTI_STATUS: 207;
+    readonly NOT_MODIFIED: 304;
+    readonly UNAUTHORIZED: 401;
+    readonly URI_TOO_LONG: 414;
+    readonly NOT_EXTENDED: 510;
+    readonly EARLY_HINTS: 103;
+    readonly BAD_REQUEST: 400;
+    readonly IM_A_TEAPOT: 418;
+    readonly BAD_GATEWAY: 502;
+    readonly PROCESSING: 102;
+    readonly NO_CONTENT: 204;
+    readonly SEE_OTHER: 303;
+    readonly USE_PROXY: 305;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly TOO_EARLY: 425;
+    readonly CONTINUE: 100;
+    readonly ACCEPTED: 202;
+    readonly CONFLICT: 409;
+    readonly CREATED: 201;
+    readonly IM_USED: 226;
+    readonly LOCKED: 423;
+    readonly FOUND: 302;
+    readonly GONE: 410;
+    readonly OK: 200;
+}>;
+type HttpStatusCode = keyof typeof HttpStatusMessage;
+/**
+ * HTTP status messages mapped by numeric code.
+ * Use for sending descriptive text in responses or logging.
+ */
+declare const HttpStatusMessage: {
+    readonly 431: "Request Header Fields Too Large";
+    readonly 511: "Network Authentication Required";
+    readonly 203: "Non-Authoritative Information";
+    readonly 407: "Proxy Authentication Required";
+    readonly 451: "Unavailable For Legal Reasons";
+    readonly 505: "HTTP Version Not Supported";
+    readonly 509: "Bandwidth Limit Exceeded";
+    readonly 506: "Variant Also Negotiates";
+    readonly 415: "Unsupported Media Type";
+    readonly 416: "Range Not Satisfiable";
+    readonly 428: "Precondition Required";
+    readonly 500: "Internal Server Error";
+    readonly 422: "Unprocessable Entity";
+    readonly 507: "Insufficient Storage";
+    readonly 101: "Switching Protocols";
+    readonly 412: "Precondition Failed";
+    readonly 421: "Misdirected Request";
+    readonly 503: "Service Unavailable";
+    readonly 307: "Temporary Redirect";
+    readonly 308: "Permanent Redirect";
+    readonly 405: "Method Not Allowed";
+    readonly 417: "Expectation Failed";
+    readonly 301: "Moved Permanently";
+    readonly 413: "Payload Too Large";
+    readonly 424: "Failed Dependency";
+    readonly 429: "Too Many Requests";
+    readonly 208: "Already Reported";
+    readonly 300: "Multiple Choices";
+    readonly 402: "Payment Required";
+    readonly 426: "Upgrade Required";
+    readonly 206: "Partial Content";
+    readonly 408: "Request Timeout";
+    readonly 411: "Length Required";
+    readonly 501: "Not Implemented";
+    readonly 504: "Gateway Timeout";
+    readonly 406: "Not Acceptable";
+    readonly 205: "Reset Content";
+    readonly 508: "Loop Detected";
+    readonly 207: "Multi-Status";
+    readonly 304: "Not Modified";
+    readonly 401: "Unauthorized";
+    readonly 414: "URI Too Long";
+    readonly 418: "I'm a Teapot";
+    readonly 510: "Not Extended";
+    readonly 103: "Early Hints";
+    readonly 400: "Bad Request";
+    readonly 502: "Bad Gateway";
+    readonly 102: "Processing";
+    readonly 204: "No Content";
+    readonly 303: "See Other";
+    readonly 305: "Use Proxy";
+    readonly 403: "Forbidden";
+    readonly 404: "Not Found";
+    readonly 425: "Too Early";
+    readonly 100: "Continue";
+    readonly 202: "Accepted";
+    readonly 226: "I'm Used";
+    readonly 409: "Conflict";
+    readonly 201: "Created";
+    readonly 423: "Locked";
+    readonly 302: "Found";
+    readonly 410: "Gone";
+    readonly 200: "OK";
+};
+type HttpStatusMessage = (typeof HttpStatusMessage)[keyof typeof HttpStatusMessage];
+
+interface ErrorParams {
+    message: string;
+    code: HttpStatusMessage;
+    status?: HttpStatusCode;
+    metadata?: Record<string, unknown>;
+    isOperational?: boolean;
+    cause?: Error;
+}
+/**
+ * Abstract base class for application-level errors with structured error handling.
+ *
+ * Extends the native Error class to provide machine-readable error codes, HTTP status codes,
+ * operational error classification, and optional metadata for better error tracking and client communication.
+ *
+ * @abstract
+ * @extends {Error}
+ *
+ * @example
+ * ```typescript
+ * class UserNotFoundError extends ApplicationError {
+ *   constructor(userId: string) {
+ *     super({
+ *       code: HttpStatusMessage['404'],
+ *       status: 404,
+ *       isOperational: true,
+ *       message: `User with id ${userId} not found`,
+ *       metadata: { userId }
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ApplicationError extends Error {
+    /** Optional cause (linked error) */
+    readonly cause?: Error | undefined;
+    /** Machine-readable error code (e.g. `OTP_LOCKED`, `USER_NOT_FOUND`) */
+    readonly code: HttpStatusMessage;
+    /** Operational vs programmer error flag */
+    readonly isOperational: boolean;
+    /** Optional structured metadata for debugging or clients */
+    readonly metadata?: Record<string, unknown> | undefined;
+    /** HTTP status code intended for response layer */
+    readonly status: HttpStatusCode;
+    constructor({ code, isOperational, status, metadata, message, cause, }: ErrorParams);
+}
+
 /**
  * Port interface for application services that execute commands or queries.
  *
@@ -33,11 +241,15 @@ interface ApplicationServicePort<I, O> {
  * (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;
+interface EntityId {
+    equals: <T extends EntityId>(other?: T) => boolean;
     toString: () => string;
+    readonly value: Readonly<Primitive$2>;
 }
 
+type Immutable<T> = T extends (...args: any[]) => any ? T : T extends Date ? T : T extends Map<infer K, infer V> ? ReadonlyMap<Immutable<K>, Immutable<V>> : T extends Set<infer U> ? ReadonlySet<Immutable<U>> : T extends object ? {
+    readonly [K in keyof T]: Immutable<T[K]>;
+} : T;
 /**
  * Configuration for the base Entity constructor.
  * Forces a single-object argument pattern to avoid positional argument errors.
@@ -48,7 +260,7 @@ interface EntityProps<ID extends EntityId, Props> {
     readonly id: ID;
     /** Optional creation timestamp; defaults to 'now' if not provided */
     readonly createdAt?: Date;
-    readonly props: Props;
+    props: Props;
 }
 /**
  * Abstract Base Entity for Domain-Driven Design (DDD).
@@ -58,15 +270,21 @@ interface EntityProps<ID extends EntityId, Props> {
  * @template ID - The specific Identity Value Object type.
  */
 declare abstract class Entity<ID extends EntityId, Props> {
+    #private;
     /** The timestamp when this entity was first instantiated/created */
     readonly createdAt: Date;
     /** The immutable unique identifier for this entity */
     readonly id: ID;
+    /**
+     * Read-only view of entity state.
+     * External code can never mutate internal state.
+     */
+    protected get props(): Immutable<Props>;
     /**
      * Protected constructor to be called by subclasses.
-     * @param props - Initial identity and metadata.
+     * @param params - Initial identity and metadata.
      */
-    protected constructor(props: EntityProps<ID, Props>);
+    protected constructor(params: EntityProps<ID, Props>);
     /**
      * Compares entities by identity.
      * In DDD, two entities are considered equal if their IDs match,
@@ -87,6 +305,7 @@ declare abstract class Entity<ID extends EntityId, Props> {
      * @throws {Error} Should throw a specific DomainError if validation fails.
      */
     abstract validate(): void;
+    protected mutate(updater: (current: Props) => Props): void;
 }
 
 type Primitive$1 = boolean | number | string | null;
@@ -95,13 +314,14 @@ type Serializable = Primitive$1 | Serializable[] | {
 };
 type DomainEventPayload = Record<string, Serializable>;
 type UnixTimestampMillis = number;
-type DomainEventProps<AggregateId extends EntityId, Payload> = {
+type DomainEventProps<Payload, AggregateId extends EntityId> = {
     id?: string;
     aggregateId: AggregateId;
     schemaVersion: number;
     occurredAt: UnixTimestampMillis;
     payload: Payload;
 };
+type CreateEventProps<EventProps, ID extends EntityId> = DomainEventProps<EventProps, ID>;
 declare abstract class DomainEvent<AggregateId extends EntityId = EntityId, T extends DomainEventPayload = DomainEventPayload> {
     readonly aggregateId: AggregateId;
     abstract readonly eventName: string;
@@ -109,7 +329,7 @@ declare abstract class DomainEvent<AggregateId extends EntityId = EntityId, T ex
     readonly occurredAt: number;
     readonly payload: Readonly<T>;
     readonly schemaVersion: number;
-    protected constructor(props: DomainEventProps<AggregateId, T>);
+    protected constructor(props: DomainEventProps<T, AggregateId>);
     toPrimitives(): Readonly<{
         id: string;
         eventName: string;
@@ -120,36 +340,28 @@ declare abstract class DomainEvent<AggregateId extends EntityId = EntityId, T ex
     }>;
 }
 
-/**
- * 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.
+ *
+ * Aggregate roots are entities that serve as entry points to aggregates. They:
+ * - Enforce invariants across the aggregate
+ * - Manage domain events
+ * - Define transaction boundaries
+ *
+ * @template ID - The type of the aggregate's identity (must extend EntityId)
+ * @template P - The type of the aggregate's properties
+ *
+ * @example
+ * ```typescript
+ * interface UserProps {
+ *   email: string;
+ *   isActive: boolean;
+ * }
+ *
+ * class User extends AggregateRoot<AggregateId, UserProps> {
+ *   // Implementation...
+ * }
+ * ```
  */
 declare abstract class AggregateRoot<ID extends EntityId, P> extends Entity<ID, P> {
     /**
@@ -169,48 +381,6 @@ declare abstract class AggregateRoot<ID extends EntityId, P> extends Entity<ID,
     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$1 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.
  *
@@ -229,12 +399,13 @@ type Primitive = boolean | number | string;
  * - Username
  * - Slug
  */
-declare abstract class PrimitiveValueObject<T extends Primitive> implements EntityId {
+declare abstract class PrimitiveValueObject<T extends Primitive$2> implements EntityId {
+    #private;
     /**
      * The underlying primitive value.
      * Guaranteed to be valid after construction.
      */
-    protected readonly value: T;
+    get value(): T;
     /**
      * Constructs a new PrimitiveValueObject.
      *
@@ -251,290 +422,376 @@ declare abstract class PrimitiveValueObject<T extends Primitive> implements Enti
      *
      * @param other - Another Value Object
      */
-    equals(other?: PrimitiveValueObject<T> | null | undefined): boolean;
+    equals(other: any): boolean;
     /**
      * Returns the primitive value.
      * Prefer explicit access over implicit coercion.
+     * @deprecated - instead use instance.value
      */
     getValue(): T;
-    /**
-     * JSON serialization hook.
-     * Produces the raw primitive value.
-     */
-    toJSON(): T;
     /**
      * String representation.
      * Useful for logging and debugging.
-     */
-    toString(): string;
-    /**
-     * Domain invariant validation.
-     * Must throw if the value is invalid.
-     *
-     * @param value - The value to validate
-     */
-    protected abstract validate(value: T): void;
-}
-
-declare abstract class ValueObject<T> {
-    get value(): T;
-    protected readonly props: Readonly<T>;
-    protected constructor(props: T);
-    /**
-     * 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;
-    /**
-     * Standard for clean API integration and logging.
-     */
-    toJSON(): T;
-    /**
-     * Useful for debugging and string-based indexing.
-     */
-    toString(): string;
-    /**
-     * 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$1 {
-    constructor(message: string, cause?: Error);
-}
-
-declare class InvalidValueObjectError extends DomainError$1 {
-    constructor(message: string);
-}
-
-/**
- * Represents a UUID (Universally Unique Identifier) value object.
- *
- * This class extends PrimitiveValueObject to provide type-safe UUID handling
- * with validation using Zod schema. UUIDs are immutable and can be generated
- * randomly or created from string values.
- *
- * @example
- * // Generate a new random UUID
- * const id = UUID.generate();
- *
- * @example
- * // Create UUID from an existing string
- * const id = UUID.fromString('550e8400-e29b-41d4-a716-446655440000');
- *
- * @throws {InvalidValueObjectError} When the provided string is not a valid UUID format
- */
-declare class UUID extends PrimitiveValueObject<string> {
-    private static readonly schema;
-    constructor(value: string);
-    /**
-     * Creates an UUID from an external string.
-     * Use only for untrusted input.
-     *
-     * @param value - UUID string
-     */
-    static fromString(value: string): UUID;
-    /**
-     * Generates a new AggregateId.
-     */
-    static generate<T extends typeof UUID>(this: T): InstanceType<T>;
-    protected validate(value: string): void;
-}
-
-/**
- * AggregateId represents a strongly-typed aggregate identifier.
- *
- * - Backed by UUID v4
- * - Immutable
- * - Comparable only to AggregateId
- */
-declare class AggregateId extends UUID {
-}
-
-/**
- * HTTP status code catalog.
- *
- * This object provides a typed, immutable map of standard HTTP status names
- * to their numeric codes. Designed for server-side frameworks such as Fastify.
- *
- * - All identifiers use clear, canonical semantic names.
- * - 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;
-    readonly NETWORK_AUTHENTICATION_REQUIRED: 511;
-    readonly NON_AUTHORITATIVE_INFORMATION: 203;
-    readonly PROXY_AUTHENTICATION_REQUIRED: 407;
-    readonly UNAVAILABLE_FOR_LEGAL_REASONS: 451;
-    readonly HTTP_VERSION_NOT_SUPPORTED: 505;
-    readonly BANDWIDTH_LIMIT_EXCEEDED: 509;
-    readonly VARIANT_ALSO_NEGOTIATES: 506;
-    readonly UNSUPPORTED_MEDIA_TYPE: 415;
-    readonly RANGE_NOT_SATISFIABLE: 416;
-    readonly PRECONDITION_REQUIRED: 428;
-    readonly INTERNAL_SERVER_ERROR: 500;
-    readonly UNPROCESSABLE_ENTITY: 422;
-    readonly INSUFFICIENT_STORAGE: 507;
-    readonly SWITCHING_PROTOCOLS: 101;
-    readonly PRECONDITION_FAILED: 412;
-    readonly MISDIRECTED_REQUEST: 421;
-    readonly SERVICE_UNAVAILABLE: 503;
-    readonly TEMPORARY_REDIRECT: 307;
-    readonly PERMANENT_REDIRECT: 308;
-    readonly METHOD_NOT_ALLOWED: 405;
-    readonly EXPECTATION_FAILED: 417;
-    readonly MOVED_PERMANENTLY: 301;
-    readonly PAYLOAD_TOO_LARGE: 413;
-    readonly FAILED_DEPENDENCY: 424;
-    readonly TOO_MANY_REQUESTS: 429;
-    readonly ALREADY_REPORTED: 208;
-    readonly MULTIPLE_CHOICES: 300;
-    readonly PAYMENT_REQUIRED: 402;
-    readonly UPGRADE_REQUIRED: 426;
-    readonly PARTIAL_CONTENT: 206;
-    readonly REQUEST_TIMEOUT: 408;
-    readonly LENGTH_REQUIRED: 411;
-    readonly NOT_IMPLEMENTED: 501;
-    readonly GATEWAY_TIMEOUT: 504;
-    readonly NOT_ACCEPTABLE: 406;
-    readonly RESET_CONTENT: 205;
-    readonly LOOP_DETECTED: 508;
-    readonly MULTI_STATUS: 207;
-    readonly NOT_MODIFIED: 304;
-    readonly UNAUTHORIZED: 401;
-    readonly URI_TOO_LONG: 414;
-    readonly NOT_EXTENDED: 510;
-    readonly EARLY_HINTS: 103;
-    readonly BAD_REQUEST: 400;
-    readonly IM_A_TEAPOT: 418;
-    readonly BAD_GATEWAY: 502;
-    readonly PROCESSING: 102;
-    readonly NO_CONTENT: 204;
-    readonly SEE_OTHER: 303;
-    readonly USE_PROXY: 305;
-    readonly FORBIDDEN: 403;
-    readonly NOT_FOUND: 404;
-    readonly TOO_EARLY: 425;
-    readonly CONTINUE: 100;
-    readonly ACCEPTED: 202;
-    readonly CONFLICT: 409;
-    readonly CREATED: 201;
-    readonly IM_USED: 226;
-    readonly LOCKED: 423;
-    readonly FOUND: 302;
-    readonly GONE: 410;
-    readonly OK: 200;
-}>;
-type HttpStatusCode = keyof typeof HttpStatusMessage;
-/**
- * HTTP status messages mapped by numeric code.
- * Use for sending descriptive text in responses or logging.
- */
-declare const HttpStatusMessage: {
-    readonly 431: "Request Header Fields Too Large";
-    readonly 511: "Network Authentication Required";
-    readonly 203: "Non-Authoritative Information";
-    readonly 407: "Proxy Authentication Required";
-    readonly 451: "Unavailable For Legal Reasons";
-    readonly 505: "HTTP Version Not Supported";
-    readonly 509: "Bandwidth Limit Exceeded";
-    readonly 506: "Variant Also Negotiates";
-    readonly 415: "Unsupported Media Type";
-    readonly 416: "Range Not Satisfiable";
-    readonly 428: "Precondition Required";
-    readonly 500: "Internal Server Error";
-    readonly 422: "Unprocessable Entity";
-    readonly 507: "Insufficient Storage";
-    readonly 101: "Switching Protocols";
-    readonly 412: "Precondition Failed";
-    readonly 421: "Misdirected Request";
-    readonly 503: "Service Unavailable";
-    readonly 307: "Temporary Redirect";
-    readonly 308: "Permanent Redirect";
-    readonly 405: "Method Not Allowed";
-    readonly 417: "Expectation Failed";
-    readonly 301: "Moved Permanently";
-    readonly 413: "Payload Too Large";
-    readonly 424: "Failed Dependency";
-    readonly 429: "Too Many Requests";
-    readonly 208: "Already Reported";
-    readonly 300: "Multiple Choices";
-    readonly 402: "Payment Required";
-    readonly 426: "Upgrade Required";
-    readonly 206: "Partial Content";
-    readonly 408: "Request Timeout";
-    readonly 411: "Length Required";
-    readonly 501: "Not Implemented";
-    readonly 504: "Gateway Timeout";
-    readonly 406: "Not Acceptable";
-    readonly 205: "Reset Content";
-    readonly 508: "Loop Detected";
-    readonly 207: "Multi-Status";
-    readonly 304: "Not Modified";
-    readonly 401: "Unauthorized";
-    readonly 414: "URI Too Long";
-    readonly 418: "I'm a Teapot";
-    readonly 510: "Not Extended";
-    readonly 103: "Early Hints";
-    readonly 400: "Bad Request";
-    readonly 502: "Bad Gateway";
-    readonly 102: "Processing";
-    readonly 204: "No Content";
-    readonly 303: "See Other";
-    readonly 305: "Use Proxy";
-    readonly 403: "Forbidden";
-    readonly 404: "Not Found";
-    readonly 425: "Too Early";
-    readonly 100: "Continue";
-    readonly 202: "Accepted";
-    readonly 226: "I'm Used";
-    readonly 409: "Conflict";
-    readonly 201: "Created";
-    readonly 423: "Locked";
-    readonly 302: "Found";
-    readonly 410: "Gone";
-    readonly 200: "OK";
-};
-type HttpStatusMessage = (typeof HttpStatusMessage)[keyof typeof HttpStatusMessage];
+     */
+    toString(): string;
+    /**
+     * Domain invariant validation.
+     * Must throw if the value is invalid.
+     *
+     * @param value - The value to validate
+     */
+    protected abstract validate(value: T): void;
+}
+
+declare abstract class ValueObject<T> {
+    get value(): T;
+    protected readonly props: Readonly<T>;
+    protected constructor(props: T);
+    /**
+     * 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;
+    /**
+     * Standard for clean API integration and logging.
+     */
+    toJSON(): T;
+    /**
+     * Useful for debugging and string-based indexing.
+     */
+    toString(): string;
+    /**
+     * Validates the value object props
+     * @throws InvalidValueObjectError if validation fails
+     */
+    protected abstract validate(props: T): void;
+}
 
+type Primitive = boolean | number | string | null | undefined;
+type Metadata<T = {}> = T extends Record<string, Primitive> ? T : {};
+/**
+ * Categories of domain errors based on the nature of the violation.
+ *
+ * @typedef {'DOMAIN.INVALID_STATE' | 'DOMAIN.INVALID_VALUE'} DomainErrorType
+ *
+ * @example
+ * // DomainErrorType usage:
+ * const errorType: DomainErrorType = 'DOMAIN.INVALID_STATE';
+ */
+type DomainErrorType = 'DOMAIN.INVALID_STATE' | 'DOMAIN.INVALID_VALUE';
+type ValueOf<T> = T[keyof T];
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Interface for declaring domain error namespaces via declaration merging.
+ * Projects extend this interface to add their own namespaces and error codes.
+ *
+ * @example
+ * // In your project's type definition file (.d.ts):
+ * declare module '@your-org/domain-errors' {
+ *   interface DomainErrorNamespaces {
+ *     USER: ['NOT_FOUND', 'INVALID_EMAIL', 'SUSPENDED'];
+ *     ORDER: ['NOT_FOUND', 'INVALID_STATUS', 'OUT_OF_STOCK'];
+ *     // Override default namespace (optional):
+ *     CORE: ['INTERNAL_ERROR', 'VALIDATION_FAILED', 'CONFIGURATION_ERROR'];
+ *   }
+ * }
+ *
+ * @example
+ * // This enables type-safe error codes:
+ * const code: DomainErrorCode = 'USER.NOT_FOUND'; // ✅ Valid
+ * const code: DomainErrorCode = 'USER.INVALID';   // ❌ TypeScript error
+ */
+interface DomainErrorNamespaces {
+    DOMAIN: ['INVALID_VALUE', 'INVALID_STATE'];
+    CORE: [
+        'INTERNAL_ERROR',
+        'VALIDATION_FAILED',
+        'CONFIGURATION_ERROR',
+        'NOT_IMPLEMENTED'
+    ];
+    SYSTEM: ['UNEXPECTED', 'TIMEOUT', 'NETWORK_ERROR', 'DEPENDENCY_ERROR'];
+}
+type Namespace = keyof DomainErrorNamespaces;
+type ErrorName<N extends Namespace> = DomainErrorNamespaces[N][number];
+/**
+ * Union type of all valid domain error codes derived from registered namespaces.
+ * Automatically updates when projects extend DomainErrorNamespaces.
+ *
+ * @example
+ * // After extending DomainErrorNamespaces with USER namespace:
+ * type ErrorCode = DomainErrorCode;
+ * // Becomes: 'CORE.INTERNAL_ERROR' | 'CORE.VALIDATION_FAILED' |
+ * //           'USER.NOT_FOUND' | 'USER.INVALID_EMAIL' | ...
+ */
+type DomainErrorCode = {
+    [N in Namespace]: `${Uppercase<string & N>}.${Uppercase<ErrorName<N>>}`;
+}[Namespace];
+type ExtractNamespace<Code extends DomainErrorCode> = Code extends `${infer N}.${string}` ? N : never;
+type ExtractErrorName<Code extends DomainErrorCode> = Code extends `${string}.${infer E}` ? E : never;
 /**
- * Strongly-typed domain error used in Result failures.
- * Does NOT extend native Error on purpose — infrastructure maps to transport later.
+ * Base class for all domain errors in a Domain-Driven Design architecture.
+ *
+ * Domain errors represent violations of business rules and domain invariants.
+ * They are pure value objects without infrastructure concerns like IDs or timestamps.
+ *
+ * @typeParam Code - The specific error code from DomainErrorCode union
+ * @typeParam Meta - Type of metadata associated with this error
+ *
+ * @example
+ * // 1. First, declare your namespaces:
+ * declare module '@your-org/domain-errors' {
+ *   interface DomainErrorNamespaces {
+ *     USER: ['NOT_FOUND', 'INVALID_EMAIL'];
+ *   }
+ * }
+ *
+ * @example
+ * // 2. Create a concrete domain error:
+ * class UserNotFoundError extends DomainError<'USER.NOT_FOUND', { userId: string }> {
+ *   public readonly code = 'USER.NOT_FOUND' as const;
+ *   public readonly type: DomainErrorType = 'DOMAIN.INVALID_VALUE';
+ *
+ *   constructor(userId: string) {
+ *     super(`User with ID '${userId}' not found`, { userId });
+ *   }
+ * }
+ *
+ * @example
+ * // 3. Usage in domain services:
+ * class UserService {
+ *   async activateUser(userId: string): Promise<Result<User, DomainError>> {
+ *     const user = await this.repository.findById(userId);
+ *
+ *     if (!user) {
+ *       return Result.failure(new UserNotFoundError(userId));
+ *     }
+ *
+ *     if (user.isSuspended) {
+ *       return Result.failure(new UserSuspendedError(userId));
+ *     }
+ *
+ *     // Business logic...
+ *   }
+ * }
+ *
+ * @abstract
  */
-declare abstract class DomainError {
-    abstract readonly code: DomainErrorCode;
+declare abstract class DomainError<Meta extends Record<string, Primitive> = {}, Code extends DomainErrorCode = DomainErrorCode> {
+    /**
+     * Machine-readable error code in format: NAMESPACE.ERROR_NAME
+     *
+     * @remarks
+     * - Must be uppercase (e.g., 'USER.NOT_FOUND')
+     * - Namespace must be declared in DomainErrorNamespaces
+     * - Error name must be in the namespace's array
+     *
+     * @example
+     * public readonly code = 'USER.NOT_FOUND' as const;
+     */
+    abstract readonly code: Code;
+    /**
+     * Human-readable error message describing the domain rule violation.
+     * Should be meaningful to developers and potentially end-users.
+     *
+     * @remarks
+     * - Avoid technical implementation details
+     * - Focus on the business rule that was violated
+     * - Can include values from metadata for context
+     *
+     * @example
+     * // Good: "Order amount $150 exceeds maximum limit of $100"
+     * // Bad: "Amount validation failed: 150 > 100"
+     */
     readonly message: string;
-    readonly metadata: Readonly<Record<string, boolean | number | string>>;
-    protected constructor(params: {
+    /**
+     * Immutable structured context providing additional information about the error.
+     * Useful for debugging, logging, and creating detailed error messages.
+     *
+     * @remarks
+     * - Values must be primitive types (string, number, boolean, etc.)
+     * - Object is frozen to prevent mutation
+     * - Type-safe based on the error code
+     *
+     * @example
+     * // For UserNotFoundError:
+     * { userId: 'usr_123', attemptedAction: 'activate' }
+     *
+     * @readonly
+     */
+    readonly metadata: Readonly<Meta>;
+    /**
+     * Category of domain error indicating the nature of violation.
+     *
+     * @remarks
+     * Use 'DOMAIN.INVALID_STATE' for state violations (e.g., "Cannot checkout empty cart")
+     * Use 'DOMAIN.INVALID_VALUE' for value violations (e.g., "Email format is invalid")
+     *
+     * @example
+     * public readonly type: DomainErrorType = 'DOMAIN.INVALID_VALUE';
+     */
+    abstract readonly type: DomainErrorType;
+    /** Get error name from error code */
+    get errorName(): ExtractErrorName<Code>;
+    /** Get namespace from error code */
+    get namespace(): ExtractNamespace<Code>;
+    /**
+     * Creates a new DomainError instance.
+     *
+     * @param message - Human-readable description of the domain rule violation
+     * @param metadata - Optional structured context (primitive values only)
+     *
+     * @example
+     * constructor(userId: string) {
+     *   super(`User with ID '${userId}' not found`, { userId });
+     * }
+     *
+     * @example
+     * constructor(amount: number, maxLimit: number) {
+     *   super(
+     *     `Order amount $${amount} exceeds maximum limit of $${maxLimit}`,
+     *     { amount, maxLimit }
+     *   );
+     * }
+     */
+    protected constructor(message: string, ...args: keyof Meta extends never ? [] | [metadata?: Meta] : [metadata: Meta]);
+    /**
+     * Serializes the error to a plain object for debugging, logging, or transport.
+     * Does not include infrastructure concerns like stack traces or timestamps.
+     *
+     * @returns Plain object with error details
+     *
+     * @example
+     * const error = new UserNotFoundError('usr_123');
+     * const json = error.toJSON();
+     * // Result:
+     * // {
+     * //   code: 'USER.NOT_FOUND',
+     * //   message: "User with ID 'usr_123' not found",
+     * //   type: 'DOMAIN.INVALID_VALUE',
+     * //   metadata: { userId: 'usr_123' }
+     * // }
+     */
+    toObject(): {
+        metadata: Readonly<Meta>;
         message: string;
-        metadata?: Record<string, boolean | number | string>;
-    });
+        code: Code;
+        type: DomainErrorType;
+    };
+    /**
+     * Returns a string representation of the error.
+     * Format: [CODE] MESSAGE
+     *
+     * @returns Human-readable string representation
+     *
+     * @example
+     * const error = new UserNotFoundError('usr_123');
+     * console.log(error.toString());
+     * // Output: [USER.NOT_FOUND] User with ID 'usr_123' not found
+     *
+     * @override
+     */
+    toString(): string;
+}
+
+/**
+ * Default domain errors for common scenarios.
+ * These errors are available across all projects using this module.
+ */
+/**
+ * Error thrown when an unexpected internal error occurs.
+ * Typically used for programming bugs, invalid assumptions, or states that should never happen.
+ *
+ * @remarks
+ * - Metadata is optional for empty metadata types and required if a non-empty type is provided.
+ * - Useful for debugging, logging, and adding context to unexpected failures.
+ *
+ * @example
+ * // Catch a programming error:
+ * try {
+ *   complexBusinessLogic();
+ * } catch (error) {
+ *   throw new InternalError({
+ *     message: 'Unexpected error in complexBusinessLogic',
+ *     metadata: { originalError: error.message, timestamp: Date.now() }
+ *   });
+ * }
+ *
+ * @example
+ * // Fallback for unhandled cases:
+ * switch (status) {
+ *   case 'PENDING':
+ *     break;
+ *   case 'COMPLETED':
+ *     break;
+ *   default:
+ *     throw new InternalError({
+ *       message: `Unhandled status: ${status}`,
+ *       metadata: { status }
+ *     });
+ * }
+ */
+declare class InternalError<T = Record<string, Primitive>> extends DomainError<Metadata<T>> {
+    /** @inheritdoc */
+    readonly code: "CORE.INTERNAL_ERROR";
+    /** @inheritdoc */
+    readonly type: DomainErrorType;
+    /**
+     * Creates a new InternalError.
+     *
+     * @param message - Description of the internal error
+     * @param metadata - Optional debug information
+     */
+    constructor(message?: string, metadata?: Metadata<T>);
+}
+
+/**
+ * Error thrown when an operation times out.
+ * Use for operations that exceed their allowed execution time.
+ *
+ * @example
+ * // Operation timeout:
+ * const timeout = setTimeout(() => {
+ *   throw new TimeoutError(
+ *     'User registration timed out'
+ *   );
+ * }, 5000);
+ *
+ * @example
+ * // With Promise.race:
+ * type Props = { url: string, timeoutMs: number }
+ * async function fetchWithTimeout(url: string, timeoutMs: number) {
+ *   const timeoutPromise = new Promise<never>((_, reject) => {
+ *     setTimeout(() => {
+ *       reject(new TimeoutError<Props>(
+ *         `Request to ${url} timed out`,
+ *         { url, timeoutMs }
+ *       ));
+ *     }, timeoutMs);
+ *   });
+ *
+ *   return await Promise.race([fetch(url), timeoutPromise]);
+ * }
+ */
+declare class TimeoutError<T = Record<string, Primitive>> extends DomainError<Metadata<T>> {
+    /** @inheritdoc */
+    readonly code: "SYSTEM.TIMEOUT";
+    /** @inheritdoc */
+    readonly type: DomainErrorType;
+    /**
+     * Creates a new TimeoutError.
+     *
+     * @param message - Description of the timeout
+     * @param metadata - Optional timeout context
+     */
+    constructor(message: string, metadata?: Metadata<T>);
 }
-type DomainErrorCode = 'DOMAIN.INVALID_STATE' | 'DOMAIN.INVALID_VALUE';
 
 /**
  * Represents the result of an operation, which can be either a success or a failure.
@@ -878,64 +1135,138 @@ declare class Result<T, E> {
 }
 
 /**
- * Utility to deeply freeze objects to ensure immutability - handles nested objects and arrays.
+ * Custom error class for entity validation failures.
+ */
+declare class EntityValidationError extends DomainError {
+    code: DomainErrorCode;
+    type: DomainErrorType;
+    static create(msg: string): EntityValidationError;
+}
+
+type Params = {
+    value: string;
+};
+type Props = Metadata<Params>;
+declare class InvalidValueObjectError extends DomainError<Props> {
+    code: DomainErrorCode;
+    type: DomainErrorType;
+    static create(msg?: string, meta?: Props): InvalidValueObjectError;
+}
+
+/**
+ * Represents a UUID (Universally Unique Identifier) value object.
+ *
+ * This class extends PrimitiveValueObject to provide type-safe UUID handling
+ * with validation using Zod schema. UUIDs are immutable and can be generated
+ * randomly or created from string values.
+ * @deprecated
+ * @example
+ * // Generate a new random UUID
+ * const id = UUID.generate();
+ *
+ * @example
+ * // Create UUID from an existing string
+ * const id = UUID.fromString('550e8400-e29b-41d4-a716-446655440000');
  *
- * @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.
+ * @throws {InvalidValueObjectError} When the provided string is not a valid UUID format
  */
-declare function deepFreeze<T>(obj: T, seen?: WeakSet<object>): Readonly<T>;
+declare class UUID extends PrimitiveValueObject<string> {
+    private static readonly schema;
+    constructor(value: string);
+    /**
+     * Creates an UUID from an external string.
+     * Use only for untrusted input.
+     *
+     * @param value - UUID string
+     */
+    static fromString(value: string): UUID;
+    /**
+     * Generates a new AggregateId.
+     */
+    static generate<T extends typeof UUID>(this: T): InstanceType<T>;
+    protected validate(value: string): void;
+}
 
-interface ErrorParams {
-    message: string;
-    code: HttpStatusMessage;
-    status?: HttpStatusCode;
-    metadata?: Record<string, unknown> | undefined;
-    isOperational?: boolean;
-    cause?: Error | undefined;
+/**
+ * AggregateId represents a strongly-typed aggregate identifier.
+ *
+ * - Backed by UUID v4
+ * - Immutable
+ * - Comparable only to AggregateId
+ */
+declare class AggregateId extends UUID {
 }
+
 /**
- * Abstract base class for application-level errors with structured error handling.
+ * UUID is a branded string type.
  *
- * Extends the native Error class to provide machine-readable error codes, HTTP status codes,
- * operational error classification, and optional metadata for better error tracking and client communication.
+ * - Prevents accidental use of arbitrary strings
+ * - Requires explicit validation or construction
+ * - Zero runtime cost after creation
+ */
+type UuID = Tagged<string, 'UUID'>;
+/**
+ * Abstract base class for all domain identifiers.
  *
- * @abstract
- * @extends {Error}
+ * Responsibilities:
+ * - Enforces that every DomainID wraps a primitive string value.
+ * - Provides a type-safe static factory `fromString` for creating concrete IDs.
+ * - Leaves domain-specific validation to subclasses via `validate`.
  *
- * @example
- * ```typescript
- * class UserNotFoundError extends ApplicationError {
- *   constructor(userId: string) {
- *     super({
- *       code: HttpStatusMessage['404'],
- *       status: 404,
- *       isOperational: true,
- *       message: `User with id ${userId} not found`,
- *       metadata: { userId }
- *     });
+ * Design Notes:
+ * - The class cannot know how to validate the ID itself, because validation
+ *   rules differ between ID types (e.g., UUID v4, ULID, NanoID).
+ * - Static factory uses `new this(value)` pattern; hence, base class is **not abstract** in TypeScript terms.
+ * - Subclasses must implement `validate(value: string)` inherited from PrimitiveValueObject.
+ *
+ * Usage:
+ * ```ts
+ * class AuthAttemptId extends DomainID {
+ *   protected validate(value: string): void {
+ *     if (!isValidUuid(value)) {
+ *       throw new Error('Invalid AuthAttemptId');
+ *     }
  *   }
  * }
+ *
+ * const id = AuthAttemptId.fromString('550e8400-e29b-41d4-a716-446655440000');
  * ```
  */
-declare abstract class ApplicationError extends Error {
-    /** Optional cause (linked error) */
-    readonly cause?: Error | undefined;
-    /** Machine-readable error code (e.g. `OTP_LOCKED`, `USER_NOT_FOUND`) */
-    readonly code: HttpStatusMessage;
-    /** Operational vs programmer error flag */
-    readonly isOperational: boolean;
-    /** Optional structured metadata for debugging or clients */
-    readonly metadata?: Record<string, unknown> | undefined;
-    /** HTTP status code intended for response layer */
-    readonly status: HttpStatusCode;
-    constructor({ code, isOperational, status, metadata, message, cause, }: ErrorParams);
+declare abstract class DomainID extends PrimitiveValueObject<UuID> {
+    static schema: z.ZodUUID;
+    constructor(value: string);
+    /**
+     * Creates a concrete DomainID from a trusted string value.
+     *
+     * - Validation is enforced in the subclass constructor.
+     * - Intended for application or infrastructure layers to produce IDs.
+     *
+     * @template T - Concrete subclass of DomainID
+     * @param this - The constructor of the concrete subclass
+     * @param value - Raw string value of the ID
+     * @returns Instance of the concrete DomainID subclass
+     */
+    static fromString<T extends new (value: string) => DomainID>(this: T, value: string): InstanceType<T>;
+    static generate<T extends new (value: string) => DomainID>(this: T): InstanceType<T>;
+    protected validate(value: UuID): 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;
+declare class Email extends PrimitiveValueObject<string> {
+    private static readonly schema;
+    constructor(value: string);
+    static fromString(value: string): Email;
+    protected validate(value: string): void;
+}
+
+/**
+ * Deeply freezes an object graph to enforce runtime immutability.
+ * - Handles arrays
+ * - Handles circular references
+ * - Skips functions
+ * - Skips already frozen objects
+ *
+ * Intended for aggregate and value object state only.
+ */
+declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): Readonly<T>;
 
-export { AggregateId, AggregateRoot, ApplicationError, type ApplicationServicePort, DomainError$1 as DomainError, type DomainErrorMetadata, DomainEvent, type DomainEventPayload, Entity, type EntityId, type EntityProps, EntityValidationError, HttpStatus, type HttpStatusCode, HttpStatusMessage, InvalidValueObjectError, PrimitiveValueObject, type Props, Result, UUID, type UnixTimestampMillis, type UnwrapValueObject, ValueObject, deepFreeze, ensureObject, unwrapValueObject };
+export { AggregateId, AggregateRoot, ApplicationError, type ApplicationServicePort, type CreateEventProps, DomainError, type DomainErrorCode, type DomainErrorNamespaces, type DomainErrorType, DomainEvent, type DomainEventPayload, DomainID, Email, Entity, type EntityId, type EntityProps, EntityValidationError, type ExtractErrorName, type ExtractNamespace, HttpStatus, type HttpStatusCode, HttpStatusMessage, type Immutable, InternalError, InvalidValueObjectError, type Metadata, type Primitive, PrimitiveValueObject, Result, TimeoutError, UUID, type UnionToIntersection, type UnixTimestampMillis, type UuID, ValueObject, type ValueOf, deepFreeze };