better_model 2.1.0 → 3.0.0

data/lib/better_model/validatable/configurator.rb

@@ -2,56 +2,45 @@
 
 module BetterModel
   module Validatable
-    # Configurator per il DSL di Validatable
+    # Configurator for Validatable DSL.
     #
-    # Questo configurator permette di definire validazioni in modo dichiarativo
-    # all'interno del blocco `validatable do...end`.
+    # This configurator enables defining validations declaratively
+    # within the `validatable do...end` block.
     #
-    # Esempio:
+    # @example
     #   validatable do
-    #     # Validazioni base
+    #     # Basic validations
     #     check :title, :content, presence: true
     #     check :email, format: { with: URI::MailTo::EMAIL_REGEXP }
     #
-    #     # Validazioni condizionali
-    #     validate_if :is_published? do
-    #       check :published_at, presence: true
-    #       check :author_id, presence: true
-    #     end
+    #     # Complex validations
+    #     check_complex :valid_pricing
+    #     check_complex :stock_check
     #
-    #     # Validazioni condizionali negate
-    #     validate_unless :is_draft? do
-    #       check :reviewer_id, presence: true
-    #     end
-    #
-    #     # Cross-field validations
-    #     validate_order :starts_at, :before, :ends_at
-    #     validate_order :min_price, :lteq, :max_price
-    #
-    #     # Business rules
-    #     validate_business_rule :valid_category
-    #     validate_business_rule :author_has_permission, on: :create
-    #
-    #     # Gruppi di validazioni
+    #     # Validation groups
     #     validation_group :step1, [:email, :password]
     #     validation_group :step2, [:first_name, :last_name]
     #   end
     #
+    # @api private
     class Configurator
       attr_reader :groups
 
+      # Initialize a new Configurator.
+      #
+      # @param model_class [Class] Model class being configured
       def initialize(model_class)
         @model_class = model_class
-        @conditional_validations = []
-        @order_validations = []
-        @business_rules = []
+        @complex_validations = []
         @groups = {}
       end
 
-      # Definisce validazioni standard sui campi
+      # Define standard validations on fields.
+      #
+      # Delegates to ActiveRecord's validates method.
       #
-      # @param fields [Array<Symbol>] Nomi dei campi
-      # @param options [Hash] Opzioni di validazione (presence, format, etc.)
+      # @param fields [Array<Symbol>] Field names
+      # @param options [Hash] Validation options (presence, format, etc.)
       #
       # @example
       #   check :title, :content, presence: true
@@ -59,164 +48,54 @@ module BetterModel
       #   check :age, numericality: { greater_than: 0 }
       #
       def check(*fields, **options)
-        # Se siamo dentro un blocco condizionale, aggiungi alla condizione corrente
-        if @current_conditional
-          @current_conditional[:validations] << {
-            fields: fields,
-            options: options
-          }
-        else
-          # Altrimenti applica direttamente alla classe
-          # Questo viene fatto subito, non in apply_validatable_config
-          @model_class.validates(*fields, **options)
-        end
-      end
-
-      # Validazioni condizionali (se condizione è vera)
-      #
-      # @param condition [Symbol, Proc] Condizione da verificare
-      # @yield Blocco con validazioni da applicare se condizione è vera
-      #
-      # @example Con simbolo (metodo)
-      #   validate_if :is_published? do
-      #     check :published_at, presence: true
-      #   end
-      #
-      # @example Con lambda
-      #   validate_if -> { status == "published" } do
-      #     check :published_at, presence: true
-      #   end
-      #
-      def validate_if(condition, &block)
-        raise ArgumentError, "validate_if requires a block" unless block_given?
-
-        conditional = {
-          condition: condition,
-          negate: false,
-          validations: []
-        }
-
-        # Set current conditional per catturare le validate dentro il blocco
-        @current_conditional = conditional
-        instance_eval(&block)
-        @current_conditional = nil
-
-        @conditional_validations << conditional
-      end
-
-      # Validazioni condizionali negate (se condizione è falsa)
-      #
-      # @param condition [Symbol, Proc] Condizione da verificare
-      # @yield Blocco con validazioni da applicare se condizione è falsa
-      #
-      # @example
-      #   validate_unless :is_draft? do
-      #     check :reviewer_id, presence: true
-      #   end
-      #
-      def validate_unless(condition, &block)
-        raise ArgumentError, "validate_unless requires a block" unless block_given?
-
-        conditional = {
-          condition: condition,
-          negate: true,
-          validations: []
-        }
-
-        @current_conditional = conditional
-        instance_eval(&block)
-        @current_conditional = nil
-
-        @conditional_validations << conditional
+        @model_class.validates(*fields, **options)
       end
 
