better_model 2.1.0 → 3.0.0

data/lib/better_model/sortable.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
-# Sortable - Sistema di ordinamento dichiarativo per modelli Rails
+require_relative "errors/sortable/sortable_error"
+require_relative "errors/sortable/configuration_error"
+
+# Sortable - Declarative sorting system for Rails models.
 #
-# Questo concern permette di definire ordinamenti sui modelli utilizzando un DSL
-# semplice e dichiarativo che genera automaticamente scope basati sul tipo di colonna.
+# This concern enables defining sorts on models using a simple, declarative DSL
+# that automatically generates scopes based on column type.
 #
-# Esempio di utilizzo:
+# @example Basic Usage
 #   class Article < ApplicationRecord
 #     include BetterModel::Sortable
 #
 #     sort :title, :view_count, :published_at
 #   end
 #
-# Utilizzo:
+# @example Generated Scopes
 #   Article.sort_title_asc                    # ORDER BY title ASC
 #   Article.sort_title_desc_i                 # ORDER BY LOWER(title) DESC
 #   Article.sort_view_count_desc_nulls_last   # ORDER BY view_count DESC NULLS LAST
@@ -23,26 +26,30 @@ module BetterModel
     extend ActiveSupport::Concern
 
     included do
-      # Valida che sia incluso solo in modelli ActiveRecord
+      # Validate ActiveRecord inheritance
       unless ancestors.include?(ActiveRecord::Base)
-        raise ArgumentError, "BetterModel::Sortable can only be included in ActiveRecord models"
+        raise BetterModel::Errors::Sortable::ConfigurationError, "BetterModel::Sortable can only be included in ActiveRecord models"
       end
 
-      # Registry dei campi sortable definiti per questa classe
+      # Registry of sortable fields defined for this class
       class_attribute :sortable_fields, default: Set.new
-      # Registry degli scope sortable generati
+      # Registry of generated sortable scopes
       class_attribute :sortable_scopes, default: Set.new
+      # Registry of custom complex sorts
+      class_attribute :complex_sorts_registry, default: {}.freeze
     end
 
     class_methods do
-      # DSL per definire campi sortable
+      # DSL to define sortable fields.
       #
-      # Genera automaticamente scope di ordinamento basati sul tipo di colonna:
+      # Automatically generates sorting scopes based on column type:
       # - String: _asc, _desc, _asc_i, _desc_i (case-insensitive)
       # - Numeric: _asc, _desc, _asc_nulls_last, _desc_nulls_last, etc.
       # - Date: _asc, _desc, _newest, _oldest
       #
-      # Esempio:
+      # @param field_names [Array<Symbol>] Field names to make sortable
+      #
+      # @example
       #   sort :title, :view_count, :published_at
       def sort(*field_names)
         field_names.each do |field_name|
@@ -67,36 +74,103 @@ module BetterModel
         end
       end
 
-      # Verifica se un campo è stato registrato come sortable
-      def sortable_field?(field_name)
-        sortable_fields.include?(field_name.to_sym)
-      end
+      # Register a custom complex sort.
+      #
+      # Allows defining complex sorts that combine multiple fields
+      # or use custom logic not covered by standard sorts.
+      #
+      # @param name [Symbol] Sort name (will be prefixed with sort_)
+      # @yield Sort implementation block
+      # @raise [BetterModel::Errors::Sortable::ConfigurationError] If block is not provided
+      #
+      # @example Multi-field sort
+      #   register_complex_sort :by_popularity do
+      #     order(view_count: :desc, published_at: :desc)
+      #   end
+      #
+      #   Article.sort_by_popularity
+      #
+      # @example Parametrized sort
+      #   register_complex_sort :by_relevance do |keyword|
+      #     order(Arel.sql("CASE WHEN title ILIKE '%#{sanitize_sql_like(keyword)}%' THEN 1 ELSE 2 END"))
+      #   end
+      #
+      #   Article.sort_by_relevance('rails')
+      def register_complex_sort(name, &block)
+        unless block_given?
+          raise BetterModel::Errors::Sortable::ConfigurationError, "Block required for complex sort"
+        end
+
+        # Register in registry
+        self.complex_sorts_registry = complex_sorts_registry.merge(name.to_sym => block).freeze
+
+        # Define scope
+        scope :"sort_#{name}", block
 
