stateful_models 0.0.1

data/spec/dummy/public/robots.txt

@@ -0,0 +1 @@
+# See https://www.robotstxt.org/robotstxt.html for documentation on how to use the robots.txt file

data/spec/dummy/tmp/local_secret.txt

@@ -0,0 +1 @@
+d932584e11af23c6015a503f0dfd79d657604b56d2be374b64c230b372e42872e55a7820b77cee6c02bef13a11870077718ebc0ffdf7efb450efb5cdf952cdc6

data/spec/factories/has_states.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# spec/factories/has_states.rb
+FactoryBot.define do
+  factory :state, class: 'HasStates::State' do
+    association :stateable, factory: :user
+    state_type { 'kyc' }
+    status { 'pending' }
+    metadata { {} }
+  end
+
+  factory :user do
+    sequence(:name) { |n| "User #{n}" }
+  end
+
+  factory :company do
+    sequence(:name) { |n| "Company #{n}" }
+  end
+end

data/spec/generators/has_states/install_generator_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require 'generators/has_states/install/install_generator'
+
+RSpec.describe HasStates::InstallGenerator do
+  let(:destination) { File.expand_path('../tmp', __dir__) }
+
+  before do
+    FileUtils.rm_rf(destination)
+    FileUtils.mkdir_p(destination)
+  end
+
+  it 'creates migration and initializer files' do
+    generator = described_class.new
+    generator.destination_root = destination
+    generator.install
+
+    # Check migration exists
+    migration = Dir[File.join(destination, 'db/migrate/*_create_has_states_states.rb')].first
+    expect(migration).to be_present
+
+    # Check initializer exists
+    initializer = File.join(destination, 'config/initializers/has_states.rb')
+    expect(File.exist?(initializer)).to be true
+  end
+end

data/spec/generators/tmp/config/initializers/has_states.rb

@@ -0,0 +1,42 @@
+ # frozen_string_literal: true
+
+HasStates.configure do |config|
+  # Configure your models and their state types below
+  #
+  # Example configuration:
+  #
+  # config.configure_model User do |model|
+  #   # KYC state type with its allowed statuses
+  #   model.state_type :kyc do |type|
+  #     type.statuses = [
+  #       'pending',              # Initial state
+  #       'documents_required',   # Waiting for user documents
+  #       'under_review',        # Documents being reviewed
+  #       'approved',            # KYC process completed successfully
+  #       'rejected'             # KYC process failed
+  #     ]
+  #   end
+  #
+  #   # Onboarding state type with different statuses
+  #   model.state_type :onboarding do |type|
+  #     type.statuses = [
+  #       'pending',          # Just started
+  #       'email_verified',   # Email verification complete
+  #       'profile_complete', # User filled all required fields
+  #       'completed'         # Onboarding finished
+  #     ]
+  #   end
+  # end
+  #
+  # config.configure_model Company do |model|
+  #   model.state_type :verification do |type|
+  #     type.statuses = [
+  #       'pending',
+  #       'documents_submitted',
+  #       'under_review',
+  #       'verified',
+  #       'rejected'
+  #     ]
+  #   end
+  # end
+end

data/spec/generators/tmp/db/migrate/20241223020432_create_has_states_states.rb

@@ -0,0 +1,17 @@
+ class CreateHasStatesStates < ActiveRecord::Migration[8.0]
+  def change
+    create_table :has_states_states do |t|
+      t.string :state_type
+      t.string :status, null: false
+
+      t.json :metadata, null: false, default: {}
+
+      t.references :stateable, polymorphic: true, null: false
+
+      t.datetime :completed_at
+      t.timestamps
+
+      t.index %i[stateable_type stateable_id]
+    end
+  end
+end

