better_model 2.0.0 → 3.0.0

data/lib/better_model/statusable.rb

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

data/lib/better_model/taggable.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
-# Taggable - Sistema di gestione tag dichiarativo per modelli Rails
+require_relative "errors/taggable/taggable_error"
+require_relative "errors/taggable/configuration_error"
+
+# Taggable - Declarative tag management system for Rails models.
 #
-# Questo concern permette di gestire tag multipli sui modelli utilizzando array PostgreSQL
-# con normalizzazione, validazione e statistiche. La ricerca è delegata a Predicable.
+# This concern enables managing multiple tags on models using PostgreSQL arrays
+# with normalization, validation, and statistics. Search is delegated to Predicable.
 #
-# Esempio di utilizzo:
+# @example Basic Usage
 #   class Article < ApplicationRecord
 #     include BetterModel
 #
@@ -16,18 +19,18 @@
 #     end
 #   end
 #
-# Utilizzo:
-#   article.tag_with("ruby", "rails")           # Aggiungi tag
-#   article.untag("rails")                      # Rimuovi tag
-#   article.tag_list = "ruby, rails, tutorial"  # Da stringa CSV
+# @example Managing Tags
+#   article.tag_with("ruby", "rails")           # Add tags
+#   article.untag("rails")                      # Remove tags
+#   article.tag_list = "ruby, rails, tutorial"  # From CSV string
 #   article.tagged_with?("ruby")                # => true
 #
-# Ricerca (delegata a Predicable):
+# @example Searching (Delegated to Predicable)
 #   Article.tags_contains("ruby")               # Predicable
 #   Article.tags_overlaps(["ruby", "python"])   # Predicable
 #   Article.search(tags_contains: "ruby")       # Searchable + Predicable
 #
-# Statistiche:
+# @example Statistics
 #   Article.tag_counts                          # => {"ruby" => 45, "rails" => 38}
 #   Article.popular_tags(limit: 10)             # => [["ruby", 45], ["rails", 38], ...]
 #
@@ -35,7 +38,11 @@ module BetterModel
   module Taggable
     extend ActiveSupport::Concern
 
-    # Configurazione Taggable
+    # Taggable Configuration.
+    #
+    # Internal configuration class for the Taggable DSL.
+    #
+    # @api private
     class Configuration
       attr_reader :validates_minimum, :validates_maximum, :allowed_tags, :forbidden_tags
 
@@ -91,19 +98,22 @@ module BetterModel
     end
 
     included do
-      # Valida che sia incluso solo in modelli ActiveRecord
+      # Validate ActiveRecord inheritance
       unless ancestors.include?(ActiveRecord::Base)
-        raise ArgumentError, "BetterModel::Taggable can only be included in ActiveRecord models"
+        raise BetterModel::Errors::Taggable::ConfigurationError, "Invalid configuration"
       end
 
-      # Configurazione Taggable per questa classe
+      # Taggable configuration for this class
       class_attribute :taggable_config, default: nil
     end
 
     class_methods do
-      # DSL per configurare Taggable
+      # DSL to configure Taggable.
       #
-      # Esempio:
+      # @yield [config] Configuration block
+      # @raise [BetterModel::Errors::Taggable::ConfigurationError] If already configured or field doesn't exist
+      #
+      # @example
       #   taggable do
       #     tag_field :tags
       #     normalize true
@@ -114,39 +124,41 @@ module BetterModel
       #     validates_tags minimum: 1, maximum: 10, allowed_tags: ["ruby", "rails"]
       #   end
       def taggable(&block)
-        # Previeni configurazione multipla
+        # Prevent multiple configuration
         if taggable_config.present?
-          raise ArgumentError, "Taggable already configured for #{name}"
+          raise BetterModel::Errors::Taggable::ConfigurationError, "Invalid configuration"
         end
 
-        # Crea configurazione
+        # Create configuration
         config = Configuration.new
         config.instance_eval(&block) if block_given?
 
-        # Valida che il campo esista
+        # Validate that field exists
         tag_field_name = config.tag_field.to_s
         unless column_names.include?(tag_field_name)
-          raise ArgumentError, "Tag field #{config.tag_field} does not exist in #{table_name}"
+          raise BetterModel::Errors::Taggable::ConfigurationError, "Invalid configuration"
         end
 
-        # Salva configurazione (frozen per thread-safety)
+        # Save configuration (frozen for thread-safety)
         self.taggable_config = config.freeze
 
-        # Auto-registra predicates per ricerca (delegato a Predicable)
+        # Auto-register predicates for search (delegated to Predicable)
         predicates config.tag_field if respond_to?(:predicates)
 
-        # Registra validazioni se configurate
+        # Register validations if configured
         setup_validations(config) if config.validates_minimum || config.validates_maximum ||
                                      config.allowed_tags || config.forbidden_tags
       end
 
       # ============================================================================
-      # CLASS METHODS - Statistiche
+      # CLASS METHODS - Statistics
       # ============================================================================
 