-      # Verifica se uno scope sortable è stato generato
-      def sortable_scope?(scope_name)
-        sortable_scopes.include?(scope_name.to_sym)
+        # Register scope
+        register_sortable_scopes(:"sort_#{name}")
       end
 
+      # Check if a field has been registered as sortable.
+      #
+      # @param field_name [Symbol] Field name to check
+      # @return [Boolean] true if field is sortable
+      #
+      # @example
+      #   Article.sortable_field?(:title)  # => true
+      def sortable_field?(field_name) = sortable_fields.include?(field_name.to_sym)
+
+      # Check if a sortable scope has been generated.
+      #
+      # @param scope_name [Symbol] Scope name to check
+      # @return [Boolean] true if scope exists
+      #
+      # @example
+      #   Article.sortable_scope?(:sort_title_asc)  # => true
+      def sortable_scope?(scope_name) = sortable_scopes.include?(scope_name.to_sym)
+
+      # Check if a complex sort has been registered.
+      #
+      # @param name [Symbol] Sort name to check
+      # @return [Boolean] true if complex sort exists
+      #
+      # @example
+      #   Article.complex_sort?(:by_popularity)  # => true
+      def complex_sort?(name) = complex_sorts_registry.key?(name.to_sym)
+
       private
 
-      # Valida che il campo esista nella tabella
+      # Validate that field exists in table.
+      #
+      # @param field_name [Symbol] Field name to validate
+      # @raise [BetterModel::Errors::Sortable::ConfigurationError] If field doesn't exist
+      # @api private
       def validate_sortable_field!(field_name)
         unless column_names.include?(field_name.to_s)
-          raise ArgumentError, "Invalid field name: #{field_name}. Field does not exist in #{table_name}"
+          raise BetterModel::Errors::Sortable::ConfigurationError, "Invalid field name: #{field_name}. Field does not exist in #{table_name}"
         end
       end
 
-      # Registra un campo nel registry sortable_fields
+      # Register a field in sortable_fields registry.
+      #
+      # @param field_name [Symbol] Field name to register
+      # @api private
       def register_sortable_field(field_name)
         self.sortable_fields = (sortable_fields + [ field_name.to_sym ]).to_set.freeze
       end
 
-      # Registra scope nel registry sortable_scopes
+      # Register scopes in sortable_scopes registry.
+      #
+      # @param scope_names [Array<Symbol>] Scope names to register
+      # @api private
       def register_sortable_scopes(*scope_names)
         self.sortable_scopes = (sortable_scopes + scope_names.map(&:to_sym)).to_set.freeze
       end
 
-      # Genera scope base: sort_field_asc e sort_field_desc
+      # Generate base sorting scopes: sort_field_asc and sort_field_desc.
+      #
+      # @param field_name [Symbol] Field name
+      # @api private
       def define_base_sorting(field_name)
         quoted_field = connection.quote_column_name(field_name)
 
@@ -109,7 +183,10 @@ module BetterModel
         )
       end
 
-      # Genera scope per campi stringa (include case-insensitive)
+      # Generate sorting scopes for string fields (includes case-insensitive).
+      #
+      # @param field_name [Symbol] Field name
+      # @api private
       def define_string_sorting(field_name)
         quoted_field = connection.quote_column_name(field_name)
 
@@ -129,21 +206,24 @@ module BetterModel
         )
       end
 
-      # Genera scope per campi numerici (include gestione NULL)
+      # Generate sorting scopes for numeric fields (includes NULL handling).
+      #
+      # @param field_name [Symbol] Field name
+      # @api private
       def define_numeric_sorting(field_name)
         quoted_field = connection.quote_column_name(field_name)
 
-        # Scope base
+        # Base scopes
         scope :"sort_#{field_name}_asc", -> { order(Arel.sql("#{quoted_field} ASC")) }
         scope :"sort_#{field_name}_desc", -> { order(Arel.sql("#{quoted_field} DESC")) }
 
-        # Pre-calcola SQL per gestione NULL (necessario perché lo scope non ha accesso ai metodi privati)
+        # Pre-calculate SQL for NULL handling (necessary because scope doesn't have access to private methods)
         sql_asc_nulls_last = nulls_order_sql(field_name, "ASC", "LAST")
         sql_desc_nulls_last = nulls_order_sql(field_name, "DESC", "LAST")
         sql_asc_nulls_first = nulls_order_sql(field_name, "ASC", "FIRST")
         sql_desc_nulls_first = nulls_order_sql(field_name, "DESC", "FIRST")
 