-      # Validazione di ordine tra campi (cross-field)
-      #
-      # Verifica che un campo sia in una relazione d'ordine rispetto ad un altro.
-      #
-      # @param first_field [Symbol] Primo campo
-      # @param comparator [Symbol] Comparatore (:before, :after, :lteq, :gteq)
-      # @param second_field [Symbol] Secondo campo
-      # @param options [Hash] Opzioni aggiuntive (on, if, unless, message)
-      #
-      # @example Date validation
-      #   validate_order :starts_at, :before, :ends_at
-      #   validate_order :starts_at, :before, :ends_at, message: "must be before end date"
-      #
-      # @example Numeric validation
-      #   validate_order :min_price, :lteq, :max_price
-      #   validate_order :discount, :lteq, :price, on: :create
-      #
-      # Comparatori supportati:
-      # - :before - first < second (date/time)
-      # - :after - first > second (date/time)
-      # - :lteq - first <= second (numeric)
-      # - :gteq - first >= second (numeric)
-      # - :lt - first < second (numeric)
-      # - :gt - first > second (numeric)
-      #
-      def validate_order(first_field, comparator, second_field, **options)
-        valid_comparators = %i[before after lteq gteq lt gt]
-        unless valid_comparators.include?(comparator)
-          raise ArgumentError, "Invalid comparator: #{comparator}. Valid: #{valid_comparators.join(', ')}"
-        end
-
-        @order_validations << {
-          first_field: first_field,
-          comparator: comparator,
-          second_field: second_field,
-          options: options
-        }
-      end
-
-      # Definisce una business rule custom
+      # Use a registered complex validation.
       #
-      # Le business rules sono metodi custom che implementano logica di validazione
-      # complessa che non può essere espressa con validatori standard.
+      # Complex validations must be registered first using
+      # register_complex_validation in the model.
       #
-      # @param rule_name [Symbol] Nome del metodo che implementa la rule
-      # @param options [Hash] Opzioni (on, if, unless)
+      # @param name [Symbol] Name of registered complex validation
+      # @raise [ArgumentError] If validation is not registered
       #
       # @example
-      #   # Nel configurator:
-      #   validate_business_rule :valid_category
-      #   validate_business_rule :author_has_permission, on: :create
-      #
-      #   # Nel modello (implementazione):
-      #   def valid_category
-      #     unless Category.exists?(id: category_id)
-      #       errors.add(:category_id, "must be a valid category")
+      #   # In model (registration):
+      #   register_complex_validation :valid_pricing do
+      #     if sale_price.present? && sale_price >= price
+      #       errors.add(:sale_price, "must be less than regular price")
       #     end
       #   end
       #
-      #   def author_has_permission
-      #     unless author&.can_create_articles?
-      #       errors.add(:author_id, "does not have permission")
-      #     end
+      #   # In configurator (usage):
+      #   validatable do
+      #     check_complex :valid_pricing
       #   end
       #
-      def validate_business_rule(rule_name, **options)
-        @business_rules << {
-          name: rule_name,
-          options: options
-        }
+      def check_complex(name)
+        unless @model_class.complex_validation?(name)
+          raise ArgumentError, "Unknown complex validation: #{name}. Use register_complex_validation to define it first."
+        end
+
+        @complex_validations << name.to_sym
       end
 
-      # Definisce un gruppo di validazioni
+      # Define a validation group.
       #
-      # I gruppi permettono di validare solo un sottoinsieme di campi,
-      # utile per form multi-step o validazioni parziali.
+      # Groups allow validating only a subset of fields,
+      # useful for multi-step forms or partial validations.
       #
-      # @param group_name [Symbol] Nome del gruppo
-      # @param fields [Array<Symbol>] Campi inclusi nel gruppo
+      # @param group_name [Symbol] Group name
+      # @param fields [Array<Symbol>] Fields included in group
+      # @raise [ArgumentError] If group name is invalid, fields not array, or group already defined
       #
       # @example
       #   validation_group :step1, [:email, :password]
       #   validation_group :step2, [:first_name, :last_name]
       #   validation_group :step3, [:address, :city, :zip_code]
       #
-      #   # Utilizzo:
-      #   user.valid?(:step1)  # Valida solo email e password
+      # @example Usage
+      #   user.valid?(:step1)  # Validate only email and password
       #   user.errors_for_group(:step1)
       #
       def validation_group(group_name, fields)
