better_model 1.0.0 → 1.2.0

data/lib/better_model/stateable/configurator.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Stateable
+    # Configurator per il DSL di Stateable
+    #
+    # Questo configurator permette di definire state machines in modo dichiarativo
+    # all'interno del blocco `stateable do...end`.
+    #
+    # Esempio:
+    #   stateable do
+    #     # Definisci stati
+    #     state :pending, initial: true
+    #     state :confirmed
+    #     state :paid
+    #
+    #     # Definisci transizioni
+    #     transition :confirm, from: :pending, to: :confirmed do
+    #       guard { items.any? }
+    #       guard :customer_valid?
+    #       guard if: :is_ready?
+    #
+    #       validate { errors.add(:base, "Invalid") unless valid_for_confirmation? }
+    #
+    #       before { prepare }
+    #       after { notify }
+    #     end
+    #   end
+    #
+    class Configurator
+      attr_reader :states, :transitions, :initial_state, :table_name
+
+      def initialize(model_class)
+        @model_class = model_class
+        @states = []
+        @transitions = {}
+        @initial_state = nil
+        @table_name = nil
+        @current_transition = nil
+      end
+
+      # Definisce uno stato
+      #
+      # @param name [Symbol] Nome dello stato
+      # @param initial [Boolean] Se questo è lo stato iniziale
+      #
+      # @example
+      #   state :draft, initial: true
+      #   state :published
+      #   state :archived
+      #
+      def state(name, initial: false)
+        raise ArgumentError, "State name must be a symbol" unless name.is_a?(Symbol)
+        raise ArgumentError, "State #{name} already defined" if @states.include?(name)
+
+        @states << name
+
+        if initial
+          raise ArgumentError, "Initial state already defined as #{@initial_state}" if @initial_state
+          @initial_state = name
+        end
+      end
+
+      # Definisce una transizione
+      #
+      # @param event [Symbol] Nome dell'evento/transizione
+      # @param from [Symbol, Array<Symbol>] Stato/i di partenza
+      # @param to [Symbol] Stato di arrivo
+      # @yield Blocco per configurare guards, validations, callbacks
+      #
+      # @example Transizione semplice
+      #   transition :publish, from: :draft, to: :published
+      #
+      # @example Con guards e callbacks
+      #   transition :confirm, from: :pending, to: :confirmed do
+      #     guard { valid? }
+      #     guard :ready_to_confirm?
+      #     before { prepare_confirmation }
+      #     after { send_email }
+      #   end
+      #
+      # @example Da multipli stati
+      #   transition :cancel, from: [:pending, :confirmed, :paid], to: :cancelled
+      #
+      def transition(event, from:, to:, &block)
+        raise ArgumentError, "Event name must be a symbol" unless event.is_a?(Symbol)
+        raise ArgumentError, "Transition #{event} already defined" if @transitions.key?(event)
+
+        # Normalizza from in array
+        from_states = Array(from)
+
+        # Verifica che gli stati esistano
+        from_states.each do |state_name|
+          unless @states.include?(state_name)
+            raise ArgumentError, "Unknown state in from: #{state_name}. Define it with 'state :#{state_name}' first."
+          end
+        end
+
+        unless @states.include?(to)
+          raise ArgumentError, "Unknown state in to: #{to}. Define it with 'state :#{to}' first."
+        end
+
+        # Inizializza configurazione transizione
+        @transitions[event] = {
+          from: from_states,
+          to: to,
+          guards: [],
+          validations: [],
+          before_callbacks: [],
+          after_callbacks: [],
+          around_callbacks: []
+        }
+
+        # Se c'è un blocco, configuralo
+        if block_given?
+          @current_transition = @transitions[event]
+          instance_eval(&block)
+          @current_transition = nil
+        end
+      end
+
+      # Definisce un guard per la transizione corrente
+      #
+      # I guards sono precondizioni che devono essere vere per permettere la transizione.
+      #
+      # @overload guard(&block)
+      #   Guard con lambda/proc
+      #   @yield Blocco da valutare nel contesto dell'istanza
+      #   @example
+      #     guard { items.any? && customer.present? }
+      #
+      # @overload guard(method_name)
+      #   Guard con metodo
+      #   @param method_name [Symbol] Nome del metodo da chiamare
+      #   @example
+      #     guard :customer_valid?
+      #
+      # @overload guard(if: predicate)
+      #   Guard con Statusable predicate
+      #   @param if [Symbol] Nome del predicate (integrazione Statusable)
+      #   @example
+      #     guard if: :is_ready_for_publishing?
+      #
+      def guard(method_name = nil, if: nil, &block)
+        raise StateableError, "guard can only be called inside a transition block" unless @current_transition
+
+        if block_given?
+          @current_transition[:guards] << { type: :block, block: block }
+        elsif method_name
+          @current_transition[:guards] << { type: :method, method: method_name }
+        elsif binding.local_variable_get(:if)
+          @current_transition[:guards] << { type: :predicate, predicate: binding.local_variable_get(:if) }
+        else
+          raise ArgumentError, "guard requires either a block, method name, or if: option"
+        end
+      end
+
+      # Definisce una validazione per la transizione corrente
+      #
+      # Le validazioni sono eseguite dopo i guards e prima dei callbacks.
+      # Devono aggiungere errori all'oggetto errors se la validazione fallisce.
+      #
+      # @yield Blocco da valutare nel contesto dell'istanza
+      #
+      # @example
+      #   validate do
+      #     errors.add(:base, "Stock unavailable") unless stock_available?
+      #     errors.add(:payment, "required") if payment_method.blank?
+      #   end
+      #
+      def validate(&block)
+        raise StateableError, "validate can only be called inside a transition block" unless @current_transition
+        raise ArgumentError, "validate requires a block" unless block_given?
+
+        @current_transition[:validations] << block
+      end
+
+      # Definisce un callback before per la transizione corrente
+      #
+      # I before callbacks sono eseguiti prima della transizione di stato.
+      #
+      # @overload before(&block)
+      #   Before callback con lambda/proc
+      #   @yield Blocco da eseguire
+      #   @example
+      #     before { calculate_total }
+      #
+      # @overload before(method_name)
+      #   Before callback con metodo
+      #   @param method_name [Symbol] Nome del metodo da chiamare
+      #   @example
+      #     before :calculate_total
+      #
+      def before(method_name = nil, &block)
+        raise StateableError, "before can only be called inside a transition block" unless @current_transition
+
+        if block_given?
+          @current_transition[:before_callbacks] << { type: :block, block: block }
+        elsif method_name
+          @current_transition[:before_callbacks] << { type: :method, method: method_name }
+        else
+          raise ArgumentError, "before requires either a block or method name"
+        end
+      end
+
+      # Definisce un callback after per la transizione corrente
+      #
+      # Gli after callbacks sono eseguiti dopo la transizione di stato.
+      #
+      # @overload after(&block)
+      #   After callback con lambda/proc
+      #   @yield Blocco da eseguire
+      #   @example
+      #     after { send_notification }
+      #
+      # @overload after(method_name)
+      #   After callback con metodo
+      #   @param method_name [Symbol] Nome del metodo da chiamare
+      #   @example
+      #     after :send_notification
+      #
+      def after(method_name = nil, &block)
+        raise StateableError, "after can only be called inside a transition block" unless @current_transition
+
+        if block_given?
+          @current_transition[:after_callbacks] << { type: :block, block: block }
+        elsif method_name
+          @current_transition[:after_callbacks] << { type: :method, method: method_name }
+        else
+          raise ArgumentError, "after requires either a block or method name"
+        end
+      end
+
+      # Definisce un callback around per la transizione corrente
+      #
+      # Gli around callbacks wrappano la transizione di stato.
+      # Il blocco riceve un altro blocco che deve chiamare per eseguire la transizione.
+      #
+      # @yield Blocco da eseguire, riceve un blocco da chiamare
+      #
+      # @example
+      #   around do |transition|
+      #     log_start
+      #     transition.call
+      #     log_end
+      #   end
+      #
+      def around(&block)
+        raise StateableError, "around can only be called inside a transition block" unless @current_transition
+        raise ArgumentError, "around requires a block" unless block_given?
+
+        @current_transition[:around_callbacks] << block
+      end
+
+      # Specifica il nome della tabella per state transitions
+      #
+      # @param name [String, Symbol] Nome della tabella
+      #
+      # @example Default (state_transitions)
+      #   stateable do
+      #     # Uses 'state_transitions' table by default
+      #   end
+      #
+      # @example Custom table name
+      #   stateable do
+      #     transitions_table 'order_transitions'
+      #   end
+      #
+      # @example Shared table across models
+      #   class Order < ApplicationRecord
+      #     stateable do
+      #       transitions_table 'transitions'
+      #     end
+      #   end
+      #
+      #   class Article < ApplicationRecord
+      #     stateable do
+      #       transitions_table 'transitions'  # Same table
+      #     end
+      #   end
+      #
+      def transitions_table(name)
+        @table_name = name.to_s
+      end
+
+      # Restituisce la configurazione completa
+      #
+      # @return [Hash] Configurazione con stati e transizioni
+      #
+      def to_h
+        {
+          states: @states,
+          transitions: @transitions,
+          initial_state: @initial_state,
+          table_name: @table_name
+        }
+      end
+    end
+  end
+end

