better_model 2.0.0 → 3.0.0

data/lib/better_model/validatable.rb

@@ -1,56 +1,62 @@
 # frozen_string_literal: true
 
-# Validatable - Sistema di validazioni dichiarativo per modelli Rails
+require_relative "errors/validatable/validatable_error"
+require_relative "errors/validatable/not_enabled_error"
+require_relative "errors/validatable/configuration_error"
+
+# Validatable - Declarative validation system for Rails models.
 #
-# Questo concern permette di definire validazioni in modo dichiarativo e leggibile,
-# con supporto per validazioni condizionali, gruppi, cross-field e business rules.
+# This concern enables defining validations declaratively and readably,
+# with support for conditional validations, groups, cross-field, and business rules.
 #
-# APPROCCIO OPT-IN: Le validazioni dichiarative non sono attive automaticamente.
-# Devi chiamare esplicitamente `validatable do...end` nel tuo modello.
+# @note OPT-IN APPROACH
+#   Declarative validations are not enabled automatically.
+#   You must explicitly call `validatable do...end` in your model.
 #
-# Esempio di utilizzo:
+# @example Basic Usage
 #   class Article < ApplicationRecord
 #     include BetterModel
 #
-#     # Status (già esistente in Statusable)
+#     # Status (from Statusable)
 #     is :draft, -> { status == "draft" }
 #     is :published, -> { status == "published" }
 #
-#     # Attiva validatable (opt-in)
-#     validatable do
-#       # Validazioni base
-#       validate :title, :content, presence: true
+#     # Register complex validations
+#     register_complex_validation :valid_date_range do
+#       return if starts_at.blank? || ends_at.blank?
+#       errors.add(:starts_at, "must be before end date") if starts_at >= ends_at
+#     end
 #
-#       # Validazioni condizionali
-#       validate_if :is_published? do
-#         validate :published_at, presence: true
-#         validate :author_id, presence: true
-#       end
+#     # Enable validatable (opt-in)
+#     validatable do
+#       # Basic validations
+#       check :title, :content, presence: true
 #
-#       # Cross-field validations
-#       validate_order :starts_at, :before, :ends_at
+#       # Conditional validations (using Rails options)
+#       check :published_at, presence: true, if: -> { status == "published" }
+#       check :author_id, presence: true, if: :is_published?
 #
-#       # Business rules
-#       validate_business_rule :valid_category
+#       # Complex validations for cross-field and business logic
+#       check_complex :valid_date_range
 #
-#       # Gruppi di validazioni
+#       # Validation groups
 #       validation_group :step1, [:email, :password]
 #       validation_group :step2, [:first_name, :last_name]
 #     end
 #   end
 #
-# Utilizzo:
-#   article.valid?           # Tutte le validazioni
-#   article.valid?(:step1)   # Solo gruppo step1
+# @example Validation Usage
+#   article.valid?           # All validations
+#   article.valid?(:step1)   # Only step1 group
 #
 module BetterModel
   module Validatable
     extend ActiveSupport::Concern
 
     included do
-      # Validazione ActiveRecord
+      # Validate ActiveRecord inheritance
       unless ancestors.include?(ActiveRecord::Base)
-        raise ArgumentError, "BetterModel::Validatable can only be included in ActiveRecord models"
+        raise BetterModel::Errors::Validatable::ConfigurationError, "Invalid configuration"
       end
 
       # Configurazione validatable (opt-in)
@@ -58,6 +64,8 @@ module BetterModel
       class_attribute :validatable_config, default: {}.freeze
       class_attribute :validatable_groups, default: {}.freeze
       class_attribute :_validatable_setup_done, default: false
+      # Registry dei complex validations custom
+      class_attribute :complex_validations_registry, default: {}.freeze
     end
 
     class_methods do
@@ -65,14 +73,12 @@ module BetterModel
       #
       # @example Attivazione base
       #   validatable do
-      #     validate :title, presence: true
+      #     check :title, presence: true
       #   end
       #
       # @example Con validazioni condizionali
       #   validatable do
-      #     validate_if :is_published? do
-      #       validate :published_at, presence: true
-      #     end
+      #     check :published_at, presence: true, if: :is_published?
       #   end
       #
       def validatable(&block)
@@ -99,98 +105,71 @@ module BetterModel
       # Verifica se validatable è attivo
       #
       # @return [Boolean]
