better_model 1.0.0 → 1.1.0

data/lib/better_model/predicable.rb

@@ -58,6 +58,9 @@ module BetterModel
           column = columns_hash[field_name.to_s]
           next unless column
 
+          # Base predicates available for all column types
+          define_base_predicates(field_name)
+
           case column.type
           when :string, :text
             define_string_predicates(field_name)
@@ -68,18 +71,14 @@ module BetterModel
           when :date, :datetime, :time, :timestamp
             define_date_predicates(field_name)
           when :jsonb, :json
-            # JSONB/JSON: base predicates + PostgreSQL-specific
-            define_base_predicates(field_name)
+            # JSONB/JSON: PostgreSQL-specific predicates
             define_postgresql_jsonb_predicates(field_name)
           else
             # Check for array columns (PostgreSQL)
             if column.respond_to?(:array?) && column.array?
-              define_base_predicates(field_name)
               define_postgresql_array_predicates(field_name)
-            else
-              # Default: genera solo predicati base
-              define_base_predicates(field_name)
             end
+            # Unknown types only get base predicates
           end
         end
       end
@@ -161,14 +160,15 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi stringa (14 scope)
+      # Genera predicati per campi stringa (12 scope)
+      # Base predicates (_eq, _not_eq) are defined separately
+      # _present is redefined here to handle empty strings
       def define_string_predicates(field_name)
         table = arel_table
         field = table[field_name]
 
-        # Comparison (2)
-        scope :"#{field_name}_eq", ->(value) { where(field.eq(value)) }
-        scope :"#{field_name}_not_eq", ->(value) { where(field.not_eq(value)) }
+        # String-specific presence check (overrides base _present)
+        scope :"#{field_name}_present", -> { where(field.not_eq(nil).and(field.not_eq(""))) }
 
         # Pattern matching (4)
         scope :"#{field_name}_matches", ->(pattern) { where(field.matches(pattern)) }
