better_model 2.0.0 → 2.1.0

data/lib/better_model/predicable.rb

@@ -17,7 +17,7 @@
 #   Article.title_i_cont("rails")               # WHERE LOWER(title) LIKE '%rails%'
 #   Article.view_count_gt(100)                  # WHERE view_count > 100
 #   Article.published_at_lteq(Date.today)       # WHERE published_at <= '2025-10-29'
-#   Article.featured_eq(true)                   # WHERE featured = TRUE
+#   Article.featured_true                       # WHERE featured = TRUE
 #   Article.status_in(["draft", "published"])   # WHERE status IN ('draft', 'published')
 #
 module BetterModel
@@ -42,10 +42,12 @@ module BetterModel
       # DSL per definire campi predicable
       #
       # Genera automaticamente scope di filtro basati sul tipo di colonna:
-      # - String: _eq, _not_eq, _matches, _start, _end, _cont, _not_cont, _i_cont, _not_i_cont, _in, _not_in, _present, _blank, _null
-      # - Numeric: _eq, _not_eq, _lt, _lteq, _gt, _gteq, _in, _not_in, _present
-      # - Boolean: _eq, _not_eq, _present (Note: _true and _false removed in v2.0.0 - use _eq(true/false))
-      # - Date: _eq, _not_eq, _lt, _lteq, _gt, _gteq, _in, _not_in, _present, _blank, _null, _not_null
+      # - String: _eq, _not_eq, _matches, _start, _end, _cont, _not_cont, _i_cont, _not_i_cont, _in, _not_in, _present(bool), _blank(bool), _null(bool)
+      # - Numeric: _eq, _not_eq, _lt, _lteq, _gt, _gteq, _between, _not_between, _in, _not_in, _present(bool)
+      # - Boolean: _eq, _not_eq, _present(bool)
+      # - Date: _eq, _not_eq, _lt, _lteq, _gt, _gteq, _between, _not_between, _in, _not_in, _within(duration), _blank(bool), _null(bool)
+      #
+      # Nota: Tutti i predicati richiedono parametri espliciti. Use _eq(true)/_eq(false) per booleani.
       #
       # Esempio:
       #   predicates :title, :view_count, :published_at, :featured
@@ -151,16 +153,11 @@ module BetterModel
         scope :"#{field_name}_not_eq", ->(value) { where(field.not_eq(value)) }
 
         # Presence - skip for string/text types as they get specialized version
-        # Required boolean parameter:
-        # - true: returns present records (NOT NULL)
-        # - false: returns null records (NULL)
+        # String types need to check for both nil and empty string
+        # Requires boolean parameter: true for present, false for absent
         unless [ :string, :text ].include?(column_type)
