better_model 1.0.0 → 1.2.0

data/lib/better_model/validatable/configurator.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Validatable
+    # Configurator per il DSL di Validatable
+    #
+    # Questo configurator permette di definire validazioni in modo dichiarativo
+    # all'interno del blocco `validatable do...end`.
+    #
+    # Esempio:
+    #   validatable do
+    #     # Validazioni base
+    #     validate :title, :content, presence: true
+    #     validate :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+    #
+    #     # Validazioni condizionali
+    #     validate_if :is_published? do
+    #       validate :published_at, presence: true
+    #       validate :author_id, presence: true
+    #     end
+    #
+    #     # Validazioni condizionali negate
+    #     validate_unless :is_draft? do
+    #       validate :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_group :step1, [:email, :password]
+    #     validation_group :step2, [:first_name, :last_name]
+    #   end
+    #
+    class Configurator
+      attr_reader :groups
+
+      def initialize(model_class)
+        @model_class = model_class
+        @conditional_validations = []
+        @order_validations = []
+        @business_rules = []
+        @groups = {}
+      end
+
+      # Definisce validazioni standard sui campi
+      #
+      # @param fields [Array<Symbol>] Nomi dei campi
+      # @param options [Hash] Opzioni di validazione (presence, format, etc.)
+      #
+      # @example
+      #   validate :title, :content, presence: true
+      #   validate :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+      #   validate :age, numericality: { greater_than: 0 }
+      #
+      def validate(*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
+      #     validate :published_at, presence: true
+      #   end
+      #
+      # @example Con lambda
+      #   validate_if -> { status == "published" } do
+      #     validate :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
+      #     validate :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
+      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
+      #
+      # Le business rules sono metodi custom che implementano logica di validazione
+      # complessa che non può essere espressa con validatori standard.
+      #
+      # @param rule_name [Symbol] Nome del metodo che implementa la rule
+      # @param options [Hash] Opzioni (on, if, unless)
+      #
+      # @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")
+      #     end
+      #   end
+      #
+      #   def author_has_permission
+      #     unless author&.can_create_articles?
+      #       errors.add(:author_id, "does not have permission")
+      #     end
+      #   end
+      #
+      def validate_business_rule(rule_name, **options)
+        @business_rules << {
+          name: rule_name,
+          options: options
+        }
+      end
+
+      # Definisce un gruppo di validazioni
+      #
+      # I gruppi permettono di validare solo un sottoinsieme di campi,
+      # utile per form multi-step o validazioni parziali.
+      #
+      # @param group_name [Symbol] Nome del gruppo
+      # @param fields [Array<Symbol>] Campi inclusi nel gruppo
+      #
+      # @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
+      #   user.errors_for_group(:step1)
+      #
+      def validation_group(group_name, fields)
+        raise ArgumentError, "Group name must be a symbol" unless group_name.is_a?(Symbol)
+        raise ArgumentError, "Fields must be an array" unless fields.is_a?(Array)
+        raise ArgumentError, "Group already defined: #{group_name}" if @groups.key?(group_name)
+
+        @groups[group_name] = {
+          name: group_name,
+          fields: fields
+        }
+      end
+
+      # Restituisce la configurazione completa
+      #
+      # @return [Hash] Configurazione con tutte le validazioni
+      def to_h
+        {
+          conditional_validations: @conditional_validations,
+          order_validations: @order_validations,
+          business_rules: @business_rules
+        }
+      end
+    end
+  end
+end

data/lib/better_model/validatable/order_validator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Validatable
+    # Validator per validazioni di ordine tra campi (cross-field)
+    #
+    # Verifica che un campo sia in una relazione d'ordine rispetto ad un altro campo.
+    # Supporta date/time (before/after) e numeri (lteq/gteq/lt/gt).
+    #
+    # Esempio:
+    #   validates_with OrderValidator,
+    #                  attributes: [:starts_at],
+    #                  second_field: :ends_at,
+    #                  comparator: :before
+    #
+    class OrderValidator < ActiveModel::EachValidator
+      COMPARATORS = {
+        before: :<,
+        after: :>,
+        lteq: :<=,
+        gteq: :>=,
+        lt: :<,
+        gt: :>
+      }.freeze
+
+      def initialize(options)
+        super
+
+        @second_field = options[:second_field]
+        @comparator = options[:comparator]
+
+        unless @second_field
+          raise ArgumentError, "OrderValidator requires :second_field option"
+        end
+
+        unless COMPARATORS.key?(@comparator)
+          raise ArgumentError, "Invalid comparator: #{@comparator}. Valid: #{COMPARATORS.keys.join(', ')}"
+        end
+      end
+
+      def validate_each(record, attribute, value)
+        second_value = record.send(@second_field)
+
+        # Skip validation if either field is nil (use presence validation for that)
+        return if value.nil? || second_value.nil?
+
+        # Get the comparison operator
+        operator = COMPARATORS[@comparator]
+
+        # Perform comparison
+        unless value.send(operator, second_value)
+          record.errors.add(attribute, error_message(attribute, @comparator, @second_field))
+        end
+      end
+
+      private
+
+      def error_message(first_field, comparator, second_field)
+        # Messaggi user-friendly basati sul comparatore
+        case comparator
+        when :before
+          "must be before #{second_field.to_s.humanize.downcase}"
+        when :after
+          "must be after #{second_field.to_s.humanize.downcase}"
+        when :lteq
+          "must be less than or equal to #{second_field.to_s.humanize.downcase}"
+        when :gteq
+          "must be greater than or equal to #{second_field.to_s.humanize.downcase}"
+        when :lt
+          "must be less than #{second_field.to_s.humanize.downcase}"
+        when :gt
+          "must be greater than #{second_field.to_s.humanize.downcase}"
+        end
+      end
+    end
+  end
+end

data/lib/better_model/validatable.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+# Validatable - Sistema di validazioni dichiarativo per modelli Rails
+#
+# Questo concern permette di definire validazioni in modo dichiarativo e leggibile,
+# con supporto per validazioni condizionali, gruppi, cross-field e business rules.
+#
+# APPROCCIO OPT-IN: Le validazioni dichiarative non sono attive automaticamente.
+# Devi chiamare esplicitamente `validatable do...end` nel tuo modello.
+#
+# Esempio di utilizzo:
+#   class Article < ApplicationRecord
+#     include BetterModel
+#
+#     # Status (già esistente in Statusable)
+#     is :draft, -> { status == "draft" }
+#     is :published, -> { status == "published" }
+#
+#     # Attiva validatable (opt-in)
+#     validatable do
+#       # Validazioni base
+#       validate :title, :content, presence: true
+#
+#       # Validazioni condizionali
+#       validate_if :is_published? do
+#         validate :published_at, presence: true
+#         validate :author_id, presence: true
+#       end
+#
+#       # Cross-field validations
+#       validate_order :starts_at, :before, :ends_at
+#
+#       # Business rules
+#       validate_business_rule :valid_category
+#
+#       # Gruppi di validazioni
+#       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
+#
+module BetterModel
+  module Validatable
+    extend ActiveSupport::Concern
+
+    included do
+      # Validazione ActiveRecord
+      unless ancestors.include?(ActiveRecord::Base)
+        raise ArgumentError, "BetterModel::Validatable can only be included in ActiveRecord models"
+      end
+
+      # Configurazione validatable (opt-in)
+      class_attribute :validatable_enabled, default: false
+      class_attribute :validatable_config, default: {}.freeze
+      class_attribute :validatable_groups, default: {}.freeze
+      class_attribute :_validatable_setup_done, default: false
+    end
+
+    class_methods do
+      # DSL per attivare e configurare validatable (OPT-IN)
+      #
+      # @example Attivazione base
+      #   validatable do
+      #     validate :title, presence: true
+      #   end
+      #
+      # @example Con validazioni condizionali
+      #   validatable do
+      #     validate_if :is_published? do
+      #       validate :published_at, presence: true
+      #     end
+      #   end
+      #
+      def validatable(&block)
+        # Attiva validatable
+        self.validatable_enabled = true
+
+        # Configura se passato un blocco
+        if block_given?
+          configurator = Configurator.new(self)
+          configurator.instance_eval(&block)
+          self.validatable_config = configurator.to_h.freeze
+          self.validatable_groups = configurator.groups.freeze
+        end
+
+        # Setup validators only once
+        return if self._validatable_setup_done
+
+        self._validatable_setup_done = true
+
+        # Apply validators from configuration
+        apply_validatable_config
+      end
+
+      # Verifica se validatable è attivo
+      #
+      # @return [Boolean]
+      def validatable_enabled?
+        validatable_enabled == true
+      end
+
+      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)
+        end
+      end
+
+      # Applica una validazione condizionale
+      def apply_conditional_validation(conditional)
+        condition = conditional[:condition]
+        negate = conditional[:negate]
+        validations = conditional[:validations]
+
+        # Create a custom validator for this conditional block
+        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
+        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
+    # @return [Boolean]
+    def valid?(context = nil)
+      if context && self.class.validatable_groups.key?(context)
+        # Valida solo il gruppo specificato
+        validate_group(context)
+      else
+        # Validazione standard Rails
+        super(context)
+      end
+    end
+
+    # Valida solo un gruppo specifico
+    #
+    # @param group_name [Symbol] Nome del gruppo
+    # @return [Boolean]
+    def validate_group(group_name)
+      raise ValidatableNotEnabledError unless self.class.validatable_enabled?
+
+      group = self.class.validatable_groups[group_name]
+      return false unless group
+
+      # Clear existing errors
+      errors.clear
+
+      # Run validations only for fields in this group
+      group[:fields].each do |field|
+        run_validations_for_field(field)
+      end
+
+      errors.empty?
+    end
+
+    # Ottieni gli errori per un gruppo specifico
+    #
+    # @param group_name [Symbol] Nome del gruppo
+    # @return [ActiveModel::Errors]
+    def errors_for_group(group_name)
+      raise ValidatableNotEnabledError unless self.class.validatable_enabled?
+
+      group = self.class.validatable_groups[group_name]
+      return errors unless group
+
+      # Filter errors to only include fields in this group
+      filtered_errors = ActiveModel::Errors.new(self)
+      group[:fields].each do |field|
+        errors[field].each do |error|
+          filtered_errors.add(field, error)
+        end
+      end
+
+      filtered_errors
+    end
+
+    private
+
+    # Run validations for a specific field
+    def run_validations_for_field(field)
+      # This is a simplified version - Rails validations are complex
+      # We'll leverage Rails' built-in validation framework
+      self.class.validators_on(field).each do |validator|
+        validator.validate(self)
+      end
+    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 = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/better_model/version_record.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module BetterModel
+  # Version model for tracking changes
+  # This is the base AR model for version history
+  # Actual table_name is set dynamically in subclasses
+  class Version < ActiveRecord::Base
+    self.abstract_class = true
+
+    # Polymorphic association to the tracked model
+    belongs_to :item, polymorphic: true, optional: true
+
+    # Optional: belongs_to user who made the change
+    # belongs_to :updated_by, class_name: "User", optional: true
+
+    # Serialize object_changes as JSON
+    # Rails handles this automatically for json/jsonb columns
+
+    # Validations
+    validates :item_type, :event, presence: true
+    validates :event, inclusion: { in: %w[created updated destroyed] }
+
+    # Scopes
+    scope :for_item, ->(item) { where(item_type: item.class.name, item_id: item.id) }
+    scope :created_events, -> { where(event: "created") }
+    scope :updated_events, -> { where(event: "updated") }
+    scope :destroyed_events, -> { where(event: "destroyed") }
+    scope :by_user, ->(user_id) { where(updated_by_id: user_id) }
+    scope :between, ->(start_time, end_time) { where(created_at: start_time..end_time) }
+    scope :recent, ->(limit = 10) { order(created_at: :desc).limit(limit) }
+
+    # Get the change for a specific field
+    #
+    # @param field_name [Symbol, String] Field name
+    # @return [Hash, nil] Hash with :before and :after keys
+    def change_for(field_name)
+      return nil unless object_changes
+
+      field = field_name.to_s
+      return nil unless object_changes.key?(field)
+
+      {
+        before: object_changes[field][0],
+        after: object_changes[field][1]
+      }
+    end
+
+    # Check if a specific field changed
+    #
+    # @param field_name [Symbol, String] Field name
+    # @return [Boolean]
+    def changed?(field_name)
+      object_changes&.key?(field_name.to_s) || false
+    end
+
+    # Get list of changed fields
+    #
+    # @return [Array<String>]
+    def changed_fields
+      object_changes&.keys || []
+    end
+  end
+end

data/lib/better_model.rb

@@ -6,6 +6,18 @@ require "better_model/sortable"
 require "better_model/predicable"
 require "better_model/searchable"
 require "better_model/archivable"
+require "better_model/version_record"
+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/stateable"
+require "better_model/stateable/configurator"
+require "better_model/stateable/errors"
+require "better_model/stateable/guard"
+require "better_model/stateable/transition"
 
 module BetterModel
   extend ActiveSupport::Concern
@@ -18,7 +30,8 @@ module BetterModel
     include BetterModel::Predicable
     include BetterModel::Searchable
     include BetterModel::Archivable
-    # Future concerns will be added here:
-    # include BetterModel::Validatable
+    include BetterModel::Traceable
+    include BetterModel::Validatable
+    include BetterModel::Stateable
   end
 end