@@ -203,14 +203,11 @@ 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 (3)
-        scope :"#{field_name}_present", -> { where(field.not_eq(nil).and(field.not_eq(""))) }
+        # Presence (2) - _present is overridden above for string-specific behavior
         scope :"#{field_name}_blank", -> { where(field.eq(nil).or(field.eq(""))) }
         scope :"#{field_name}_null", -> { where(field.eq(nil)) }
 
         register_predicable_scopes(
-          :"#{field_name}_eq",
-          :"#{field_name}_not_eq",
           :"#{field_name}_matches",
           :"#{field_name}_start",
           :"#{field_name}_end",
@@ -226,14 +223,13 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi numerici (11 scope)
+      # Genera predicati per campi numerici (8 scope)
+      # Base predicates (_eq, _not_eq, _present) are defined separately
       def define_numeric_predicates(field_name)
         table = arel_table
         field = table[field_name]
 
-        # Comparison (6)
-        scope :"#{field_name}_eq", ->(value) { where(field.eq(value)) }
-        scope :"#{field_name}_not_eq", ->(value) { where(field.not_eq(value)) }
+        # Comparison (4)
         scope :"#{field_name}_lt", ->(value) { where(field.lt(value)) }
         scope :"#{field_name}_lteq", ->(value) { where(field.lteq(value)) }
         scope :"#{field_name}_gt", ->(value) { where(field.gt(value)) }
@@ -247,12 +243,7 @@ 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 (1)
-        scope :"#{field_name}_present", -> { where(field.not_eq(nil)) }
-
         register_predicable_scopes(
-          :"#{field_name}_eq",
-          :"#{field_name}_not_eq",
           :"#{field_name}_lt",
           :"#{field_name}_lteq",
           :"#{field_name}_gt",
@@ -265,28 +256,19 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi booleani (5 scope)
+      # Genera predicati per campi booleani (2 scope)
+      # Base predicates (_eq, _not_eq, _present) are defined separately
       def define_boolean_predicates(field_name)
         table = arel_table
         field = table[field_name]
 
-        # Comparison (2)
-        scope :"#{field_name}_eq", ->(value) { where(field.eq(value)) }
-        scope :"#{field_name}_not_eq", ->(value) { where(field.not_eq(value)) }
-
         # Boolean shortcuts (2)
         scope :"#{field_name}_true", -> { where(field.eq(true)) }
         scope :"#{field_name}_false", -> { where(field.eq(false)) }
 
-        # Presence (1)
-        scope :"#{field_name}_present", -> { where(field.not_eq(nil)) }
-
         register_predicable_scopes(
-          :"#{field_name}_eq",
-          :"#{field_name}_not_eq",
           :"#{field_name}_true",
-          :"#{field_name}_false",
-          :"#{field_name}_present"
+          :"#{field_name}_false"
         )
       end
 
@@ -391,14 +373,13 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi data/datetime (22 scope)
+      # Genera predicati per campi data/datetime (17 scope)
+      # Base predicates (_eq, _not_eq, _present) are defined separately
       def define_date_predicates(field_name)
         table = arel_table
         field = table[field_name]
 
-        # Comparison (6)
-        scope :"#{field_name}_eq", ->(value) { where(field.eq(value)) }
-        scope :"#{field_name}_not_eq", ->(value) { where(field.not_eq(value)) }
+        # Comparison (4)
         scope :"#{field_name}_lt", ->(value) { where(field.lt(value)) }
         scope :"#{field_name}_lteq", ->(value) { where(field.lteq(value)) }
         scope :"#{field_name}_gt", ->(value) { where(field.gt(value)) }
@@ -440,15 +421,12 @@ module BetterModel
           where(field.gteq(time_ago))
         }
 
-        # Presence (4)
-        scope :"#{field_name}_present", -> { where(field.not_eq(nil)) }
+        # Presence (3) - _present is defined in base predicates
         scope :"#{field_name}_blank", -> { where(field.eq(nil)) }
         scope :"#{field_name}_null", -> { where(field.eq(nil)) }
         scope :"#{field_name}_not_null", -> { where(field.not_eq(nil)) }
 
         register_predicable_scopes(
-          :"#{field_name}_eq",
-          :"#{field_name}_not_eq",
           :"#{field_name}_lt",
           :"#{field_name}_lteq",
           :"#{field_name}_gt",
@@ -465,7 +443,6 @@ module BetterModel
           :"#{field_name}_past",
           :"#{field_name}_future",
           :"#{field_name}_within",
-          :"#{field_name}_present",
           :"#{field_name}_blank",
           :"#{field_name}_null",
           :"#{field_name}_not_null"

data/lib/better_model/state_transition.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module BetterModel
+  # StateTransition - Base ActiveRecord model for state transition history
+  #
+  # Questo è un modello abstract. Le classi concrete vengono generate dinamicamente
+  # per ogni tabella (state_transitions, order_transitions, etc.).
+  #
+  # Schema della tabella:
+  #   t.string :transitionable_type, null: false
+  #   t.integer :transitionable_id, null: false
+  #   t.string :event, null: false
+  #   t.string :from_state, null: false
+  #   t.string :to_state, null: false
+  #   t.json :metadata
+  #   t.datetime :created_at, null: false
+  #
+  # Utilizzo:
+  #   # Tutte le transizioni di un modello
+  #   order.state_transitions
+  #
+  #   # Query globali (tramite classi dinamiche)
+  #   BetterModel::StateTransitions.for_model(Order)
+  #   BetterModel::OrderTransitions.by_event(:confirm)
+  #
+  class StateTransition < ActiveRecord::Base
+    # Default table name (can be overridden by dynamic subclasses)
+    self.table_name = "state_transitions"
+
+    # Polymorphic association
+    belongs_to :transitionable, polymorphic: true
+
+    # Validations
+    validates :event, :from_state, :to_state, presence: true
+
+    # Scopes
+
+    # Scope per modello specifico
+    #
+    # @param model_class [Class] Classe del modello
+    # @return [ActiveRecord::Relation]
+    #
+    scope :for_model, ->(model_class) {
+      where(transitionable_type: model_class.name)
+    }
+
+    # Scope per evento specifico
+    #
+    # @param event [Symbol, String] Nome dell'evento
+    # @return [ActiveRecord::Relation]
+    #
+    scope :by_event, ->(event) {
+      where(event: event.to_s)
+    }
+
+    # Scope per stato di partenza
+    #
+    # @param state [Symbol, String] Stato di partenza
+    # @return [ActiveRecord::Relation]
+    #
+    scope :from_state, ->(state) {
+      where(from_state: state.to_s)
+    }
+
+    # Scope per stato di arrivo
+    #
+    # @param state [Symbol, String] Stato di arrivo
+    # @return [ActiveRecord::Relation]
+    #
+    scope :to_state, ->(state) {
+      where(to_state: state.to_s)
+    }
+
+    # Scope per transizioni recenti
+    #
+    # @param duration [ActiveSupport::Duration] Durata (es. 7.days)
+    # @return [ActiveRecord::Relation]
+    #
+    scope :recent, ->(duration = 7.days) {
+      where("created_at >= ?", duration.ago)
+    }
+
+    # Scope per transizioni in un periodo
+    #
+    # @param start_time [Time, Date] Inizio periodo
+    # @param end_time [Time, Date] Fine periodo
+    # @return [ActiveRecord::Relation]
+    #
+    scope :between, ->(start_time, end_time) {
+      where(created_at: start_time..end_time)
+    }
+
+    # Metodi di istanza
+
+    # Formatted description della transizione
+    #
+    # @return [String]
+    #
+    def description
+      "#{transitionable_type}##{transitionable_id}: #{from_state} -> #{to_state} (#{event})"
+    end
+
+    # Alias per retrocompatibilità
+    alias_method :to_s, :description
+  end
+end

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