better_model 2.1.0 → 3.0.0

data/lib/better_model/stateable/guard.rb

@@ -2,25 +2,32 @@
 
 module BetterModel
   module Stateable
-    # Check evaluator per Stateable (internal class name remains Guard for compatibility)
+    # Check evaluator for Stateable transitions.
     #
-    # Valuta le check conditions per determinare se una transizione è permessa.
-    # Supporta tre tipi di checks:
-    # - Block: lambda/proc valutato nel contesto dell'istanza
-    # - Method: metodo chiamato sull'istanza
-    # - Predicate: integrazione con Statusable (is_ready?, etc.)
+    # Evaluates check conditions to determine if a transition is allowed.
+    # Supports three types of checks:
+    # - Block: lambda/proc evaluated in instance context
+    # - Method: method called on instance
+    # - Predicate: integration with Statusable (is_ready?, etc.)
     #
+    # @api private
     class Guard
+      # Initialize a new Guard.
+      #
+      # @param instance [Object] Model instance
+      # @param guard_config [Hash] Guard configuration hash
       def initialize(instance, guard_config)
         @instance = instance
         @guard_config = guard_config
       end
 
-      # Valuta il check
+      # Evaluate the check.
       #
-      # @return [Boolean] true se il check passa
-      # @raise [CheckFailedError] Se il check fallisce (opzionale, dipende dal contesto)
+      # @return [Boolean] true if check passes
+      # @raise [BetterModel::Errors::Stateable::CheckFailedError] If check fails (optional, context-dependent)
       #
+      # @example
+      #   guard.evaluate  # => true
       def evaluate
         case @guard_config[:type]
         when :block
@@ -30,14 +37,16 @@ module BetterModel
         when :predicate
           evaluate_predicate
         else
-          raise StateableError, "Unknown check type: #{@guard_config[:type]}"
+          raise BetterModel::Errors::Stateable::StateableError, "Unknown check type: #{@guard_config[:type]}"
         end
       end
 
-      # Descrizione del check per messaggi di errore
+      # Description of check for error messages.
       #
-      # @return [String] Descrizione human-readable
+      # @return [String] Human-readable description
       #
+      # @example
+      #   guard.description  # => "method check: customer_valid?"
       def description
         case @guard_config[:type]
         when :block
@@ -53,13 +62,20 @@ module BetterModel
 
       private
 
-      # Valuta un check block
+      # Evaluate a block check.
+      #
+      # @return [Boolean] Result of block evaluation
+      # @api private
       def evaluate_block
         block = @guard_config[:block]
         @instance.instance_exec(&block)
       end
 
-      # Valuta un check method
+      # Evaluate a method check.
+      #
+      # @return [Boolean] Result of method call
+      # @raise [NoMethodError] If method not found
+      # @api private
       def evaluate_method
         method_name = @guard_config[:method]
 
@@ -71,7 +87,11 @@ module BetterModel
         @instance.send(method_name)
       end
 
-      # Valuta un check predicate (integrazione Statusable)
+      # Evaluate a predicate check (Statusable integration).
+      #
+      # @return [Boolean] Result of predicate call
+      # @raise [NoMethodError] If predicate not found
+      # @api private
       def evaluate_predicate
         predicate_name = @guard_config[:predicate]
 

data/lib/better_model/stateable/transition.rb

@@ -1,17 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "../errors/stateable/check_failed_error"
+require_relative "../errors/stateable/validation_failed_error"
+
 module BetterModel
   module Stateable
-    # Transition executor per Stateable
+    # Transition executor for Stateable.
     #
-    # Gestisce l'esecuzione di una transizione di stato, includendo:
-    # - Valutazione checks
-    # - Esecuzione validazioni
-    # - Esecuzione callbacks (before_transition/after_transition/around)
-    # - Aggiornamento stato nel database
-    # - Creazione record StateTransition per storico
+    # Handles the execution of a state transition, including:
+    # - Check evaluation
+    # - Validation execution
+    # - Callback execution (before_transition/after_transition/around)
+    # - State update in database
+    # - StateTransition record creation for history
     #
+    # @api private
     class Transition
+      # Initialize a new Transition.
+      #
+      # @param instance [Object] Model instance
+      # @param event [Symbol] Transition event name
+      # @param config [Hash] Transition configuration
+      # @param metadata [Hash] Additional metadata for transition
       def initialize(instance, event, config, metadata = {})
         @instance = instance
         @event = event
@@ -21,23 +31,25 @@ module BetterModel
         @to_state = config[:to]
       end
 
-      # Esegue la transizione
+      # Execute the transition.
       #
-      # @raise [CheckFailedError] Se un check fallisce
-      # @raise [ValidationFailedError] Se una validazione fallisce
-      # @raise [ActiveRecord::RecordInvalid] Se il save! fallisce
-      # @return [Boolean] true se la transizione ha successo
+      # @raise [BetterModel::Errors::Stateable::CheckFailedError] If a check fails
+      # @raise [BetterModel::Errors::Stateable::ValidationFailedError] If a validation fails
+      # @raise [ActiveRecord::RecordInvalid] If save! fails
+      # @return [Boolean] true if transition succeeds
       #
+      # @example
+      #   transition.execute!  # => true
       def execute!
-        # 1. Valuta checks
+        # 1. Evaluate checks
         evaluate_checks!
 
-        # 2. Esegui validazioni
+        # 2. Execute validations
         execute_validations!
 
         # 3. Wrap in transaction
         @instance.class.transaction do
-          # 4. Esegui callbacks around (se presenti)
+          # 4. Execute around callbacks (if present)
           if @config[:around_callbacks].any?
             execute_around_callbacks do
               perform_transition!
@@ -52,25 +64,31 @@ module BetterModel
 
       private
 
-      # Valuta tutti i checks
+      # Evaluate all checks.
+      #
+      # @raise [BetterModel::Errors::Stateable::CheckFailedError] If any check fails
+      # @api private
       def evaluate_checks!
-        checks = @config[:guards] || []  # Manteniamo :guards per compatibilità interna
+        checks = @config[:guards] || []  # Keep :guards for internal compatibility
 
         checks.each do |check_config|
           check = Guard.new(@instance, check_config)  # Guard class handles the logic
 
           unless check.evaluate
-            raise CheckFailedError.new(@event, check.description)
+            raise BetterModel::Errors::Stateable::CheckFailedError, "Check failed for transition #{@event}"
           end
         end
       end
 
-      # Esegue tutte le validazioni
+      # Execute all validations.
+      #
+      # @raise [BetterModel::Errors::Stateable::ValidationFailedError] If validations fail
+      # @api private
       def execute_validations!
         validations = @config[:validations] || []
         return if validations.empty?
 
-        # Clear existing errors per questa transizione
+        # Clear existing errors for this transition
         @instance.errors.clear
 
         validations.each do |validation_block|
@@ -78,11 +96,15 @@ module BetterModel
         end
 
         if @instance.errors.any?
-          raise ValidationFailedError.new(@event, @instance.errors)
+          error_messages = @instance.errors.full_messages.join(", ")
+          raise BetterModel::Errors::Stateable::ValidationFailedError, "Validation failed for transition #{@event}: #{error_messages}"
         end
       end
 
-      # Esegue i callback around
+      # Execute around callbacks.
+      #
+      # @yield Block to wrap with around callbacks
+      # @api private
       def execute_around_callbacks(&block)
         around_callbacks = @config[:around_callbacks] || []
 
@@ -99,25 +121,30 @@ module BetterModel
         chain.call
       end
 
-      # Esegue la transizione effettiva
+      # Perform the actual transition.
+      #
+      # @api private
       def perform_transition!
-        # 1. Esegui before_transition callbacks
+        # 1. Execute before_transition callbacks
         execute_callbacks(@config[:before_callbacks] || [])
 
-        # 2. Aggiorna stato
+        # 2. Update state
         @instance.state = @to_state.to_s
 
-        # 3. Salva il record (valida il modello)
+        # 3. Save record (validates model)
         @instance.save!
 
-        # 4. Crea record StateTransition
+        # 4. Create StateTransition record
         create_state_transition_record
 
-        # 5. Esegui after_transition callbacks
+        # 5. Execute after_transition callbacks
         execute_callbacks(@config[:after_callbacks] || [])
       end
 
-      # Esegue una lista di callbacks
+      # Execute a list of callbacks.
+      #
+      # @param callbacks [Array<Hash>] Callback configurations
+      # @api private
       def execute_callbacks(callbacks)
         callbacks.each do |callback_config|
           case callback_config[:type]
@@ -129,7 +156,9 @@ module BetterModel
         end
       end
 
-      # Crea il record StateTransition per lo storico
+      # Create StateTransition record for history.
+      #
+      # @api private
       def create_state_transition_record
         @instance.state_transitions.create!(
           event: @event.to_s,

data/lib/better_model/stateable.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "errors/stateable/stateable_error"
+require_relative "errors/stateable/not_enabled_error"
+require_relative "errors/stateable/invalid_state_error"
+require_relative "errors/stateable/invalid_transition_error"
+require_relative "errors/stateable/check_failed_error"
+require_relative "errors/stateable/validation_failed_error"
+require_relative "errors/stateable/configuration_error"
+
 # Stateable - Declarative State Machine per modelli Rails
 #
 # Questo concern permette di definire state machines dichiarative con:
@@ -96,7 +104,7 @@ module BetterModel
     included do
       # Validazione ActiveRecord
       unless ancestors.include?(ActiveRecord::Base)
-        raise ArgumentError, "BetterModel::Stateable can only be included in ActiveRecord models"
+        raise BetterModel::Errors::Stateable::ConfigurationError, "Invalid configuration"
       end
 
       # Configurazione stateable (opt-in)
@@ -171,9 +179,7 @@ module BetterModel
       # Verifica se stateable è attivo
       #
       # @return [Boolean]
-      def stateable_enabled?
-        stateable_enabled == true
-      end
+      def stateable_enabled? = stateable_enabled == true
 
       private
 
@@ -214,7 +220,7 @@ module BetterModel
           end
 
           # Create new StateTransition class dynamically
-          transition_class = Class.new(BetterModel::StateTransition) do
+          transition_class = Class.new(BetterModel::Models::StateTransition) do
             self.table_name = table_name
           end
 
@@ -236,8 +242,11 @@ module BetterModel
         # 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)
+          # Accepts both positional hash and keyword arguments for flexibility
+          define_method "#{event_name}!" do |metadata = {}, **kwargs|
+            # Convert positional hash to keyword args if provided
+            combined_metadata = metadata.merge(kwargs)
+            transition_to!(event_name, **combined_metadata)
           end
 
           # can_event? - controlla se transizione è possibile
@@ -269,23 +278,27 @@ module BetterModel
     #
     # @param event [Symbol] Nome della transizione
     # @param metadata [Hash] Metadata opzionale da salvare nella StateTransition
-    # @raise [InvalidTransitionError] Se la transizione non è valida
-    # @raise [CheckFailedError] Se un check fallisce
-    # @raise [ValidationFailedError] Se una validazione fallisce
+    # @raise [BetterModel::Errors::Stateable::InvalidTransitionError] Se la transizione non è valida
+    # @raise [BetterModel::Errors::Stateable::CheckFailedError] Se un check fallisce
+    # @raise [BetterModel::Errors::Stateable::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?
+      unless self.class.stateable_enabled?
+        raise BetterModel::Errors::Stateable::NotEnabledError, "Module is not enabled"
+      end
 
       transition_config = self.class.stateable_transitions[event.to_sym]
-      raise ArgumentError, "Unknown transition: #{event}" unless transition_config
+      unless transition_config
+        raise BetterModel::Errors::Stateable::ConfigurationError, "Unknown transition: #{event}"
+      end
 
       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])
+        raise BetterModel::Errors::Stateable::InvalidTransitionError, "Cannot transition from #{current_state} to #{transition_config[:to]} via #{event}"
       end
 
       # Esegui la transizione usando Transition executor
@@ -322,7 +335,9 @@ module BetterModel
     # @return [Array<Hash>] Array di transizioni con :event, :from, :to, :at, :metadata
     #
     def transition_history
