better_model 1.0.0

data/lib/better_model/sortable.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+# Sortable - Sistema di ordinamento dichiarativo per modelli Rails
+#
+# Questo concern permette di definire ordinamenti sui modelli utilizzando un DSL
+# semplice e dichiarativo che genera automaticamente scope basati sul tipo di colonna.
+#
+# Esempio di utilizzo:
+#   class Article < ApplicationRecord
+#     include BetterModel::Sortable
+#
+#     sort :title, :view_count, :published_at
+#   end
+#
+# Utilizzo:
+#   Article.sort_title_asc                    # ORDER BY title ASC
+#   Article.sort_title_desc_i                 # ORDER BY LOWER(title) DESC
+#   Article.sort_view_count_desc_nulls_last   # ORDER BY view_count DESC NULLS LAST
+#   Article.sort_published_at_newest          # ORDER BY published_at DESC
+#
+module BetterModel
+  module Sortable
+    extend ActiveSupport::Concern
+
+    included do
+      # Valida che sia incluso solo in modelli ActiveRecord
+      unless ancestors.include?(ActiveRecord::Base)
+        raise ArgumentError, "BetterModel::Sortable can only be included in ActiveRecord models"
+      end
+
+      # Registry dei campi sortable definiti per questa classe
+      class_attribute :sortable_fields, default: Set.new
+      # Registry degli scope sortable generati
+      class_attribute :sortable_scopes, default: Set.new
+    end
+
+    class_methods do
+      # DSL per definire campi sortable
+      #
+      # Genera automaticamente scope di ordinamento basati sul tipo di colonna:
+      # - String: _asc, _desc, _asc_i, _desc_i (case-insensitive)
+      # - Numeric: _asc, _desc, _asc_nulls_last, _desc_nulls_last, etc.
+      # - Date: _asc, _desc, _newest, _oldest
+      #
+      # Esempio:
+      #   sort :title, :view_count, :published_at
+      def sort(*field_names)
+        field_names.each do |field_name|
+          validate_sortable_field!(field_name)
+          register_sortable_field(field_name)
+
+          # Auto-rileva tipo e genera scope appropriati
+          column = columns_hash[field_name.to_s]
+          next unless column
+
+          case column.type
+          when :string, :text
+            define_string_sorting(field_name)
+          when :integer, :decimal, :float, :bigint
+            define_numeric_sorting(field_name)
+          when :date, :datetime, :time, :timestamp
+            define_date_sorting(field_name)
+          else
+            # Default: genera solo scope base
+            define_base_sorting(field_name)
+          end
+        end
+      end
+
+      # Verifica se un campo è stato registrato come sortable
+      def sortable_field?(field_name)
+        sortable_fields.include?(field_name.to_sym)
+      end
+
+      # Verifica se uno scope sortable è stato generato
+      def sortable_scope?(scope_name)
+        sortable_scopes.include?(scope_name.to_sym)
+      end
+
+      private
+
+      # Valida che il campo esista nella tabella
+      def validate_sortable_field!(field_name)
+        unless column_names.include?(field_name.to_s)
+          raise ArgumentError, "Invalid field name: #{field_name}. Field does not exist in #{table_name}"
+        end
+      end
+
+      # Registra un campo nel registry sortable_fields
+      def register_sortable_field(field_name)
+        self.sortable_fields = (sortable_fields + [ field_name.to_sym ]).to_set.freeze
+      end
+
+      # Registra scope nel registry sortable_scopes
+      def register_sortable_scopes(*scope_names)
+        self.sortable_scopes = (sortable_scopes + scope_names.map(&:to_sym)).to_set.freeze
+      end
+
+      # Genera scope base: sort_field_asc e sort_field_desc
+      def define_base_sorting(field_name)
+        quoted_field = connection.quote_column_name(field_name)
+
+        scope :"sort_#{field_name}_asc", -> { order(Arel.sql("#{quoted_field} ASC")) }
+        scope :"sort_#{field_name}_desc", -> { order(Arel.sql("#{quoted_field} DESC")) }
+
+        register_sortable_scopes(
+          :"sort_#{field_name}_asc",
+          :"sort_#{field_name}_desc"
+        )
+      end
+
+      # Genera scope per campi stringa (include case-insensitive)
+      def define_string_sorting(field_name)
+        quoted_field = connection.quote_column_name(field_name)
+
+        # Scope base
+        scope :"sort_#{field_name}_asc", -> { order(Arel.sql("#{quoted_field} ASC")) }
+        scope :"sort_#{field_name}_desc", -> { order(Arel.sql("#{quoted_field} DESC")) }
+
+        # Scope case-insensitive
+        scope :"sort_#{field_name}_asc_i", -> { order(Arel.sql("LOWER(#{quoted_field}) ASC")) }
+        scope :"sort_#{field_name}_desc_i", -> { order(Arel.sql("LOWER(#{quoted_field}) DESC")) }
+
+        register_sortable_scopes(
+          :"sort_#{field_name}_asc",
+          :"sort_#{field_name}_desc",
+          :"sort_#{field_name}_asc_i",
+          :"sort_#{field_name}_desc_i"
+        )
+      end
+
+      # Genera scope per campi numerici (include gestione NULL)
+      def define_numeric_sorting(field_name)
+        quoted_field = connection.quote_column_name(field_name)
+
+        # Scope base
+        scope :"sort_#{field_name}_asc", -> { order(Arel.sql("#{quoted_field} ASC")) }
+        scope :"sort_#{field_name}_desc", -> { order(Arel.sql("#{quoted_field} DESC")) }
+
+        # Pre-calcola SQL per gestione NULL (necessario perché lo scope non ha accesso ai metodi privati)
+        sql_asc_nulls_last = nulls_order_sql(field_name, "ASC", "LAST")
+        sql_desc_nulls_last = nulls_order_sql(field_name, "DESC", "LAST")
+        sql_asc_nulls_first = nulls_order_sql(field_name, "ASC", "FIRST")
+        sql_desc_nulls_first = nulls_order_sql(field_name, "DESC", "FIRST")
+
+        # Scope con gestione NULL
+        scope :"sort_#{field_name}_asc_nulls_last", -> {
+          order(Arel.sql(sql_asc_nulls_last))
+        }
+        scope :"sort_#{field_name}_desc_nulls_last", -> {
+          order(Arel.sql(sql_desc_nulls_last))
+        }
+        scope :"sort_#{field_name}_asc_nulls_first", -> {
+          order(Arel.sql(sql_asc_nulls_first))
+        }
+        scope :"sort_#{field_name}_desc_nulls_first", -> {
+          order(Arel.sql(sql_desc_nulls_first))
+        }
+
+        register_sortable_scopes(
+          :"sort_#{field_name}_asc",
+          :"sort_#{field_name}_desc",
+          :"sort_#{field_name}_asc_nulls_last",
+          :"sort_#{field_name}_desc_nulls_last",
+          :"sort_#{field_name}_asc_nulls_first",
+          :"sort_#{field_name}_desc_nulls_first"
+        )
+      end
+
+      # Genera scope per campi data/datetime (include shortcuts semantici)
+      def define_date_sorting(field_name)
+        quoted_field = connection.quote_column_name(field_name)
+
+        # Scope base
+        scope :"sort_#{field_name}_asc", -> { order(Arel.sql("#{quoted_field} ASC")) }
+        scope :"sort_#{field_name}_desc", -> { order(Arel.sql("#{quoted_field} DESC")) }
+
+        # Shortcuts semantici
+        scope :"sort_#{field_name}_newest", -> { order(Arel.sql("#{quoted_field} DESC")) }
+        scope :"sort_#{field_name}_oldest", -> { order(Arel.sql("#{quoted_field} ASC")) }
+
+        register_sortable_scopes(
+          :"sort_#{field_name}_asc",
+          :"sort_#{field_name}_desc",
+          :"sort_#{field_name}_newest",
+          :"sort_#{field_name}_oldest"
+        )
+      end
+
+      # Genera SQL per gestione NULL multi-database
+      def nulls_order_sql(field_name, direction, nulls_position)
+        quoted_field = connection.quote_column_name(field_name)
+
+        # PostgreSQL e SQLite 3.30+ supportano NULLS LAST/FIRST nativamente
+        if connection.adapter_name.match?(/PostgreSQL|SQLite/)
+          "#{quoted_field} #{direction} NULLS #{nulls_position}"
+        else
+          # MySQL/MariaDB: emulazione con CASE
+          if nulls_position == "LAST"
+            "CASE WHEN #{quoted_field} IS NULL THEN 1 ELSE 0 END, #{quoted_field} #{direction}"
+          else # FIRST
+            "CASE WHEN #{quoted_field} IS NULL THEN 0 ELSE 1 END, #{quoted_field} #{direction}"
+          end
+        end
+      end
+    end
+
+    # Metodi di istanza
+
+    # Ritorna lista di attributi sortable (esclude campi sensibili)
+    def sortable_attributes
+      self.class.column_names.reject do |attr|
+        attr.start_with?("password", "encrypted_")
+      end
+    end
+  end
+end