-      # Restituisce un hash con il conteggio di ciascun tag
+      # Returns a hash with the count of each tag.
+      #
+      # @return [Hash{String => Integer}] Tag counts
       #
-      # Esempio:
+      # @example
       #   Article.tag_counts  # => {"ruby" => 45, "rails" => 38, "tutorial" => 12}
       def tag_counts
         return {} unless taggable_config
@@ -163,9 +175,12 @@ module BetterModel
         counts
       end
 
-      # Restituisce i tag più popolari con il loro conteggio
+      # Returns the most popular tags with their counts.
       #
-      # Esempio:
+      # @param limit [Integer] Maximum number of tags to return
+      # @return [Array<Array(String, Integer)>] Tag-count pairs sorted by count
+      #
+      # @example
       #   Article.popular_tags(limit: 10)
       #   # => [["ruby", 45], ["rails", 38], ["tutorial", 12]]
       def popular_tags(limit: 10)
@@ -176,9 +191,13 @@ module BetterModel
           .first(limit)
       end
 
-      # Restituisce i tag che appaiono insieme al tag specificato
+      # Returns tags that appear together with the specified tag.
+      #
+      # @param tag [String] Tag to find related tags for
+      # @param limit [Integer] Maximum number of related tags to return
+      # @return [Array<String>] Related tags sorted by frequency
       #
-      # Esempio:
+      # @example
       #   Article.related_tags("ruby", limit: 10)
       #   # => ["rails", "gem", "activerecord"]
       def related_tags(tag, limit: 10)
@@ -187,25 +206,25 @@ module BetterModel
         field = taggable_config.tag_field
         related_counts = Hash.new(0)
 
-        # Normalizza il tag query
+        # Normalize query tag
         config = taggable_config
         normalized_tag = tag.to_s
         normalized_tag = normalized_tag.strip if config.strip
         normalized_tag = normalized_tag.downcase if config.normalize
 
-        # Trova record che contengono il tag
+        # Find records containing the tag
         find_each do |record|
           tags = record.public_send(field) || []
           next unless tags.include?(normalized_tag)
 
-          # Conta gli altri tag che appaiono insieme
+          # Count other tags that appear together
           tags.each do |other_tag|
             next if other_tag == normalized_tag
             related_counts[other_tag] += 1
           end
         end
 
-        # Restituisci ordinati per frequenza
+        # Return sorted by frequency
         related_counts
           .sort_by { |_tag, count| -count }
           .first(limit)
@@ -214,11 +233,14 @@ module BetterModel
 
       private
 
-      # Setup delle validazioni ActiveRecord
+      # Setup ActiveRecord validations.
+      #
+      # @param config [Configuration] Taggable configuration
+      # @api private
       def setup_validations(config)
         field = config.tag_field
 
-        # Validazione minimum
+        # Minimum validation
         if config.validates_minimum
           min = config.validates_minimum
           validate do
@@ -229,7 +251,7 @@ module BetterModel
           end
         end
 
-        # Validazione maximum
+        # Maximum validation
         if config.validates_maximum
           max = config.validates_maximum
           validate do
@@ -240,7 +262,7 @@ module BetterModel
           end
         end
 
-        # Validazione whitelist
+        # Whitelist validation
         if config.allowed_tags
           allowed = config.allowed_tags
           validate do
@@ -252,7 +274,7 @@ module BetterModel
           end
         end
 
-        # Validazione blacklist
+        # Blacklist validation
         if config.forbidden_tags
           forbidden = config.forbidden_tags
           validate do
@@ -267,12 +289,15 @@ module BetterModel
     end
 
     # ============================================================================
-    # INSTANCE METHODS - Gestione Tag
+    # INSTANCE METHODS - Tag Management
     # ============================================================================
 
-    # Aggiunge uno o più tag al record
+    # Add one or more tags to the record.
+    #
+    # @param new_tags [Array<String>] Tags to add
+    # @return [void]
     #
-    # Esempio:
+    # @example
     #   article.tag_with("ruby")
     #   article.tag_with("ruby", "rails", "tutorial")
     def tag_with(*new_tags)
@@ -281,21 +306,24 @@ module BetterModel
       config = self.class.taggable_config
       field = config.tag_field
 
-      # Inizializza array se nil
+      # Initialize array if nil
       current_tags = public_send(field) || []
 
-      # Normalizza e aggiungi tag (evita duplicati con |)
+      # Normalize and add tags (avoid duplicates with |)
       normalized_tags = new_tags.flatten.map { |tag| normalize_tag(tag) }.compact
       updated_tags = (current_tags | normalized_tags)
 
-      # Aggiorna il campo
+      # Update field
       public_send("#{field}=", updated_tags)
       save if persisted?
     end
 
-    # Rimuove uno o più tag dal record
+    # Remove one or more tags from the record.
     #