@@ -230,14 +109,12 @@ module BetterModel
         }
       end
 
-      # Restituisce la configurazione completa
+      # Return complete configuration.
       #
-      # @return [Hash] Configurazione con tutte le validazioni
+      # @return [Hash] Configuration with all validations
       def to_h
         {
-          conditional_validations: @conditional_validations,
-          order_validations: @order_validations,
-          business_rules: @business_rules
+          complex_validations: @complex_validations
         }
       end
     end

data/lib/better_model/validatable.rb

@@ -1,56 +1,62 @@
 # frozen_string_literal: true
 
-# Validatable - Sistema di validazioni dichiarativo per modelli Rails
+require_relative "errors/validatable/validatable_error"
+require_relative "errors/validatable/not_enabled_error"
+require_relative "errors/validatable/configuration_error"
+
+# Validatable - Declarative validation system for Rails models.
 #
-# Questo concern permette di definire validazioni in modo dichiarativo e leggibile,
-# con supporto per validazioni condizionali, gruppi, cross-field e business rules.
+# This concern enables defining validations declaratively and readably,
+# with support for conditional validations, groups, cross-field, and business rules.
 #
-# APPROCCIO OPT-IN: Le validazioni dichiarative non sono attive automaticamente.
-# Devi chiamare esplicitamente `validatable do...end` nel tuo modello.
+# @note OPT-IN APPROACH
+#   Declarative validations are not enabled automatically.
+#   You must explicitly call `validatable do...end` in your model.
 #
-# Esempio di utilizzo:
+# @example Basic Usage
 #   class Article < ApplicationRecord
 #     include BetterModel
 #
-#     # Status (già esistente in Statusable)
+#     # Status (from Statusable)
 #     is :draft, -> { status == "draft" }
 #     is :published, -> { status == "published" }
 #
-#     # Attiva validatable (opt-in)
-#     validatable do
-#       # Validazioni base
-#       validate :title, :content, presence: true
+#     # Register complex validations
+#     register_complex_validation :valid_date_range do
+#       return if starts_at.blank? || ends_at.blank?
+#       errors.add(:starts_at, "must be before end date") if starts_at >= ends_at
+#     end
 #
-#       # Validazioni condizionali
-#       validate_if :is_published? do
-#         validate :published_at, presence: true
-#         validate :author_id, presence: true
-#       end
+#     # Enable validatable (opt-in)
+#     validatable do
+#       # Basic validations
+#       check :title, :content, presence: true
 #
-#       # Cross-field validations
-#       validate_order :starts_at, :before, :ends_at
+#       # Conditional validations (using Rails options)
+#       check :published_at, presence: true, if: -> { status == "published" }
+#       check :author_id, presence: true, if: :is_published?
 #
-#       # Business rules
-#       validate_business_rule :valid_category
+#       # Complex validations for cross-field and business logic
+#       check_complex :valid_date_range
 #
-#       # Gruppi di validazioni
+#       # Validation groups
 #       validation_group :step1, [:email, :password]
 #       validation_group :step2, [:first_name, :last_name]
 #     end
 #   end
 #
-# Utilizzo:
-#   article.valid?           # Tutte le validazioni
-#   article.valid?(:step1)   # Solo gruppo step1
+# @example Validation Usage
+#   article.valid?           # All validations
+#   article.valid?(:step1)   # Only step1 group
 #
 module BetterModel
   module Validatable
     extend ActiveSupport::Concern
 
     included do
-      # Validazione ActiveRecord
+      # Validate ActiveRecord inheritance
       unless ancestors.include?(ActiveRecord::Base)
-        raise ArgumentError, "BetterModel::Validatable can only be included in ActiveRecord models"
+        raise BetterModel::Errors::Validatable::ConfigurationError, "Invalid configuration"
       end
 
       # Configurazione validatable (opt-in)
@@ -58,6 +64,8 @@ module BetterModel
       class_attribute :validatable_config, default: {}.freeze
       class_attribute :validatable_groups, default: {}.freeze
       class_attribute :_validatable_setup_done, default: false
+      # Registry dei complex validations custom
+      class_attribute :complex_validations_registry, default: {}.freeze
     end
 
     class_methods do
@@ -65,14 +73,12 @@ module BetterModel
       #
       # @example Attivazione base
       #   validatable do
-      #     validate :title, presence: true
+      #     check :title, presence: true
       #   end
       #
       # @example Con validazioni condizionali
       #   validatable do
-      #     validate_if :is_published? do
-      #       validate :published_at, presence: true
-      #     end
+      #     check :published_at, presence: true, if: :is_published?
       #   end
       #
       def validatable(&block)
