better_model 1.0.0 → 1.1.0

data/lib/generators/better_model/stateable/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module BetterModel
+  module Generators
+    module Stateable
+      # Generator per creare la tabella state_transitions
+      #
+      # Usage:
+      #   rails generate better_model:stateable:install
+      #   rails generate better_model:stateable:install --table-name=order_transitions
+      #
+      class InstallGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        class_option :table_name, type: :string, default: "state_transitions",
+                                  desc: "Custom table name for state transitions (default: state_transitions)"
+
+        desc "Creates the state_transitions table for Stateable history tracking"
+
+        def create_migration_file
+          migration_template "install_migration.rb.tt", "db/migrate/create_#{transitions_table_name}.rb"
+        end
+
+        private
+
+        def transitions_table_name
+          options[:table_name]
+        end
+      end
+    end
+  end
+end

data/lib/generators/better_model/stateable/stateable_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module BetterModel
+  module Generators
+    # Generator per aggiungere Stateable a un modello esistente
+    #
+    # Usage:
+    #   rails generate better_model:stateable MODEL_NAME [options]
+    #
+    # Examples:
+    #   rails generate better_model:stateable Order
+    #   rails generate better_model:stateable Article --initial-state=draft
+    #
+    class StateableGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :initial_state, type: :string, default: nil,
+                                   desc: "Initial state name (default: first state defined)"
+
+      desc "Adds Stateable support to an existing model by adding a 'state' column"
+
+      def create_migration_file
+        migration_template "migration.rb.tt", "db/migrate/add_stateable_to_#{table_name}.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def table_name
+        name.tableize
+      end
+
+      def model_name
+        name.camelize
+      end
+
+      def initial_state_value
+        options[:initial_state] || "pending"
+      end
+    end
+  end
+end

data/lib/generators/better_model/stateable/templates/README

@@ -0,0 +1,38 @@
+===============================================================================
+
+Stateable column has been added to your model!
+
+Next steps:
+
+1. Run the migration:
+   $ bin/rails db:migrate
+
+2. Add Stateable configuration to your model:
+
+   class <%= model_name %> < ApplicationRecord
+     include BetterModel
+
+     stateable do
+       # Define states
+       state :<%= initial_state_value %>, initial: true
+       state :confirmed
+       state :completed
+
+       # Define transitions
+       transition :confirm, from: :<%= initial_state_value %>, to: :confirmed do
+         guard { valid? }
+         before { prepare_confirmation }
+         after { send_notification }
+       end
+
+       transition :complete, from: :confirmed, to: :completed
+     end
+   end
+
+3. Don't forget to create the state_transitions table (once per app):
+   $ bin/rails generate better_model:stateable:install
+   $ bin/rails db:migrate
+
+For more information, see: docs/stateable.md
+
+===============================================================================

data/lib/generators/better_model/stateable/templates/install_migration.rb.tt

@@ -0,0 +1,20 @@
+class Create<%= transitions_table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= transitions_table_name %> do |t|
+      t.string :transitionable_type, null: false
+      t.integer :transitionable_id, null: false
+      t.string :event, null: false
+      t.string :from_state, null: false
+      t.string :to_state, null: false
+      t.json :metadata
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :<%= transitions_table_name %>, [:transitionable_type, :transitionable_id], name: "index_<%= transitions_table_name %>_on_transitionable"
+    add_index :<%= transitions_table_name %>, :event
+    add_index :<%= transitions_table_name %>, :from_state
+    add_index :<%= transitions_table_name %>, :to_state
+    add_index :<%= transitions_table_name %>, :created_at
+  end
+end

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

@@ -0,0 +1,9 @@
+class AddStateableTo<%= table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    change_table :<%= table_name %> do |t|
+      t.string :state, null: false, default: "<%= initial_state_value %>"
+    end
+
+    add_index :<%= table_name %>, :state
+  end
+end

data/lib/generators/better_model/traceable/templates/create_table_migration.rb.tt

