cmdx 1.0.0 → 1.1.0

data/lib/cmdx/error.rb

@@ -2,224 +2,59 @@
 
 module CMDx
 
-  ##
-  # Base exception class for all CMDx-specific errors.
-  # All other CMDx exceptions inherit from this class, providing a common
-  # hierarchy for error handling and rescue operations.
+  # Base exception class for all CMDx-related errors.
   #
-  # This allows for catching all CMDx-related exceptions with a single rescue clause
-  # while still maintaining specific error types for detailed error handling.
-  #
-  # @example Catching all CMDx errors
-  #   begin
-  #     ProcessOrderTask.call(invalid_params)
-  #   rescue CMDx::Error => e
-  #     logger.error "CMDx error occurred: #{e.message}"
-  #   end
-  #
-  # @example Specific error handling
-  #   begin
-  #     ProcessOrderTask.call(order_id: "invalid")
-  #   rescue CMDx::CoercionError => e
-  #     # Handle type coercion failures
-  #   rescue CMDx::ValidationError => e
-  #     # Handle validation failures
-  #   rescue CMDx::Error => e
-  #     # Handle any other CMDx errors
-  #   end
-  #
-  # @see StandardError Ruby's standard error base class
-  # @since 1.0.0
+  # This serves as the root exception class for all errors raised by the CMDx
+  # framework. It inherits from StandardError and provides a common base for
+  # handling CMDx-specific exceptions.
   Error = Class.new(StandardError)
 
-  ##
-  # Raised when a value cannot be coerced to the specified type.
-  # This exception occurs during parameter processing when type coercion fails,
-  # typically due to incompatible data formats or invalid input values.
-  #
-  # CoercionError is raised by the various coercion modules when they encounter
-  # values that cannot be converted to the target type. Each coercion module
-  # provides specific error messages indicating the expected type and the
-  # problematic value.
-  #
-  # @example Integer coercion failure
-  #   class MyTask < CMDx::Task
-  #     required :count, type: :integer
-  #   end
-  #
-  #   # This will raise CoercionError during parameter processing
-  #   MyTask.call(count: "not_a_number")
-  #   # => CMDx::CoercionError: could not coerce into an integer
-  #
-  # @example Date coercion failure
-  #   class ScheduleTask < CMDx::Task
-  #     required :due_date, type: :date
-  #   end
-  #
-  #   ScheduleTask.call(due_date: "invalid_date")
-  #   # => CMDx::CoercionError: could not coerce into a date
+  # Raised when parameter coercion fails during task execution.
   #
-  # @example Handling coercion errors
-  #   begin
-  #     MyTask.call(count: "invalid")
-  #   rescue CMDx::CoercionError => e
-  #     # Log the coercion failure and provide user-friendly message
-  #     logger.warn "Invalid input format: #{e.message}"
-  #     render json: { error: "Please provide a valid number" }
-  #   end
-  #
-  # @see Parameter Parameter type definitions and coercion
-  # @see ParameterValue Parameter value processing and coercion
-  # @since 1.0.0
+  # This error occurs when a parameter value cannot be converted to the expected
+  # type using the registered coercion handlers. It indicates that the provided
+  # value is incompatible with the parameter's defined type.
   CoercionError = Class.new(Error)
 
-  ##
-  # Raised when a task class doesn't implement the required `call` method.
-  # This exception enforces the CMDx contract that all task classes must
-  # provide a `call` method containing their business logic.
-  #
-  # This error typically occurs during development when creating new task
-  # classes that inherit from CMDx::Task but forget to implement the
-  # abstract `call` method.
-  #
-  # @example Missing call method
-  #   class IncompleteTask < CMDx::Task
-  #     required :data, type: :string
-  #     # Missing call method implementation
-  #   end
-  #
-  #   IncompleteTask.call(data: "test")
-  #   # => CMDx::UndefinedCallError: call method not defined in IncompleteTask
+  # Raised when a deprecated task is used.
   #
-  # @example Proper task implementation
-  #   class CompleteTask < CMDx::Task
-  #     required :data, type: :string
-  #
-  #     def call
-  #       # Business logic implementation
-  #       context.result = process(data)
-  #     end
-  #   end
-  #
-  # @example Handling undefined call errors
-  #   begin
-  #     SomeTask.call(params)
-  #   rescue CMDx::UndefinedCallError => e
-  #     # This should typically only happen during development
-  #     logger.error "Task implementation incomplete: #{e.message}"
-  #     raise # Re-raise as this is a programming error
-  #   end
+  # This error occurs when a deprecated task is called. It indicates that the
+  # task is no longer supported and should be replaced with a newer alternative.
+  DeprecationError = Class.new(Error)
+
+  # Raised when an abstract method is called without being implemented.
   #
-  # @see Task Task base class and call method requirement
-  # @see Workflow Workflow base class and call method requirement
-  # @since 1.0.0
+  # This error occurs when a subclass fails to implement required abstract methods
+  # such as call methods in validators, callbacks, or middleware. It indicates
+  # incomplete implementation of required functionality.
   UndefinedCallError = Class.new(Error)
 