data/spec/has_states/callback_spec.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+# spec/has_states/callback_spec.rb
+RSpec.describe HasStates::Callback do
+  let(:state) { double('state', state_type: 'kyc', status: 'completed') }
+  let(:block) { ->(_s) { :called } }
+
+  describe '#matches?' do
+    context 'with state type only' do
+      let(:callback) { described_class.new('kyc', {}, block) }
+
+      it 'matches on state type' do
+        expect(callback.matches?(state)).to be true
+      end
+
+      it "doesn't match different state type" do
+        different_state = double('state', state_type: 'identity')
+        expect(callback.matches?(different_state)).to be false
+      end
+    end
+
+    context 'with status conditions' do
+      let(:callback) { described_class.new('kyc', { to: 'completed' }, block) }
+
+      it 'matches when conditions are met' do
+        expect(callback.matches?(state)).to be true
+      end
+
+      it "doesn't match when conditions aren't met" do
+        pending_state = double('state', state_type: 'kyc', status: 'pending')
+        expect(callback.matches?(pending_state)).to be false
+      end
+    end
+
+    context 'with from condition' do
+      let(:callback) { described_class.new('kyc', { from: 'pending' }, block) }
+      let(:state_with_history) do
+        double('state',
+               state_type: 'kyc',
+               status: 'completed',
+               status_before_last_save: 'pending')
+      end
+
+      it 'matches when previous status matches' do
+        expect(callback.matches?(state_with_history)).to be true
+      end
+    end
+  end
+
+  describe '#call' do
+    let(:callback) { described_class.new('kyc', {}, block) }
+
+    it 'executes the stored block with the state' do
+      expect(callback.call(state)).to eq(:called)
+    end
+  end
+
+  describe 'equality' do
+    let(:block1) { ->(_s) { :called } }
+    let(:block2) { ->(_s) { :called } }
+
+    it 'considers callbacks equal if they have the same state_type, conditions, and block' do
+      callback1 = described_class.new('kyc', { to: 'completed' }, block1)
+      callback2 = described_class.new('kyc', { to: 'completed' }, block1)
+
+      expect(callback1).to eq(callback2)
+    end
+
+    it 'considers callbacks different if they have different blocks' do
+      callback1 = described_class.new('kyc', { to: 'completed' }, block1)
+      callback2 = described_class.new('kyc', { to: 'completed' }, block2)
+
+      expect(callback1).not_to eq(callback2)
+    end
+
+    it 'considers callbacks different if they have different conditions' do
+      callback1 = described_class.new('kyc', { to: 'completed' }, block1)
+      callback2 = described_class.new('kyc', { to: 'pending' }, block1)
+
+      expect(callback1).not_to eq(callback2)
+    end
+
+    it 'considers callbacks different if they have different state types' do
+      callback1 = described_class.new('kyc', { to: 'completed' }, block1)
+      callback2 = described_class.new('identity', { to: 'completed' }, block1)
+
+      expect(callback1).not_to eq(callback2)
+    end
+  end
+end