-      def validatable_enabled?
-        validatable_enabled == true
+      def validatable_enabled? = validatable_enabled == true
+
+      # Registra una validazione complessa custom
+      #
+      # Permette di definire validazioni complesse riutilizzabili che possono combinare
+      # più campi o utilizzare logica custom non coperta dalle validazioni standard.
+      #
+      # @param name [Symbol] il nome della validazione
+      # @param block [Proc] il blocco di validazione che verrà eseguito nel contesto dell'istanza
+      #
+      # @example Validazione complessa base
+      #   register_complex_validation :valid_pricing do
+      #     if sale_price.present? && sale_price >= price
+      #       errors.add(:sale_price, "must be less than regular price")
+      #     end
+      #   end
+      #
+      # @example Con logica multi-campo
+      #   register_complex_validation :valid_dates do
+      #     if starts_at.present? && ends_at.present? && starts_at >= ends_at
+      #       errors.add(:ends_at, "must be after start date")
+      #     end
+      #   end
+      #
+      def register_complex_validation(name, &block)
+        unless block_given?
+          raise BetterModel::Errors::Validatable::ConfigurationError, "Invalid configuration"
+        end
+
+        # Registra nel registry
+        self.complex_validations_registry = complex_validations_registry.merge(name.to_sym => block).freeze
       end
 
+      # Verifica se una validazione complessa è stata registrata
+      #
+      # @param name [Symbol] il nome della validazione
+      # @return [Boolean]
+      def complex_validation?(name) = complex_validations_registry.key?(name.to_sym)
+
       private
 
       # Applica le configurazioni di validazione al modello
       def apply_validatable_config
         return unless validatable_config.present?
 
-        # Apply conditional validations
-        validatable_config[:conditional_validations]&.each do |conditional|
-          apply_conditional_validation(conditional)
-        end
-
-        # Apply order validations
-        validatable_config[:order_validations]&.each do |order_val|
-          apply_order_validation(order_val)
-        end
-
-        # Apply business rules
-        validatable_config[:business_rules]&.each do |rule|
-          apply_business_rule(rule)
+        # Apply complex validations
+        validatable_config[:complex_validations]&.each do |name|
+          apply_complex_validation(name)
         end
       end
 
-      # Applica una validazione condizionale
-      def apply_conditional_validation(conditional)
-        condition = conditional[:condition]
-        negate = conditional[:negate]
-        validations = conditional[:validations]
+      # Applica una validazione complessa
+      def apply_complex_validation(name)
+        block = complex_validations_registry[name]
+        return unless block
 
-        # Create a custom validator for this conditional block
+        # Crea un validator custom per questa validazione complessa
         validate do
-          condition_met = if condition.is_a?(Symbol)
-                            send(condition)
-          elsif condition.is_a?(Proc)
-                            instance_exec(&condition)
-          else
-                            raise ArgumentError, "Condition must be a Symbol or Proc"
-          end
-
-          condition_met = !condition_met if negate
-
-          if condition_met
-            validations.each do |validation|
-              apply_validation_in_context(validation)
-            end
-          end
+          instance_eval(&block)
         end
       end
-
-      # Applica una validazione order (cross-field)
-      def apply_order_validation(order_val)
-        validates_with BetterModel::Validatable::OrderValidator,
-                       attributes: [ order_val[:first_field] ],
-                       second_field: order_val[:second_field],
-                       comparator: order_val[:comparator],
-                       **order_val[:options]
-      end
-
-      # Applica una business rule
-      def apply_business_rule(rule)
-        validates_with BetterModel::Validatable::BusinessRuleValidator,
-                       rule_name: rule[:name],
-                       **rule[:options]
-      end
     end
 
     # Metodi di istanza
 
-    # Apply a validation in the context of the current instance
-    def apply_validation_in_context(validation)
-      fields = validation[:fields]
-      options = validation[:options]
-
-      fields.each do |field|
-        options.each do |validator_type, validator_options|
-          # Prepare validator options
-          # If validator_options is true, convert to empty hash
-          # If it's a hash, use as-is
-          opts = validator_options.is_a?(Hash) ? validator_options : {}
-
-          validator = ActiveModel::Validations.const_get("#{validator_type.to_s.camelize}Validator").new(
-            attributes: [ field ],
-            **opts
-          )
-          validator.validate(self)
-        end
-      end
-    end
-
     # Override valid? per supportare validation groups
     #
     # @param context [Symbol, nil] Context o gruppo di validazione