@@ -0,0 +1,28 @@
+class Create<%= versions_table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= versions_table_name %> do |t|
+      # Polymorphic association to tracked models
+      t.string :item_type, null: false
+      t.integer :item_id, null: false
+
+      # Event type: created, updated, destroyed
+      t.string :event, null: false
+
+      # Changes stored as JSON (before/after values)
+      # SQLite uses json, PostgreSQL can use jsonb
+      t.json :object_changes
+
+      # Optional tracking fields
+      t.integer :updated_by_id
+      t.string :updated_reason
+
+      t.datetime :created_at, null: false
+    end
+
+    # Indexes for performance
+    add_index :<%= versions_table_name %>, [ :item_type, :item_id ], name: "index_<%= versions_table_name %>_on_item"
+    add_index :<%= versions_table_name %>, :created_at
+    add_index :<%= versions_table_name %>, :updated_by_id
+    add_index :<%= versions_table_name %>, :event
+  end
+end

data/lib/generators/better_model/traceable/traceable_generator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module BetterModel
+  module Generators
+    class TraceableGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name, type: :string, default: "model", desc: "Model name (optional, used for default table name)"
+
+      class_option :create_table, type: :boolean, default: false,
+                   desc: "Create the versions table (only needed once per table)"
+
+      class_option :table_name, type: :string, default: nil,
+                   desc: "Custom table name for versions (default: {model}_versions)"
+
+      def create_migration_file
+        if options[:create_table]
+          template "create_table_migration.rb.tt",
+                   "db/migrate/#{timestamp}_create_#{versions_table_name}.rb"
+
+          say "Created migration for '#{versions_table_name}' table", :green
+          say "Run 'rails db:migrate' to create the table", :green
+        else
+          say "Traceable will use the '#{versions_table_name}' table", :yellow
+          say "If the table doesn't exist yet, run:", :yellow
+          say "  rails g better_model:traceable #{name} --create-table#{table_name_option_hint}", :green
+          say "  rails db:migrate", :green
+        end
+      end
+
+      def show_usage_instructions
+        say "\nTo enable Traceable in your model:", :yellow
+        say "  class #{class_name} < ApplicationRecord", :white
+        say "    include BetterModel", :white
+        say "    ", :white
+        say "    traceable do", :white
+        say "      track :field1, :field2, :field3", :white
+        if custom_table_name?
+          say "      table_name '#{versions_table_name}'", :white
+        else
+          say "      # table_name '#{versions_table_name}' (default)", :white
+        end
+        say "    end", :white
+        say "  end", :white
+        say "\nSee documentation for more options and usage examples", :yellow
+      end
+
+      private
+
+      def timestamp
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def class_name
+        name.camelize
+      end
+
+      def model_name
+        name.underscore
+      end
+
+      def versions_table_name
+        @versions_table_name ||= options[:table_name] || "#{model_name}_versions"
+      end
+
+      def custom_table_name?
+        options[:table_name].present?
+      end
+
+      def table_name_option_hint
+        custom_table_name? ? " --table-name=#{versions_table_name}" : ""
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_model
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-29 00:00:00.000000000 Z
+date: 2025-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -33,7 +33,7 @@ dependencies:
 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
+- alessio.bussolari@pandev.it
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -48,10 +48,29 @@ files:
 - lib/better_model/railtie.rb
 - lib/better_model/searchable.rb
 - lib/better_model/sortable.rb
+- lib/better_model/state_transition.rb
+- lib/better_model/stateable.rb
+- lib/better_model/stateable/configurator.rb
+- lib/better_model/stateable/errors.rb
+- lib/better_model/stateable/guard.rb
+- lib/better_model/stateable/transition.rb
 - lib/better_model/statusable.rb
+- lib/better_model/traceable.rb
+- lib/better_model/validatable.rb
+- lib/better_model/validatable/business_rule_validator.rb
+- lib/better_model/validatable/configurator.rb
+- lib/better_model/validatable/order_validator.rb
 - lib/better_model/version.rb
+- lib/better_model/version_record.rb
 - lib/generators/better_model/archivable/archivable_generator.rb
 - lib/generators/better_model/archivable/templates/migration.rb.tt
+- lib/generators/better_model/stateable/install_generator.rb
+- lib/generators/better_model/stateable/stateable_generator.rb
+- lib/generators/better_model/stateable/templates/README
+- lib/generators/better_model/stateable/templates/install_migration.rb.tt
+- lib/generators/better_model/stateable/templates/migration.rb.tt
+- lib/generators/better_model/traceable/templates/create_table_migration.rb.tt
+- lib/generators/better_model/traceable/traceable_generator.rb
 - lib/tasks/better_model_tasks.rake
 homepage: https://github.com/alessiobussolari/better_model
 licenses: