better_model 2.0.0 → 3.0.0

data/lib/better_model/errors/sortable/sortable_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "../better_model_error"
+
+module BetterModel
+  module Errors
+    module Sortable
+      # Base error class for all Sortable-related errors.
+      class SortableError < BetterModelError
+      end
+    end
+  end
+end

data/lib/better_model/errors/stateable/check_failed_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "stateable_error"
+
+module BetterModel
+  module Errors
+    module Stateable
+      class CheckFailedError < StateableError; end
+
+      # Alias for backward compatibility
+      GuardFailedError = CheckFailedError
+    end
+  end
+end

data/lib/better_model/errors/stateable/configuration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+
+module BetterModel
+  module Errors
+    module Stateable
+      class ConfigurationError < ArgumentError; end
+    end
+  end
+end

data/lib/better_model/errors/stateable/invalid_state_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "stateable_error"
+
+module BetterModel
+  module Errors
+    module Stateable
+      class InvalidStateError < StateableError; end
+    end
+  end
+end

data/lib/better_model/errors/stateable/invalid_transition_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "stateable_error"
+
+module BetterModel
+  module Errors
+    module Stateable
+      class InvalidTransitionError < StateableError; end
+    end
+  end
+end

data/lib/better_model/errors/stateable/not_enabled_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "stateable_error"
+
+module BetterModel
+  module Errors
+    module Stateable
+      class NotEnabledError < StateableError; end
+    end
+  end
+end

data/lib/better_model/errors/stateable/stateable_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "../better_model_error"
+
+module BetterModel
+  module Errors
+    module Stateable
+      # Base error class for all Stateable-related errors.
+      class StateableError < BetterModelError
+      end
+    end
+  end
+end

data/lib/better_model/errors/stateable/validation_failed_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "stateable_error"
+
+module BetterModel
+  module Errors
+    module Stateable
+      class ValidationFailedError < StateableError; end
+    end
+  end
+end

data/lib/better_model/errors/statusable/configuration_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Errors
+    module Statusable
+      class ConfigurationError < ArgumentError; end
+    end
+  end
+end

data/lib/better_model/errors/statusable/statusable_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "../better_model_error"
+
+module BetterModel
+  module Errors
+    module Statusable
+      # Base error class for all Statusable-related errors.
+      class StatusableError < BetterModelError
+      end
+    end
+  end
+end

data/lib/better_model/errors/taggable/configuration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+
+module BetterModel
+  module Errors
+    module Taggable
+      class ConfigurationError < ArgumentError; end
+    end
+  end
+end

data/lib/better_model/errors/taggable/taggable_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "../better_model_error"
+
+module BetterModel
+  module Errors
+    module Taggable
+      # Base error class for all Taggable-related errors.
+      class TaggableError < BetterModelError
+      end
+    end
+  end
+end

data/lib/better_model/errors/traceable/configuration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+
+module BetterModel
+  module Errors
+    module Traceable
+      class ConfigurationError < ArgumentError; end
+    end
+  end
+end

data/lib/better_model/errors/traceable/not_enabled_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "traceable_error"
+
+module BetterModel
+  module Errors
+    module Traceable
+      class NotEnabledError < TraceableError; end
+    end
+  end
+end

data/lib/better_model/errors/traceable/traceable_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "../better_model_error"
+
+module BetterModel
+  module Errors
+    module Traceable
+      # Base error class for all Traceable-related errors.
+      class TraceableError < BetterModelError
+      end
+    end
+  end
+end

data/lib/better_model/errors/validatable/configuration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+
+module BetterModel
+  module Errors
+    module Validatable
+      class ConfigurationError < ArgumentError; end
+    end
+  end
+end

data/lib/better_model/errors/validatable/not_enabled_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "validatable_error"
+
+module BetterModel
+  module Errors
+    module Validatable
+      class NotEnabledError < ValidatableError; end
+    end
+  end
+end

data/lib/better_model/errors/validatable/validatable_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "../better_model_error"
+
+module BetterModel
+  module Errors
+    module Validatable
+      # Base error class for all Validatable-related errors.
+      class ValidatableError < BetterModelError
+      end
+    end
+  end
+end

