@rineex/ddd 1.6.1 → 2.1.0

package/dist/index.d.mts

@@ -197,7 +197,7 @@ interface DomainErrorMetadata {
  *   }
  * }
  */
-declare abstract class DomainError extends Error {
+declare abstract class DomainError$1 extends Error {
     /** Stable, machine-readable error code */
     readonly code: string;
     /** Structured, immutable domain metadata */
@@ -310,11 +310,11 @@ declare abstract class ValueObject<T> {
 /**
  * Custom error class for entity validation failures.
  */
-declare class EntityValidationError extends DomainError {
+declare class EntityValidationError extends DomainError$1 {
     constructor(message: string, cause?: Error);
 }
 
-declare class InvalidValueObjectError extends DomainError {
+declare class InvalidValueObjectError extends DomainError$1 {
     constructor(message: string);
 }
 
@@ -522,138 +522,359 @@ 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.
+ * Strongly-typed domain error used in Result failures.
+ * Does NOT extend native Error on purpose — infrastructure maps to transport later.
  */
-declare abstract class DomainViolation {
-    abstract readonly code: string;
-    abstract readonly message: string;
-    readonly metadata: Readonly<Record<string, unknown>>;
-    protected constructor(metadata?: Record<string, unknown>);
+declare abstract class DomainError {
+    abstract readonly code: DomainErrorCode;
+    readonly message: string;
+    readonly metadata: Readonly<Record<string, boolean | number | string>>;
+    protected constructor(params: {
+        message: string;
+        metadata?: Record<string, boolean | number | string>;
+    });
 }
+type DomainErrorCode = 'DOMAIN.INVALID_STATE' | 'DOMAIN.INVALID_VALUE';
 
 /**
- * Represents the outcome of an operation that can either succeed or fail,
- * without relying on exceptions for control flow.
+ * Represents the result of an operation, which can be either a success or a failure.
  *
- * This pattern is commonly used in domain and application layers to make
- * success and failure states explicit, predictable, and type-safe.
+ * This is a functional programming pattern that helps avoid throwing exceptions
+ * and makes error handling explicit in the type system. It's commonly used in
+ * Domain-Driven Design (DDD) to represent domain operation outcomes.
  *
- * ## 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).
+ * @template T The type of a successful result.
+ * @template E The type of the error in case of failure (defaults to DomainError).
  *
- * @typeParam T - Type of the success value
- * @typeParam E - Type of the failure error
+ * @example
+ * ```typescript
+ * // Creating a successful result
+ * const success = Result.ok({ id: 1, name: 'John' });
+ * if (success.isSuccess) {
+ *   const user = success.getValue(); // { id: 1, name: 'John' }
+ * }
+ *
+ * // Creating a failed result
+ * const failure = Result.fail(new InvalidUserError('User not found'));
+ * if (failure.isFailure) {
+ *   const error = failure.getError(); // InvalidUserError instance
+ * }
+ * ```
  *
  * @example
- * ```ts
- * function parseNumber(input: string): Result<number, string> {
- *   const value = Number(input);
+ * ```typescript
+ * // Using in a domain service
+ * function createUser(name: string): Result<User, DomainError> {
+ *   if (!name || name.trim().length === 0) {
+ *     return Result.fail(new InvalidValueError('Name cannot be empty'));
+ *   }
  *
- *   if (Number.isNaN(value)) {
- *     return Result.fail('Invalid number');
+ *   const user = new User(name);
+ *   return Result.ok(user);
+ * }
+ *
+ * const result = createUser('John Doe');
+ * if (result.isSuccess) {
+ *   console.log('User created:', result.getValue());
+ * } else {
+ *   console.error('Failed:', result.getError()?.message);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Chaining operations
+ * function validateEmail(email: string): Result<string, DomainError> {
+ *   if (!email.includes('@')) {
+ *     return Result.fail(new InvalidValueError('Invalid email format'));
+ *   }
+ *   return Result.ok(email);
+ * }
+ *
+ * function createAccount(email: string): Result<Account, DomainError> {
+ *   const emailResult = validateEmail(email);
+ *   if (emailResult.isFailure) {
+ *     return emailResult; // Forward the error
  *   }
  *
- *   return Result.ok(value);
+ *   const account = new Account(emailResult.getValue()!);
+ *   return Result.ok(account);
  * }
+ * ```
  *
- * const result = parseNumber('42');
+ * @example
+ * ```typescript
+ * // Working with async operations
+ * async function fetchUser(id: number): Promise<Result<User, DomainError>> {
+ *   try {
+ *     const user = await userRepository.findById(id);
+ *     if (!user) {
+ *       return Result.fail(new NotFoundError(`User ${id} not found`));
+ *     }
+ *     return Result.ok(user);
+ *   } catch (error) {
+ *     return Result.fail(new SystemError('Database connection failed'));
+ *   }
+ * }
  *
+ * const result = await fetchUser(123);
  * if (result.isSuccess) {
- *   console.log(result.getValue()); // 42
+ *   // Handle success
  * } else {
- *   console.error(result.getError());
+ *   // Handle failure
  * }
  * ```
  */
 declare class Result<T, E> {
-    private readonly _value?;
-    private readonly _error?;
     /**
-     * Indicates whether the result represents a failed outcome.
+     * Indicates if the result is a failure.
      *
-     * This flag is mutually exclusive with {@link isSuccess}.
+     * @example
+     * ```typescript
+     * const result = Result.fail(new Error('Something went wrong'));
+     * if (result.isFailure) {
+     *   // Handle error case
+     *   console.error(result.getError());
+     * }
+     * ```
      */
     readonly isFailure: boolean;
     /**
-     * Indicates whether the result represents a successful outcome.
+     * Indicates if the result is a success.
      *
-     * This flag is mutually exclusive with {@link isFailure}.
+     * @example
+     * ```typescript
+     * const result = Result.ok(42);
+     * if (result.isSuccess) {
+     *   // Handle success case
+     *   const value = result.getValue(); // 42
+     * }
+     * ```
      */
     readonly isSuccess: 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)
+     * The error, if any.
+     * @private
+     */
+    private readonly _error?;
+    /**
+     * The value, if any.
+     * @private
+     */
+    private readonly _value?;
+    /**
+     * Private constructor to enforce the use of static methods.
+     * @param params.value The value on success.
+     * @param params.error The error on failure.
+     * @private
      */
     private constructor();
     /**
-     * Creates a failed {@link Result}.
+     * Creates a failed result.
      *
-     * @param error - Error describing the failure
-     * @returns A failure {@link Result} containing the provided error
+     * @template T The type of a successful result (never for failure).
+     * @template E The type of the error (defaults to DomainError).
+     * @param error The error object.
+     * @returns {Result<T, E>} A failed Result instance.
      *
      * @example
-     * ```ts
-     * return Result.fail(new ValidationError('Email is invalid'));
+     * ```typescript
+     * // With DomainError
+     * class InvalidValueError extends DomainError {
+     *   public readonly code = 'DOMAIN.INVALID_VALUE' as const;
+     *   constructor(message: string) {
+     *     super({ message });
+     *   }
+     * }
+     *
+     * const result = Result.fail(new InvalidValueError('Value must be positive'));
+     * // result.isFailure === true
+     * // result.getError() === InvalidValueError instance
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With custom error type
+     * interface ValidationError {
+     *   field: string;
+     *   message: string;
+     * }
+     *
+     * const result = Result.fail<never, ValidationError>({
+     *   field: 'email',
+     *   message: 'Invalid email format'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // In a validation function
+     * function validateAge(age: number): Result<number, DomainError> {
+     *   if (age < 0) {
+     *     return Result.fail(new InvalidValueError('Age cannot be negative'));
+     *   }
+     *   if (age > 150) {
+     *     return Result.fail(new InvalidValueError('Age seems unrealistic'));
+     *   }
+     *   return Result.ok(age);
+     * }
      * ```
      */
-    static fail<T, E>(error: E): Result<T, E>;
+    static fail<T = never, E = DomainError>(error: E): Result<T, E>;
     /**
-     * Creates a successful {@link Result}.
+     * Creates a successful result.
+     *
+     * @template T The type of the successful result.
+     * @template E The type of the error (never for success).
+     * @param value The success value.
+     * @returns {Result<T, E>} A successful Result instance.
+     *
+     * @example
+     * ```typescript
+     * // With primitive value
+     * const result = Result.ok(42);
+     * // result.isSuccess === true
+     * // result.getValue() === 42
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With object
+     * const user = { id: 1, name: 'John', email: 'john@example.com' };
+     * const result = Result.ok(user);
+     * if (result.isSuccess) {
+     *   const savedUser = result.getValue(); // { id: 1, name: 'John', ... }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With domain entity
+     * class User {
+     *   constructor(public readonly id: number, public readonly name: string) {}
+     * }
+     *
+     * function createUser(name: string): Result<User, DomainError> {
+     *   const user = new User(Date.now(), name);
+     *   return Result.ok(user);
+     * }
      *
-     * @param value - Value representing a successful outcome
-     * @returns A success {@link Result} containing the provided value
+     * const result = createUser('Alice');
+     * if (result.isSuccess) {
+     *   console.log(`Created user: ${result.getValue()?.name}`);
+     * }
+     * ```
      *
      * @example
-     * ```ts
-     * return Result.ok(user);
+     * ```typescript
+     * // With void/undefined (for operations that don't return a value)
+     * function deleteUser(id: number): Result<void, DomainError> {
+     *   // ... deletion logic ...
+     *   return Result.ok(undefined);
+     * }
+     *
+     * const result = deleteUser(123);
+     * if (result.isSuccess) {
+     *   console.log('User deleted successfully');
+     * }
      * ```
      */
-    static ok<T, E>(value: T): Result<T, E>;
+    static ok<T, E = never>(value: T): Result<T, E>;
     /**
-     * Returns the failure error.
+     * Returns the error if present, otherwise undefined.
      *
-     * @returns The error associated with a failed result
+     * **Note:** Always check `isFailure` before calling this method to ensure
+     * the result is actually a failure. This method will return `undefined` for
+     * successful results.
      *
-     * @throws {Error}
-     * Thrown if this result represents a success.
-     * This is a fail-fast guard against incorrect usage.
+     * @returns {E | undefined} The error or undefined if successful.
      *
      * @example
-     * ```ts
+     * ```typescript
+     * const result = Result.fail(new InvalidValueError('Invalid input'));
+     *
      * if (result.isFailure) {
      *   const error = result.getError();
+     *   if (error) {
+     *     console.error(`Error code: ${error.code}, Message: ${error.message}`);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Safe error handling pattern
+     * function handleResult<T>(result: Result<T, DomainError>): void {
+     *   if (result.isFailure) {
+     *     const error = result.getError();
+     *     if (error) {
+     *       // Log error with metadata
+     *       console.error({
+     *         code: error.code,
+     *         message: error.message,
+     *         metadata: error.metadata
+     *       });
+     *     }
+     *   }
      * }
      * ```
      */
-    getError(): E;
+    getError(): E | undefined;
     /**
-     * Returns the success value.
+     * Returns the value if present, otherwise undefined.
+     *
+     * **Note:** Always check `isSuccess` before calling this method to ensure
+     * the result is actually a success. This method will return `undefined` for
+     * failed results.
+     *
+     * @returns {T | undefined} The value or undefined if failed.
+     *
+     * @example
+     * ```typescript
+     * const result = Result.ok({ id: 1, name: 'John' });
      *
-     * @returns The value associated with a successful result
+     * if (result.isSuccess) {
+     *   const user = result.getValue();
+     *   if (user) {
+     *     console.log(`User: ${user.name} (ID: ${user.id})`);
+     *   }
+     * }
+     * ```
      *
-     * @throws {Error}
-     * Thrown if this result represents a failure.
-     * This is a fail-fast guard against incorrect usage.
+     * @example
+     * ```typescript
+     * // Type-safe value extraction
+     * function processUser(result: Result<User, DomainError>): void {
+     *   if (result.isSuccess) {
+     *     const user = result.getValue();
+     *     // TypeScript knows user is User | undefined here
+     *     if (user) {
+     *       // Process the user
+     *       userRepository.save(user);
+     *     }
+     *   }
+     * }
+     * ```
      *
      * @example
-     * ```ts
+     * ```typescript
+     * // Using non-null assertion (use with caution)
+     * const result = Result.ok(42);
      * if (result.isSuccess) {
-     *   const value = result.getValue();
+     *   const value = result.getValue()!; // Safe because we checked isSuccess
+     *   console.log(value * 2); // 84
      * }
      * ```
      */
-    getValue(): T;
+    getValue(): T | undefined;
+    /**
+     * Type guard for failure.
+     */
+    isFailureResult(): this is Result<never, E>;
+    /**
+     * Type guard for success.
+     */
+    isSuccessResult(): this is Result<T, never>;
 }
 
 /**
@@ -717,4 +938,4 @@ 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, 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 };
+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 };