better_model 2.1.0 → 3.0.0

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_model
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.0.0
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-05 00:00:00.000000000 Z
+date: 2025-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -43,28 +43,65 @@ files:
 - Rakefile
 - lib/better_model.rb
 - lib/better_model/archivable.rb
+- lib/better_model/errors/archivable/already_archived_error.rb
+- lib/better_model/errors/archivable/archivable_error.rb
+- lib/better_model/errors/archivable/configuration_error.rb
+- lib/better_model/errors/archivable/not_archived_error.rb
+- lib/better_model/errors/archivable/not_enabled_error.rb
+- lib/better_model/errors/better_model_error.rb
+- lib/better_model/errors/permissible/configuration_error.rb
+- lib/better_model/errors/permissible/permissible_error.rb
+- lib/better_model/errors/predicable/configuration_error.rb
+- lib/better_model/errors/predicable/predicable_error.rb
+- lib/better_model/errors/searchable/configuration_error.rb
+- lib/better_model/errors/searchable/invalid_order_error.rb
+- lib/better_model/errors/searchable/invalid_pagination_error.rb
+- lib/better_model/errors/searchable/invalid_predicate_error.rb
+- lib/better_model/errors/searchable/invalid_security_error.rb
+- lib/better_model/errors/searchable/searchable_error.rb
+- lib/better_model/errors/sortable/configuration_error.rb
+- lib/better_model/errors/sortable/sortable_error.rb
+- lib/better_model/errors/stateable/check_failed_error.rb
+- lib/better_model/errors/stateable/configuration_error.rb
+- lib/better_model/errors/stateable/invalid_state_error.rb
+- lib/better_model/errors/stateable/invalid_transition_error.rb
+- lib/better_model/errors/stateable/not_enabled_error.rb
+- lib/better_model/errors/stateable/stateable_error.rb
+- lib/better_model/errors/stateable/validation_failed_error.rb
+- lib/better_model/errors/statusable/configuration_error.rb
+- lib/better_model/errors/statusable/statusable_error.rb
+- lib/better_model/errors/taggable/configuration_error.rb
+- lib/better_model/errors/taggable/taggable_error.rb
+- lib/better_model/errors/traceable/configuration_error.rb
+- lib/better_model/errors/traceable/not_enabled_error.rb
+- lib/better_model/errors/traceable/traceable_error.rb
+- lib/better_model/errors/validatable/configuration_error.rb
+- lib/better_model/errors/validatable/not_enabled_error.rb
+- lib/better_model/errors/validatable/validatable_error.rb
+- lib/better_model/models/state_transition.rb
+- lib/better_model/models/version.rb
 - lib/better_model/permissible.rb
 - lib/better_model/predicable.rb
 - lib/better_model/railtie.rb
+- lib/better_model/repositable.rb
+- lib/better_model/repositable/base_repository.rb
 - lib/better_model/searchable.rb
 - lib/better_model/sortable.rb
-- lib/better_model/state_transition.rb
 - lib/better_model/stateable.rb
 - lib/better_model/stateable/configurator.rb
-- lib/better_model/stateable/errors.rb
 - lib/better_model/stateable/guard.rb
 - lib/better_model/stateable/transition.rb
 - lib/better_model/statusable.rb
 - lib/better_model/taggable.rb
 - lib/better_model/traceable.rb
 - lib/better_model/validatable.rb
-- lib/better_model/validatable/business_rule_validator.rb
 - lib/better_model/validatable/configurator.rb
-- lib/better_model/validatable/order_validator.rb
 - lib/better_model/version.rb
-- lib/better_model/version_record.rb
 - lib/generators/better_model/archivable/archivable_generator.rb
 - lib/generators/better_model/archivable/templates/migration.rb.tt
+- lib/generators/better_model/repository/repository_generator.rb
+- lib/generators/better_model/repository/templates/application_repository.rb.tt
+- lib/generators/better_model/repository/templates/repository.rb.tt
 - lib/generators/better_model/stateable/install_generator.rb
 - lib/generators/better_model/stateable/stateable_generator.rb
 - lib/generators/better_model/stateable/templates/README

data/lib/better_model/state_transition.rb