data/lib/better_model/models/state_transition.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Models
+    # StateTransition - Base ActiveRecord model for state transition history.
+    #
+    # This is an abstract model. Concrete classes are generated dynamically
+    # for each table (state_transitions, order_transitions, etc.).
+    #
+    # @note Table Schema
+    #   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
+    #
+    # @example Usage
+    #   # All transitions for a model
+    #   order.state_transitions
+    #
+    # @example Global queries (via dynamic classes)
+    #   BetterModel::Models::StateTransitions.for_model(Order)
+    #   BetterModel::Models::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 for specific model.
+      #
+      # @param model_class [Class] Model class
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   StateTransition.for_model(Order)
+      scope :for_model, ->(model_class) {
+        where(transitionable_type: model_class.name)
+      }
+
+      # Scope for specific event.
+      #
+      # @param event [Symbol, String] Event name
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   StateTransition.by_event(:confirm)
+      scope :by_event, ->(event) {
+        where(event: event.to_s)
+      }
+
+      # Scope for source state.
+      #
+      # @param state [Symbol, String] Source state
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   StateTransition.from_state(:pending)
+      scope :from_state, ->(state) {
+        where(from_state: state.to_s)
+      }
+
+      # Scope for destination state.
+      #
+      # @param state [Symbol, String] Destination state
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   StateTransition.to_state(:confirmed)
+      scope :to_state, ->(state) {
+        where(to_state: state.to_s)
+      }
+
+      # Scope for recent transitions.
+      #
+      # @param duration [ActiveSupport::Duration] Time duration (e.g., 7.days)
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   StateTransition.recent(7.days)
+      scope :recent, ->(duration = 7.days) {
+        where("created_at >= ?", duration.ago)
+      }
+
+      # Scope for transitions in a time period.
+      #
+      # @param start_time [Time, Date] Period start
+      # @param end_time [Time, Date] Period end
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   StateTransition.between(1.week.ago, Time.current)
+      scope :between, ->(start_time, end_time) {
+        where(created_at: start_time..end_time)
+      }
+
+      # Instance Methods
+
+      # Formatted description of the transition.
+      #
+      # @return [String] Human-readable transition description
+      #
+      # @example
+      #   transition.description  # => "Order#123: pending -> confirmed (confirm)"
+      def description
+        "#{transitionable_type}##{transitionable_id}: #{from_state} -> #{to_state} (#{event})"
+      end
+
+      # Alias for backward compatibility
+      alias_method :to_s, :description
+    end
+  end
+end

data/lib/better_model/models/version.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Models
+    # Version model for tracking changes
+    # This is the base AR model for version history
+    # Actual table_name is set dynamically in subclasses
+    class Version < ActiveRecord::Base
+      self.abstract_class = true
+
+      # Polymorphic association to the tracked model
+      belongs_to :item, polymorphic: true, optional: true
+
+      # Optional: belongs_to user who made the change
+      # belongs_to :updated_by, class_name: "User", optional: true
+
+      # Serialize object_changes as JSON
+      # Rails handles this automatically for json/jsonb columns
+
+      # Validations
+      validates :item_type, :event, presence: true
+      validates :event, inclusion: { in: %w[created updated destroyed] }
+
+      # Scopes
+      scope :for_item, ->(item) { where(item_type: item.class.name, item_id: item.id) }
+      scope :created_events, -> { where(event: "created") }
+      scope :updated_events, -> { where(event: "updated") }
+      scope :destroyed_events, -> { where(event: "destroyed") }
+      scope :by_user, ->(user_id) { where(updated_by_id: user_id) }
+      scope :between, ->(start_time, end_time) { where(created_at: start_time..end_time) }
+      scope :recent, ->(limit = 10) { order(created_at: :desc).limit(limit) }
+
+      # Get the change for a specific field
+      #
+      # @param field_name [Symbol, String] Field name
+      # @return [Hash, nil] Hash with :before and :after keys
+      def change_for(field_name)
+        return nil unless object_changes
+
+        field = field_name.to_s
+        return nil unless object_changes.key?(field)
+
+        {
+          before: object_changes[field][0],
+          after: object_changes[field][1]
+        }
+      end
+
+      # Check if a specific field changed in this version
+      # This method overrides ActiveRecord's changed? to accept a field_name parameter
+      #
+      # @param field_name [Symbol, String, nil] Field name (if nil, calls ActiveRecord's changed?)
+      # @return [Boolean]
+      def changed?(field_name = nil)
+        return super() if field_name.nil?
+
+        object_changes&.key?(field_name.to_s) || false
+      end
+
+      # Get list of changed fields
+      #
+      # @return [Array<String>]
+      def changed_fields
+        object_changes&.keys || []
+      end
+    end
+  end
+end