@@ -99,98 +105,71 @@ module BetterModel
       # Verifica se validatable è attivo
       #
       # @return [Boolean]
-      def validatable_enabled?
-        validatable_enabled == true
+      def validatable_enabled? = validatable_enabled == true
+
+      # Registra una validazione complessa custom
+      #
+      # Permette di definire validazioni complesse riutilizzabili che possono combinare
+      # più campi o utilizzare logica custom non coperta dalle validazioni standard.
+      #
+      # @param name [Symbol] il nome della validazione
+      # @param block [Proc] il blocco di validazione che verrà eseguito nel contesto dell'istanza
+      #
+      # @example Validazione complessa base
+      #   register_complex_validation :valid_pricing do
+      #     if sale_price.present? && sale_price >= price
+      #       errors.add(:sale_price, "must be less than regular price")
+      #     end
+      #   end
+      #
+      # @example Con logica multi-campo
+      #   register_complex_validation :valid_dates do
+      #     if starts_at.present? && ends_at.present? && starts_at >= ends_at
+      #       errors.add(:ends_at, "must be after start date")
+      #     end
+      #   end
+      #
+      def register_complex_validation(name, &block)
+        unless block_given?
+          raise BetterModel::Errors::Validatable::ConfigurationError, "Invalid configuration"
+        end
+
+        # Registra nel registry
+        self.complex_validations_registry = complex_validations_registry.merge(name.to_sym => block).freeze
       end
 
+      # Verifica se una validazione complessa è stata registrata
+      #
+      # @param name [Symbol] il nome della validazione
+      # @return [Boolean]
+      def complex_validation?(name) = complex_validations_registry.key?(name.to_sym)
+
       private
 
       # Applica le configurazioni di validazione al modello
       def apply_validatable_config
         return unless validatable_config.present?
 
-        # Apply conditional validations
-        validatable_config[:conditional_validations]&.each do |conditional|
-          apply_conditional_validation(conditional)
-        end
-
-        # Apply order validations
-        validatable_config[:order_validations]&.each do |order_val|
-          apply_order_validation(order_val)
-        end
-
-        # Apply business rules
-        validatable_config[:business_rules]&.each do |rule|
-          apply_business_rule(rule)
+        # Apply complex validations
+        validatable_config[:complex_validations]&.each do |name|
+          apply_complex_validation(name)
         end
       end
 
-      # Applica una validazione condizionale
-      def apply_conditional_validation(conditional)
-        condition = conditional[:condition]
-        negate = conditional[:negate]
-        validations = conditional[:validations]
+      # Applica una validazione complessa
+      def apply_complex_validation(name)
+        block = complex_validations_registry[name]
+        return unless block
 
-        # Create a custom validator for this conditional block
+        # Crea un validator custom per questa validazione complessa
         validate do
-          condition_met = if condition.is_a?(Symbol)
-                            send(condition)
-          elsif condition.is_a?(Proc)
-                            instance_exec(&condition)
-          else
-                            raise ArgumentError, "Condition must be a Symbol or Proc"
-          end
-
-          condition_met = !condition_met if negate
-
-          if condition_met
-            validations.each do |validation|
-              apply_validation_in_context(validation)
-            end
-          end
+          instance_eval(&block)
         end
       end
-
-      # Applica una validazione order (cross-field)
-      def apply_order_validation(order_val)
-        validates_with BetterModel::Validatable::OrderValidator,
-                       attributes: [ order_val[:first_field] ],
-                       second_field: order_val[:second_field],
-                       comparator: order_val[:comparator],
-                       **order_val[:options]
-      end
-
-      # Applica una business rule
-      def apply_business_rule(rule)
-        validates_with BetterModel::Validatable::BusinessRuleValidator,
-                       rule_name: rule[:name],
-                       **rule[:options]
-      end
     end
 
     # Metodi di istanza
 
-    # Apply a validation in the context of the current instance
-    def apply_validation_in_context(validation)
-      fields = validation[:fields]
-      options = validation[:options]
-
-      fields.each do |field|
-        options.each do |validator_type, validator_options|
-          # Prepare validator options
-          # If validator_options is true, convert to empty hash
-          # If it's a hash, use as-is
-          opts = validator_options.is_a?(Hash) ? validator_options : {}
-
-          validator = ActiveModel::Validations.const_get("#{validator_type.to_s.camelize}Validator").new(
-            attributes: [ field ],
-            **opts
-          )
-          validator.validate(self)
-        end
-      end
-    end
-
     # Override valid? per supportare validation groups
     #
     # @param context [Symbol, nil] Context o gruppo di validazione
