better_model 2.1.0 → 3.0.0

data/lib/better_model/errors/better_model_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module BetterModel
+  module Errors
+    # Root error class for all BetterModel errors.
+    # All module-specific errors inherit from this class.
+    class BetterModelError < StandardError; end
+  end
+end

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

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

data/lib/better_model/errors/permissible/permissible_error.rb

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

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

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

data/lib/better_model/errors/predicable/predicable_error.rb

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

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

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

data/lib/better_model/errors/searchable/invalid_order_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "searchable_error"
+
+module BetterModel
+  module Errors
+    module Searchable
+      class InvalidOrderError < SearchableError; end
+    end
+  end
+end

data/lib/better_model/errors/searchable/invalid_pagination_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "searchable_error"
+
+module BetterModel
+  module Errors
+    module Searchable
+      class InvalidPaginationError < SearchableError; end
+    end
+  end
+end

data/lib/better_model/errors/searchable/invalid_predicate_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "searchable_error"
+
+module BetterModel
+  module Errors
+    module Searchable
+      class InvalidPredicateError < SearchableError; end
+    end
+  end
+end

data/lib/better_model/errors/searchable/invalid_security_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "searchable_error"
+
+module BetterModel
+  module Errors
+    module Searchable
+      class InvalidSecurityError < SearchableError; end
+    end
+  end
+end

data/lib/better_model/errors/searchable/searchable_error.rb

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

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

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

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