-    # Esempio:
+    # @param tags_to_remove [Array<String>] Tags to remove
+    # @return [void]
+    #
+    # @example
     #   article.untag("tutorial")
     #   article.untag("ruby", "rails")
     def untag(*tags_to_remove)
@@ -304,23 +332,26 @@ module BetterModel
       config = self.class.taggable_config
       field = config.tag_field
 
-      # Ottieni tag attuali
+      # Get current tags
       current_tags = public_send(field) || []
 
-      # Normalizza tag da rimuovere
+      # Normalize tags to remove
       normalized_tags = tags_to_remove.flatten.map { |tag| normalize_tag(tag) }.compact
 
-      # Rimuovi tag
+      # Remove tags
       updated_tags = current_tags - normalized_tags
 
-      # Aggiorna il campo
+      # Update field
       public_send("#{field}=", updated_tags)
       save if persisted?
     end
 
-    # Sostituisce tutti i tag esistenti con nuovi tag
+    # Replace all existing tags with new tags.
+    #
+    # @param new_tags [Array<String>] New tags to set
+    # @return [void]
     #
-    # Esempio:
+    # @example
     #   article.retag("python", "django")
     def retag(*new_tags)
       return unless taggable_enabled?
@@ -328,17 +359,20 @@ module BetterModel
       config = self.class.taggable_config
       field = config.tag_field
 
-      # Normalizza nuovi tag
+      # Normalize new tags
       normalized_tags = new_tags.flatten.map { |tag| normalize_tag(tag) }.compact.uniq
 
-      # Sostituisci tutti i tag
+      # Replace all tags
       public_send("#{field}=", normalized_tags)
       save if persisted?
     end
 
-    # Verifica se il record ha un determinato tag
+    # Check if record has a specific tag.
     #
-    # Esempio:
+    # @param tag [String] Tag to check
+    # @return [Boolean] true if record has the tag
+    #
+    # @example
     #   article.tagged_with?("ruby")  # => true/false
     def tagged_with?(tag)
       return false unless taggable_enabled?
@@ -356,9 +390,11 @@ module BetterModel
     # TAG LIST (CSV Interface)
     # ============================================================================
 
-    # Restituisce i tag come stringa separata da delimitatore
+    # Returns tags as a delimited string.
+    #
+    # @return [String] Tags joined by delimiter
     #
-    # Esempio:
+    # @example
     #   article.tag_list  # => "ruby, rails, tutorial"
     def tag_list
       return "" unless taggable_enabled?
@@ -369,14 +405,17 @@ module BetterModel
 
       current_tags = public_send(field) || []
 
-      # Aggiungi spazio dopo virgola per leggibilità (solo se delimiter è virgola)
+      # Add space after comma for readability (only if delimiter is comma)
       separator = delimiter == "," ? "#{delimiter} " : delimiter
       current_tags.join(separator)
     end
 
-    # Imposta i tag da una stringa separata da delimitatore
+    # Set tags from a delimited string.
     #
-    # Esempio:
+    # @param tag_string [String] Delimited tag string
+    # @return [void]
+    #
+    # @example
     #   article.tag_list = "ruby, rails, tutorial"
     def tag_list=(tag_string)
       return unless taggable_enabled?
@@ -401,25 +440,26 @@ module BetterModel
     # JSON SERIALIZATION
     # ============================================================================
 
-    # Override as_json per includere informazioni tag
+    # Override as_json to include tag information.
     #
-    # Opzioni:
-    #   include_tag_list: true    # Includi tag_list come string
-    #   include_tag_stats: true   # Includi statistiche tag
+    # @param options [Hash] Options for as_json
+    # @option options [Boolean] :include_tag_list Include tag_list as string
+    # @option options [Boolean] :include_tag_stats Include tag statistics
+    # @return [Hash] JSON representation
     #
-    # Esempio:
+    # @example
     #   article.as_json(include_tag_list: true, include_tag_stats: true)
     def as_json(options = {})
       json = super(options)
 
       return json unless taggable_enabled?
 
-      # Aggiungi tag_list se richiesto
+      # Add tag_list if requested
       if options[:include_tag_list]
         json["tag_list"] = tag_list
       end
 
-      # Aggiungi statistiche tag se richiesto
+      # Add tag statistics if requested
       if options[:include_tag_stats]
         config = self.class.taggable_config
         field = config.tag_field
@@ -436,12 +476,17 @@ module BetterModel
 
     private
 
-    # Verifica se Taggable è abilitato per questa classe
-    def taggable_enabled?
-      self.class.taggable_config.present?
-    end
+    # Check if Taggable is enabled for this class.
+    #
+    # @return [Boolean] true if enabled
+    # @api private
+    def taggable_enabled? = self.class.taggable_config.present?
 
-    # Normalizza un tag secondo la configurazione
+    # Normalize a tag according to configuration.
+    #
+    # @param tag [String] Tag to normalize
+    # @return [String, nil] Normalized tag or nil if invalid
+    # @api private
     def normalize_tag(tag)
       return nil if tag.blank?