better_model 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75b360674e8e3baf46d99e536d2e012f0bbeea56169f2133d65193f9e093973b
-  data.tar.gz: e4feb8e169012f8b94fe9f9ad720838d68d24df3e811c4de2fb1f018e4edef9a
+  metadata.gz: ec236d26e4c1e0a5a62e9932606a1baa28de1bcadf8b447f1da545fb35d029b6
+  data.tar.gz: 24e4aa004924ab09c6104cad770229041b8c8d24556ce5f2f2d190bf15071e90
 SHA512:
-  metadata.gz: bc082d6e0b93b1750f73ab4878f26f7f99aa2080aeb05c8382f5e4b47ee6287402b984686cebe665a7ffa1b154683aa00ddb8b7a78e841d41f3446a27d104957
-  data.tar.gz: 5fd80c99b6e83ad69870226c06c949ba11b8e15e44883ba5b33c7e2ca8e79e0f0c79f8465ad6c176ba6726f8b3947819b39feaa94a316935fc2045f41b78a13c
+  metadata.gz: 77d291e54bcbbb179eabd842290530d0f42e03636981e93bfdeb6575d5d0e02960d359072c0b0db0144f35cdbea647d463bf7320037c557552f6fce8365a393e
+  data.tar.gz: bfe3bf61206cb343dce4d84b2ff643e719c09b93a623de77e127a00aadbce646d25bfcc2cd66ca3bd725b6af224a82eb7cff2e059f79f45c8e026d5d878c95d6

data/README.md

@@ -91,7 +91,13 @@ class Article < ApplicationRecord
     transition :archive, from: [:draft, :published], to: :archived
   end
 
-  # 8. SEARCHABLE - Configure unified search interface
+  # 8. TRACEABLE - Audit trail with time-travel (opt-in)
+  traceable do
+    track :title, :content, :status, :published_at
+    versions_table :article_versions  # Optional: custom table
+  end
+
+  # 9. SEARCHABLE - Configure unified search interface
   searchable do
     per_page 25
     max_per_page 100
@@ -149,6 +155,17 @@ article.published?       # => true
 article.state_transitions  # History of all transitions
 article.transition_history # Formatted history array
 
