better_model 1.3.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93cc27ca4bb13c22c5d3ac1f0aa96010f7377bf687805b5f76bee89d44b83f5f
-  data.tar.gz: 5234fde47b3b13fc0ccc2da3fc3948f094ccd0f7eaa2cb4d8d219e6cf291a1c3
+  metadata.gz: 3237879bac91f8200057cba591a1a2f09ccc761f55fd2ded1f1acb5a156c65f2
+  data.tar.gz: 6ab53b6128104cac44fdb5ad8ce80ca662a78072724a29c946c9380ad66701f2
 SHA512:
-  metadata.gz: 3f9394cdc2201586b8b1d510d60aa286d29a86ab1a0c313f61401b850545a1924b08b16489b446d786aac38aa919ff7546dd6e3d3d5c9a9ca8a310b74ecbddc0
-  data.tar.gz: 8f218e1eb37bc94cb8510cda0ae32033458b1befe2ff5012a766b7c9874865b63b90facb72d7ba97deb1b80175fef06dbf27f6e42b2b9d44d3f47e212908cc7e
+  metadata.gz: cf5e0a75c42e6f8c81f76756dd4f292779d1df7e258741bc19877665530a50363d7271c31fcace870d4dc61ac75e7dbd6bf01db3c28857fc29da8ab8e87cbed5
+  data.tar.gz: 61992d1b052d377e1db14d312ea3eb024998d2f0e36dcb031fd9e900a3bd35b0add348bfbfb6dc687c41b37ce9df85952924cbb5fb7942abd484af107ce87664

data/README.md

@@ -55,11 +55,11 @@ class Article < ApplicationRecord
   # 6. VALIDATABLE - Declarative validation system (opt-in)
   validatable do
     # Basic validations
-    validate :title, :content, presence: true
+    check :title, :content, presence: true
 
     # Conditional validations
     validate_if :is_published? do
-      validate :published_at, presence: true
+      check :published_at, presence: true
     end
 
     # Cross-field validations
@@ -82,10 +82,10 @@ class Article < ApplicationRecord
 
     # Define transitions with guards and callbacks
     transition :publish, from: :draft, to: :published do
-      guard { valid? }
-      guard if: :is_ready_for_publishing?  # Statusable integration
-      before { set_published_at }
-      after { notify_subscribers }
+      check { valid? }
+      check { title.present? && content.present? }
+      before_transition { self.published_at = Time.current }
+      after_transition { Rails.logger.info "Article #{id} published" }
     end
 
     transition :archive, from: [:draft, :published], to: :archived
@@ -94,6 +94,9 @@ class Article < ApplicationRecord
   # 8. TRACEABLE - Audit trail with time-travel (opt-in)
   traceable do
     track :title, :content, :status, :published_at
+    track :password_hash, sensitive: :full    # Complete redaction
+    track :credit_card, sensitive: :partial   # Pattern-based masking
+    track :api_token, sensitive: :hash        # SHA256 hashing
     versions_table :article_versions  # Optional: custom table
   end
 