-        # Scope con gestione NULL
+        # Scopes with NULL handling
         scope :"sort_#{field_name}_asc_nulls_last", -> {
           order(Arel.sql(sql_asc_nulls_last))
         }
@@ -167,15 +247,18 @@ module BetterModel
         )
       end
 
-      # Genera scope per campi data/datetime (include shortcuts semantici)
+      # Generate sorting scopes for date/datetime fields (includes semantic shortcuts).
+      #
+      # @param field_name [Symbol] Field name
+      # @api private
       def define_date_sorting(field_name)
         quoted_field = connection.quote_column_name(field_name)
 
-        # Scope base
+        # Base scopes
         scope :"sort_#{field_name}_asc", -> { order(Arel.sql("#{quoted_field} ASC")) }
         scope :"sort_#{field_name}_desc", -> { order(Arel.sql("#{quoted_field} DESC")) }
 
-        # Shortcuts semantici
+        # Semantic shortcuts
         scope :"sort_#{field_name}_newest", -> { order(Arel.sql("#{quoted_field} DESC")) }
         scope :"sort_#{field_name}_oldest", -> { order(Arel.sql("#{quoted_field} ASC")) }
 
@@ -187,19 +270,24 @@ module BetterModel
         )
       end
 
-      # Genera SQL per gestione NULL multi-database
+      # Generate SQL for NULL handling across different databases.
       #
-      # NOTA: Il blocco MySQL else qui sotto non è coperto da test automatici
-      # perché i test vengono eseguiti su SQLite. Testare manualmente su MySQL
-      # con: rails console RAILS_ENV=test
+      # @param field_name [Symbol] Field name
+      # @param direction [String] Sort direction ('ASC' or 'DESC')
+      # @param nulls_position [String] NULL position ('FIRST' or 'LAST')
+      # @return [String] SQL ORDER BY clause
+      # @api private
+      #
+      # @note The MySQL/MariaDB else block is not covered by automated tests
+      #   because tests run on SQLite. Test manually on MySQL with: rails console RAILS_ENV=test
       def nulls_order_sql(field_name, direction, nulls_position)
         quoted_field = connection.quote_column_name(field_name)
 
-        # PostgreSQL e SQLite 3.30+ supportano NULLS LAST/FIRST nativamente
+        # PostgreSQL and SQLite 3.30+ support NULLS LAST/FIRST natively
         if connection.adapter_name.match?(/PostgreSQL|SQLite/)
           "#{quoted_field} #{direction} NULLS #{nulls_position}"
         else
-          # MySQL/MariaDB: emulazione con CASE
+          # MySQL/MariaDB: emulate with CASE
           if nulls_position == "LAST"
             "CASE WHEN #{quoted_field} IS NULL THEN 1 ELSE 0 END, #{quoted_field} #{direction}"
           else # FIRST
@@ -209,9 +297,17 @@ module BetterModel
       end
     end
 
-    # Metodi di istanza
-
-    # Ritorna lista di attributi sortable (esclude campi sensibili)
+    # Instance Methods
+
+    # Returns list of sortable attributes (excludes sensitive fields).
+    #
+    # Automatically filters out password and encrypted fields for security.
+    #
+    # @return [Array<String>] Sortable attribute names
+    #
+    # @example
+    #   article.sortable_attributes
+    #   # => ["id", "title", "view_count", "published_at", "created_at", "updated_at"]
     def sortable_attributes
       self.class.column_names.reject do |attr|
         attr.start_with?("password", "encrypted_")

data/lib/better_model/stateable/configurator.rb

@@ -2,19 +2,19 @@
 
 module BetterModel
   module Stateable
-    # Configurator per il DSL di Stateable
+    # Configurator for Stateable DSL.
     #
-    # Questo configurator permette di definire state machines in modo dichiarativo
-    # all'interno del blocco `stateable do...end`.
+    # This configurator enables defining state machines declaratively
+    # within the `stateable do...end` block.
     #
-    # Esempio:
+    # @example
     #   stateable do
-    #     # Definisci stati
+    #     # Define states
     #     state :pending, initial: true
     #     state :confirmed
     #     state :paid
     #