+# ⏰ Time travel & rollback (Traceable)
+article.audit_trail              # Full change history
+article.as_of(3.days.ago)        # Reconstruct past state
+article.rollback_to(version)     # Restore to previous version
+article.changes_for(:status)     # Changes for specific field
+
+# 🔍 Query changes
+Article.changed_by(user.id)
+Article.changed_between(1.week.ago, Time.current)
+Article.status_changed_from("draft").to("published")
+
 # 🔎 Unified search with filters, sorting, and pagination
 Article.search(
   { status_eq: "published", view_count_gteq: 50 },
@@ -166,6 +183,7 @@ class Article < ApplicationRecord
   include BetterModel::Statusable    # Only status management
   include BetterModel::Permissible   # Only permissions
   include BetterModel::Archivable    # Only archiving
+  include BetterModel::Traceable     # Only audit trail & time-travel
   include BetterModel::Sortable      # Only sorting
   include BetterModel::Predicable    # Only filtering
   include BetterModel::Validatable   # Only validations
@@ -176,6 +194,24 @@ class Article < ApplicationRecord
 end
 ```
 
+## 📋 Features Overview
+
+BetterModel provides nine powerful concerns that work seamlessly together:
+
+### Core Features
+
+- **✨ Statusable** - Declarative status management with lambda-based conditions
+- **🔐 Permissible** - State-based permission system
+- **🗄️ Archivable** - Soft delete with tracking (by user, reason)
+- **⏰ Traceable** 🆕 - Complete audit trail with time-travel and rollback
+- **⬆️ Sortable** - Type-aware sorting scopes
+- **🔍 Predicable** - Advanced filtering with rich predicate system
+- **🔎 Searchable** - Unified search interface (Predicable + Sortable)
+- **✅ Validatable** - Declarative validation DSL with conditional rules
+- **🔄 Stateable** 🆕 - Declarative state machines with guards & callbacks
+
+[See all features in detail →](#-features)
+
 ## ⚙️ Requirements
 
 - **Ruby:** 3.0 or higher
@@ -286,6 +322,27 @@ Define state machines declaratively with transitions, guards, validations, and c
 
 ---
 
+### ⏰ Traceable - Audit Trail with Time-Travel
+
+Track all changes to your records with complete audit trail, time-travel capabilities, and rollback support.
+
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- 📝 Automatic change tracking on create, update, and destroy
+- 👤 User attribution: track who made each change
+- 💬 Change reasons: optional context for changes
+- ⏰ Time-travel: reconstruct object state at any point in history
+- ↩️ Rollback support: restore records to previous versions
+- 🔍 Rich query API: find changes by user, time, or field transitions
+- 📊 Flexible table naming: per-model, shared, or custom tables
+- 🔗 Polymorphic association for efficient storage
+- 💾 Database adapter safety: PostgreSQL, MySQL, SQLite support
+- 🔒 Thread-safe dynamic class creation
+
+**[📖 Full Documentation →](docs/traceable.md)**
+
+---
+
 ### ⬆️ Sortable - Type-Aware Sorting Scopes
 
 Generate intelligent sorting scopes automatically with database-specific optimizations and NULL handling.
@@ -487,6 +544,38 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
 - 💻 **Source Code:** [GitHub Repository](https://github.com/alessiobussolari/better_model)
 - 📖 **Documentation:** This README and detailed docs in `docs/` directory
 
+## 📚 Complete Documentation
+
+### 📖 Feature Guides
+
+Detailed documentation for each BetterModel concern:
+
+- [**Statusable**](docs/statusable.md) - Status management with derived conditions
+- [**Permissible**](docs/permissible.md) - Permission system based on state
+- [**Archivable**](docs/archivable.md) - Soft delete with comprehensive tracking
+- [**Traceable**](docs/traceable.md) 🆕 - Audit trail, time-travel, and rollback
+- [**Sortable**](docs/sortable.md) - Type-aware sorting system
+- [**Predicable**](docs/predicable.md) - Advanced filtering and predicates
+- [**Searchable**](docs/searchable.md) - Unified search interface
+- [**Validatable**](docs/validatable.md) - Declarative validation system
+- [**Stateable**](docs/stateable.md) 🆕 - State machine with transitions
+
+### 🎓 Advanced Guides
+
+Learn how to master BetterModel in production:
+
+- [**Integration Guide**](docs/integration_guide.md) 🆕 - Combining multiple concerns effectively
+- [**Performance Guide**](docs/performance_guide.md) 🆕 - Optimization strategies and indexing
+- [**Migration Guide**](docs/migration_guide.md) 🆕 - Adding BetterModel to existing apps
+
+### 💡 Quick Links
+
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Features Overview](#-features-overview)
+- [Requirements](#%EF%B8%8F-requirements)
+- [Contributing](#-contributing)
+
 ## 🤝 Contributing
 
 We welcome contributions! Here's how you can help:
@@ -532,6 +621,27 @@ bundle exec rake test  # Coverage report in coverage/index.html
 bundle exec rubocop
 ```
 
+### 📊 Test Coverage Notes
+
+The test suite runs on **SQLite** for performance and portability. Current coverage: **91.45%** (1272 / 1391 lines).
+
+**Database-Specific Features Not Covered:**
+- **Predicable**: PostgreSQL array predicates (`_overlaps`, `_contains`, `_contained_by`) and JSONB predicates (`_has_key`, `_has_any_key`, `_has_all_keys`, `_jsonb_contains`) - lines 278-376 in `lib/better_model/predicable.rb`
+- **Traceable**: PostgreSQL JSONB queries and MySQL JSON_EXTRACT queries for field-specific change tracking - lines 454-489 in `lib/better_model/traceable.rb`
+- **Sortable**: MySQL NULLS emulation with CASE statements - lines 198-203 in `lib/better_model/sortable.rb`
+
+These features are fully implemented with proper SQL sanitization but require manual testing on PostgreSQL/MySQL:
+
+```bash
+# Test on PostgreSQL
+RAILS_ENV=test DATABASE_URL=postgresql://user:pass@localhost/better_model_test rails console
+
+# Test on MySQL
+RAILS_ENV=test DATABASE_URL=mysql2://user:pass@localhost/better_model_test rails console
+```
+
+All code has inline comments marking database-specific sections for maintainability.
+
 ### 📐 Code Guidelines
 
 - ✨ Follow the existing code style (enforced by RuboCop Omakase)

data/lib/better_model/predicable.rb

@@ -59,7 +59,7 @@ module BetterModel
           next unless column
 
           # Base predicates available for all column types
-          define_base_predicates(field_name)
+          define_base_predicates(field_name, column.type)
 
           case column.type
           when :string, :text
@@ -142,7 +142,7 @@ module BetterModel
       end
 
       # Genera predicati base: _eq, _not_eq, _present
-      def define_base_predicates(field_name)
+      def define_base_predicates(field_name, column_type = nil)
         table = arel_table
         field = table[field_name]
 
@@ -150,24 +150,26 @@ module BetterModel
         scope :"#{field_name}_eq", ->(value) { where(field.eq(value)) }
         scope :"#{field_name}_not_eq", ->(value) { where(field.not_eq(value)) }
 
-        # Presence
-        scope :"#{field_name}_present", -> { where(field.not_eq(nil)) }
+        # Presence - skip for string/text types as they get specialized version
+        # String types need to check for both nil and empty string
+        unless [ :string, :text ].include?(column_type)
+          scope :"#{field_name}_present", -> { where(field.not_eq(nil)) }
+        end
 
-        register_predicable_scopes(
-          :"#{field_name}_eq",
-          :"#{field_name}_not_eq",
-          :"#{field_name}_present"
-        )
+        scopes_to_register = [ :"#{field_name}_eq", :"#{field_name}_not_eq" ]
+        scopes_to_register << :"#{field_name}_present" unless [ :string, :text ].include?(column_type)
+
+        register_predicable_scopes(*scopes_to_register)
       end
 
       # Genera predicati per campi stringa (12 scope)
       # Base predicates (_eq, _not_eq) are defined separately
-      # _present is redefined here to handle empty strings
+      # _present is defined here to handle both nil and empty strings
       def define_string_predicates(field_name)
         table = arel_table
         field = table[field_name]
 
-        # String-specific presence check (overrides base _present)
+        # String-specific presence check (checks both nil and empty string)
         scope :"#{field_name}_present", -> { where(field.not_eq(nil).and(field.not_eq(""))) }
 
         # Pattern matching (4)
@@ -273,6 +275,10 @@ module BetterModel
       end
 
       # Genera predicati per campi array PostgreSQL (3 scope)
+      #
+      # NOTA: Questo metodo non è coperto da test automatici perché richiede
+      # PostgreSQL. I test vengono eseguiti su SQLite per performance.
+      # Testare manualmente su PostgreSQL con: rails console RAILS_ENV=test
       def define_postgresql_array_predicates(field_name)
         return unless postgresql_adapter?
 
@@ -325,6 +331,10 @@ module BetterModel
       end
 
       # Genera predicati per campi JSONB PostgreSQL (4 scope)
+      #
+      # NOTA: Questo metodo non è coperto da test automatici perché richiede
+      # PostgreSQL con supporto JSONB. I test vengono eseguiti su SQLite per performance.
+      # Testare manualmente su PostgreSQL con: rails console RAILS_ENV=test
       def define_postgresql_jsonb_predicates(field_name)
         return unless postgresql_adapter?
 

data/lib/better_model/sortable.rb

@@ -188,6 +188,10 @@ module BetterModel
       end
 
       # Genera SQL per gestione NULL multi-database
+      #
+      # NOTA: Il blocco MySQL else qui sotto non è coperto da test automatici
+      # perché i test vengono eseguiti su SQLite. Testare manualmente su MySQL
+      # con: rails console RAILS_ENV=test
       def nulls_order_sql(field_name, direction, nulls_position)
         quoted_field = connection.quote_column_name(field_name)
 

data/lib/better_model/stateable.rb

@@ -90,6 +90,9 @@ module BetterModel
   module Stateable
     extend ActiveSupport::Concern
 
+    # Thread-safe mutex for dynamic class creation
+    CLASS_CREATION_MUTEX = Mutex.new
+
     included do
       # Validazione ActiveRecord
       unless ancestors.include?(ActiveRecord::Base)
@@ -188,6 +191,9 @@ module BetterModel
 
       # Create or retrieve a StateTransition class for the given table name
       #
+      # Thread-safe implementation using mutex to prevent race conditions
+      # when multiple threads try to create the same class simultaneously.
+      #
       # @param table_name [String] Table name for state transitions
       # @return [Class] StateTransition class
       #
@@ -195,19 +201,27 @@ module BetterModel
         # Create a unique class name based on table name
         class_name = "#{table_name.camelize.singularize}"
 
-        # Check if class already exists in BetterModel namespace
+        # Fast path: check if class already exists (no lock needed)
         if BetterModel.const_defined?(class_name, false)
           return BetterModel.const_get(class_name)
         end
 
-        # Create new StateTransition class dynamically
-        transition_class = Class.new(BetterModel::StateTransition) do
-          self.table_name = table_name
-        end
+        # Slow path: acquire lock and create class
+        CLASS_CREATION_MUTEX.synchronize do
+          # Double-check after acquiring lock (another thread may have created it)
+          if BetterModel.const_defined?(class_name, false)
+            return BetterModel.const_get(class_name)
+          end
 
-        # Register the class in BetterModel namespace
-        BetterModel.const_set(class_name, transition_class)
-        transition_class
+          # Create new StateTransition class dynamically
+          transition_class = Class.new(BetterModel::StateTransition) do
+            self.table_name = table_name
+          end
+
+          # Register the class in BetterModel namespace
+          BetterModel.const_set(class_name, transition_class)
+          transition_class
+        end
       end
 
       # Setup dynamic methods per stati e transizioni

data/lib/better_model/traceable.rb

@@ -53,6 +53,9 @@ module BetterModel
   module Traceable
     extend ActiveSupport::Concern
 
+    # Thread-safe mutex for dynamic class creation
+    CLASS_CREATION_MUTEX = Mutex.new
+
     included do
       # Validazione ActiveRecord
       unless ancestors.include?(ActiveRecord::Base)
@@ -175,25 +178,36 @@ module BetterModel
 
       # Create or retrieve a Version class for the given table name
       #
+      # Thread-safe implementation using mutex to prevent race conditions
+      # when multiple threads try to create the same class simultaneously.
+      #
       # @param table_name [String] Table name for versions
       # @return [Class] Version class
       def create_version_class_for_table(table_name)
         # Create a unique class name based on table name
         class_name = "#{table_name.camelize.singularize}"
 
-        # Check if class already exists in BetterModel namespace
+        # Fast path: check if class already exists (no lock needed)
         if BetterModel.const_defined?(class_name, false)
           return BetterModel.const_get(class_name)
         end
 
-        # Create new Version class dynamically
-        version_class = Class.new(BetterModel::Version) do
-          self.table_name = table_name
+        # Slow path: acquire lock and create class
+        CLASS_CREATION_MUTEX.synchronize do
+          # Double-check after acquiring lock (another thread may have created it)
+          if BetterModel.const_defined?(class_name, false)
+            return BetterModel.const_get(class_name)
+          end
+
+          # Create new Version class dynamically
+          version_class = Class.new(BetterModel::Version) do
+            self.table_name = table_name
+          end
+
+          # Register the class in BetterModel namespace
+          BetterModel.const_set(class_name, version_class)
+          version_class
         end
-
-        # Register the class in BetterModel namespace
-        BetterModel.const_set(class_name, version_class)
-        version_class
       end
     end
 
@@ -271,14 +285,10 @@ module BetterModel
     def rollback_to(version, updated_by_id: nil, updated_reason: nil)
       raise NotEnabledError unless self.class.traceable_enabled?
 
-      begin
-        version = versions.find(version) if version.is_a?(Integer)
-      rescue ActiveRecord::RecordNotFound
-        raise ArgumentError, "Version not found"
-      end
+      version = versions.find(version) if version.is_a?(Integer)
 
-      raise ArgumentError, "Version not found" unless version
-      raise ArgumentError, "Version does not belong to this record" unless version.item == self
+      raise ActiveRecord::RecordNotFound, "Version not found" unless version
+      raise ActiveRecord::RecordNotFound, "Version does not belong to this record" unless version.item == self
 
       # Apply changes from version
       if version.object_changes
@@ -352,7 +362,7 @@ module BetterModel
     # Get final state for destroyed records
     def tracked_final_state
       self.class.traceable_fields.each_with_object({}) do |field, hash|
-        hash[field.to_s] = [send(field), nil]
+        hash[field.to_s] = [ send(field), nil ]
       end
     end
 
@@ -427,17 +437,59 @@ module BetterModel
 
     private
 
+    # Check if database supports JSON/JSONB queries
+    def postgres?
+      ActiveRecord::Base.connection.adapter_name.downcase == "postgresql"
+    end
+
+    def mysql?
+      adapter = ActiveRecord::Base.connection.adapter_name.downcase
+      adapter.include?("mysql") || adapter == "trilogy"
+    end
+
     def execute_query
-      query = @model_class
-              .joins(:versions)
-              .where("#{@table_name}.object_changes->>'#{@field}' IS NOT NULL")
+      # Base query
+      query = @model_class.joins(:versions)
 
-      if @from_value
-        query = query.where("#{@table_name}.object_changes->>'#{@field}' LIKE ?", "%#{@from_value}%")
-      end
+      # NOTA: I blocchi PostgreSQL e MySQL qui sotto non sono coperti da test
+      # automatici perché i test vengono eseguiti su SQLite per performance.
+      # Testare manualmente su PostgreSQL/MySQL con: rails console RAILS_ENV=test
+
+      # PostgreSQL: Use JSONB operators for better performance
+      if postgres?
+        query = query.where("#{@table_name}.object_changes ? :field", field: @field)
+
+        if @from_value
+          query = query.where("#{@table_name}.object_changes->>'#{@field}' LIKE ?", "%#{@from_value}%")
+        end
 
-      if @to_value
-        query = query.where("#{@table_name}.object_changes->>'#{@field}' LIKE ?", "%#{@to_value}%")
+        if @to_value
+          query = query.where("#{@table_name}.object_changes->>'#{@field}' LIKE ?", "%#{@to_value}%")
+        end
+      # MySQL 5.7+: Use JSON_EXTRACT
+      elsif mysql?
+        query = query.where("JSON_EXTRACT(#{@table_name}.object_changes, '$.#{@field}') IS NOT NULL")
+
+        if @from_value
+          query = query.where("JSON_EXTRACT(#{@table_name}.object_changes, '$.#{@field}') LIKE ?", "%#{@from_value}%")
+        end
+
+        if @to_value
+          query = query.where("JSON_EXTRACT(#{@table_name}.object_changes, '$.#{@field}') LIKE ?", "%#{@to_value}%")
+        end
+      # SQLite or fallback: Use text-based search (limited functionality)
+      else
+        Rails.logger.warn "Traceable field-specific queries may have limited functionality on #{ActiveRecord::Base.connection.adapter_name}"
+
+        query = query.where("#{@table_name}.object_changes LIKE ?", "%\"#{@field}\"%")
+
+        if @from_value
+          query = query.where("#{@table_name}.object_changes LIKE ?", "%#{@from_value}%")
+        end
+
+        if @to_value
+          query = query.where("#{@table_name}.object_changes LIKE ?", "%#{@to_value}%")
+        end
       end
 
       query.distinct

data/lib/better_model/validatable.rb

@@ -135,11 +135,11 @@ module BetterModel
         validate do
           condition_met = if condition.is_a?(Symbol)
                             send(condition)
-                          elsif condition.is_a?(Proc)
+          elsif condition.is_a?(Proc)
                             instance_exec(&condition)
-                          else
+          else
                             raise ArgumentError, "Condition must be a Symbol or Proc"
-                          end
+          end
 
           condition_met = !condition_met if negate
 

data/lib/better_model/version.rb

@@ -1,3 +1,3 @@
 module BetterModel
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_model
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - alessiobussolari