data/lib/better_model/statusable.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# Statusable - Sistema di stati dichiarativi per modelli Rails
+#
+# Questo concern permette di definire stati sui modelli utilizzando un DSL
+# semplice e dichiarativo, simile al pattern Enrichable ma per gli stati.
+#
+# Esempio di utilizzo:
+#   class Communications::Consult < ApplicationRecord
+#     include BetterModel::Statusable
+#
+#     is :pending, -> { status == 'initialized' }
+#     is :active_session, -> { status == 'active' && !expired? }
+#     is :expired, -> { expires_at.present? && expires_at <= Time.current }
+#     is :scheduled, -> { scheduled_at.present? }
+#     is :immediate, -> { scheduled_at.blank? }
+#     is :ready_to_start, -> { scheduled? && scheduled_at <= Time.current }
+#   end
+#
+# Utilizzo:
+#   consult.is?(:pending)           # => true/false
+#   consult.is_pending?             # => true/false
+#   consult.is_active_session?      # => true/false
+#   consult.is_expired?             # => true/false
+#   consult.is_scheduled?           # => true/false
+#
+module BetterModel
+  module Statusable
+    extend ActiveSupport::Concern
+
+    included do
+      # Registry degli stati definiti per questa classe
+      class_attribute :is_definitions
+      self.is_definitions = {}
+    end
+
+    class_methods do
+      # DSL per definire stati
+      #
+      # Parametri:
+      # - status_name: simbolo che rappresenta lo stato (es. :pending, :active)
+      # - condition_proc: lambda o proc che definisce la condizione
+      # - block: blocco alternativo alla condition_proc
+      #
+      # Esempi:
+      #   is :pending, -> { status == 'initialized' }
+      #   is :expired, -> { expires_at.present? && expires_at <= Time.current }
+      #   is :ready do
+      #     scheduled_at.present? && scheduled_at <= Time.current
+      #   end
+      def is(status_name, condition_proc = nil, &block)
+        # Valida i parametri prima di convertire
+        raise ArgumentError, "Status name cannot be blank" if status_name.blank?
+
+        status_name = status_name.to_sym
+        condition = condition_proc || block
+        raise ArgumentError, "Condition proc or block is required" unless condition
+        raise ArgumentError, "Condition must respond to call" unless condition.respond_to?(:call)
+
+        # Registra lo stato nel registry
+        self.is_definitions = is_definitions.merge(status_name => condition.freeze).freeze
+
+        # Genera il metodo dinamico is_#{status_name}?
+        define_is_method(status_name)
+      end
+
+      # Lista di tutti gli stati definiti per questa classe
+      def defined_statuses
+        is_definitions.keys
+      end
+
+      # Verifica se uno stato è definito
+      def status_defined?(status_name)
+        is_definitions.key?(status_name.to_sym)
+      end
+
+      private
+
+      # Genera dinamicamente il metodo is_#{status_name}? per ogni stato definito
+      def define_is_method(status_name)
+        method_name = "is_#{status_name}?"
+
+        # Evita di ridefinire metodi se già esistono
+        return if method_defined?(method_name)
+
+        define_method(method_name) do
+          is?(status_name)
+        end
+      end
+    end
+
+    # Metodo generico per verificare se uno stato è attivo
+    #
+    # Parametri:
+    # - status_name: simbolo dello stato da verificare
+    #
+    # Ritorna:
+    # - true se lo stato è attivo
+    # - false se lo stato non è attivo o non è definito
+    #
+    # Esempio:
+    #   consult.is?(:pending)
+    def is?(status_name)
+      status_name = status_name.to_sym
+      condition = self.class.is_definitions[status_name]
+
+      # Se lo stato non è definito, ritorna false (secure by default)
+      return false unless condition
+
+      # Valuta la condizione nel contesto dell'istanza del modello
+      # Gli errori si propagano naturalmente - fail fast
+      instance_exec(&condition)
+    end
+
+    # Ritorna tutti gli stati disponibili per questa istanza con i loro valori
+    #
+    # Ritorna:
+    # - Hash con chiavi simbolo (stati) e valori booleani (attivi/inattivi)
+    #
+    # Esempio:
+    #   consult.statuses
+    #   # => { pending: true, active: false, expired: false, scheduled: true }
+    def statuses
+      self.class.is_definitions.each_with_object({}) do |(status_name, _condition), result|
+        result[status_name] = is?(status_name)
+      end
+    end
+
+    # Verifica se l'istanza ha almeno uno stato attivo
+    def has_any_status?
+      statuses.values.any?
+    end
+
+    # Verifica se l'istanza ha tutti gli stati specificati attivi
+    def has_all_statuses?(status_names)
+      Array(status_names).all? { |status_name| is?(status_name) }
+    end
+
+    # Filtra una lista di stati restituendo solo quelli attivi
+    def active_statuses(status_names)
+      Array(status_names).select { |status_name| is?(status_name) }
+    end
+
+    # Override di as_json per includere automaticamente gli stati se richiesto
+    def as_json(options = {})
+      result = super
+
+      # Include gli stati se esplicitamente richiesto, converting symbol keys to strings
+      result["statuses"] = statuses.transform_keys(&:to_s) if options[:include_statuses]
+
+      result
+    end
+  end
+end