-          scope :"#{field_name}_present", ->(condition) {
-            if condition
-              where(field.not_eq(nil))
-            else
-              where(field.eq(nil))
-            end
+          scope :"#{field_name}_present", ->(value) {
+            value ? where(field.not_eq(nil)) : where(field.eq(nil))
           }
         end
 
@@ -170,23 +167,17 @@ module BetterModel
         register_predicable_scopes(*scopes_to_register)
       end
 
-      # Genera predicati per campi stringa (12 scope)
+      # Genera predicati per campi stringa (14 scope)
       # Base predicates (_eq, _not_eq) are defined separately
-      # _present is defined here to handle both nil and empty strings
+      # _present(bool), _blank(bool), _null(bool) handle presence with parameters
       def define_string_predicates(field_name)
         table = arel_table
         field = table[field_name]
 
         # String-specific presence check (checks both nil and empty string)
-        # Required boolean parameter:
-        # - true: returns present records (NOT NULL AND NOT '')
-        # - false: returns blank records (NULL OR '')
-        scope :"#{field_name}_present", ->(condition) {
-          if condition
-            where(field.not_eq(nil).and(field.not_eq("")))
-          else
-            where(field.eq(nil).or(field.eq("")))
-          end
+        # Requires boolean parameter: true for present, false for blank
+        scope :"#{field_name}_present", ->(value) {
+          value ? where(field.not_eq(nil).and(field.not_eq(""))) : where(field.eq(nil).or(field.eq("")))
         }
 
         # Pattern matching (4)
@@ -222,23 +213,13 @@ module BetterModel
         scope :"#{field_name}_in", ->(values) { where(field.in(Array(values))) }
         scope :"#{field_name}_not_in", ->(values) { where.not(field.in(Array(values))) }
 
-        # Presence (2)
-        # Required boolean parameter:
-        # - true: returns blank/null records
-        # - false: returns present/not-null records
-        scope :"#{field_name}_blank", ->(condition) {
-          if condition
-            where(field.eq(nil).or(field.eq("")))
-          else
-            where(field.not_eq(nil).and(field.not_eq("")))
-          end
+        # Presence predicates (3) - _present is overridden above for string-specific behavior
+        # All require boolean parameter: true for condition, false for negation
+        scope :"#{field_name}_blank", ->(value) {
+          value ? where(field.eq(nil).or(field.eq(""))) : where(field.not_eq(nil).and(field.not_eq("")))
         }
-        scope :"#{field_name}_null", ->(condition) {
-          if condition
-            where(field.eq(nil))
-          else
-            where(field.not_eq(nil))
-          end
+        scope :"#{field_name}_null", ->(value) {
+          value ? where(field.eq(nil)) : where(field.not_eq(nil))
         }
 
         register_predicable_scopes(
@@ -257,8 +238,8 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi numerici (8 scope)
-      # Base predicates (_eq, _not_eq, _present) are defined separately
+      # Genera predicati per campi numerici (11 scope)
+      # Base predicates (_eq, _not_eq, _present(bool)) are defined separately
       def define_numeric_predicates(field_name)
         table = arel_table
         field = table[field_name]
@@ -290,16 +271,12 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi booleani
+      # Genera predicati per campi booleani (0 scope)
       # Base predicates (_eq, _not_eq, _present) are defined separately
-      #
-      # Note: In v2.0.0, we removed _true and _false predicates as they were
-      # redundant with the base _eq predicate. Use these instead:
-      #   field_eq(true)   # instead of field_true
-      #   field_eq(false)  # instead of field_false
+      # Use _eq(true) or _eq(false) for boolean filtering
       def define_boolean_predicates(field_name)
-        # Boolean fields only use base predicates (_eq, _not_eq, _present)
-        # No additional predicates needed
+        # No additional scopes needed for boolean fields
+        # Use field_eq(true) or field_eq(false) instead
       end
 
       # Genera predicati per campi array PostgreSQL (3 scope)
@@ -411,8 +388,9 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi data/datetime (17 scope)
-      # Base predicates (_eq, _not_eq, _present) are defined separately
+      # Genera predicati per campi data/datetime (11 scope)
+      # Base predicates (_eq, _not_eq, _present(bool)) are defined separately
+      # Date convenience shortcuts removed except _within(duration)
       def define_date_predicates(field_name)
         table = arel_table
         field = table[field_name]
@@ -431,37 +409,20 @@ module BetterModel
         scope :"#{field_name}_in", ->(values) { where(field.in(Array(values))) }
         scope :"#{field_name}_not_in", ->(values) { where.not(field.in(Array(values))) }
 
-        # Date time-based filter (1)
+        # Date convenience - only _within with explicit parameter
         scope :"#{field_name}_within", ->(duration) {
           # Auto-detect: ActiveSupport::Duration or numeric (days)
           time_ago = duration.respond_to?(:ago) ? duration.ago : duration.to_i.days.ago
           where(field.gteq(time_ago))
         }
 
-        # Presence (3) - _present is defined in base predicates
-        # Required boolean parameter:
-        # - true: returns blank/null records
-        # - false: returns not-blank/not-null records
-        scope :"#{field_name}_blank", ->(condition) {
-          if condition
-            where(field.eq(nil))
-          else
-            where(field.not_eq(nil))
-          end
+        # Presence predicates (2) - _present(bool) is defined in base predicates
+        # _blank and _null require boolean parameter: true for condition, false for negation
+        scope :"#{field_name}_blank", ->(value) {
+          value ? where(field.eq(nil)) : where(field.not_eq(nil))
         }
-        scope :"#{field_name}_null", ->(condition) {
-          if condition
-            where(field.eq(nil))
-          else
-            where(field.not_eq(nil))
-          end
-        }
-        scope :"#{field_name}_not_null", ->(condition) {
-          if condition
-            where(field.not_eq(nil))
-          else
-            where(field.eq(nil))
-          end
+        scope :"#{field_name}_null", ->(value) {
+          value ? where(field.eq(nil)) : where(field.not_eq(nil))
         }
 
         register_predicable_scopes(
@@ -475,8 +436,7 @@ module BetterModel
           :"#{field_name}_not_in",
           :"#{field_name}_within",
           :"#{field_name}_blank",
-          :"#{field_name}_null",
-          :"#{field_name}_not_null"
+          :"#{field_name}_null"
         )
       end
 

data/lib/better_model/searchable.rb

@@ -90,6 +90,9 @@ module BetterModel
         pagination = options.delete(:pagination)
         orders = options.delete(:orders)
         security = options.delete(:security)
+        includes_param = options.delete(:includes)
+        preload_param = options.delete(:preload)
+        eager_load_param = options.delete(:eager_load)
 
         # If there are remaining unknown options, they might be misplaced predicates
         if options.any?
@@ -132,6 +135,11 @@ module BetterModel
         # Apply pagination
         scope = apply_pagination(scope, pagination) if pagination.present?
 
+        # Apply eager loading associations
+        scope = apply_includes(scope, includes_param) if includes_param.present?
+        scope = apply_preload(scope, preload_param) if preload_param.present?
+        scope = apply_eager_load(scope, eager_load_param) if eager_load_param.present?
+
         scope
       end
 
@@ -227,13 +235,14 @@ module BetterModel
           next if value.nil?
           next if value.respond_to?(:empty?) && value.empty?
 
-          # v2.0.0: ALL predicates require parameters
-          # Apply scope with parameter
-          scope = if value.is_a?(Array)
+          # Apply scope
+          scope = if value == true || value == "true"
+            # All predicates require parameters, pass true
+            scope.public_send(predicate_scope, true)
+          elsif value.is_a?(Array)
             # Splat array values for predicates like _between that expect multiple args
             scope.public_send(predicate_scope, *value)
           else
-            # Pass value as parameter (all predicates require at least one parameter)
             scope.public_send(predicate_scope, value)
           end
         end
@@ -319,6 +328,24 @@ module BetterModel
         scope.limit(per_page).offset(offset)
       end
 
+      # Applica includes per eager loading delle associazioni (usa LEFT OUTER JOIN)
+      def apply_includes(scope, includes_param)
+        return scope if includes_param.blank?
+        scope.includes(includes_param)
+      end
+
+      # Applica preload per eager loading delle associazioni (carica con query separate)
+      def apply_preload(scope, preload_param)
+        return scope if preload_param.blank?
+        scope.preload(preload_param)
+      end
+
+      # Applica eager_load per eager loading delle associazioni (forza LEFT OUTER JOIN)
+      def apply_eager_load(scope, eager_load_param)
+        return scope if eager_load_param.blank?
+        scope.eager_load(eager_load_param)
+      end
+
       # Valida che i predicati obbligatori della security siano presenti con valori validi
       def validate_security(security_name, predicates)
         # Converti security_name a symbol

data/lib/better_model/stateable/configurator.rb

@@ -16,14 +16,14 @@ module BetterModel
     #
     #     # Definisci transizioni
     #     transition :confirm, from: :pending, to: :confirmed do
-    #       guard { items.any? }
-    #       guard :customer_valid?
-    #       guard if: :is_ready?
+    #       check { items.any? }
+    #       check :customer_valid?
+    #       check if: :is_ready?
     #
     #       validate { errors.add(:base, "Invalid") unless valid_for_confirmation? }
     #
-    #       before { prepare }
-    #       after { notify }
+    #       before_transition { prepare }
+    #       after_transition { notify }
     #     end
     #   end
     #
@@ -71,12 +71,12 @@ module BetterModel
       # @example Transizione semplice
       #   transition :publish, from: :draft, to: :published
       #
-      # @example Con guards e callbacks
+      # @example Con checks e callbacks
       #   transition :confirm, from: :pending, to: :confirmed do
-      #     guard { valid? }
-      #     guard :ready_to_confirm?
-      #     before { prepare_confirmation }
-      #     after { send_email }
+      #     check { valid? }
+      #     check :ready_to_confirm?
+      #     before_transition { prepare_confirmation }
+      #     after_transition { send_email }
       #   end
       #
       # @example Da multipli stati
@@ -119,30 +119,30 @@ module BetterModel
         end
       end
 
-      # Definisce un guard per la transizione corrente
+      # Definisce un check per la transizione corrente
       #
-      # I guards sono precondizioni che devono essere vere per permettere la transizione.
+      # I checks sono precondizioni che devono essere vere per permettere la transizione.
       #
-      # @overload guard(&block)
-      #   Guard con lambda/proc
+      # @overload check(&block)
+      #   Check con lambda/proc
       #   @yield Blocco da valutare nel contesto dell'istanza
       #   @example
-      #     guard { items.any? && customer.present? }
+      #     check { items.any? && customer.present? }
       #
-      # @overload guard(method_name)
-      #   Guard con metodo
+      # @overload check(method_name)
+      #   Check con metodo
       #   @param method_name [Symbol] Nome del metodo da chiamare
       #   @example
-      #     guard :customer_valid?
+      #     check :customer_valid?
       #
-      # @overload guard(if: predicate)
-      #   Guard con Statusable predicate
+      # @overload check(if: predicate)
+      #   Check con Statusable predicate
       #   @param if [Symbol] Nome del predicate (integrazione Statusable)
       #   @example
-      #     guard if: :is_ready_for_publishing?
+      #     check 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
+      def check(method_name = nil, if: nil, &block)
+        raise StateableError, "check can only be called inside a transition block" unless @current_transition
 
         if block_given?
           @current_transition[:guards] << { type: :block, block: block }
@@ -151,7 +151,7 @@ module BetterModel
         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"
+          raise ArgumentError, "check requires either a block, method name, or if: option"
         end
       end
 
@@ -175,59 +175,59 @@ module BetterModel
         @current_transition[:validations] << block
       end
 
-      # Definisce un callback before per la transizione corrente
+      # Definisce un callback before_transition per la transizione corrente
       #
-      # I before callbacks sono eseguiti prima della transizione di stato.
+      # I before_transition callbacks sono eseguiti prima della transizione di stato.
       #
-      # @overload before(&block)
-      #   Before callback con lambda/proc
+      # @overload before_transition(&block)
+      #   Before_transition callback con lambda/proc
       #   @yield Blocco da eseguire
       #   @example
-      #     before { calculate_total }
+      #     before_transition { calculate_total }
       #
-      # @overload before(method_name)
-      #   Before callback con metodo
+      # @overload before_transition(method_name)
+      #   Before_transition callback con metodo
       #   @param method_name [Symbol] Nome del metodo da chiamare
       #   @example
-      #     before :calculate_total
+      #     before_transition :calculate_total
       #
-      def before(method_name = nil, &block)
-        raise StateableError, "before can only be called inside a transition block" unless @current_transition
+      def before_transition(method_name = nil, &block)
+        raise StateableError, "before_transition 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"
+          raise ArgumentError, "before_transition requires either a block or method name"
         end
       end
 
-      # Definisce un callback after per la transizione corrente
+      # Definisce un callback after_transition per la transizione corrente
       #
-      # Gli after callbacks sono eseguiti dopo la transizione di stato.
+      # Gli after_transition callbacks sono eseguiti dopo la transizione di stato.
       #
-      # @overload after(&block)
-      #   After callback con lambda/proc
+      # @overload after_transition(&block)
+      #   After_transition callback con lambda/proc
       #   @yield Blocco da eseguire
       #   @example
-      #     after { send_notification }
+      #     after_transition { send_notification }
       #
-      # @overload after(method_name)
-      #   After callback con metodo
+      # @overload after_transition(method_name)
+      #   After_transition callback con metodo
       #   @param method_name [Symbol] Nome del metodo da chiamare
       #   @example
-      #     after :send_notification
+      #     after_transition :send_notification
       #
-      def after(method_name = nil, &block)
-        raise StateableError, "after can only be called inside a transition block" unless @current_transition
+      def after_transition(method_name = nil, &block)
+        raise StateableError, "after_transition 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"
+          raise ArgumentError, "after_transition requires either a block or method name"
         end
       end
 

data/lib/better_model/stateable/errors.rb

@@ -26,15 +26,18 @@ module BetterModel
       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
+    # Raised when a check condition fails
+    class CheckFailedError < StateableError
+      def initialize(event, check_description = nil)
+        msg = "Check failed for transition #{event.inspect}"
+        msg += ": #{check_description}" if check_description
         super(msg)
       end
     end
 
+    # Alias for backwards compatibility
+    GuardFailedError = CheckFailedError
+
     # Raised when a transition validation fails
     class ValidationFailedError < StateableError
       def initialize(event, errors)

data/lib/better_model/stateable/guard.rb

@@ -2,10 +2,10 @@
 
 module BetterModel
   module Stateable
-    # Guard evaluator per Stateable
+    # Check evaluator per Stateable (internal class name remains Guard for compatibility)
     #
-    # Valuta le guard conditions per determinare se una transizione è permessa.
-    # Supporta tre tipi di guards:
+    # 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.)
@@ -16,10 +16,10 @@ module BetterModel
         @guard_config = guard_config
       end
 
-      # Valuta il guard
+      # Valuta il check
       #
-      # @return [Boolean] true se il guard passa
-      # @raise [GuardFailedError] Se il guard fallisce (opzionale, dipende dal contesto)
+      # @return [Boolean] true se il check passa
+      # @raise [CheckFailedError] Se il check fallisce (opzionale, dipende dal contesto)
       #
       def evaluate
         case @guard_config[:type]
@@ -30,53 +30,53 @@ module BetterModel
         when :predicate
           evaluate_predicate
         else
-          raise StateableError, "Unknown guard type: #{@guard_config[:type]}"
+          raise StateableError, "Unknown check type: #{@guard_config[:type]}"
         end
       end
 
-      # Descrizione del guard per messaggi di errore
+      # Descrizione del check per messaggi di errore
       #
       # @return [String] Descrizione human-readable
       #
       def description
         case @guard_config[:type]
         when :block
-          "block guard"
+          "block check"
         when :method
-          "method guard: #{@guard_config[:method]}"
+          "method check: #{@guard_config[:method]}"
         when :predicate
-          "predicate guard: #{@guard_config[:predicate]}"
+          "predicate check: #{@guard_config[:predicate]}"
         else
-          "unknown guard"
+          "unknown check"
         end
       end
 
       private
 
-      # Valuta un guard block
+      # Valuta un check block
       def evaluate_block
         block = @guard_config[:block]
         @instance.instance_exec(&block)
       end
 
-      # Valuta un guard method
+      # Valuta un check 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}. " \
+          raise NoMethodError, "Check 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)
+      # Valuta un check 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}. " \
+          raise NoMethodError, "Check predicate '#{predicate_name}' not found in #{@instance.class.name}. " \
                                "Make sure Statusable is enabled and the predicate is defined: is :ready, -> { ... }"
         end
 

data/lib/better_model/stateable/transition.rb

@@ -5,9 +5,9 @@ module BetterModel
     # Transition executor per Stateable
     #
     # Gestisce l'esecuzione di una transizione di stato, includendo:
-    # - Valutazione guards
+    # - Valutazione checks
     # - Esecuzione validazioni
-    # - Esecuzione callbacks (before/after/around)
+    # - Esecuzione callbacks (before_transition/after_transition/around)
     # - Aggiornamento stato nel database
     # - Creazione record StateTransition per storico
     #
@@ -23,14 +23,14 @@ module BetterModel
 
       # Esegue la transizione
       #
-      # @raise [GuardFailedError] Se un guard fallisce
+      # @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
       #
       def execute!
-        # 1. Valuta guards
-        evaluate_guards!
+        # 1. Valuta checks
+        evaluate_checks!
 
         # 2. Esegui validazioni
         execute_validations!
@@ -52,15 +52,15 @@ module BetterModel
 
       private
 
-      # Valuta tutti i guards
-      def evaluate_guards!
-        guards = @config[:guards] || []
+      # Valuta tutti i checks
+      def evaluate_checks!
+        checks = @config[:guards] || []  # Manteniamo :guards per compatibilità interna
 
-        guards.each do |guard_config|
-          guard = Guard.new(@instance, guard_config)
+        checks.each do |check_config|
+          check = Guard.new(@instance, check_config)  # Guard class handles the logic
 
-          unless guard.evaluate
-            raise GuardFailedError.new(@event, guard.description)
+          unless check.evaluate
+            raise CheckFailedError.new(@event, check.description)
           end
         end
       end
@@ -101,7 +101,7 @@ module BetterModel
 
       # Esegue la transizione effettiva
       def perform_transition!
-        # 1. Esegui before callbacks
+        # 1. Esegui before_transition callbacks
         execute_callbacks(@config[:before_callbacks] || [])
 
         # 2. Aggiorna stato
@@ -113,7 +113,7 @@ module BetterModel
         # 4. Crea record StateTransition
         create_state_transition_record
 
-        # 5. Esegui after callbacks
+        # 5. Esegui after_transition callbacks
         execute_callbacks(@config[:after_callbacks] || [])
       end