better_model 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56752c6458384a8ebb0bf5eb0e6e02adbd8bc822ce817705cc85d0502abce8aa
-  data.tar.gz: 8b8ce273a9b81d572f044154dd46486d1ad06086a7585b302875cd34069d28fc
+  metadata.gz: 43311885d24f9c9001eba91737135c5fa8787cc42e5f5e7beaaf912e2ae177d0
+  data.tar.gz: cc80f44ca0c7c5992302175d949ef237d3b0f4d2274c9b1d13bba6398f6dad6c
 SHA512:
-  metadata.gz: a509b30bdb21978f8f75cced201a5b4bc6bc77b96dfd7a28dba6242c3d8b274984d6bf7e1d2f73902d404fab47eda51edb7b67cd8fcca918e3f85f5ad745f9c9
-  data.tar.gz: 69a04f82516a2de9bfa837091ee4823c7c4036f764d9cd8ad1e12615cdeac291929a0f491320c1a698fd2f9d6988e904716b7c08ad942d2683f16a4e99a3eb3c
+  metadata.gz: 77874dd1ad5221c36a5498b74810f1812e978a984f24e35e50dcdfba0019899d4afe742bf431c68a3b5c94e30a3fe1e9c0f7d3e16e16722044ec4f91b2538b57
+  data.tar.gz: 11f774a0981cd7bc2ec1f307a63a8d0e3f91dc7431b58e262cd9bb5edc858e9548c8f51ea190e7e50a8b17c88965cdbc6d0bbb36e39e819fef9d7464ffb032de

data/README.md

@@ -53,20 +53,20 @@ class Article < ApplicationRecord
   end
 
   # 6. VALIDATABLE - Declarative validation system (opt-in)
+  register_complex_validation :published_requirements do
+    return unless status == "published"
+    errors.add(:published_at, "must be present for published articles") if published_at.blank?
+  end
+
   validatable do
     # Basic validations
-    validate :title, :content, presence: true
-
-    # Conditional validations
-    validate_if :is_published? do
-      validate :published_at, presence: true
-    end
+    check :title, :content, presence: true
 
-    # Cross-field validations
-    validate_order :starts_at, :before, :ends_at
+    # Conditional validations using Rails options
+    check :published_at, presence: true, if: -> { status == "published" }
 
-    # Business rules
-    validate_business_rule :valid_category
+    # Complex validations for business rules
+    check_complex :published_requirements
 
     # Validation groups (multi-step forms)
     validation_group :step1, [:title, :content]
@@ -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
@@ -365,24 +335,111 @@ rails db:migrate
 # See model setup instructions after running each generator
 ```
 
+### Repository Generator
+
+Create repository classes that implement the Repository Pattern:
+
+```bash
+# Basic usage - creates model repository and ApplicationRepository
+rails g better_model:repository Article
+
+# Custom path
+rails g better_model:repository Article --path app/services/repositories
+
+# Skip ApplicationRepository creation
+rails g better_model:repository Article --skip-base
+
+# With namespace
+rails g better_model:repository Article --namespace Admin
+```
+
+**Generated repository includes:**
+- Repository class inheriting from `ApplicationRepository` (or `BetterModel::Repositable::BaseRepository` with `--skip-base`)
+- Modern Ruby 3 endless method syntax: `def model_class = Article`
+- Commented examples of custom query methods
+- Integration with BetterModel's Searchable, Predicable, and Sortable features
+- Auto-generated documentation of available predicates and sort scopes (if model uses BetterModel)
+
+**ApplicationRepository (generated once):**
+- Base class for all repositories in your application
+- Inherits from `BetterModel::Repositable::BaseRepository`
+- Can be customized with application-wide repository behaviors
+
+**Example usage:**
+
+```ruby
+# app/repositories/article_repository.rb
+class ArticleRepository < ApplicationRepository
+  def model_class = Article
+
+  def published
+    search({ status_eq: "published" })
+  end
+
+  def recent(days: 7)
+    search({ created_at_gteq: days.days.ago }, order_scope: { field: :created_at, direction: :desc })
+  end
+
+  def popular(min_views: 100)
+    search({ view_count_gteq: min_views }, orders: [:sort_view_count_desc])
+  end
+
+  def search_text(query)
+    search({
+      or: [
+        { title_i_cont: query },
+        { content_i_cont: query }
+      ]
+    })
+  end
+end
+
+# In your controllers/services
+repo = ArticleRepository.new
+articles = repo.published
+popular = repo.popular(min_views: 200)
+results = repo.search({ status_eq: "published" }, page: 1, per_page: 20)
+article = repo.search({ id_eq: 1 }, limit: 1)
+```
+
+**BaseRepository features:**
+- `search(predicates, page:, per_page:, includes:, joins:, order:, order_scope:, limit:)` - Main search method
+- `find(id)`, `find_by(...)` - Standard ActiveRecord finders
+- `create(attrs)`, `create!(attrs)` - Create records
+- `build(attrs)` - Build new instances
+- `update(id, attrs)` - Update records
+- `delete(id)` - Delete records
+- `where(...)`, `all`, `count`, `exists?` - Basic ActiveRecord methods
+
+**Search method parameters:**
+- **predicates**: Hash of BetterModel predicates (e.g., `{ status_eq: "published", view_count_gt: 100 }`)
+- **page/per_page**: Pagination (default: page 1, 20 per page)
+- **includes/joins**: Eager loading and associations
+- **order**: SQL order clause
+- **order_scope**: BetterModel sort scope (e.g., `{ field: :published_at, direction: :desc }`)
+- **limit**: Result limit (Integer for limit, `:default` for pagination, `nil` for all results)
+
 ## 📋 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
 
@@ -406,9 +463,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
 
-BetterModel provides eight powerful concerns that work together seamlessly:
+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` |
+
+**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
 
@@ -464,11 +534,10 @@ Define validations declaratively with support for conditional rules, cross-field
 
 **🎯 Key Benefits:**
 - 🎛️ Opt-in activation: only enabled when explicitly configured
-- ✨ Declarative DSL for all validation types
-- 🔀 Conditional validations: `validate_if` / `validate_unless`
-- 🔗 Cross-field validations: `validate_order` for date/number comparisons
-- 💼 Business rules: delegate complex logic to custom methods
+- ✨ Declarative DSL with `check` method for basic validations
+- 🔗 Complex validations: reusable validation blocks for cross-field and business logic
 - 📋 Validation groups: partial validation for multi-step forms
+- 🔀 Conditional validations using Rails `if:` / `unless:` options
 - 🔒 Thread-safe with immutable configuration
 
 **[📖 Full Documentation →](docs/validatable.md)**
@@ -542,9 +611,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 +694,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 +762,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 +787,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 +824,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 +871,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).