better_model 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56752c6458384a8ebb0bf5eb0e6e02adbd8bc822ce817705cc85d0502abce8aa
-  data.tar.gz: 8b8ce273a9b81d572f044154dd46486d1ad06086a7585b302875cd34069d28fc
+  metadata.gz: 3237879bac91f8200057cba591a1a2f09ccc761f55fd2ded1f1acb5a156c65f2
+  data.tar.gz: 6ab53b6128104cac44fdb5ad8ce80ca662a78072724a29c946c9380ad66701f2
 SHA512:
-  metadata.gz: a509b30bdb21978f8f75cced201a5b4bc6bc77b96dfd7a28dba6242c3d8b274984d6bf7e1d2f73902d404fab47eda51edb7b67cd8fcca918e3f85f5ad745f9c9
-  data.tar.gz: 69a04f82516a2de9bfa837091ee4823c7c4036f764d9cd8ad1e12615cdeac291929a0f491320c1a698fd2f9d6988e904716b7c08ad942d2683f16a4e99a3eb3c
+  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
@@ -307,34 +307,6 @@ rails db:migrate
    - Optional metadata (JSON)
    - Optimized indexes
 
-### Taggable Generator
-
-Add tags column with database-specific optimizations:
-
-```bash
-# Basic usage - adds tags column
-rails g better_model:taggable Article
-
-# Custom column name
-rails g better_model:taggable Article --column-name=categories
-
-# Skip GIN index (PostgreSQL only)
-rails g better_model:taggable Article --skip-index
-
-# Run migrations
-rails db:migrate
-```
-
-**Generated migration includes:**
-- **PostgreSQL**: Native array column (`array: true, default: []`) with GIN index for optimal performance
-- **SQLite/MySQL**: Text column with serialization instructions
-- Database-specific detection and optimization
-- Automatic index creation for PostgreSQL (GIN index)
-
-**Database-specific behavior:**
-- PostgreSQL: Ready to use immediately with native array support
-- SQLite/MySQL: Requires adding `serialize :tags, coder: JSON, type: Array` to model
-
 ### Generator Options
 
 All generators support these common options:
@@ -350,13 +322,11 @@ All generators support these common options:
 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
-rails g better_model:taggable Article --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
-rails g better_model:taggable Article
 
 # 3. Run migrations
 rails db:migrate
@@ -369,20 +339,23 @@ rails db:migrate
 
 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
 
@@ -406,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
 
@@ -542,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
@@ -559,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
@@ -582,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.
@@ -748,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
 
@@ -792,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
@@ -810,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).

data/lib/better_model/archivable.rb

@@ -104,7 +104,6 @@ module BetterModel
         sort :archived_at unless sortable_field?(:archived_at)
 
         # Definisci gli scope alias (approccio ibrido)
-        # v2.0.0: predicates require parameters
         scope :archived, -> { archived_at_present(true) }
         scope :not_archived, -> { archived_at_null(true) }