@@ -1,106 +0,0 @@
-# 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/errors.rb

@@ -1,48 +0,0 @@
-# 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 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)
-        super("Validation failed for transition #{event.inspect}: #{errors.full_messages.join(', ')}")
-      end
-    end
-  end
-end

data/lib/better_model/validatable/business_rule_validator.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module BetterModel
-  module Validatable
-    # Validator per business rules custom
-    #
-    # Permette di eseguire metodi custom come validatori, delegando la logica
-    # di validazione complessa a metodi del modello.
-    #
-    # Il metodo della business rule deve aggiungere errori tramite `errors.add`
-    # se la validazione fallisce.
-    #
-    # Esempio:
-    #   validates_with BusinessRuleValidator, rule_name: :valid_category
-    #
-    #   # Nel modello:
-    #   def valid_category
-    #     unless Category.exists?(id: category_id)
-    #       errors.add(:category_id, "must be a valid category")
-    #     end
-    #   end
-    #
-    class BusinessRuleValidator < ActiveModel::Validator
-      def initialize(options)
-        super
-
-        @rule_name = options[:rule_name]
-
-        unless @rule_name
-          raise ArgumentError, "BusinessRuleValidator requires :rule_name option"
-        end
-      end
-
-      def validate(record)
-        # Verifica che il metodo esista
-        unless record.respond_to?(@rule_name, true)
-          raise NoMethodError, "Business rule method '#{@rule_name}' not found in #{record.class.name}. " \
-                               "Define it in your model: def #{@rule_name}; ...; end"
-        end
-
-        # Esegui il metodo della business rule
-        # Il metodo stesso è responsabile di aggiungere errori tramite errors.add
-        record.send(@rule_name)
-      end
-    end
-  end
-end

data/lib/better_model/validatable/order_validator.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-module BetterModel
-  module Validatable
-    # Validator per validazioni di ordine tra campi (cross-field)
-    #
-    # Verifica che un campo sia in una relazione d'ordine rispetto ad un altro campo.
-    # Supporta date/time (before/after) e numeri (lteq/gteq/lt/gt).
-    #
-    # Esempio:
-    #   validates_with OrderValidator,
-    #                  attributes: [:starts_at],
-    #                  second_field: :ends_at,
-    #                  comparator: :before
-    #
-    class OrderValidator < ActiveModel::EachValidator
-      COMPARATORS = {
-        before: :<,
-        after: :>,
-        lteq: :<=,
-        gteq: :>=,
-        lt: :<,
-        gt: :>
-      }.freeze
-
-      def initialize(options)
-        super
-
-        @second_field = options[:second_field]
-        @comparator = options[:comparator]
-
-        unless @second_field
-          raise ArgumentError, "OrderValidator requires :second_field option"
-        end
-
-        unless COMPARATORS.key?(@comparator)
-          raise ArgumentError, "Invalid comparator: #{@comparator}. Valid: #{COMPARATORS.keys.join(', ')}"
-        end
-      end
-
-      def validate_each(record, attribute, value)
-        second_value = record.send(@second_field)
-
-        # Skip validation if either field is nil (use presence validation for that)
-        return if value.nil? || second_value.nil?
-
-        # Get the comparison operator
-        operator = COMPARATORS[@comparator]
-
-        # Perform comparison
-        unless value.send(operator, second_value)
-          record.errors.add(attribute, error_message(attribute, @comparator, @second_field))
-        end
-      end
-
-      private
-
-      def error_message(first_field, comparator, second_field)
-        # Messaggi user-friendly basati sul comparatore
-        case comparator
-        when :before
-          "must be before #{second_field.to_s.humanize.downcase}"
-        when :after
-          "must be after #{second_field.to_s.humanize.downcase}"
-        when :lteq
-          "must be less than or equal to #{second_field.to_s.humanize.downcase}"
-        when :gteq
-          "must be greater than or equal to #{second_field.to_s.humanize.downcase}"
-        when :lt
-          "must be less than #{second_field.to_s.humanize.downcase}"
-        when :gt
-          "must be greater than #{second_field.to_s.humanize.downcase}"
-        end
-      end
-    end
-  end
-end

data/lib/better_model/version_record.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module BetterModel
-  # 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