-      raise NotEnabledError unless self.class.stateable_enabled?
+      unless self.class.stateable_enabled?
+        raise BetterModel::Errors::Stateable::NotEnabledError, "Module is not enabled"
+      end
 
       state_transitions.map do |transition|
         {
@@ -345,7 +360,10 @@ module BetterModel
       result = super
 
       if options[:include_transition_history] && self.class.stateable_enabled?
-        result["transition_history"] = transition_history
+        # Convert symbol keys to string keys for JSON compatibility
+        result["transition_history"] = transition_history.map do |item|
+          item.transform_keys(&:to_s)
+        end
       end
 
       result

data/lib/better_model/statusable.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
-# Statusable - Sistema di stati dichiarativi per modelli Rails
+require_relative "errors/statusable/statusable_error"
+require_relative "errors/statusable/configuration_error"
+
+# Statusable - Declarative status system for Rails models.
 #
-# Questo concern permette di definire stati sui modelli utilizzando un DSL
-# semplice e dichiarativo, simile al pattern Enrichable ma per gli stati.
+# This concern enables defining statuses on models using a simple, declarative DSL
+# similar to the Enrichable pattern but for statuses.
 #
-# Esempio di utilizzo:
+# @example Basic Usage
 #   class Communications::Consult < ApplicationRecord
 #     include BetterModel::Statusable
 #
@@ -17,7 +20,7 @@
 #     is :ready_to_start, -> { scheduled? && scheduled_at <= Time.current }
 #   end
 #
-# Utilizzo:
+# @example Checking Statuses
 #   consult.is?(:pending)           # => true/false
 #   consult.is_pending?             # => true/false
 #   consult.is_active_session?      # => true/false
@@ -29,58 +32,79 @@ module BetterModel
     extend ActiveSupport::Concern
 
     included do
-      # Registry degli stati definiti per questa classe
+      # Registry of statuses defined for this class
       class_attribute :is_definitions
       self.is_definitions = {}
     end
 
     class_methods do
-      # DSL per definire stati
+      # DSL to define statuses.
+      #
+      # Defines a status check that can be evaluated against model instances.
+      # Automatically creates a convenience method is_<status_name>? for each status.
       #
-      # Parametri:
-      # - status_name: simbolo che rappresenta lo stato (es. :pending, :active)
-      # - condition_proc: lambda o proc che definisce la condizione
-      # - block: blocco alternativo alla condition_proc
+      # @param status_name [Symbol, String] Status identifier (e.g., :pending, :active)
+      # @param condition_proc [Proc, nil] Lambda or proc that defines the condition
+      # @yield Alternative to condition_proc parameter
+      # @raise [BetterModel::Errors::Statusable::ConfigurationError] If parameters are invalid
       #
-      # Esempi:
+      # @example With lambda parameter
       #   is :pending, -> { status == 'initialized' }
-      #   is :expired, -> { expires_at.present? && expires_at <= Time.current }
+      #
+      # @example With block
+      #   is :expired do
+      #     expires_at.present? && expires_at <= Time.current
+      #   end
+      #
+      # @example Complex condition
       #   is :ready do
       #     scheduled_at.present? && scheduled_at <= Time.current
       #   end
       def is(status_name, condition_proc = nil, &block)
-        # Valida i parametri prima di convertire
-        raise ArgumentError, "Status name cannot be blank" if status_name.blank?
+        # Validate parameters before converting
+        if status_name.blank?
+          raise BetterModel::Errors::Statusable::ConfigurationError, "Status name cannot be blank"
+        end
 
         status_name = status_name.to_sym
         condition = condition_proc || block
-        raise ArgumentError, "Condition proc or block is required" unless condition
-        raise ArgumentError, "Condition must respond to call" unless condition.respond_to?(:call)
 
-        # Registra lo stato nel registry
+        unless condition
+          raise BetterModel::Errors::Statusable::ConfigurationError, "Condition proc or block is required"
+        end
+
+        unless condition.respond_to?(:call)
+          raise BetterModel::Errors::Statusable::ConfigurationError, "Condition must respond to call"
+        end
+
+        # Register status in registry
         self.is_definitions = is_definitions.merge(status_name => condition.freeze).freeze
 
-        # Genera il metodo dinamico is_#{status_name}?
+        # Generate dynamic method is_#{status_name}?
         define_is_method(status_name)
       end
 
-      # Lista di tutti gli stati definiti per questa classe
-      def defined_statuses
-        is_definitions.keys
-      end
+      # List all statuses defined for this class.
+      #
+      # @return [Array<Symbol>] Array of defined status names
+      def defined_statuses = is_definitions.keys
 
-      # Verifica se uno stato è definito
-      def status_defined?(status_name)
-        is_definitions.key?(status_name.to_sym)
-      end
+      # Check if a status is defined.
+      #
+      # @param status_name [Symbol, String] Status name to check
+      # @return [Boolean] true if status is defined
+      def status_defined?(status_name) = is_definitions.key?(status_name.to_sym)
 
       private
 
-      # Genera dinamicamente il metodo is_#{status_name}? per ogni stato definito
+      # Generate dynamic method is_#{status_name}? for each defined status.
+      #
+      # @param status_name [Symbol] Status name
+      # @api private
       def define_is_method(status_name)
         method_name = "is_#{status_name}?"
 
-        # Evita di ridefinire metodi se già esistono
+        # Avoid redefining methods if they already exist
         return if method_defined?(method_name)
 
         define_method(method_name) do
@@ -89,35 +113,33 @@ module BetterModel
       end
     end
 
-    # Metodo generico per verificare se uno stato è attivo
+    # Generic method to check if a status is active.
     #
-    # Parametri:
-    # - status_name: simbolo dello stato da verificare
+    # Evaluates the status condition in the context of the model instance.
+    # Returns false if status is not defined (secure by default).
     #
-    # Ritorna:
-    # - true se lo stato è attivo
-    # - false se lo stato non è attivo o non è definito
+    # @param status_name [Symbol, String] Status name to check
+    # @return [Boolean] true if status is active, false otherwise
     #
-    # Esempio:
-    #   consult.is?(:pending)
+    # @example
+    #   consult.is?(:pending)  # => true
     def is?(status_name)
       status_name = status_name.to_sym
       condition = self.class.is_definitions[status_name]
 
-      # Se lo stato non è definito, ritorna false (secure by default)
+      # If status is not defined, return false (secure by default)
       return false unless condition
 
-      # Valuta la condizione nel contesto dell'istanza del modello
-      # Gli errori si propagano naturalmente - fail fast
+      # Evaluate condition in context of model instance
+      # Errors propagate naturally - fail fast
       instance_exec(&condition)
     end
 
-    # Ritorna tutti gli stati disponibili per questa istanza con i loro valori
+    # Returns all available statuses for this instance with their values.
     #
-    # Ritorna:
-    # - Hash con chiavi simbolo (stati) e valori booleani (attivi/inattivi)
+    # @return [Hash{Symbol => Boolean}] Hash with status names and their active state
     #
-    # Esempio:
+    # @example
     #   consult.statuses
     #   # => { pending: true, active: false, expired: false, scheduled: true }
     def statuses
@@ -126,26 +148,36 @@ module BetterModel
       end
     end
 
-    # Verifica se l'istanza ha almeno uno stato attivo
-    def has_any_status?
-      statuses.values.any?
-    end
+    # Check if instance has at least one active status.
+    #
+    # @return [Boolean] true if any status is active
+    def has_any_status? = statuses.values.any?
 
-    # Verifica se l'istanza ha tutti gli stati specificati attivi
+    # Check if instance has all specified statuses active.
+    #
+    # @param status_names [Array<Symbol>] Status names to check
+    # @return [Boolean] true if all statuses are active
     def has_all_statuses?(status_names)
       Array(status_names).all? { |status_name| is?(status_name) }
     end
 
-    # Filtra una lista di stati restituendo solo quelli attivi
+    # Filter a list of statuses returning only active ones.
+    #
+    # @param status_names [Array<Symbol>] Status names to filter
+    # @return [Array<Symbol>] Active statuses
     def active_statuses(status_names)
       Array(status_names).select { |status_name| is?(status_name) }
     end
 
-    # Override di as_json per includere automaticamente gli stati se richiesto
+    # Override as_json to automatically include statuses if requested.
+    #
+    # @param options [Hash] Options for as_json
+    # @option options [Boolean] :include_statuses Include statuses in JSON output
+    # @return [Hash] JSON representation
     def as_json(options = {})
       result = super
 
-      # Include gli stati se esplicitamente richiesto, converting symbol keys to strings
+      # Include statuses if explicitly requested, converting symbol keys to strings
       result["statuses"] = statuses.transform_keys(&:to_s) if options[:include_statuses]
 
       result