better_model 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec236d26e4c1e0a5a62e9932606a1baa28de1bcadf8b447f1da545fb35d029b6
-  data.tar.gz: 24e4aa004924ab09c6104cad770229041b8c8d24556ce5f2f2d190bf15071e90
+  metadata.gz: 56752c6458384a8ebb0bf5eb0e6e02adbd8bc822ce817705cc85d0502abce8aa
+  data.tar.gz: 8b8ce273a9b81d572f044154dd46486d1ad06086a7585b302875cd34069d28fc
 SHA512:
-  metadata.gz: 77d291e54bcbbb179eabd842290530d0f42e03636981e93bfdeb6575d5d0e02960d359072c0b0db0144f35cdbea647d463bf7320037c557552f6fce8365a393e
-  data.tar.gz: bfe3bf61206cb343dce4d84b2ff643e719c09b93a623de77e127a00aadbce646d25bfcc2cd66ca3bd725b6af224a82eb7cff2e059f79f45c8e026d5d878c95d6
+  metadata.gz: a509b30bdb21978f8f75cced201a5b4bc6bc77b96dfd7a28dba6242c3d8b274984d6bf7e1d2f73902d404fab47eda51edb7b67cd8fcca918e3f85f5ad745f9c9
+  data.tar.gz: 69a04f82516a2de9bfa837091ee4823c7c4036f764d9cd8ad1e12615cdeac291929a0f491320c1a698fd2f9d6988e904716b7c08ad942d2683f16a4e99a3eb3c

data/README.md

@@ -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
 
@@ -104,6 +107,17 @@ class Article < ApplicationRecord
     default_order [:sort_published_at_desc]
     security :status_required, [:status_eq]
   end
+
+  # 10. TAGGABLE - Tag management with statistics (opt-in)
+  taggable do
+    tag_field :tags
+    normalize true         # Automatic lowercase
+    strip true             # Remove whitespace
+    min_length 2           # Minimum tag length
+    max_length 30          # Maximum tag length
+    delimiter ","          # CSV delimiter
+    validates_tags minimum: 1, maximum: 10
+  end
 end
 ```
 
@@ -172,6 +186,22 @@ Article.search(
   orders: [:sort_published_at_desc],
   pagination: { page: 1, per_page: 25 }
 )
+
+# 🏷️ Manage tags
+article.tag_with("ruby", "rails", "tutorial")
+article.untag("tutorial")
+article.tagged_with?("ruby")  # => true
+article.tag_list = "ruby, rails, api"
+
+# 📊 Query with tags (via Predicable)
+Article.tags_contains("ruby")
+Article.tags_overlaps(["ruby", "python"])
+Article.tags_contains_all(["ruby", "rails"])
+
+# 📈 Tag statistics
+Article.tag_counts                    # => {"ruby" => 45, "rails" => 38}
+Article.popular_tags(limit: 10)       # => [["ruby", 45], ["rails", 38]]
+Article.related_tags("ruby", limit: 5)  # => ["rails", "gem", "tutorial"]
 ```
 
 ### 🎯 Including Individual Concerns (Advanced)
@@ -189,26 +219,168 @@ class Article < ApplicationRecord
   include BetterModel::Validatable   # Only validations
   include BetterModel::Stateable     # Only state machine
   include BetterModel::Searchable    # Only search (requires Predicable & Sortable)
+  include BetterModel::Taggable      # Only tag management
 
   # Define your features...
 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
+
+### 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:
+
+- `--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
+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
+
+# 4. Enable in your model (generators show you the code)
+# See model setup instructions after running each generator
+```
+
 ## 📋 Features Overview
 