-  ##
-  # Raised when an unknown or unsupported coercion type is specified.
-  # This exception occurs when parameter definitions reference type coercions
-  # that don't exist or aren't registered in the CMDx coercion system.
-  #
-  # This error helps catch typos in type specifications and ensures that
-  # only supported data types are used in parameter definitions.
+  # Raised when attempting to use an unregistered callback.
   #
-  # @example Unknown type specification
-  #   class MyTask < CMDx::Task
-  #     required :value, type: :unknown_type  # Typo or unsupported type
-  #   end
-  #
-  #   MyTask.call(value: "test")
-  #   # => CMDx::UnknownCoercionError: unknown coercion unknown_type
-  #
-  # @example Common typos
-  #   class TaskWithTypo < CMDx::Task
-  #     required :count, type: :integr      # Should be :integer
-  #     required :flag, type: :bool         # Should be :boolean
-  #     required :data, type: :json         # Should be :hash
-  #   end
-  #
-  # @example Supported types
-  #   class ProperTask < CMDx::Task
-  #     required :id, type: :integer
-  #     required :active, type: :boolean
-  #     required :metadata, type: :hash
-  #     required :tags, type: :array
-  #     required :name, type: :string
-  #     required :score, type: :float
-  #     required :created_at, type: :date_time
-  #   end
-  #
-  # @example Handling unknown coercion errors
-  #   begin
-  #     MyTask.call(params)
-  #   rescue CMDx::UnknownCoercionError => e
-  #     # This indicates a programming error in parameter definition
-  #     logger.error "Invalid type specification: #{e.message}"
-  #     raise # Re-raise as this should be fixed in code
-  #   end
+  # This error occurs when trying to reference a callback that hasn't been
+  # registered in the callback registry. It indicates that the callback name
+  # is not recognized or was misspelled.
+  UnknownCallbackError = Class.new(Error)
+
+  # Raised when attempting to use an unregistered coercion type.
   #
-  # @see Parameter Parameter type definitions
-  # @see ParameterValue Type coercion processing
-  # @since 1.0.0
+  # This error occurs when trying to use a parameter type that doesn't have
+  # a corresponding coercion handler registered. It indicates that the specified
+  # type is not supported by the coercion system.
   UnknownCoercionError = Class.new(Error)
 
-  ##
-  # Raised when a parameter value fails validation rules.
-  # This exception occurs during parameter processing when values don't meet
-  # the specified validation criteria, such as format requirements, length
-  # constraints, or custom validation logic.
-  #
-  # ValidationError provides detailed feedback about why validation failed,
-  # helping developers and users understand what corrections are needed.
-  #
-  # @example Presence validation failure
-  #   class CreateUserTask < CMDx::Task
-  #     required :email, type: :string, presence: true
-  #   end
-  #
-  #   CreateUserTask.call(email: "")
-  #   # => CMDx::ValidationError: cannot be empty
+  # Raised when attempting to use an unregistered validator.
   #
-  # @example Format validation failure
-  #   class ValidateEmailTask < CMDx::Task
-  #     required :email, type: :string, format: { with: /@/ }
-  #   end
-  #
-  #   ValidateEmailTask.call(email: "invalid-email")
-  #   # => CMDx::ValidationError: is an invalid format
-  #
-  # @example Length validation failure
-  #   class SetPasswordTask < CMDx::Task
-  #     required :password, type: :string, length: { min: 8 }
-  #   end
-  #
-  #   SetPasswordTask.call(password: "short")
-  #   # => CMDx::ValidationError: length must be at least 8
-  #
-  # @example Custom validation failure
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :quantity, type: :integer, custom: -> (val) { val > 0 }
-  #   end
-  #
-  #   ProcessOrderTask.call(quantity: -1)
-  #   # => CMDx::ValidationError: is not valid
-  #
-  # @example Handling validation errors
-  #   begin
-  #     CreateUserTask.call(email: "", password: "short")
-  #   rescue CMDx::ValidationError => e
-  #     # Provide user-friendly feedback
-  #     render json: {
-  #       error: "Validation failed",
-  #       message: e.message,
-  #       field: extract_field_from_context(e)
-  #     }
-  #   end
+  # This error occurs when trying to reference a validator that hasn't been
+  # registered in the validator registry. It indicates that the validator name
+  # is not recognized or was misspelled.
+  UnknownValidatorError = Class.new(Error)
+
+  # Raised when parameter validation fails during task execution.
   #
-  # @see Parameter Parameter validation options
-  # @see ParameterValue Validation processing
-  # @see Validators Validation modules (Presence, Format, Length, etc.)
-  # @since 1.0.0
+  # This error occurs when a parameter value doesn't meet the validation criteria
+  # defined by the validator. It indicates that the provided value violates
+  # business rules or data integrity constraints.
   ValidationError = Class.new(Error)
 
 end