better_model 1.0.0 → 1.1.0

data/lib/better_model/stateable/guard.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Stateable
+    # Guard evaluator per Stateable
+    #
+    # Valuta le guard conditions per determinare se una transizione è permessa.
+    # Supporta tre tipi di guards:
+    # - Block: lambda/proc valutato nel contesto dell'istanza
+    # - Method: metodo chiamato sull'istanza
+    # - Predicate: integrazione con Statusable (is_ready?, etc.)
+    #
+    class Guard
+      def initialize(instance, guard_config)
+        @instance = instance
+        @guard_config = guard_config
+      end
+
+      # Valuta il guard
+      #
+      # @return [Boolean] true se il guard passa
+      # @raise [GuardFailedError] Se il guard fallisce (opzionale, dipende dal contesto)
+      #
+      def evaluate
+        case @guard_config[:type]
+        when :block
+          evaluate_block
+        when :method
+          evaluate_method
+        when :predicate
+          evaluate_predicate
+        else
+          raise StateableError, "Unknown guard type: #{@guard_config[:type]}"
+        end
+      end
+
+      # Descrizione del guard per messaggi di errore
+      #
+      # @return [String] Descrizione human-readable
+      #
+      def description
+        case @guard_config[:type]
+        when :block
+          "block guard"
+        when :method
+          "method guard: #{@guard_config[:method]}"
+        when :predicate
+          "predicate guard: #{@guard_config[:predicate]}"
+        else
+          "unknown guard"
+        end
+      end
+
+      private
+
+      # Valuta un guard block
+      def evaluate_block
+        block = @guard_config[:block]
+        @instance.instance_exec(&block)
+      end
+
+      # Valuta un guard method
+      def evaluate_method
+        method_name = @guard_config[:method]
+
+        unless @instance.respond_to?(method_name, true)
+          raise NoMethodError, "Guard method '#{method_name}' not found in #{@instance.class.name}. " \
+                               "Define it in your model: def #{method_name}; ...; end"
+        end
+
+        @instance.send(method_name)
+      end
+
+      # Valuta un guard predicate (integrazione Statusable)
+      def evaluate_predicate
+        predicate_name = @guard_config[:predicate]
+
+        unless @instance.respond_to?(predicate_name)
+          raise NoMethodError, "Guard predicate '#{predicate_name}' not found in #{@instance.class.name}. " \
+                               "Make sure Statusable is enabled and the predicate is defined: is :ready, -> { ... }"
+        end
+
+        @instance.send(predicate_name)
+      end
+    end
+  end
+end