data/lib/better_model/version.rb

@@ -0,0 +1,3 @@
+module BetterModel
+  VERSION = "1.0.0"
+end

data/lib/better_model.rb

@@ -0,0 +1,24 @@
+require "better_model/version"
+require "better_model/railtie"
+require "better_model/statusable"
+require "better_model/permissible"
+require "better_model/sortable"
+require "better_model/predicable"
+require "better_model/searchable"
+require "better_model/archivable"
+
+module BetterModel
+  extend ActiveSupport::Concern
+
+  # When BetterModel is included, automatically include all sub-concerns
+  included do
+    include BetterModel::Statusable
+    include BetterModel::Permissible
+    include BetterModel::Sortable
+    include BetterModel::Predicable
+    include BetterModel::Searchable
+    include BetterModel::Archivable
+    # Future concerns will be added here:
+    # include BetterModel::Validatable
+  end
+end

data/lib/generators/better_model/archivable/archivable_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module BetterModel
+  module Generators
+    class ArchivableGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :with_tracking, type: :boolean, default: false,
+                   desc: "Add archived_by_id and archive_reason columns"
+      class_option :with_by, type: :boolean, default: false,
+                   desc: "Add archived_by_id column only"
+      class_option :with_reason, type: :boolean, default: false,
+                   desc: "Add archive_reason column only"
+      class_option :skip_indexes, type: :boolean, default: false,
+                   desc: "Skip adding indexes"
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def create_migration_file
+        migration_template "migration.rb.tt",
+                          "db/migrate/add_archivable_to_#{table_name}.rb"
+      end
+
+      private
+
+      def table_name
+        name.tableize
+      end
+
+      def migration_class_name
+        "AddArchivableTo#{name.camelize.pluralize}"
+      end
+
+      def with_by_column?
+        options[:with_tracking] || options[:with_by]
+      end
+
+      def with_reason_column?
+        options[:with_tracking] || options[:with_reason]
+      end
+
+      def add_indexes?
+        !options[:skip_indexes]
+      end
+    end
+  end
+end