data/spec/has_states/configuration_spec.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+# spec/has_states/configuration_spec.rb
+require 'rails_helper'
+
+RSpec.describe HasStates::Configuration do
+  let(:configuration) { described_class.instance }
+
+  before do
+    configuration.clear_callbacks!
+    configuration.model_configurations.clear
+  end
+
+  describe 'model configuration' do
+    it 'configures models with their state types and statuses' do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending completed]
+        end
+      end
+
+      expect(configuration.valid_status?(User, 'kyc', 'pending')).to be true
+      expect(configuration.valid_status?(User, 'kyc', 'invalid')).to be false
+    end
+
+    it 'allows different statuses for different state types' do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending verified]
+        end
+
+        model.state_type :onboarding do |type|
+          type.statuses = %w[started completed]
+        end
+      end
+
+      expect(configuration.valid_status?(User, 'kyc', 'verified')).to be true
+      expect(configuration.valid_status?(User, 'onboarding', 'verified')).to be false
+      expect(configuration.valid_status?(User, 'onboarding', 'completed')).to be true
+    end
+
+    it 'allows different configurations for different models' do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending verified]
+        end
+      end
+
+      configuration.configure_model Company do |model|
+        model.state_type :onboarding do |type|
+          type.statuses = %w[pending active]
+        end
+      end
+
+      expect(configuration.valid_state_type?(User, 'kyc')).to be true
+      expect(configuration.valid_state_type?(Company, 'kyc')).to be false
+      expect(configuration.valid_state_type?(Company, 'onboarding')).to be true
+    end
+
+    it 'automatically includes Stateable in configured models' do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = ['pending']
+        end
+      end
+
+      expect(User.included_modules).to include(HasStates::Stateable)
+    end
+
+    it 'raises error for non-ActiveRecord models' do
+      expect do
+        configuration.configure_model String do |model|
+          model.state_type :test
+        end
+      end.to raise_error(ArgumentError, /must be an ActiveRecord model/)
+    end
+  end
+
+  describe 'callbacks' do
+    let(:state_completed) { create(:state, state_type: 'kyc', status: 'completed') }
+
+    before do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending completed failed]
+        end
+      end
+
+      configuration.on(:kyc, id: :failed_callback, to: 'failed') { |_s| :kyc_failed }
+      configuration.on(:kyc, id: :pending_callback, to: 'pending') { |_s| :kyc_pending }
+      configuration.on(:kyc, id: :complete_callback, to: 'completed') { |_s| :kyc_completed }
+    end
+
+    describe '#on' do
+      it 'registers callbacks' do
+        expect(configuration.callbacks.size).to eq(3)
+      end
+
+      it 'matches callbacks for the right state' do
+        matching = configuration.matching_callbacks(state_completed)
+
+        expect(matching.length).to eq(1)
+      end
+
+      it 'registers callbacks with auto-generated ids' do
+        configuration.on(:kyc) { |_s| :some_action }
+        expect(configuration.callbacks.keys.last).to match(/\Acallback_\d+\z/)
+      end
+
+      it 'registers callbacks with custom ids' do
+        configuration.on(:kyc, id: :my_custom_callback) { |_s| :some_action }
+        expect(configuration.callbacks.keys).to include(:my_custom_callback)
+      end
+
+      it 'converts string ids to symbols' do
+        configuration.on(:kyc, id: 'my_string_id') { |_s| :some_action }
+        expect(configuration.callbacks.keys).to include(:my_string_id)
+      end
+    end
+
+    describe '#off' do
+      it 'removes a callback by id' do
+        configuration.on(:kyc, id: :removable) { |_s| :some_action }
+        expect { configuration.off(:removable) }
+          .to change { configuration.callbacks.size }.by(-1)
+      end
+
+      it 'removes a callback by callback object' do
+        callback = configuration.on(:kyc) { |_s| :some_action }
+        expect { configuration.off(callback) }
+          .to change { configuration.callbacks.size }.by(-1)
+      end
+
+      it 'properly removes callback when given a callback object' do
+        callback = configuration.on(:kyc, id: :test) { |_s| :some_action }
+        expect(configuration.callbacks.values).to include(callback)
+
+        configuration.off(callback)
+        expect(configuration.callbacks.values).not_to include(callback)
+      end
+    end
+
+    describe '#clear_callbacks!' do
+      it 'removes all callbacks' do
+        expect { configuration.clear_callbacks! }.to change { configuration.callbacks.size }.to(0)
+      end
+    end
+
+    describe '#matching_callbacks' do
+      it 'finds callbacks matching state type and conditions regardless of id' do
+        configuration.clear_callbacks!
+        configuration.on(:kyc, id: :complete_callback, to: 'completed') { |_s| :kyc_completed }
+
+        matching = configuration.matching_callbacks(state_completed)
+
+        expect(matching.size).to eq(1)
+        expect(matching.first.call(state_completed)).to eq(:kyc_completed)
+      end
+    end
+  end
+end

data/spec/has_states/state_spec.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe HasStates::State, type: :model do
+  subject { build(:state) }
+
+  before do
+    HasStates.configuration.clear_callbacks!
+    HasStates.configuration.model_configurations.clear
+
+    HasStates.configure do |config|
+      config.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending completed]
+        end
+
+        model.state_type :onboarding do |type|
+          type.statuses = %w[pending completed]
+        end
+      end
+    end
+  end
+
+  describe 'validations' do
+    context 'status' do
+      it 'validates status presence' do
+        expect(subject).not_to allow_value(nil).for(:status)
+      end
+
+      it 'validates status is configured' do
+        expect(subject).to allow_value('pending').for(:status)
+      end
+
+      it 'validates status that is not configured' do
+        expect(subject).not_to allow_value('invalid').for(:status)
+      end
+    end
+
+    context 'state_type' do
+      it 'validates state_type presence' do
+        expect(subject).not_to allow_value(nil).for(:state_type)
+      end
+
+      it 'validates state_type is configured' do
+        expect(subject).to allow_value('kyc').for(:state_type)
+      end
+
+      it 'validates state_type that is not configured' do
+        expect(subject).not_to allow_value('invalid').for(:state_type)
+      end
+    end
+  end
+
+  describe 'scopes' do
+    let(:state) { create(:state, state_type: 'kyc') }
+
+    it 'defines a scope for each state type' do
+      expect(described_class.kyc).to eq([state])
+    end
+  end
+
+  describe 'instance methods' do
+    let(:state) { create(:state, state_type: 'kyc', status: 'pending') }
+    let(:model_config) { HasStates.configuration.model_configurations[User] }
+    let(:all_statuses) do
+      model_config.state_types.values.flat_map(&:statuses).uniq
+    end
+
+    it 'defines predicate methods for all configured statuses' do
+      all_statuses.each do |status|
+        expect(state).to respond_to("#{status}?")
+      end
+    end
+
+    it 'returns true if the status is pending' do
+      expect(state.pending?).to be(true)
+    end
+
+    it 'returns false if the status is not completed' do
+      expect(state.completed?).to be(false)
+    end
+  end
+
+  describe 'metadata' do
+    let(:user) { FactoryBot.create(:user) }
+
+    it 'stores and retrieves simple metadata' do
+      state = user.add_state('kyc', metadata: { reason: 'documents_missing' })
+      expect(state.metadata['reason']).to eq('documents_missing')
+    end
+
+    it 'stores and retrieves nested metadata' do
+      metadata = {
+        documents: {
+          passport: { status: 'rejected', reason: 'expired' },
+          utility_bill: { status: 'pending' }
+        }
+      }
+
+      state = user.add_state('kyc', metadata: metadata)
+      expect(state.metadata['documents']['passport']['reason']).to eq('expired')
+    end
+
+    it 'handles arrays in metadata' do
+      metadata = {
+        missing_documents: %w[passport utility_bill],
+        review_history: [
+          { date: '2024-01-01', status: 'rejected' },
+          { date: '2024-01-02', status: 'approved' }
+        ]
+      }
+
+      state = user.add_state('kyc', metadata: metadata)
+      expect(state.metadata['missing_documents']).to eq(%w[passport utility_bill])
+      expect(state.metadata['review_history'].size).to eq(2)
+    end
+
+    it 'handles different data types' do
+      metadata = {
+        string_value: 'test',
+        integer_value: 42,
+        float_value: 42.5,
+        boolean_value: true,
+        null_value: nil,
+        date_value: '2024-01-01'
+      }
+
+      state = user.add_state('kyc', metadata: metadata)
+      expect(state.metadata['string_value']).to eq('test')
+      expect(state.metadata['integer_value']).to eq(42)
+      expect(state.metadata['float_value']).to eq(42.5)
+      expect(state.metadata['boolean_value']).to be true
+      expect(state.metadata['null_value']).to be_nil
+      expect(state.metadata['date_value']).to eq('2024-01-01')
+    end
+
+    it 'defaults to empty hash when no metadata provided' do
+      state = user.add_state('kyc')
+      expect(state.metadata).to eq({})
+    end
+
+    it 'persists metadata across database reads' do
+      state = user.add_state('kyc', metadata: { key: 'value' })
+      reloaded_state = HasStates::State.find(state.id)
+      expect(reloaded_state.metadata['key']).to eq('value')
+    end
+  end
+
+  describe 'callbacks' do
+    let(:user) { create(:user) }
+    let(:callback_executed) { false }
+
+    before do
+      HasStates.configure do |config|
+        config.configure_model User do |model|
+          model.state_type :onboarding do |type|
+            type.statuses = %w[pending completed]
+          end
+        end
+
+        # Register a callback for when onboarding is completed
+        config.on(:onboarding, id: :complete_onboarding, to: 'completed') do |state|
+          state.stateable.update!(name: 'Onboarded User')
+        end
+      end
+    end
+
+    it 'executes callback when state changes to completed' do
+      # Create initial pending state
+      state = user.add_state('onboarding', status: 'pending')
+      expect(user.name).not_to eq('Onboarded User')
+
+      # Update to completed
+      state.update!(status: 'completed')
+
+      # Verify callback was executed
+      expect(user.reload.name).to eq('Onboarded User')
+    end
+
+    it 'does not execute callback for other status changes' do
+      state = user.add_state('onboarding', status: 'completed')
+      user.update!(name: 'Original Name')
+
+      # Update to pending
+      state.update!(status: 'pending')
+
+      # Verify callback was not executed
+      expect(user.reload.name).to eq('Original Name')
+    end
+  end
+
+  describe 'limited execution callbacks' do
+    let(:user) { create(:user) }
+
+    before do
+      # Clear ALL configuration
+      HasStates.configuration.clear_callbacks!
+      HasStates.configuration.model_configurations.clear
+
+      # Set up fresh configuration
+      HasStates.configure do |config|
+        config.configure_model User do |model|
+          model.state_type :onboarding do |type|
+            type.statuses = %w[pending completed]
+          end
+        end
+      end
+
+      @execution_count = 0
+    end
+
+    it 'executes callback only specified number of times' do
+      HasStates.configure do |config|
+        config.on(:onboarding, id: :counter, to: 'completed', times: 2) do |state|
+          state.stateable.update!(name: "Execution #{@execution_count += 1}")
+        end
+      end
+
+      # First execution
+      state1 = user.add_state('onboarding', status: 'pending')
+      state1.update!(status: 'completed')
+      expect(user.reload.name).to eq('Execution 1')
+
+      # Second execution
+      state2 = user.add_state('onboarding', status: 'pending')
+      state2.update!(status: 'completed')
+      expect(user.reload.name).to eq('Execution 2')
+
+      # Third execution - callback should be expired
+      user.update!(name: 'Final Name')
+      state3 = user.add_state('onboarding', status: 'pending')
+      state3.update!(status: 'completed')
+      expect(user.reload.name).to eq('Final Name') # Name shouldn't change
+    end
+
+    it 'keeps callback active indefinitely when times is not specified' do
+      HasStates.configure do |config|
+        config.on(:onboarding, id: :infinite, to: 'completed') do |state|
+          state.stateable.update!(name: "Execution #{@execution_count += 1}")
+        end
+      end
+
+      3.times do |i|
+        state = user.add_state('onboarding', status: 'pending')
+        state.update!(status: 'completed')
+        expect(user.reload.name).to eq("Execution #{i + 1}")
+      end
+    end
+
+    it 'removes expired callbacks from configuration' do
+      HasStates.configure do |config|
+        config.on(:onboarding, id: :one_time, to: 'completed', times: 1) do |state|
+          state.stateable.update!(name: 'Executed')
+        end
+      end
+
+      expect do
+        state = user.add_state('onboarding', status: 'pending')
+        state.update!(status: 'completed')
+      end.to change { HasStates.configuration.callbacks.size }.from(1).to(0)
+    end
+  end
+end