-    #     # Definisci transizioni
+    #     # Define transitions
     #     transition :confirm, from: :pending, to: :confirmed do
     #       check { items.any? }
     #       check :customer_valid?
@@ -27,9 +27,13 @@ module BetterModel
     #     end
     #   end
     #
+    # @api private
     class Configurator
       attr_reader :states, :transitions, :initial_state, :table_name
 
+      # Initialize a new Configurator.
+      #
+      # @param model_class [Class] Model class being configured
       def initialize(model_class)
         @model_class = model_class
         @states = []
@@ -39,16 +43,19 @@ module BetterModel
         @current_transition = nil
       end
 
-      # Definisce uno stato
+      # Define a state.
       #
-      # @param name [Symbol] Nome dello stato
-      # @param initial [Boolean] Se questo è lo stato iniziale
+      # @param name [Symbol] State name
+      # @param initial [Boolean] Whether this is the initial state
+      # @raise [ArgumentError] If state name is invalid or already defined
       #
       # @example
       #   state :draft, initial: true
       #   state :published
       #   state :archived
       #
+      # @example With initial state
+      #   state :pending, initial: true
       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)
@@ -61,17 +68,18 @@ module BetterModel
         end
       end
 
-      # Definisce una transizione
+      # Define a transition.
       #
-      # @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
+      # @param event [Symbol] Event/transition name
+      # @param from [Symbol, Array<Symbol>] Source state(s)
+      # @param to [Symbol] Destination state
+      # @yield Block to configure guards, validations, callbacks
+      # @raise [ArgumentError] If event is invalid, already defined, or states don't exist
       #
-      # @example Transizione semplice
+      # @example Simple transition
       #   transition :publish, from: :draft, to: :published
       #
-      # @example Con checks e callbacks
+      # @example With checks and callbacks
       #   transition :confirm, from: :pending, to: :confirmed do
       #     check { valid? }
       #     check :ready_to_confirm?
@@ -79,17 +87,17 @@ module BetterModel
       #     after_transition { send_email }
       #   end
       #
-      # @example Da multipli stati
+      # @example From multiple states
       #   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
+        # Normalize from to array
         from_states = Array(from)
 
-        # Verifica che gli stati esistano
+        # Verify states exist
         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."
@@ -100,7 +108,7 @@ module BetterModel
           raise ArgumentError, "Unknown state in to: #{to}. Define it with 'state :#{to}' first."
         end
 
-        # Inizializza configurazione transizione
+        # Initialize transition configuration
         @transitions[event] = {
           from: from_states,
           to: to,
@@ -111,7 +119,7 @@ module BetterModel
           around_callbacks: []
         }
 
-        # Se c'è un blocco, configuralo
+        # If block provided, configure it
         if block_given?
           @current_transition = @transitions[event]
           instance_eval(&block)
@@ -119,28 +127,30 @@ module BetterModel
         end
       end
 
-      # Definisce un check per la transizione corrente
+      # Define a check for the current transition.
       #
-      # I checks sono precondizioni che devono essere vere per permettere la transizione.
+      # Checks are preconditions that must be true to allow the transition.
       #
       # @overload check(&block)
-      #   Check con lambda/proc
-      #   @yield Blocco da valutare nel contesto dell'istanza
+      #   Check with lambda/proc
+      #   @yield Block to evaluate in instance context
       #   @example
       #     check { items.any? && customer.present? }
       #
       # @overload check(method_name)
-      #   Check con metodo
-      #   @param method_name [Symbol] Nome del metodo da chiamare
+      #   Check with method
+      #   @param method_name [Symbol] Method name to call
       #   @example
       #     check :customer_valid?
       #
       # @overload check(if: predicate)
-      #   Check con Statusable predicate
-      #   @param if [Symbol] Nome del predicate (integrazione Statusable)
+      #   Check with Statusable predicate
+      #   @param if [Symbol] Predicate name (Statusable integration)
       #   @example
       #     check if: :is_ready_for_publishing?
       #
+      # @raise [StateableError] If called outside transition block
+      # @raise [ArgumentError] If no check provided
       def check(method_name = nil, if: nil, &block)
         raise StateableError, "check can only be called inside a transition block" unless @current_transition
 
@@ -155,12 +165,14 @@ module BetterModel
         end
       end
 