data/lib/better_model/stateable/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Stateable
+    # Base error for all Stateable errors
+    class StateableError < StandardError; end
+
+    # Raised when Stateable is not enabled but methods are called
+    class NotEnabledError < StateableError
+      def initialize(msg = nil)
+        super(msg || "Stateable is not enabled. Add 'stateable do...end' to your model.")
+      end
+    end
+
+    # Raised when an invalid state is referenced
+    class InvalidStateError < StateableError
+      def initialize(state)
+        super("Invalid state: #{state.inspect}")
+      end
+    end
+
+    # Raised when trying to transition to an invalid state from current state
+    class InvalidTransitionError < StateableError
+      def initialize(event, from_state, to_state)
+        super("Cannot transition from #{from_state.inspect} to #{to_state.inspect} via #{event.inspect}")
+      end
+    end
+
+    # Raised when a guard condition fails
+    class GuardFailedError < StateableError
+      def initialize(event, guard_description = nil)
+        msg = "Guard failed for transition #{event.inspect}"
+        msg += ": #{guard_description}" if guard_description
+        super(msg)
+      end
+    end
+
+    # Raised when a transition validation fails
+    class ValidationFailedError < StateableError
+      def initialize(event, errors)
+        super("Validation failed for transition #{event.inspect}: #{errors.full_messages.join(', ')}")
+      end
+    end
+  end
+end

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