data/spec/has_states_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+RSpec.describe HasStates do
+  it 'has a version number' do
+    expect(HasStates::VERSION).not_to be_nil
+  end
+
+  it 'has a configuration' do
+    expect(described_class.configuration).to be_a(HasStates::Configuration)
+  end
+
+  describe 'configuration' do
+    before do
+      described_class.configure do |config|
+        # User configuration
+        config.configure_model User do |model|
+          model.state_type :kyc do |type|
+            type.statuses = %w[pending completed]
+          end
+
+          model.state_type :onboarding do |type|
+            type.statuses = %w[started finished]
+          end
+        end
+
+        # Company configuration
+        config.configure_model Company do |model|
+          model.state_type :procurement do |type|
+            type.statuses = %w[in_progress completed failed]
+          end
+        end
+      end
+    end
+
+    it 'configures the state types for User' do
+      expect(described_class.configuration.state_types_for(User).keys).to eq(%w[kyc onboarding])
+    end
+
+    it 'configures the statuses for User' do
+      expect(described_class.configuration.statuses_for(User, 'kyc')).to eq(%w[pending completed])
+      expect(described_class.configuration.statuses_for(User, 'onboarding')).to eq(%w[started finished])
+    end
+
+    it 'configures the state types for Company' do
+      expect(described_class.configuration.state_types_for(Company).keys).to eq(['procurement'])
+    end
+
+    it 'configures the statuses for Company' do
+      expect(described_class.configuration.statuses_for(Company, 'procurement')).to eq(%w[in_progress completed failed])
+    end
+  end
+end