data/lib/better_model/stateable/transition.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Stateable
+    # Transition executor per Stateable
+    #
+    # Gestisce l'esecuzione di una transizione di stato, includendo:
+    # - Valutazione guards
+    # - Esecuzione validazioni
+    # - Esecuzione callbacks (before/after/around)
+    # - Aggiornamento stato nel database
+    # - Creazione record StateTransition per storico
+    #
+    class Transition
+      def initialize(instance, event, config, metadata = {})
+        @instance = instance
+        @event = event
+        @config = config
+        @metadata = metadata
+        @from_state = instance.state.to_sym
+        @to_state = config[:to]
+      end
+
+      # Esegue la transizione
+      #
+      # @raise [GuardFailedError] Se un guard fallisce
+      # @raise [ValidationFailedError] Se una validazione fallisce
+      # @raise [ActiveRecord::RecordInvalid] Se il save! fallisce
+      # @return [Boolean] true se la transizione ha successo
+      #
+      def execute!
+        # 1. Valuta guards
+        evaluate_guards!
+
+        # 2. Esegui validazioni
+        execute_validations!
+
+        # 3. Wrap in transaction
+        @instance.class.transaction do
+          # 4. Esegui callbacks around (se presenti)
+          if @config[:around_callbacks].any?
+            execute_around_callbacks do
+              perform_transition!
+            end
+          else
+            perform_transition!
+          end
+        end
+
+        true
+      end
+
+      private
+
+      # Valuta tutti i guards
+      def evaluate_guards!
+        guards = @config[:guards] || []
+
+        guards.each do |guard_config|
+          guard = Guard.new(@instance, guard_config)
+
+          unless guard.evaluate
+            raise GuardFailedError.new(@event, guard.description)
+          end
+        end
+      end
+
+      # Esegue tutte le validazioni
+      def execute_validations!
+        validations = @config[:validations] || []
+        return if validations.empty?
+
+        # Clear existing errors per questa transizione
+        @instance.errors.clear
+
+        validations.each do |validation_block|
+          @instance.instance_exec(&validation_block)
+        end
+
+        if @instance.errors.any?
+          raise ValidationFailedError.new(@event, @instance.errors)
+        end
+      end
+
+      # Esegue i callback around
+      def execute_around_callbacks(&block)
+        around_callbacks = @config[:around_callbacks] || []
+
+        if around_callbacks.empty?
+          block.call
+          return
+        end
+
+        # Nested around callbacks
+        chain = around_callbacks.reverse.reduce(block) do |inner, around_callback|
+          proc { @instance.instance_exec(inner, &around_callback) }
+        end
+
+        chain.call
+      end
+
+      # Esegue la transizione effettiva
+      def perform_transition!
+        # 1. Esegui before callbacks
+        execute_callbacks(@config[:before_callbacks] || [])
+
+        # 2. Aggiorna stato
+        @instance.state = @to_state.to_s
+
+        # 3. Salva il record (valida il modello)
+        @instance.save!
+
+        # 4. Crea record StateTransition
+        create_state_transition_record
+
+        # 5. Esegui after callbacks
+        execute_callbacks(@config[:after_callbacks] || [])
+      end
+
+      # Esegue una lista di callbacks
+      def execute_callbacks(callbacks)
+        callbacks.each do |callback_config|
+          case callback_config[:type]
+          when :block
+            @instance.instance_exec(&callback_config[:block])
+          when :method
+            @instance.send(callback_config[:method])
+          end
+        end
+      end
+
+      # Crea il record StateTransition per lo storico
+      def create_state_transition_record
+        @instance.state_transitions.create!(
+          event: @event.to_s,
+          from_state: @from_state.to_s,
+          to_state: @to_state.to_s,
+          metadata: @metadata
+        )
+      end
+    end
+  end
+end