data/lib/better_model/permissible.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
-# Permissible - Sistema di permessi dichiarativi per modelli Rails
+require_relative "errors/permissible/permissible_error"
+require_relative "errors/permissible/configuration_error"
+
+# Permissible - Declarative permissions system for Rails models.
 #
-# Questo concern permette di definire permessi/capacità sui modelli utilizzando un DSL
-# semplice e dichiarativo, simile al pattern Statusable ma per le operazioni.
+# This concern enables defining permissions/capabilities on models using a simple,
+# declarative DSL, similar to the Statusable pattern but for operations.
 #
-# Esempio di utilizzo:
+# @example Basic Usage
 #   class Article < ApplicationRecord
 #     include BetterModel::Permissible
 #
@@ -15,7 +18,7 @@
 #     permit :archive, -> { is?(:published) && created_at < 1.year.ago }
 #   end
 #
-# Utilizzo:
+# @example Checking Permissions
 #   article.permit?(:delete)           # => true/false
 #   article.permit_delete?             # => true/false
 #   article.permit_edit?               # => true/false
@@ -26,58 +29,85 @@ module BetterModel
     extend ActiveSupport::Concern
 
     included do
-      # Registry dei permessi definiti per questa classe
+      # Registry of permissions defined for this class
       class_attribute :permit_definitions
       self.permit_definitions = {}
     end
 
     class_methods do
-      # DSL per definire permessi
+      # DSL to define permissions.
+      #
+      # Defines a permission check that can be evaluated against model instances.
+      # Automatically creates a convenience method permit_<permission_name>? for each permission.
       #
-      # Parametri:
-      # - permission_name: simbolo che rappresenta il permesso (es. :delete, :edit)
-      # - condition_proc: lambda o proc che definisce la condizione
-      # - block: blocco alternativo alla condition_proc
+      # @param permission_name [Symbol, String] Permission identifier (e.g., :delete, :edit)
+      # @param condition_proc [Proc, nil] Lambda or proc that defines the condition
+      # @yield Alternative to condition_proc parameter
+      # @raise [BetterModel::Errors::Permissible::ConfigurationError] If parameters are invalid
       #
-      # Esempi:
+      # @example With lambda parameter
       #   permit :delete, -> { status != "published" }
-      #   permit :edit, -> { is?(:draft) }
+      #
+      # @example With block
+      #   permit :edit do
+      #     is?(:draft)
+      #   end
+      #
+      # @example Complex condition
       #   permit :publish do
       #     is?(:draft) && valid?(:publication)
       #   end
       def permit(permission_name, condition_proc = nil, &block)
-        # Valida i parametri prima di convertire
-        raise ArgumentError, "Permission name cannot be blank" if permission_name.blank?
+        # Validate parameters before converting
+        if permission_name.blank?
+          raise BetterModel::Errors::Permissible::ConfigurationError, "Permission name cannot be blank"
+        end
 
         permission_name = permission_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 il permesso nel registry
+        unless condition
+          raise BetterModel::Errors::Permissible::ConfigurationError, "Condition proc or block is required"
+        end
+
+        unless condition.respond_to?(:call)
+          raise BetterModel::Errors::Permissible::ConfigurationError, "Condition must respond to call"
+        end
+
+        # Register permission in registry
         self.permit_definitions = permit_definitions.merge(permission_name => condition.freeze).freeze
 
-        # Genera il metodo dinamico permit_#{permission_name}?
+        # Generate dynamic method permit_#{permission_name}?
         define_permit_method(permission_name)
       end
 
-      # Lista di tutti i permessi definiti per questa classe
-      def defined_permissions
-        permit_definitions.keys
-      end
+      # List all permissions defined for this class.
+      #
+      # @return [Array<Symbol>] Array of defined permission names
+      #
+      # @example
+      #   Article.defined_permissions  # => [:delete, :edit, :publish]
+      def defined_permissions = permit_definitions.keys
 