data/lib/generators/better_model/archivable/templates/migration.rb.tt

@@ -0,0 +1,26 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    change_table :<%= table_name %> do |t|
+      # Required column for archivable
+      t.datetime :archived_at
+<% if with_by_column? -%>
+
+      # Optional: track who archived the record
+      t.integer :archived_by_id
+<% end -%>
+<% if with_reason_column? -%>
+
+      # Optional: track why the record was archived
+      t.string :archive_reason
+<% end -%>
+    end
+<% if add_indexes? -%>
+
+    # Indexes for performance
+    add_index :<%= table_name %>, :archived_at
+<% if with_by_column? -%>
+    add_index :<%= table_name %>, :archived_by_id
+<% end -%>
+<% end -%>
+  end
+end

data/lib/tasks/better_model_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :better_model do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: better_model
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- alessiobussolari
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: BetterModel is a Rails engine gem (Rails 8.1+) that provides powerful
+  extensions for ActiveRecord models including declarative status management and more.
+email:
+- alessio@cosmic.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/better_model.rb
+- lib/better_model/archivable.rb
+- lib/better_model/permissible.rb
+- lib/better_model/predicable.rb
+- lib/better_model/railtie.rb
+- lib/better_model/searchable.rb
+- lib/better_model/sortable.rb
+- lib/better_model/statusable.rb
+- lib/better_model/version.rb
+- lib/generators/better_model/archivable/archivable_generator.rb
+- lib/generators/better_model/archivable/templates/migration.rb.tt
+- lib/tasks/better_model_tasks.rake
+homepage: https://github.com/alessiobussolari/better_model
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/alessiobussolari/better_model
+  changelog_uri: https://github.com/alessiobussolari/better_model/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Rails engine gem that extends ActiveRecord model functionality
+test_files: []