better_model 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ba3b1688c75e16f9499780eebd533c307cd8ba18f9c37a03597c8d62310fae7
+  data.tar.gz: '0835904e4ea513187668f8f9c36e3d9855096bc46a2150555fae900b320b764d'
+SHA512:
+  metadata.gz: d42074244a7e4af9321b68e9657f343ac4c087956856cfd0cbfe68e72adc1fce5200fc051cdfe1badd0e6bc753dfa3abcf0603113e3dede3cd7ce083b3ba932c
+  data.tar.gz: e5305841ab87d40047b6bc458bdac8a163a96d0d9e864ead0a0335ab84b53759a5da837cb6b95f1c2bdc3596fcd74dc7281d77d370a3db0aa9cc98f72c281708

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright alessiobussolari
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,312 @@
+# BetterModel
+
+BetterModel is a Rails engine gem (Rails 8.1+) that provides powerful extensions for ActiveRecord models, including declarative status management, permissions, archiving, sorting, filtering, and unified search capabilities.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "better_model"
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+```bash
+$ gem install better_model
+```
+
+## Quick Start
+
+Simply include `BetterModel` in your model to get all features:
+
+```ruby
+class Article < ApplicationRecord
+  include BetterModel  # Includes all BetterModel concerns
+
+  # 1. STATUSABLE - Define statuses with lambdas
+  is :draft, -> { status == "draft" }
+  is :published, -> { status == "published" && published_at.present? }
+  is :expired, -> { expires_at.present? && expires_at <= Time.current }
+  is :popular, -> { view_count >= 100 }
+  is :active, -> { is?(:published) && !is?(:expired) }
+
+  # 2. PERMISSIBLE - Define permissions based on statuses
+  permit :edit, -> { is?(:draft) || (is?(:published) && !is?(:expired)) }
+  permit :delete, -> { is?(:draft) }
+  permit :publish, -> { is?(:draft) }
+  permit :unpublish, -> { is?(:published) }
+
+  # 3. SORTABLE - Define sortable fields
+  sort :title, :view_count, :published_at, :created_at
+
+  # 4. PREDICABLE - Define searchable/filterable fields
+  predicates :title, :status, :view_count, :published_at, :created_at, :featured
+
+  # 5. ARCHIVABLE - Soft delete with tracking (opt-in)
+  archivable do
+    skip_archived_by_default true  # Hide archived records by default
+  end
+
+  # 6. SEARCHABLE - Configure unified search interface
+  searchable do
+    per_page 25
+    max_per_page 100
+    default_order [:sort_published_at_desc]
+    security :status_required, [:status_eq]
+  end
+end
+```
+
+Now you can use all the features:
+
+```ruby
+# Check statuses
+article.is?(:draft)          # => true/false
+article.is_published?        # => true/false
+article.statuses             # => { draft: true, published: false, ... }
+
+# Check permissions
+article.permit?(:edit)       # => true/false
+article.permit_delete?       # => true/false
+article.permissions          # => { edit: true, delete: true, ... }
+
+# Sort
+Article.sort_title_asc
+Article.sort_view_count_desc
+Article.sort_published_at_desc
+
+# Filter with predicates
+Article.status_eq("published")
+Article.title_cont("Rails")
+Article.view_count_gteq(100)
+Article.published_at_present
+
+# Archive records
+article.archive!(by: current_user, reason: "Outdated")
+article.archived?  # => true
+article.restore!
+
+# Query archived records
+Article.archived
+Article.not_archived
+Article.archived_recently(7.days)
+
+# Unified search with filters, sorting, and pagination
+Article.search(
+  { status_eq: "published", view_count_gteq: 50 },
+  orders: [:sort_published_at_desc],
+  pagination: { page: 1, per_page: 25 }
+)
+```
+
+### Including Individual Concerns (Advanced)
+
+If you only need specific features, you can include individual concerns:
+
+```ruby
+class Article < ApplicationRecord
+  include BetterModel::Statusable    # Only status management
+  include BetterModel::Permissible   # Only permissions
+  include BetterModel::Archivable    # Only archiving
+  include BetterModel::Sortable      # Only sorting
+  include BetterModel::Predicable    # Only filtering
+  include BetterModel::Searchable    # Only search (requires Predicable & Sortable)
+
+  # Define your features...
+end
+```
+
+## Requirements
+
+- **Ruby:** 3.0 or higher
+- **Rails:** 8.1 or higher
+- **ActiveRecord:** Included with Rails
+
+## Database Compatibility
+
+BetterModel works with all databases supported by ActiveRecord:
+
+| Database | Status | Notes |
+|----------|--------|-------|
+| **PostgreSQL** | ✅ Full support | Recommended. Includes array and JSONB predicates |
+| **MySQL/MariaDB** | ✅ Full support | NULLS emulation for sorting |
+| **SQLite** | ✅ Full support | Great for development and testing |
+| **SQL Server** | ✅ Full support | Standard features work |
+| **Oracle** | ✅ Full support | Standard features work |
+
+**PostgreSQL-Specific Features:**
+- Array predicates: `overlaps`, `contains`, `contained_by`
+- JSONB predicates: `has_key`, `has_any_key`, `has_all_keys`, `jsonb_contains`
+
+## Features
+
+BetterModel provides six powerful concerns that work together seamlessly:
+
+### 📋 Statusable - Declarative Status Management
+
+Define derived statuses dynamically based on model attributes - no database columns needed!
+
+**Key Benefits:**
+- Declarative DSL with clear, readable conditions
+- Statuses calculated in real-time from model attributes
+- Reference other statuses in conditions
+- Automatic method generation (`is_draft?`, `is_published?`)
+- Thread-safe with immutable registry
+
+**[📖 Full Documentation →](docs/statusable.md)**
+
+---
+
+### 🔐 Permissible - Declarative Permission Management
+
+Define permissions dynamically based on model state and statuses - perfect for authorization logic!
+
+**Key Benefits:**
+- Declarative DSL following Statusable pattern
+- Permissions calculated from model state
+- Reference statuses in permission logic
+- Automatic method generation (`permit_edit?`, `permit_delete?`)
+- Thread-safe with immutable registry
+
+**[📖 Full Documentation →](docs/permissible.md)**
+
+---
+
+### 🗄️ Archivable - Soft Delete with Archive Management
+
+Soft-delete records with archive tracking, audit trails, and restoration capabilities.
+
+**Key Benefits:**
+- Opt-in activation: only enabled when explicitly configured
+- Archive and restore methods with optional tracking
+- Status methods: `archived?` and `active?`
+- Semantic scopes: `archived`, `not_archived`, `archived_only`
+- Helper predicates: `archived_today`, `archived_this_week`, `archived_recently`
+- Optional default scope to hide archived records
+- Migration generator with flexible options
+- Thread-safe with immutable configuration
+
+**[📖 Full Documentation →](docs/archivable.md)**
+
+---
+
+### ⬆️ Sortable - Type-Aware Sorting Scopes
+
+Generate intelligent sorting scopes automatically with database-specific optimizations and NULL handling.
+
+**Key Benefits:**
+- Type-aware scope generation (string, numeric, datetime, boolean)
+- Case-insensitive sorting for strings
+- Database-specific NULLS FIRST/LAST support
+- Sort by multiple fields with chaining
+- Optimized queries with proper indexing support
+
+**[📖 Full Documentation →](docs/sortable.md)**
+
+---
+
+### 🔍 Predicable - Advanced Query Scopes
+
+Generate comprehensive predicate scopes for filtering and searching with support for all data types.
+
+**Key Benefits:**
+- Complete coverage: string, numeric, datetime, boolean, null predicates
+- Type-safe predicates based on column type
+- Case-insensitive string matching
+- Range queries (between) for numerics and dates
+- PostgreSQL array and JSONB support
+- Chainable with standard ActiveRecord queries
+
+**[📖 Full Documentation →](docs/predicable.md)**
+
+---
+
+### 🔎 Searchable - Unified Search Interface
+
+Orchestrate Predicable and Sortable into a powerful, secure search interface with pagination and security.
+
+**Key Benefits:**
+- Unified API: single `search()` method for all operations
+- OR conditions for complex logic
+- Built-in pagination with DoS protection (max_per_page)
+- Security enforcement with required predicates
+- Default ordering configuration
+- Strong parameters integration
+- Type-safe validation of all parameters
+
+**[📖 Full Documentation →](docs/searchable.md)**
+
+---
+
+## Version & Changelog
+
+**Current Version:** 1.0.0
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
+
+## Support & Community
+
+- **Issues & Bugs:** [GitHub Issues](https://github.com/alessiobussolari/better_model/issues)
+- **Source Code:** [GitHub Repository](https://github.com/alessiobussolari/better_model)
+- **Documentation:** This README and detailed docs in `docs/` directory
+
+## Contributing
+
+We welcome contributions! Here's how you can help:
+
+### Reporting Bugs
+
+1. Check if the issue already exists in [GitHub Issues](https://github.com/alessiobussolari/better_model/issues)
+2. Create a new issue with:
+   - Clear description of the problem
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Ruby/Rails versions
+   - Database adapter
+
+### Submitting Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes with tests
+4. Run the test suite (`bundle exec rake test`)
+5. Ensure RuboCop passes (`bundle exec rubocop`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/better_model.git
+cd better_model
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake test
+
+# Run SimpleCov for coverage
+bundle exec rake test  # Coverage report in coverage/index.html
+
+# Run RuboCop
+bundle exec rubocop
+```
+
+### Code Guidelines
+
+- Follow the existing code style (enforced by RuboCop Omakase)
+- Write tests for new features
+- Update documentation (README) for user-facing changes
+- Keep pull requests focused (one feature/fix per PR)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/lib/better_model/archivable.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+# Archivable - Sistema di archiviazione dichiarativa per modelli Rails
+#
+# Questo concern permette di archiviare e ripristinare record utilizzando un DSL
+# semplice e dichiarativo, con supporto per predicati e scopes.
+#
+# SETUP RAPIDO:
+#   # Opzione 1: Generator automatico (raccomandato)
+#   rails g better_model:archivable Article --with-tracking
+#   rails db:migrate
+#
+#   # Opzione 2: Migration manuale
+#   rails g migration AddArchivableToArticles archived_at:datetime archived_by_id:integer archive_reason:string
+#   rails db:migrate
+#
+# APPROCCIO OPT-IN: L'archiviazione non è attiva automaticamente. Devi chiamare
+# esplicitamente `archivable do...end` nel tuo modello per attivarla.
+#
+# APPROCCIO IBRIDO: Usa i predicati esistenti (archived_at_present, archived_at_null, etc.)
+# e fornisce alias semantici (archived, not_archived) per una migliore leggibilità.
+#
+# REQUISITI DATABASE:
+#   - archived_at (datetime)    - REQUIRED (obbligatorio)
+#   - archived_by_id (integer)  - OPTIONAL (per tracking utente)
+#   - archive_reason (string)   - OPTIONAL (per motivazione)
+#
+# Esempio di utilizzo:
+#   class Article < ApplicationRecord
+#     include BetterModel
+#
+#     # Attiva archivable (opt-in)
+#     archivable do
+#       skip_archived_by_default true  # Opzionale: nascondi archiviati di default
+#     end
+#   end
+#
+# Utilizzo:
+#   article.archive!                        # Archive the record
+#   article.archive!(by: user)              # Archive with user tracking
+#   article.archive!(reason: "Outdated")    # Archive with reason
+#   article.restore!                        # Restore archived record
+#   article.archived?                       # Check if archived
+#   article.active?                         # Check if not archived
+#
+#   # Scopes semantici
+#   Article.archived                        # Find archived records
+#   Article.not_archived                    # Find active records
+#   Article.archived_only                   # Bypass default scope
+#
+#   # Predicati potenti (generati automaticamente)
+#   Article.archived_at_within(7.days)      # Archived in last 7 days
+#   Article.archived_at_today               # Archived today
+#   Article.archived_at_between(start, end) # Archived in range
+#
+#   # Helper methods
+#   Article.archived_today                  # Alias for archived_at_today
+#   Article.archived_this_week              # Alias for archived_at_this_week
+#   Article.archived_recently(7.days)       # Alias for archived_at_within
+#
+#   # Con Searchable
+#   Article.search({ archived_at_null: true, status_eq: "published" })
+#
+module BetterModel
+  module Archivable
+    extend ActiveSupport::Concern
+
+    included do
+      # Validazione ActiveRecord
+      unless ancestors.include?(ActiveRecord::Base)
+        raise ArgumentError, "BetterModel::Archivable can only be included in ActiveRecord models"
+      end
+
+      # Configurazione archivable (opt-in)
+      class_attribute :archivable_enabled, default: false
+      class_attribute :archivable_config, default: {}.freeze
+    end
+
+    class_methods do
+      # DSL per attivare e configurare archivable (OPT-IN)
+      #
+      # @example Attivazione base
+      #   archivable
+      #
+      # @example Con configurazione
+      #   archivable do
+      #     skip_archived_by_default true
+      #   end
+      def archivable(&block)
+        # Valida che archived_at esista
+        unless column_names.include?("archived_at")
+          raise ArgumentError,
+            "Archivable requires an 'archived_at' datetime column. " \
+            "Add it with: rails g migration AddArchivedAtTo#{table_name.classify.pluralize} archived_at:datetime"
+        end
+
+        # Attiva archivable
+        self.archivable_enabled = true
+
+        # Definisci predicati su archived_at (opt-in!)
+        predicates :archived_at unless predicable_field?(:archived_at)
+
+        # Definisci anche sort su archived_at (opt-in!)
+        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 }
+
+        # Configura se passato un blocco
+        if block_given?
+          configurator = ArchivableConfigurator.new(self)
+          configurator.instance_eval(&block)
+          self.archivable_config = configurator.to_h.freeze
+
+          # Applica default scope SOLO se configurato
+          if archivable_config[:skip_archived_by_default]
+            default_scope -> { not_archived }
+          end
+        end
+      end
+
+      # Trova SOLO record archiviati, bypassando default scope
+      #
+      # @return [ActiveRecord::Relation]
+      def archived_only
+        raise NotEnabledError unless archivable_enabled?
+        unscoped.archived
+      end
+
+      # Helper: alias per archived_at_today
+      def archived_today
+        raise NotEnabledError unless archivable_enabled?
+        archived_at_today
+      end
+
+      # Helper: alias per archived_at_this_week
+      def archived_this_week
+        raise NotEnabledError unless archivable_enabled?
+        archived_at_this_week
+      end
+
+      # Helper: alias per archived_at_within
+      #
+      # @param duration [ActiveSupport::Duration] Durata (es: 7.days)
+      # @return [ActiveRecord::Relation]
+      def archived_recently(duration = 7.days)
+        raise NotEnabledError unless archivable_enabled?
+        archived_at_within(duration)
+      end
+
+      # Verifica se archivable è attivo
+      #
+      # @return [Boolean]
+      def archivable_enabled?
+        archivable_enabled == true
+      end
+    end
+
+    # Metodi di istanza
+
+    # Archivia il record
+    #
+    # @param by [Integer, Object] ID utente o oggetto user (opzionale)
+    # @param reason [String] Motivo dell'archiviazione (opzionale)
+    # @return [self]
+    # @raise [NotEnabledError] se archivable non è attivo
+    # @raise [AlreadyArchivedError] se già archiviato
+    def archive!(by: nil, reason: nil)
+      raise NotEnabledError unless self.class.archivable_enabled?
+      raise AlreadyArchivedError, "Record is already archived" if archived?
+
+      self.archived_at = Time.current
+
+      # Set archived_by_id: accetta sia ID che oggetti con .id
+      if respond_to?(:archived_by_id=) && by.present?
+        self.archived_by_id = by.respond_to?(:id) ? by.id : by
+      end
+
+      self.archive_reason = reason if respond_to?(:archive_reason=)
+
+      save!(validate: false)
+      self
+    end
+
+    # Ripristina record archiviato
+    #
+    # @return [self]
+    # @raise [NotEnabledError] se archivable non è attivo
+    # @raise [NotArchivedError] se non archiviato
+    def restore!
+      raise NotEnabledError unless self.class.archivable_enabled?
+      raise NotArchivedError, "Record is not archived" unless archived?
+
+      self.archived_at = nil
+      self.archived_by_id = nil if respond_to?(:archived_by_id=)
+      self.archive_reason = nil if respond_to?(:archive_reason=)
+
+      save!(validate: false)
+      self
+    end
+
+    # Verifica se il record è archiviato
+    #
+    # @return [Boolean]
+    def archived?
+      return false unless self.class.archivable_enabled?
+      archived_at.present?
+    end
+
+    # Verifica se il record è attivo (non archiviato)
+    #
+    # @return [Boolean]
+    def active?
+      !archived?
+    end
+
+    # Override as_json per includere info archivio
+    #
+    # @param options [Hash] Opzioni as_json
+    # @option options [Boolean] :include_archive_info Include archive metadata
+    # @return [Hash]
+    def as_json(options = {})
+      result = super
+
+      if options[:include_archive_info] && self.class.archivable_enabled?
+        result["archive_info"] = {
+          "archived" => archived?,
+          "archived_at" => archived_at,
+          "archived_by_id" => (respond_to?(:archived_by_id) ? archived_by_id : nil),
+          "archive_reason" => (respond_to?(:archive_reason) ? archive_reason : nil)
+        }
+      end
+
+      result
+    end
+  end
+
+  # Errori custom
+  class ArchivableError < StandardError; end
+  class AlreadyArchivedError < ArchivableError; end
+  class NotArchivedError < ArchivableError; end
+
+  class NotEnabledError < ArchivableError
+    def initialize(msg = nil)
+      super(msg || "Archivable is not enabled. Add 'archivable do...end' to your model.")
+    end
+  end
+
+  # Configurator per archivable DSL
+  class ArchivableConfigurator
+    attr_reader :config
+
+    def initialize(model_class)
+      @model_class = model_class
+      @config = {
+        skip_archived_by_default: false
+      }
+    end
+
+    # Configura default scope per nascondere archiviati
+    #
+    # @param value [Boolean] true per nascondere archiviati di default
+    def skip_archived_by_default(value)
+      @config[:skip_archived_by_default] = !!value
+    end
+
+    def to_h
+      @config
+    end
+  end
+end