-      # Verifica se un permesso è definito
-      def permission_defined?(permission_name)
-        permit_definitions.key?(permission_name.to_sym)
-      end
+      # Check if a permission is defined.
+      #
+      # @param permission_name [Symbol, String] Permission name to check
+      # @return [Boolean] true if permission is defined
+      #
+      # @example
+      #   Article.permission_defined?(:delete)  # => true
+      def permission_defined?(permission_name) = permit_definitions.key?(permission_name.to_sym)
 
       private
 
-      # Genera dinamicamente il metodo permit_#{permission_name}? per ogni permesso definito
+      # Generate dynamic method permit_#{permission_name}? for each defined permission.
+      #
+      # @param permission_name [Symbol] Permission name
+      # @api private
       def define_permit_method(permission_name)
         method_name = "permit_#{permission_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
@@ -86,35 +116,33 @@ module BetterModel
       end
     end
 
-    # Metodo generico per verificare se un permesso è garantito
+    # Generic method to check if a permission is granted.
     #
-    # Parametri:
-    # - permission_name: simbolo del permesso da verificare
+    # Evaluates the permission condition in the context of the model instance.
+    # Returns false if permission is not defined (secure by default).
     #
-    # Ritorna:
-    # - true se il permesso è garantito
-    # - false se il permesso non è garantito o non è definito
+    # @param permission_name [Symbol, String] Permission name to check
+    # @return [Boolean] true if permission is granted, false otherwise
     #
-    # Esempio:
-    #   article.permit?(:delete)
+    # @example
+    #   article.permit?(:delete)  # => true
     def permit?(permission_name)
       permission_name = permission_name.to_sym
       condition = self.class.permit_definitions[permission_name]
 
-      # Se il permesso non è definito, ritorna false (secure by default)
+      # If permission 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 i permessi disponibili per questa istanza con i loro valori
+    # Returns all available permissions for this instance with their values.
     #
-    # Ritorna:
-    # - Hash con chiavi simbolo (permessi) e valori booleani (garantiti/negati)
+    # @return [Hash{Symbol => Boolean}] Hash with permission names and their granted status
     #
-    # Esempio:
+    # @example
     #   article.permissions
     #   # => { delete: true, edit: false, publish: false, archive: false }
     def permissions
@@ -123,26 +151,49 @@ module BetterModel
       end
     end
 
-    # Verifica se l'istanza ha almeno un permesso garantito
-    def has_any_permission?
-      permissions.values.any?
-    end
+    # Check if instance has at least one granted permission.
+    #
+    # @return [Boolean] true if any permission is granted
+    #
+    # @example
+    #   article.has_any_permission?  # => true
+    def has_any_permission? = permissions.values.any?
 
-    # Verifica se l'istanza ha tutti i permessi specificati garantiti
+    # Check if instance has all specified permissions granted.
+    #
+    # @param permission_names [Array<Symbol>] Permission names to check
+    # @return [Boolean] true if all permissions are granted
+    #
+    # @example
+    #   article.has_all_permissions?([:edit, :publish])  # => false
     def has_all_permissions?(permission_names)
       Array(permission_names).all? { |permission_name| permit?(permission_name) }
     end
 
-    # Filtra una lista di permessi restituendo solo quelli garantiti
+    # Filter a list of permissions returning only granted ones.
+    #
+    # @param permission_names [Array<Symbol>] Permission names to filter
+    # @return [Array<Symbol>] Granted permissions
+    #
+    # @example
+    #   article.granted_permissions([:edit, :delete, :publish])  # => [:edit]
     def granted_permissions(permission_names)
       Array(permission_names).select { |permission_name| permit?(permission_name) }
     end
 
-    # Override di as_json per includere automaticamente i permessi se richiesto
+    # Override as_json to automatically include permissions if requested.
+    #
+    # @param options [Hash] Options for as_json
+    # @option options [Boolean] :include_permissions Include permissions in JSON output
+    # @return [Hash] JSON representation
+    #
+    # @example
+    #   article.as_json(include_permissions: true)
+    #   # => { ..., "permissions" => { "delete" => true, "edit" => false } }
     def as_json(options = {})
       result = super
 
-      # Include i permessi se esplicitamente richiesto, converting symbol keys to strings
+      # Include permissions if explicitly requested, converting symbol keys to strings
       result["permissions"] = permissions.transform_keys(&:to_s) if options[:include_permissions]
 
       result