@@ -210,7 +189,9 @@ module BetterModel
     # @param group_name [Symbol] Nome del gruppo
     # @return [Boolean]
     def validate_group(group_name)
-      raise ValidatableNotEnabledError unless self.class.validatable_enabled?
+      unless self.class.validatable_enabled?
+        raise BetterModel::Errors::Validatable::NotEnabledError, "Module is not enabled"
+      end
 
       group = self.class.validatable_groups[group_name]
       return false unless group
@@ -231,7 +212,9 @@ module BetterModel
     # @param group_name [Symbol] Nome del gruppo
     # @return [ActiveModel::Errors]
     def errors_for_group(group_name)
-      raise ValidatableNotEnabledError unless self.class.validatable_enabled?
+      unless self.class.validatable_enabled?
+        raise BetterModel::Errors::Validatable::NotEnabledError, "Module is not enabled"
+      end
 
       group = self.class.validatable_groups[group_name]
       return errors unless group
@@ -259,12 +242,4 @@ module BetterModel
     end
   end
 
-  # Errori custom
-  class ValidatableError < StandardError; end
-
-  class ValidatableNotEnabledError < ValidatableError
-    def initialize(msg = nil)
-      super(msg || "Validatable is not enabled. Add 'validatable do...end' to your model.")
-    end
-  end
 end

data/lib/better_model/version.rb

@@ -1,3 +1,3 @@
 module BetterModel
-  VERSION = "2.0.0"
+  VERSION = "3.0.0"
 end

data/lib/better_model.rb

@@ -1,27 +1,61 @@
 require "better_model/version"
 require "better_model/railtie"
+
+# Load all error classes first
+require "better_model/errors/better_model_error"
+require "better_model/errors/archivable/archivable_error"
+require "better_model/errors/archivable/already_archived_error"
+require "better_model/errors/archivable/not_archived_error"
+require "better_model/errors/archivable/not_enabled_error"
+require "better_model/errors/validatable/validatable_error"
+require "better_model/errors/validatable/not_enabled_error"
+require "better_model/errors/traceable/traceable_error"
+require "better_model/errors/traceable/not_enabled_error"
+require "better_model/errors/searchable/searchable_error"
+require "better_model/errors/searchable/invalid_predicate_error"
+require "better_model/errors/searchable/invalid_order_error"
+require "better_model/errors/searchable/invalid_pagination_error"
+require "better_model/errors/searchable/invalid_security_error"
+require "better_model/errors/stateable/stateable_error"
+require "better_model/errors/stateable/not_enabled_error"
+require "better_model/errors/stateable/invalid_state_error"
+require "better_model/errors/stateable/invalid_transition_error"
+require "better_model/errors/stateable/check_failed_error"
+require "better_model/errors/stateable/validation_failed_error"
+require "better_model/errors/stateable/configuration_error"
+require "better_model/errors/archivable/configuration_error"
+require "better_model/errors/validatable/configuration_error"
+require "better_model/errors/traceable/configuration_error"
+require "better_model/errors/searchable/configuration_error"
+require "better_model/errors/predicable/predicable_error"
+require "better_model/errors/predicable/configuration_error"
+require "better_model/errors/sortable/sortable_error"
+require "better_model/errors/sortable/configuration_error"
+require "better_model/errors/statusable/statusable_error"
+require "better_model/errors/statusable/configuration_error"
+require "better_model/errors/permissible/permissible_error"
+require "better_model/errors/permissible/configuration_error"
+require "better_model/errors/taggable/taggable_error"
+require "better_model/errors/taggable/configuration_error"
+
+# Load modules
 require "better_model/statusable"
 require "better_model/permissible"
 require "better_model/sortable"
 require "better_model/predicable"
 require "better_model/searchable"
 require "better_model/archivable"
-require "better_model/version_record"
+require "better_model/models/version"
 require "better_model/traceable"
 require "better_model/validatable"
 require "better_model/validatable/configurator"
-require "better_model/validatable/order_validator"
-require "better_model/validatable/business_rule_validator"
-require "better_model/state_transition"
+require "better_model/models/state_transition"
 require "better_model/stateable"
 require "better_model/stateable/configurator"
-require "better_model/stateable/errors"
 require "better_model/stateable/guard"
 require "better_model/stateable/transition"
 require "better_model/taggable"
-require "better_model/schedulable"
-require "better_model/schedulable/schedule_builder"
-require "better_model/schedulable/occurrence_calculator"
+require "better_model/repositable"
 
 module BetterModel
   extend ActiveSupport::Concern