data/lib/better_model/stateable.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+# Stateable - Declarative State Machine per modelli Rails
+#
+# Questo concern permette di definire state machines dichiarative con:
+# - Stati espliciti con initial state
+# - Transizioni con guards, validazioni e callbacks
+# - Tracking storico transizioni
+# - Integrazione con Statusable per guards
+#
+# APPROCCIO OPT-IN: La state machine non è attiva automaticamente.
+# Devi chiamare esplicitamente `stateable do...end` nel tuo modello.
+#
+# REQUISITI DATABASE:
+#   - Colonna `state` (string) nel modello
+#   - Tabella per storico transizioni (default: `state_transitions`, configurabile)
+#
+# Esempio di utilizzo:
+#   class Order < ApplicationRecord
+#     include BetterModel
+#
+#     # Optional: Statusable per status derivati
+#     is :payable, -> { confirmed? && !paid? }
+#
+#     # Attiva stateable (opt-in)
+#     stateable do
+#       # Stati
+#       state :pending, initial: true
+#       state :confirmed
+#       state :paid
+#       state :cancelled
+#
+#       # Transizioni
+#       transition :confirm, from: :pending, to: :confirmed do
+#         guard { items.any? }
+#         guard :customer_valid?
+#         guard if: :is_payable?  # Statusable integration
+#
+#         validate { errors.add(:base, "Stock unavailable") unless stock_available? }
+#
+#         before { calculate_total }
+#         after { send_confirmation_email }
+#       end
+#
+#       transition :pay, from: :confirmed, to: :paid do
+#         before { charge_payment }
+#       end
+#
+#       transition :cancel, from: [:pending, :confirmed], to: :cancelled
+#     end
+#
+#     # Optional: Custom table name for transitions
+#     transitions_table 'order_transitions'
+#   end
+#
+# Utilizzo:
+#   order.state              # => "pending"
+#   order.pending?           # => true
+#   order.can_confirm?       # => true (controlla guards)
+#   order.confirm!           # Esegue transizione
+#   order.state              # => "confirmed"
+#
+#   order.state_transitions  # => Array di StateTransition records
+#   order.transition_history # => Array formattato di transizioni
+#
+# Table Naming Options:
+#   # Option 1: Default shared table (state_transitions)
+#   stateable do
+#     # Uses 'state_transitions' table by default
+#   end
+#
+#   # Option 2: Custom table name
+#   stateable do
+#     transitions_table 'order_transitions'
+#   end
+#
+#   # Option 3: Shared custom table
+#   class Order < ApplicationRecord
+#     stateable do
+#       transitions_table 'transitions'
+#     end
+#   end
+#   class Article < ApplicationRecord
+#     stateable do
+#       transitions_table 'transitions'  # Same table
+#     end
+#   end
+#
+module BetterModel
+  module Stateable
+    extend ActiveSupport::Concern
+
+    included do
+      # Validazione ActiveRecord
+      unless ancestors.include?(ActiveRecord::Base)
+        raise ArgumentError, "BetterModel::Stateable can only be included in ActiveRecord models"
+      end
+
+      # Configurazione stateable (opt-in)
+      class_attribute :stateable_enabled, default: false
+      class_attribute :stateable_config, default: {}.freeze
+      class_attribute :stateable_states, default: [].freeze
+      class_attribute :stateable_transitions, default: {}.freeze
+      class_attribute :stateable_initial_state, default: nil
+      class_attribute :stateable_table_name, default: nil
+      class_attribute :_stateable_setup_done, default: false
+    end
+
+    class_methods do
+      # DSL per attivare e configurare stateable (OPT-IN)
+      #
+      # @example Attivazione base
+      #   stateable do
+      #     state :draft, initial: true
+      #     state :published
+      #     transition :publish, from: :draft, to: :published
+      #   end
+      #
+      # @example Con guards e callbacks
+      #   stateable do
+      #     state :pending, initial: true
+      #     state :confirmed
+      #
+      #     transition :confirm, from: :pending, to: :confirmed do
+      #       guard { valid? }
+      #       before { prepare_confirmation }
+      #       after { send_notification }
+      #     end
+      #   end
+      #
+      def stateable(&block)
+        # Attiva stateable
+        self.stateable_enabled = true
+
+        # Configura se passato un blocco
+        if block_given?
+          configurator = Configurator.new(self)
+          configurator.instance_eval(&block)
+
+          self.stateable_config = configurator.to_h.freeze
+          self.stateable_states = configurator.states.freeze
+          self.stateable_transitions = configurator.transitions.freeze
+          self.stateable_initial_state = configurator.initial_state
+          self.stateable_table_name = configurator.table_name
+        end
+
+        # Set default table name if not configured
+        self.stateable_table_name ||= "state_transitions"
+
+        # Setup methods only once
+        return if self._stateable_setup_done
+
+        self._stateable_setup_done = true
+
+        # Setup association con StateTransition
+        setup_state_transitions_association
+
+        # Setup dynamic methods
+        setup_dynamic_methods
+
+        # Setup validations
+        setup_state_validation
+
+        # Setup callbacks
+        setup_initial_state_callback
+      end
+
+      # Verifica se stateable è attivo
+      #
+      # @return [Boolean]
+      def stateable_enabled?
+        stateable_enabled == true
+      end
+
+      private
+
+      # Setup association con StateTransition model
+      def setup_state_transitions_association
+        # Create or retrieve a StateTransition class for the given table name
+        transition_class = create_state_transition_class_for_table(stateable_table_name)
+
+        has_many :state_transitions,
+                 -> { order(created_at: :desc) },
+                 as: :transitionable,
+                 class_name: transition_class.name,
+                 dependent: :destroy
+      end
+
+      # Create or retrieve a StateTransition class for the given table name
+      #
+      # @param table_name [String] Table name for state transitions
+      # @return [Class] StateTransition class
+      #
+      def create_state_transition_class_for_table(table_name)
+        # Create a unique class name based on table name
+        class_name = "#{table_name.camelize.singularize}"
+
+        # Check if class already exists in BetterModel namespace
+        if BetterModel.const_defined?(class_name, false)
+          return BetterModel.const_get(class_name)
+        end
+
+        # Create new StateTransition class dynamically
+        transition_class = Class.new(BetterModel::StateTransition) do
+          self.table_name = table_name
+        end
+
+        # Register the class in BetterModel namespace
+        BetterModel.const_set(class_name, transition_class)
+        transition_class
+      end
+
+      # Setup dynamic methods per stati e transizioni
+      def setup_dynamic_methods
+        # Metodi per ogni stato: pending?, confirmed?, etc.
+        stateable_states.each do |state_name|
+          define_method "#{state_name}?" do
+            state.to_s == state_name.to_s
+          end
+        end
+
+        # Metodi per ogni transizione: confirm!, can_confirm?, etc.
+        stateable_transitions.each do |event_name, transition_config|
+          # event! - esegue transizione (raise se fallisce)
+          define_method "#{event_name}!" do |**metadata|
+            transition_to!(event_name, **metadata)
+          end
+
+          # can_event? - controlla se transizione è possibile
+          define_method "can_#{event_name}?" do
+            can_transition_to?(event_name)
+          end
+        end
+      end
+
+      # Setup validazione dello stato
+      def setup_state_validation
+        validates :state, presence: true, inclusion: { in: ->(_) { stateable_states.map(&:to_s) } }
+      end
+
+      # Setup callback per impostare initial state
+      def setup_initial_state_callback
+        before_validation :set_initial_state, on: :create
+
+        define_method :set_initial_state do
+          return if state.present?
+          self.state = self.class.stateable_initial_state.to_s if self.class.stateable_initial_state
+        end
+      end
+    end
+
+    # Metodi di istanza
+
+    # Esegue una transizione di stato
+    #
+    # @param event [Symbol] Nome della transizione
+    # @param metadata [Hash] Metadata opzionale da salvare nella StateTransition
+    # @raise [InvalidTransitionError] Se la transizione non è valida
+    # @raise [GuardFailedError] Se un guard fallisce
+    # @raise [ValidationFailedError] Se una validazione fallisce
+    # @return [Boolean] true se la transizione ha successo
+    #
+    def transition_to!(event, **metadata)
+      raise NotEnabledError unless self.class.stateable_enabled?
+
+      transition_config = self.class.stateable_transitions[event.to_sym]
+      raise ArgumentError, "Unknown transition: #{event}" unless transition_config
+
+      current_state = state.to_sym
+
+      # Verifica che from_state sia valido
+      from_states = Array(transition_config[:from])
+      unless from_states.include?(current_state)
+        raise InvalidTransitionError.new(event, current_state, transition_config[:to])
+      end
+
+      # Esegui la transizione usando Transition executor
+      transition = Transition.new(self, event, transition_config, metadata)
+      transition.execute!
+    end
+
+    # Verifica se una transizione è possibile
+    #
+    # @param event [Symbol] Nome della transizione
+    # @return [Boolean] true se la transizione è possibile
+    #
+    def can_transition_to?(event)
+      return false unless self.class.stateable_enabled?
+
+      transition_config = self.class.stateable_transitions[event.to_sym]
+      return false unless transition_config
+
+      current_state = state.to_sym
+      from_states = Array(transition_config[:from])
+      return false unless from_states.include?(current_state)
+
+      # Verifica guards
+      guards = transition_config[:guards] || []
+      guards.all? do |guard|
+        Guard.new(self, guard).evaluate
+      end
+    rescue StandardError
+      false
+    end
+
+    # Ottieni lo storico delle transizioni formattato
+    #
+    # @return [Array<Hash>] Array di transizioni con :event, :from, :to, :at, :metadata
+    #
+    def transition_history
+      raise NotEnabledError unless self.class.stateable_enabled?
+
+      state_transitions.map do |transition|
+        {
+          event: transition.event,
+          from: transition.from_state,
+          to: transition.to_state,
+          at: transition.created_at,
+          metadata: transition.metadata
+        }
+      end
+    end
+
+    # Override as_json per includere transition history
+    #
+    # @param options [Hash] Options
+    # @option options [Boolean] :include_transition_history Include full history
+    # @return [Hash]
+    #
+    def as_json(options = {})
+      result = super
+
+      if options[:include_transition_history] && self.class.stateable_enabled?
+        result["transition_history"] = transition_history
+      end
+
+      result
+    end
+  end
+end