better_model 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93cc27ca4bb13c22c5d3ac1f0aa96010f7377bf687805b5f76bee89d44b83f5f
-  data.tar.gz: 5234fde47b3b13fc0ccc2da3fc3948f094ccd0f7eaa2cb4d8d219e6cf291a1c3
+  metadata.gz: 56752c6458384a8ebb0bf5eb0e6e02adbd8bc822ce817705cc85d0502abce8aa
+  data.tar.gz: 8b8ce273a9b81d572f044154dd46486d1ad06086a7585b302875cd34069d28fc
 SHA512:
-  metadata.gz: 3f9394cdc2201586b8b1d510d60aa286d29a86ab1a0c313f61401b850545a1924b08b16489b446d786aac38aa919ff7546dd6e3d3d5c9a9ca8a310b74ecbddc0
-  data.tar.gz: 8f218e1eb37bc94cb8510cda0ae32033458b1befe2ff5012a766b7c9874865b63b90facb72d7ba97deb1b80175fef06dbf27f6e42b2b9d44d3f47e212908cc7e
+  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
 
@@ -222,6 +225,146 @@ 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
+
+### 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 ten powerful concerns that work seamlessly together:
@@ -358,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
@@ -698,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",