@@ -210,7 +189,9 @@ module BetterModel
     # @param group_name [Symbol] Nome del gruppo
     # @return [Boolean]
     def validate_group(group_name)
-      raise ValidatableNotEnabledError unless self.class.validatable_enabled?
+      unless self.class.validatable_enabled?
+        raise BetterModel::Errors::Validatable::NotEnabledError, "Module is not enabled"
+      end
 
       group = self.class.validatable_groups[group_name]
       return false unless group
@@ -231,7 +212,9 @@ module BetterModel
     # @param group_name [Symbol] Nome del gruppo
     # @return [ActiveModel::Errors]
     def errors_for_group(group_name)
-      raise ValidatableNotEnabledError unless self.class.validatable_enabled?
+      unless self.class.validatable_enabled?
+        raise BetterModel::Errors::Validatable::NotEnabledError, "Module is not enabled"
+      end
 
       group = self.class.validatable_groups[group_name]
       return errors unless group
@@ -259,12 +242,4 @@ module BetterModel
     end
   end
 
-  # Errori custom
-  class ValidatableError < StandardError; end
-
-  class ValidatableNotEnabledError < ValidatableError
-    def initialize(msg = nil)
-      super(msg || "Validatable is not enabled. Add 'validatable do...end' to your model.")
-    end
-  end
 end

data/lib/better_model/version.rb

@@ -1,3 +1,3 @@
 module BetterModel
-  VERSION = "2.1.0"
+  VERSION = "3.0.0"
 end

data/lib/better_model.rb

@@ -1,24 +1,61 @@
 require "better_model/version"
 require "better_model/railtie"
+
+# Load all error classes first
+require "better_model/errors/better_model_error"
+require "better_model/errors/archivable/archivable_error"
+require "better_model/errors/archivable/already_archived_error"
+require "better_model/errors/archivable/not_archived_error"
+require "better_model/errors/archivable/not_enabled_error"
+require "better_model/errors/validatable/validatable_error"
+require "better_model/errors/validatable/not_enabled_error"
+require "better_model/errors/traceable/traceable_error"
+require "better_model/errors/traceable/not_enabled_error"
+require "better_model/errors/searchable/searchable_error"
+require "better_model/errors/searchable/invalid_predicate_error"
+require "better_model/errors/searchable/invalid_order_error"
+require "better_model/errors/searchable/invalid_pagination_error"
+require "better_model/errors/searchable/invalid_security_error"
+require "better_model/errors/stateable/stateable_error"
+require "better_model/errors/stateable/not_enabled_error"
+require "better_model/errors/stateable/invalid_state_error"
+require "better_model/errors/stateable/invalid_transition_error"
+require "better_model/errors/stateable/check_failed_error"
+require "better_model/errors/stateable/validation_failed_error"
+require "better_model/errors/stateable/configuration_error"
+require "better_model/errors/archivable/configuration_error"
+require "better_model/errors/validatable/configuration_error"
+require "better_model/errors/traceable/configuration_error"
+require "better_model/errors/searchable/configuration_error"
+require "better_model/errors/predicable/predicable_error"
+require "better_model/errors/predicable/configuration_error"
+require "better_model/errors/sortable/sortable_error"
+require "better_model/errors/sortable/configuration_error"
+require "better_model/errors/statusable/statusable_error"
+require "better_model/errors/statusable/configuration_error"
+require "better_model/errors/permissible/permissible_error"
+require "better_model/errors/permissible/configuration_error"
+require "better_model/errors/taggable/taggable_error"
+require "better_model/errors/taggable/configuration_error"
+
+# Load modules
 require "better_model/statusable"
 require "better_model/permissible"
 require "better_model/sortable"
 require "better_model/predicable"
 require "better_model/searchable"
 require "better_model/archivable"
-require "better_model/version_record"
+require "better_model/models/version"
 require "better_model/traceable"
 require "better_model/validatable"
 require "better_model/validatable/configurator"
-require "better_model/validatable/order_validator"
-require "better_model/validatable/business_rule_validator"
-require "better_model/state_transition"
+require "better_model/models/state_transition"
 require "better_model/stateable"
 require "better_model/stateable/configurator"
-require "better_model/stateable/errors"
 require "better_model/stateable/guard"
 require "better_model/stateable/transition"
 require "better_model/taggable"
+require "better_model/repositable"
 
 module BetterModel
   extend ActiveSupport::Concern