-      # Definisce una validazione per la transizione corrente
+      # Define a validation for the current transition.
       #
-      # Le validazioni sono eseguite dopo i guards e prima dei callbacks.
-      # Devono aggiungere errori all'oggetto errors se la validazione fallisce.
+      # Validations are executed after guards and before callbacks.
+      # They must add errors to the errors object if validation fails.
       #
-      # @yield Blocco da valutare nel contesto dell'istanza
+      # @yield Block to evaluate in instance context
+      # @raise [StateableError] If called outside transition block
+      # @raise [ArgumentError] If no block provided
       #
       # @example
       #   validate do
@@ -175,22 +187,24 @@ module BetterModel
         @current_transition[:validations] << block
       end
 
-      # Definisce un callback before_transition per la transizione corrente
+      # Define a before_transition callback for the current transition.
       #
-      # I before_transition callbacks sono eseguiti prima della transizione di stato.
+      # Before_transition callbacks are executed before the state transition.
       #
       # @overload before_transition(&block)
-      #   Before_transition callback con lambda/proc
-      #   @yield Blocco da eseguire
+      #   Before_transition callback with lambda/proc
+      #   @yield Block to execute
       #   @example
       #     before_transition { calculate_total }
       #
       # @overload before_transition(method_name)
-      #   Before_transition callback con metodo
-      #   @param method_name [Symbol] Nome del metodo da chiamare
+      #   Before_transition callback with method
+      #   @param method_name [Symbol] Method name to call
       #   @example
       #     before_transition :calculate_total
       #
+      # @raise [StateableError] If called outside transition block
+      # @raise [ArgumentError] If no callback provided
       def before_transition(method_name = nil, &block)
         raise StateableError, "before_transition can only be called inside a transition block" unless @current_transition
 
@@ -203,22 +217,24 @@ module BetterModel
         end
       end
 
-      # Definisce un callback after_transition per la transizione corrente
+      # Define an after_transition callback for the current transition.
       #
-      # Gli after_transition callbacks sono eseguiti dopo la transizione di stato.
+      # After_transition callbacks are executed after the state transition.
       #
       # @overload after_transition(&block)
-      #   After_transition callback con lambda/proc
-      #   @yield Blocco da eseguire
+      #   After_transition callback with lambda/proc
+      #   @yield Block to execute
       #   @example
       #     after_transition { send_notification }
       #
       # @overload after_transition(method_name)
-      #   After_transition callback con metodo
-      #   @param method_name [Symbol] Nome del metodo da chiamare
+      #   After_transition callback with method
+      #   @param method_name [Symbol] Method name to call
       #   @example
       #     after_transition :send_notification
       #
+      # @raise [StateableError] If called outside transition block
+      # @raise [ArgumentError] If no callback provided
       def after_transition(method_name = nil, &block)
         raise StateableError, "after_transition can only be called inside a transition block" unless @current_transition
 
@@ -231,12 +247,14 @@ module BetterModel
         end
       end
 
-      # Definisce un callback around per la transizione corrente
+      # Define an around callback for the current transition.
       #
-      # Gli around callbacks wrappano la transizione di stato.
-      # Il blocco riceve un altro blocco che deve chiamare per eseguire la transizione.
+      # Around callbacks wrap the state transition.
+      # The block receives another block that must be called to execute the transition.
       #
-      # @yield Blocco da eseguire, riceve un blocco da chiamare
+      # @yield Block to execute, receives a block to call
+      # @raise [StateableError] If called outside transition block
+      # @raise [ArgumentError] If no block provided
       #
       # @example
       #   around do |transition|
@@ -252,9 +270,9 @@ module BetterModel
         @current_transition[:around_callbacks] << block
       end
 
-      # Specifica il nome della tabella per state transitions
+      # Specify the table name for state transitions.
       #
-      # @param name [String, Symbol] Nome della tabella
+      # @param name [String, Symbol] Table name
       #
       # @example Default (state_transitions)
       #   stateable do
@@ -283,9 +301,9 @@ module BetterModel
         @table_name = name.to_s
       end
 
-      # Restituisce la configurazione completa
+      # Return complete configuration.
       #
-      # @return [Hash] Configurazione con stati e transizioni
+      # @return [Hash] Configuration with states and transitions
       #
       def to_h
         {