-BetterModel provides nine powerful concerns that work seamlessly together:
+BetterModel provides ten 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
+- **⏰ 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
+- **🔄 Stateable** - Declarative state machines with guards & callbacks
+- **🏷️ Taggable** 🆕 - Tag management with normalization, validation, and statistics
 
 [See all features in detail →](#-features)
 
@@ -329,10 +501,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
@@ -391,6 +564,24 @@ Orchestrate Predicable and Sortable into a powerful, secure search interface wit
 
 ---
 
+### 🏷️ Taggable - Tag Management with Statistics
+
+Manage tags with automatic normalization, validation, and comprehensive statistics - integrated with Predicable for powerful searches.
+
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- 🤖 Automatic normalization (lowercase, strip, length limits)
+- ✅ Validation (min/max count, whitelist, blacklist)
+- 📊 Statistics (tag counts, popularity, co-occurrence)
+- 🔍 Automatic Predicable integration for searches
+- 📝 CSV import/export with tag_list
+- 🐘 PostgreSQL arrays or serialized JSON for SQLite
+- 🎯 Thread-safe configuration
+
+**[📖 Full Documentation →](docs/taggable.md)** | **[📚 Examples →](docs/examples/11_taggable.md)**
+
+---
+
 ### 📜 Traceable - Audit Trail & Change Tracking
 
 Track all changes to your records with comprehensive audit trail functionality, time-travel queries, and rollback capabilities.
@@ -532,9 +723,7 @@ article.update!(title: "Corrected Title")
 
 ---
 
-## 📌 Version & Changelog
-
-**Current Version:** 1.0.0
+## 📌 Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
 
@@ -623,12 +812,13 @@ bundle exec rubocop
 
 ### 📊 Test Coverage Notes
 
-The test suite runs on **SQLite** for performance and portability. Current coverage: **91.45%** (1272 / 1391 lines).
+The test suite runs on **SQLite** for performance and portability. Current coverage: **92.57%** (1507 / 1628 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`
+- **Predicable**: PostgreSQL array predicates (`_overlaps`, `_contains`, `_contained_by`) and JSONB predicates (`_has_key`, `_has_any_key`, `_has_all_keys`, `_jsonb_contains`)
+- **Traceable**: PostgreSQL JSONB queries and MySQL JSON_EXTRACT queries for field-specific change tracking
+- **Sortable**: MySQL NULLS emulation with CASE statements
+- **Taggable**: PostgreSQL native array operations (covered by Predicable tests)
 
 These features are fully implemented with proper SQL sanitization but require manual testing on PostgreSQL/MySQL:
 
@@ -652,3 +842,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,9 @@ 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 }
+        # v2.0.0: predicates require parameters
+        scope :archived, -> { archived_at_present(true) }
+        scope :not_archived, -> { archived_at_null(true) }
 
         # Configura se passato un blocco
         if block_given?

data/lib/better_model/predicable.rb

@@ -17,7 +17,7 @@
 #   Article.title_i_cont("rails")               # WHERE LOWER(title) LIKE '%rails%'
 #   Article.view_count_gt(100)                  # WHERE view_count > 100
 #   Article.published_at_lteq(Date.today)       # WHERE published_at <= '2025-10-29'
-#   Article.featured_true                       # WHERE featured = TRUE
+#   Article.featured_eq(true)                   # WHERE featured = TRUE
 #   Article.status_in(["draft", "published"])   # WHERE status IN ('draft', 'published')
 #
 module BetterModel
@@ -44,7 +44,7 @@ module BetterModel
       # Genera automaticamente scope di filtro basati sul tipo di colonna:
       # - String: _eq, _not_eq, _matches, _start, _end, _cont, _not_cont, _i_cont, _not_i_cont, _in, _not_in, _present, _blank, _null
       # - Numeric: _eq, _not_eq, _lt, _lteq, _gt, _gteq, _in, _not_in, _present
-      # - Boolean: _eq, _not_eq, _true, _false, _present
+      # - Boolean: _eq, _not_eq, _present (Note: _true and _false removed in v2.0.0 - use _eq(true/false))
       # - Date: _eq, _not_eq, _lt, _lteq, _gt, _gteq, _in, _not_in, _present, _blank, _null, _not_null
       #
       # Esempio:
@@ -151,9 +151,17 @@ module BetterModel
         scope :"#{field_name}_not_eq", ->(value) { where(field.not_eq(value)) }
 
         # Presence - skip for string/text types as they get specialized version
-        # String types need to check for both nil and empty string
+        # Required boolean parameter:
+        # - true: returns present records (NOT NULL)
+        # - false: returns null records (NULL)
         unless [ :string, :text ].include?(column_type)
-          scope :"#{field_name}_present", -> { where(field.not_eq(nil)) }
+          scope :"#{field_name}_present", ->(condition) {
+            if condition
+              where(field.not_eq(nil))
+            else
+              where(field.eq(nil))
+            end
+          }
         end
 
         scopes_to_register = [ :"#{field_name}_eq", :"#{field_name}_not_eq" ]
@@ -170,7 +178,16 @@ module BetterModel
         field = table[field_name]
 
         # String-specific presence check (checks both nil and empty string)
-        scope :"#{field_name}_present", -> { where(field.not_eq(nil).and(field.not_eq(""))) }
+        # Required boolean parameter:
+        # - true: returns present records (NOT NULL AND NOT '')
+        # - false: returns blank records (NULL OR '')
+        scope :"#{field_name}_present", ->(condition) {
+          if condition
+            where(field.not_eq(nil).and(field.not_eq("")))
+          else
+            where(field.eq(nil).or(field.eq("")))
+          end
+        }
 
         # Pattern matching (4)
         scope :"#{field_name}_matches", ->(pattern) { where(field.matches(pattern)) }
@@ -205,9 +222,24 @@ module BetterModel
         scope :"#{field_name}_in", ->(values) { where(field.in(Array(values))) }
         scope :"#{field_name}_not_in", ->(values) { where.not(field.in(Array(values))) }
 
-        # Presence (2) - _present is overridden above for string-specific behavior
-        scope :"#{field_name}_blank", -> { where(field.eq(nil).or(field.eq(""))) }
-        scope :"#{field_name}_null", -> { where(field.eq(nil)) }
+        # Presence (2)
+        # Required boolean parameter:
+        # - true: returns blank/null records
+        # - false: returns present/not-null records
+        scope :"#{field_name}_blank", ->(condition) {
+          if condition
+            where(field.eq(nil).or(field.eq("")))
+          else
+            where(field.not_eq(nil).and(field.not_eq("")))
+          end
+        }
+        scope :"#{field_name}_null", ->(condition) {
+          if condition
+            where(field.eq(nil))
+          else
+            where(field.not_eq(nil))
+          end
+        }
 
         register_predicable_scopes(
           :"#{field_name}_matches",
@@ -258,20 +290,16 @@ module BetterModel
         )
       end
 
-      # Genera predicati per campi booleani (2 scope)
+      # Genera predicati per campi booleani
       # Base predicates (_eq, _not_eq, _present) are defined separately
+      #
+      # Note: In v2.0.0, we removed _true and _false predicates as they were
+      # redundant with the base _eq predicate. Use these instead:
+      #   field_eq(true)   # instead of field_true
+      #   field_eq(false)  # instead of field_false
       def define_boolean_predicates(field_name)
-        table = arel_table
-        field = table[field_name]
-
-        # Boolean shortcuts (2)
-        scope :"#{field_name}_true", -> { where(field.eq(true)) }
-        scope :"#{field_name}_false", -> { where(field.eq(false)) }
-
-        register_predicable_scopes(
-          :"#{field_name}_true",
-          :"#{field_name}_false"
-        )
+        # Boolean fields only use base predicates (_eq, _not_eq, _present)
+        # No additional predicates needed
       end
 
       # Genera predicati per campi array PostgreSQL (3 scope)
@@ -403,28 +431,7 @@ module BetterModel
         scope :"#{field_name}_in", ->(values) { where(field.in(Array(values))) }
         scope :"#{field_name}_not_in", ->(values) { where.not(field.in(Array(values))) }
 
-        # Date convenience shortcuts (8)
-        scope :"#{field_name}_today", -> {
-          where(field.between(Date.current.beginning_of_day..Date.current.end_of_day))
-        }
-        scope :"#{field_name}_yesterday", -> {
-          where(field.between(1.day.ago.beginning_of_day..1.day.ago.end_of_day))
-        }
-        scope :"#{field_name}_this_week", -> {
-          where(field.gteq(Date.current.beginning_of_week))
-        }
-        scope :"#{field_name}_this_month", -> {
-          where(field.gteq(Date.current.beginning_of_month))
-        }
-        scope :"#{field_name}_this_year", -> {
-          where(field.gteq(Date.current.beginning_of_year))
-        }
-        scope :"#{field_name}_past", -> {
-          where(field.lt(Time.current))
-        }
-        scope :"#{field_name}_future", -> {
-          where(field.gt(Time.current))
-        }
+        # Date time-based filter (1)
         scope :"#{field_name}_within", ->(duration) {
           # Auto-detect: ActiveSupport::Duration or numeric (days)
           time_ago = duration.respond_to?(:ago) ? duration.ago : duration.to_i.days.ago
@@ -432,9 +439,30 @@ module BetterModel
         }
 
         # Presence (3) - _present is defined in base predicates
-        scope :"#{field_name}_blank", -> { where(field.eq(nil)) }
-        scope :"#{field_name}_null", -> { where(field.eq(nil)) }
-        scope :"#{field_name}_not_null", -> { where(field.not_eq(nil)) }
+        # Required boolean parameter:
+        # - true: returns blank/null records
+        # - false: returns not-blank/not-null records
+        scope :"#{field_name}_blank", ->(condition) {
+          if condition
+            where(field.eq(nil))
+          else
+            where(field.not_eq(nil))
+          end
+        }
+        scope :"#{field_name}_null", ->(condition) {
+          if condition
+            where(field.eq(nil))
+          else
+            where(field.not_eq(nil))
+          end
+        }
+        scope :"#{field_name}_not_null", ->(condition) {
+          if condition
+            where(field.not_eq(nil))
+          else
+            where(field.eq(nil))
+          end
+        }
 
         register_predicable_scopes(
           :"#{field_name}_lt",
@@ -445,13 +473,6 @@ module BetterModel
           :"#{field_name}_not_between",
           :"#{field_name}_in",
           :"#{field_name}_not_in",
-          :"#{field_name}_today",
-          :"#{field_name}_yesterday",
-          :"#{field_name}_this_week",
-          :"#{field_name}_this_month",
-          :"#{field_name}_this_year",
-          :"#{field_name}_past",
-          :"#{field_name}_future",
           :"#{field_name}_within",
           :"#{field_name}_blank",
           :"#{field_name}_null",