@@ -38,6 +72,5 @@ module BetterModel
     include BetterModel::Validatable
     include BetterModel::Stateable
     include BetterModel::Taggable
-    include BetterModel::Schedulable
   end
 end

data/lib/generators/better_model/repository/repository_generator.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module BetterModel
+  module Generators
+    # Generator for creating repository classes that implement the Repository Pattern.
+    #
+    # This generator creates a repository class for a given model, integrating seamlessly
+    # with BetterModel's Searchable, Predicable, and Sortable concerns.
+    #
+    # @example Generate a repository for Article model
+    #   rails generate better_model:repository Article
+    #
+    # @example Generate with custom path
+    #   rails generate better_model:repository Article --path app/services/repositories
+    #
+    # @example Skip ApplicationRepository creation
+    #   rails generate better_model:repository Article --skip-base
+    #
+    class RepositoryGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :path, type: :string, default: "app/repositories",
+                   desc: "Directory where the repository will be created"
+      class_option :skip_base, type: :boolean, default: false,
+                   desc: "Skip creating ApplicationRepository if it doesn't exist"
+      class_option :namespace, type: :string, default: nil,
+                   desc: "Namespace for the repository class"
+
+      # Create the ApplicationRepository base class if it doesn't exist
+      def create_application_repository
+        return if options[:skip_base]
+        return if File.exist?(File.join(destination_root, application_repository_path))
+
+        template "application_repository.rb.tt", application_repository_path
+        say "Created ApplicationRepository at #{application_repository_path}", :green
+      end
+
+      # Create the model-specific repository class
+      def create_repository_file
+        template "repository.rb.tt", repository_path
+        say "Created #{repository_class_name} at #{repository_path}", :green
+      end
+
+      # Display usage instructions
+      def show_instructions
+        say "\nRepository created successfully!", :green
+        say "\nUsage example:", :yellow
+        say "  repo = #{repository_class_name}.new", :white
+        say "  results = repo.search({ #{example_predicate} })", :white
+        say "  record = repo.search({ id_eq: 1 }, limit: 1)", :white
+        say "  all = repo.search({}, limit: nil)", :white
+        say "\nAdd custom methods to #{repository_path}", :yellow
+
+        if model_has_better_model_features?
+          say "\nYour model has BetterModel features enabled:", :green
+          display_available_features
+        else
+          say "\nTip: Include BetterModel in your #{class_name} model to unlock:", :yellow
+          say "  - Predicable: Auto-generated filter scopes", :white
+          say "  - Sortable: Auto-generated sort scopes", :white
+          say "  - Searchable: Unified search interface", :white
+        end
+      end
+
+      private
+
+      def repository_path
+        File.join(options[:path], "#{file_name}_repository.rb")
+      end
+
+      def application_repository_path
+        File.join(options[:path], "application_repository.rb")
+      end
+
+      def repository_class_name
+        if options[:namespace]
+          "#{options[:namespace]}::#{class_name}Repository"
+        else
+          "#{class_name}Repository"
+        end
+      end
+
+      def base_repository_class
+        if options[:skip_base]
+          "BetterModel::Repositable::BaseRepository"
+        else
+          "ApplicationRepository"
+        end
+      end
+
+      def example_predicate
+        if model_class_exists? && model_class.column_names.include?("name")
+          "name_cont: 'search'"
+        elsif model_class_exists? && model_class.column_names.include?("title")
+          "title_cont: 'search'"
+        elsif model_class_exists? && model_class.column_names.include?("status")
+          "status_eq: 'active'"
+        else
+          "id_eq: 1"
+        end
+      end
+
+      def model_class_exists?
+        return false unless Object.const_defined?(class_name)
+        klass = class_name.constantize
+        klass < ActiveRecord::Base && klass.table_exists?
+      rescue NameError, ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError
+        false
+      end
+
+      def model_class
+        class_name.constantize if model_class_exists?
+      end
+
+      def model_has_better_model_features?
+        return false unless model_class_exists?
+        model_class.respond_to?(:predicable_fields) ||
+          model_class.respond_to?(:sortable_fields) ||
+          model_class.respond_to?(:searchable_fields)
+      end
+
+      def display_available_features
+        return unless model_class_exists?
+
+        if model_class.respond_to?(:predicable_fields) && model_class.predicable_fields.any?
+          say "  • Predicable fields: #{model_class.predicable_fields.to_a.join(', ')}", :white
+        end
+
+        if model_class.respond_to?(:sortable_fields) && model_class.sortable_fields.any?
+          say "  • Sortable fields: #{model_class.sortable_fields.to_a.join(', ')}", :white
+        end
+
+        if model_class.respond_to?(:searchable_fields) && model_class.searchable_fields.any?
+          say "  • Searchable fields: #{model_class.searchable_fields.to_a.join(', ')}", :white
+        end
+      end
+    end
+  end
+end