@@ -222,24 +225,137 @@ class Article < ApplicationRecord
 end
 ```
 
+## 🛠️ Generators
+
+Better Model provides Rails generators to help you quickly set up migrations for features that require database tables or columns.
+
+### Traceable Generator
+
+Create migrations for audit trail version tables:
+
+```bash
+# Basic usage - shows setup instructions
+rails g better_model:traceable Article
+
+# Create migration for versions table
+rails g better_model:traceable Article --create-table
+
+# Custom table name
+rails g better_model:traceable Article --create-table --table-name=audit_log
+
+# Run migrations
+rails db:migrate
+```
+
+**Generated migration includes:**
+- Polymorphic association (`item_type`, `item_id`)
+- Event tracking (`created`, `updated`, `destroyed`)
+- Change tracking (`object_changes` as JSON)
+- User attribution (`updated_by_id`)
+- Change reason (`updated_reason`)
+- Optimized indexes
+
+### Archivable Generator
+
+Add soft-delete columns to existing models:
+
+```bash
+# Basic usage - shows setup instructions
+rails g better_model:archivable Article
+
+# Add archivable columns to articles table
+rails g better_model:archivable Article --create-columns
+
+# Run migrations
+rails db:migrate
+```
+
+**Generated migration adds:**
+- `archived_at` (datetime) - when archived
+- `archived_by_id` (integer) - who archived it
+- `archive_reason` (string) - why archived
+- Index on `archived_at`
+
+### Stateable Generator
+
+Create state machine with state column and transitions tracking:
+
+```bash
+# Basic usage - shows setup instructions
+rails g better_model:stateable Article
+
+# Create both state column and transitions table
+rails g better_model:stateable Article --create-tables
+
+# Custom initial state (default: draft)
+rails g better_model:stateable Article --create-tables --initial-state=pending
+
+# Custom transitions table name
+rails g better_model:stateable Article --create-tables --table-name=article_state_history
+
+# Run migrations
+rails db:migrate
+```
+
+**Generated migrations include:**
+1. **State column migration:**
+   - `state` (string) with default value and index
+
+2. **Transitions table migration:**
+   - Polymorphic association (`transitionable_type`, `transitionable_id`)
+   - Event name and state tracking
+   - Optional metadata (JSON)
+   - Optimized indexes
+
+### Generator Options
+
+All generators support these common options:
+
+- `--pretend` - Dry run, show what would be generated
+- `--skip-model` - Only generate migrations, don't show model setup instructions
+- `--force` - Overwrite existing files
+
+**Example workflow:**
+
+```bash
+# 1. Generate migrations (dry-run first to preview)
+rails g better_model:traceable Article --create-table --pretend
+rails g better_model:archivable Article --create-columns --pretend
+rails g better_model:stateable Article --create-tables --pretend
+
+# 2. Generate for real
+rails g better_model:traceable Article --create-table
+rails g better_model:archivable Article --create-columns
+rails g better_model:stateable Article --create-tables
+
+# 3. Run migrations
+rails db:migrate
+
+# 4. Enable in your model (generators show you the code)
+# See model setup instructions after running each generator
+```
+
 ## 📋 Features Overview
 
 BetterModel provides ten powerful concerns that work seamlessly together:
 
-### Core Features
+### Core Features (Always Available)
 
 - **✨ 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
+
+### Opt-in Features (Require Activation)
+
 - **🔎 Searchable** - Unified search interface (Predicable + Sortable)
+- **🗄️ Archivable** - Soft delete with tracking (by user, reason)
 - **✅ Validatable** - Declarative validation DSL with conditional rules
 - **🔄 Stateable** - Declarative state machines with guards & callbacks
+- **⏰ Traceable** - Complete audit trail with time-travel and rollback
 - **🏷️ Taggable** 🆕 - Tag management with normalization, validation, and statistics
 
-[See all features in detail →](#-features)
+[See all features in detail →](#feature-details)
 
 ## ⚙️ Requirements
 
@@ -263,9 +379,22 @@ BetterModel works with all databases supported by ActiveRecord:
 - Array predicates: `overlaps`, `contains`, `contained_by`
 - JSONB predicates: `has_key`, `has_any_key`, `has_all_keys`, `jsonb_contains`
 
-## 📚 Features
+## 🗄️ Database Requirements
+
+Some opt-in features require database columns. Use the provided generators to add them:
+
+| Feature | Database Requirement | Generator Command |
+|---------|---------------------|-------------------|
+| **Archivable** | `archived_at` column | `rails g better_model:archivable Model` |
+| **Stateable** | `state`, `transitions` columns | `rails g better_model:stateable Model` |
+| **Traceable** | `version_records` table | `rails g better_model:traceable Model` |
+| **Taggable** | `tags` JSONB/text column | `rails g better_model:taggable Model` |
 
-BetterModel provides eight powerful concerns that work together seamlessly:
+**Core features** (Statusable, Permissible, Predicable, Sortable, Searchable, Validatable) require no database changes.
+
+## 📚 Feature Details
+
+BetterModel provides ten powerful concerns that work together seamlessly:
 
 ### 📋 Statusable - Declarative Status Management
 
@@ -358,10 +487,11 @@ Track all changes to your records with complete audit trail, time-travel capabil
 **🎯 Key Benefits:**
 - 🎛️ Opt-in activation: only enabled when explicitly configured
 - 📝 Automatic change tracking on create, update, and destroy
+- 🔐 Sensitive data protection: 3-level redaction system (full, partial, hash)
 - 👤 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
+- ↩️ Rollback support: restore records to previous versions (with sensitive field protection)
 - 🔍 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
@@ -398,9 +528,75 @@ Generate comprehensive predicate scopes for filtering and searching with support
 - 📊 Range queries (between) for numerics and dates
 - 🐘 PostgreSQL array and JSONB support
 - 🔗 Chainable with standard ActiveRecord queries
+- 🧩 Custom complex predicates for business logic
 
 **[📖 Full Documentation →](docs/predicable.md)**
 
+#### 🧩 Complex Predicates
+
+For queries that go beyond single-field filtering, you can register **complex predicates** - custom scopes that combine multiple conditions, work with associations, or encapsulate business logic.
+
+**Basic Example:**
+
+```ruby
+class Article < ApplicationRecord
+  include BetterModel
+
+  predicates :title, :view_count, :published_at
+
+  # Define a complex predicate with parameters
+  register_complex_predicate :trending do |days = 7, min_views = 100|
+    where("published_at >= ? AND view_count >= ?", days.days.ago, min_views)
+  end
+
+  # Define a complex predicate for association queries
+  register_complex_predicate :popular_author do |min_articles = 10|
+    joins(:author)
+      .group("articles.author_id")
+      .having("COUNT(articles.id) >= ?", min_articles)
+  end
+end
+```
+
+**Usage:**
+
+```ruby
+# Use with default parameters
+Article.trending
+# => Articles from last 7 days with 100+ views
+
+# Use with custom parameters
+Article.trending(14, 200)
+# => Articles from last 14 days with 200+ views
+
+# Chain with standard predicates
+Article.trending(7, 100)
+       .title_cont("Ruby")
+       .status_eq("published")
+       .sort_view_count_desc
+
+# Association-based queries
+Article.popular_author(5)
+       .published_at_within(30.days)
+```
+
+**When to Use Complex Predicates:**
+
+| Standard Predicates ✅ | Complex Predicates 🧩 |
+|------------------------|------------------------|
+| Single field filtering | Multi-field conditions |
+| `title_eq("Ruby")` | `trending(days, views)` |
+| `view_count_gt(100)` | Association queries |
+| `published_at_within(7.days)` | Business logic encapsulation |
+| Simple comparisons | Custom SQL expressions |
+
+**Check if Defined:**
+
+```ruby
+Article.complex_predicate?(:trending)  # => true
+Article.complex_predicates_registry    # => { trending: #<Proc> }
+```
+
 ---
 
 ### 🔎 Searchable - Unified Search Interface
@@ -415,9 +611,54 @@ Orchestrate Predicable and Sortable into a powerful, secure search interface wit
 - ⚙️ Default ordering configuration
 - 💪 Strong parameters integration
 - ✅ Type-safe validation of all parameters
+- 🚀 Eager loading support with `includes:`, `preload:`, `eager_load:`
 
 **[📖 Full Documentation →](docs/searchable.md)**
 
+#### 🔗 Eager Loading Associations
+
+Optimize N+1 queries with built-in eager loading support:
+
+```ruby
+# Single association (always use array syntax)
+Article.search(
+  { status_eq: "published" },
+  includes: [:author]
+)
+
+# Multiple associations
+Article.search(
+  { status_eq: "published" },
+  includes: [:author, :comments],
+  preload: [:tags]
+)
+
+# Nested associations
+Article.search(
+  { status_eq: "published" },
+  includes: [{ author: :profile }]
+)
+
+# Complex mix of associations
+Article.search(
+  { status_eq: "published" },
+  includes: [:tags, { author: :profile }, { comments: :user }]
+)
+
+# Combined with pagination and ordering
+Article.search(
+  { status_eq: "published" },
+  pagination: { page: 1, per_page: 25 },
+  orders: [:sort_view_count_desc],
+  includes: [:author, :comments]
+)
+```
+
+**Strategies:**
+- `includes:` - Smart loading (LEFT OUTER JOIN or separate queries)
+- `preload:` - Separate queries (avoids JOIN ambiguity)
+- `eager_load:` - Force LEFT OUTER JOIN (use with caution with default_order)
+
 ---
 
 ### 🏷️ Taggable - Tag Management with Statistics
@@ -438,147 +679,6 @@ Manage tags with automatic normalization, validation, and comprehensive statisti
 
 ---
 
-### 📜 Traceable - Audit Trail & Change Tracking
-
-Track all changes to your records with comprehensive audit trail functionality, time-travel queries, and rollback capabilities.
-
-**🎯 Key Benefits:**
-- 🎛️ Opt-in activation: only enabled when explicitly configured
-- 🤖 Automatic change tracking on create/update/destroy
-- ⏰ Time-travel: reconstruct record state at any point in time
-- ↩️ Rollback: restore to previous versions
-- 📝 Audit trail with who/why tracking
-- 🔍 Query changes by user, date range, or field transitions
-- 🗂️ Flexible table naming: per-model tables (default), shared table, or custom names
-
-**[📖 Full Documentation →](docs/traceable.md)**
-
-#### 🚀 Quick Setup
-
-**1️⃣ Step 1: Create the versions table**
-
-By default, each model gets its own versions table (`{model}_versions`):
-
-```bash
-# Creates migration for article_versions table
-rails g better_model:traceable Article --create-table
-rails db:migrate
-```
-
-Or use a custom table name:
-
-```bash
-# Creates migration for custom table name
-rails g better_model:traceable Article --create-table --table-name=audit_log
-rails db:migrate
-```
-
-**2️⃣ Step 2: Enable in your model**
-
-```ruby
-class Article < ApplicationRecord
-  include BetterModel
-
-  # Activate traceable (opt-in)
-  traceable do
-    track :status, :title, :published_at  # Fields to track
-    # versions_table 'audit_log'  # Optional: custom table (default: article_versions)
-  end
-end
-```
-
-**💡 Usage:**
-
-```ruby
-# 🤖 Automatic tracking on changes
-article.update!(status: "published", updated_by_id: user.id, updated_reason: "Approved")
-
-# 🔍 Query version history
-article.versions                              # All versions (ordered desc)
-article.changes_for(:status)                  # Changes for specific field
-article.audit_trail                           # Full formatted history
-
-# ⏰ Time-travel: reconstruct state at specific time
-past_article = article.as_of(3.days.ago)
-past_article.status                           # => "draft" (what it was 3 days ago)
-
-# ↩️ Rollback to previous version
-version = article.versions.where(event: "updated").first
-article.rollback_to(version, updated_by_id: user.id, updated_reason: "Mistake")
-
-# 📊 Class-level queries
-Article.changed_by(user.id)                   # Records changed by user
-Article.changed_between(1.week.ago, Time.current)  # Changes in period
-Article.status_changed_from("draft").to("published")  # Specific transitions (PostgreSQL)
-
-# 📦 Integration with as_json
-article.as_json(include_audit_trail: true)    # Include full history in JSON
-```
-
-**💾 Database Schema:**
-
-By default, each model gets its own versions table (e.g., `article_versions` for Article model).
-You can also use a shared table across multiple models or a custom table name.
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `item_type` | string | Polymorphic model name |
-| `item_id` | integer | Polymorphic record ID |
-| `event` | string | Event type: created/updated/destroyed |
-| `object_changes` | json | Before/after values for tracked fields |
-| `updated_by_id` | integer | Optional: user who made the change |
-| `updated_reason` | string | Optional: reason for the change |
-| `created_at` | datetime | When the change occurred |
-
-**🗂️ Table Naming Options:**
-
-```ruby
-# 1️⃣ Option 1: Per-model table (default)
-class Article < ApplicationRecord
-  traceable do
-    track :status
-    # Uses article_versions table automatically
-  end
-end
-
-# 2️⃣ Option 2: Custom table name
-class Article < ApplicationRecord
-  traceable do
-    track :status
-    versions_table 'audit_log'  # Uses audit_log table
-  end
-end
-
-# 3️⃣ Option 3: Shared table across models
-class Article < ApplicationRecord
-  traceable do
-    track :status
-    versions_table 'versions'  # Shared table
-  end
-end
-
-class User < ApplicationRecord
-  traceable do
-    track :email
-    versions_table 'versions'  # Same shared table
-  end
-end
-```
-
-**📝 Optional Tracking:**
-
-To track who made changes and why, simply set attributes before saving:
-
-```ruby
-article.updated_by_id = current_user.id
-article.updated_reason = "Fixed typo"
-article.update!(title: "Corrected Title")
-
-# The version will automatically include updated_by_id and updated_reason
-```
-
----
-
 ## 📌 Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
@@ -604,22 +704,15 @@ Detailed documentation for each BetterModel concern:
 - [**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
+- [**Taggable**](docs/taggable.md) 🆕 - Flexible tag management with normalization
 
 ### 💡 Quick Links
 
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [Features Overview](#-features-overview)
-- [Requirements](#%EF%B8%8F-requirements)
-- [Contributing](#-contributing)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Features Overview](#features-overview)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
 
 ## 🤝 Contributing
 
@@ -648,6 +741,35 @@ We welcome contributions! Here's how you can help:
 
 ### 🔧 Development Setup
 
+#### 🐳 Using Docker (Recommended)
+
+The easiest way to get started is with Docker, which provides a consistent development environment:
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/better_model.git
+cd better_model
+
+# One-time setup: build image and install dependencies
+bin/docker-setup
+
+# Run tests
+bin/docker-test
+
+# Run RuboCop
+bin/docker-rubocop
+
+# Open interactive shell for debugging
+docker compose run --rm app sh
+
+# Run any command in the container
+docker compose run --rm app bundle exec [command]
+```
+
+#### 💻 Local Setup (Without Docker)
+
+If you prefer to use your local Ruby installation:
+
 ```bash
 # Clone your fork
 git clone https://github.com/YOUR_USERNAME/better_model.git
@@ -666,6 +788,11 @@ bundle exec rake test  # Coverage report in coverage/index.html
 bundle exec rubocop
 ```
 
+**Requirements:**
+- Ruby 3.0+ (Ruby 3.3 recommended)
+- Rails 8.1+
+- SQLite3
+
 ### 📊 Test Coverage Notes
 
 The test suite runs on **SQLite** for performance and portability. Current coverage: **92.57%** (1507 / 1628 lines).
@@ -698,3 +825,13 @@ All code has inline comments marking database-specific sections for maintainabil
 ## 📝 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+<div align="center">
+
+**Made with ❤️ by [Alessio Bussolari](https://github.com/alessiobussolari)**
+
+[Report Bug](https://github.com/alessiobussolari/better_model/issues) · [Request Feature](https://github.com/alessiobussolari/better_model/issues) · [Documentation](https://github.com/alessiobussolari/better_model)
+
+</div>

data/lib/better_model/archivable.rb

@@ -104,8 +104,8 @@ module BetterModel
         sort :archived_at unless sortable_field?(:archived_at)
 
         # Definisci gli scope alias (approccio ibrido)
-        scope :archived, -> { archived_at_present }
-        scope :not_archived, -> { archived_at_null }
+        scope :archived, -> { archived_at_present(true) }
+        scope :not_archived, -> { archived_at_null(true) }
 
         # Configura se passato un blocco
         if block_given?