data/lib/generators/better_model/repository/templates/application_repository.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Base repository class for the application.
+#
+# Inherits from BetterModel::Repositable::BaseRepository and can be customized with
+# application-wide repository behaviors.
+#
+# @example Add custom methods available to all repositories
+#   class ApplicationRepository < BetterModel::Repositable::BaseRepository
+#     def find_active(id)
+#       search({ id_eq: id, status_eq: "active" }, limit: 1)
+#     end
+#
+#     def paginated_search(filters, page: 1)
+#       search(filters, page: page, per_page: 25)
+#     end
+#   end
+#
+class ApplicationRepository < BetterModel::Repositable::BaseRepository
+  # Add application-wide repository methods here
+end

data/lib/generators/better_model/repository/templates/repository.rb.tt

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+<% if options[:namespace] -%>
+module <%= options[:namespace] %>
+  class <%= class_name %>Repository < <%= base_repository_class %>
+    def model_class = <%= class_name %>
+
+    # Add your custom query methods here
+    #
+    # Example methods:
+    # def active
+    #   search({ status_eq: "active" })
+    # end
+    #
+    # def recent(days: 7)
+    #   search({ created_at_gteq: days.days.ago }, order_scope: { field: :created_at, direction: :desc })
+    # end
+    #
+    # def find_with_details(id)
+    #   search({ id_eq: id }, includes: [:associated_records], limit: 1)
+    # end
+<% if model_class_exists? && model_class.respond_to?(:predicable_fields) && model_class.predicable_fields.any? -%>
+
+    # Available predicates for <%= class_name %>:
+<% model_class.predicable_fields.each do |field| -%>
+    #   <%= field %>: <%= model_class.searchable_predicates_for(field).map { |p| ":#{p}" }.join(", ") %>
+<% end -%>
+<% end -%>
+<% if model_class_exists? && model_class.respond_to?(:sortable_fields) && model_class.sortable_fields.any? -%>
+
+    # Available sort scopes for <%= class_name %>:
+<% model_class.sortable_fields.each do |field| -%>
+    #   <%= field %>: <%= model_class.searchable_sorts_for(field).join(", ") %>
+<% end -%>
+<% end -%>
+  end
+end
+<% else -%>
+class <%= class_name %>Repository < <%= base_repository_class %>
+  def model_class = <%= class_name %>
+
+  # Add your custom query methods here
+  #
+  # Example methods:
+  # def active
+  #   search({ status_eq: "active" })
+  # end
+  #
+  # def recent(days: 7)
+  #   search({ created_at_gteq: days.days.ago }, order_scope: { field: :created_at, direction: :desc })
+  # end
+  #
+  # def find_with_details(id)
+  #   search({ id_eq: id }, includes: [:associated_records], limit: 1)
+  # end
+<% if model_class_exists? && model_class.respond_to?(:predicable_fields) && model_class.predicable_fields.any? -%>
+
+  # Available predicates for <%= class_name %>:
+<% model_class.predicable_fields.each do |field| -%>
+  #   <%= field %>: <%= model_class.searchable_predicates_for(field).map { |p| ":#{p}" }.join(", ") %>
+<% end -%>
+<% end -%>
+<% if model_class_exists? && model_class.respond_to?(:sortable_fields) && model_class.sortable_fields.any? -%>
+
+  # Available sort scopes for <%= class_name %>:
+<% model_class.sortable_fields.each do |field| -%>
+  #   <%= field %>: <%= model_class.searchable_sorts_for(field).join(", ") %>
+<% end -%>
+<% end -%>
+end
+<% end -%>

data/lib/generators/better_model/stateable/templates/README

@@ -20,7 +20,7 @@ Next steps:
 
        # Define transitions
        transition :confirm, from: :<%= initial_state_value %>, to: :confirmed do
-         guard { valid? }
+         check { valid? }
          before { prepare_confirmation }
          after { send_notification }
        end