meta_states 0.1.0

data/spec/meta_states/state_spec.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe MetaStates::State, type: :model do
+  subject { build(:state) }
+
+  before do
+    MetaStates.configuration.clear_callbacks!
+    MetaStates.configuration.model_configurations.clear
+
+    MetaStates.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 'indexes' do
+    it 'defines an index on stateable_type and stateable_id' do
+      expect(subject).to have_db_index(%i[stateable_type stateable_id])
+    end
+
+    it 'defines an index on stateable_id and state_type' do
+      expect(subject).to have_db_index(%i[stateable_id state_type])
+    end
+
+    it 'defines an index on stateable_id, state_type, and status' do
+      expect(subject).to have_db_index(%i[stateable_id state_type status])
+    end
+
+    it 'defines an index on stateable_id, state_type, and created_at' do
+      expect(subject).to have_db_index(%i[stateable_id state_type created_at])
+    end
+
+    it 'defines an index on stateable_id, state_type, status, and created_at' do
+      expect(subject).to have_db_index(%i[stateable_id state_type status created_at])
+    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) { MetaStates.configuration.model_configurations[User] }
+    let(:all_statuses) { model_config.state_types.values.flat_map(&:statuses).uniq }
+
+    context 'predicate methods' do
+      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
+  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 = MetaStates::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
+      MetaStates.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
+      MetaStates.configuration.clear_callbacks!
+      MetaStates.configuration.model_configurations.clear
+
+      # Set up fresh configuration
+      MetaStates.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
+      MetaStates.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
+      MetaStates.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
+      MetaStates.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 { MetaStates.configuration.callbacks.size }.from(1).to(0)
+    end
+  end
+
+  describe 'custom state types' do
+    # Create a custom state class for testing
+    class KYCState < MetaStates::Base
+      validates :metadata, presence: true
+      validate :required_metadata_fields
+
+      private
+
+      def required_metadata_fields
+        return if metadata&.key?('document_type')
+
+        errors.add(:metadata, 'must include document_type')
+      end
+    end
+
+    let(:user) { create(:user) }
+
+    it 'allows creation of custom state types' do
+      state = user.add_state(
+        'kyc',
+        status: 'pending',
+        metadata: { document_type: 'passport' },
+        state_class: KYCState
+      )
+
+      expect(state).to be_valid
+      expect(state).to be_a(KYCState)
+    end
+
+    it 'enforces custom validations' do
+      expect do
+        user.add_state(
+          'kyc',
+          status: 'pending',
+          metadata: { other_field: 'value' },
+          state_class: KYCState
+        )
+      end.to raise_error(
+        ActiveRecord::RecordInvalid,
+        /Metadata must include document_type/
+      )
+    end
+
+    it 'defaults to MetaStates::State when no state_class specified' do
+      state = user.add_state('kyc', status: 'pending')
+
+      expect(state).to be_a(MetaStates::State)
+      expect(state).to be_valid
+    end
+
+    it 'maintains STI type across database reads' do
+      state = user.add_state(
+        'kyc',
+        status: 'pending',
+        metadata: { document_type: 'passport' },
+        state_class: KYCState
+      )
+
+      reloaded_state = MetaStates::Base.find(state.id)
+      expect(reloaded_state).to be_a(KYCState)
+    end
+  end
+end

data/spec/meta_states/stateable_spec.rb

@@ -0,0 +1,183 @@
+require 'rails_helper'
+
+RSpec.describe MetaStates::Stateable do
+  # Create a test class that includes the concern
+  let(:test_class) do
+    Class.new do
+      include MetaStates::Stateable
+      include ActiveRecord::Model
+    end
+  end
+
+  let(:user) { create(:user) } # Assuming you have a User factory
+
+  before do
+    # MetaStates.configuration.clear_callbacks!
+    # MetaStates.configuration.model_configurations.clear
+
+    MetaStates.configure do |config|
+      config.configure_model User do |model|
+        model.state_type :test_type do |type|
+          type.statuses = %w[pending completed]
+        end
+
+        model.state_type :other_test_type do |type|
+          type.statuses = %w[pending completed]
+        end
+      end
+    end
+  end
+
+  describe 'associations' do
+    it 'has many states' do
+      association = User.reflect_on_association(:states)
+
+      expect(association.macro).to eq :has_many
+      expect(association.options[:as]).to eq :stateable
+      expect(association.options[:dependent]).to eq :destroy
+      expect(association.options[:class_name]).to eq 'MetaStates::Base'
+    end
+  end
+
+  describe '#add_state' do
+    context 'with default parameters' do
+      it 'creates a new state with default values' do
+        state = user.add_state('test_type')
+
+        expect(state).to be_persisted
+        expect(state.metadata).to eq({})
+        expect(state.status).to eq 'pending'
+        expect(state.state_type).to eq 'test_type'
+        expect(state.type).to eq 'MetaStates::State'
+      end
+    end
+
+    context 'with custom parameters' do
+      let(:metadata) { { key: 'value' } }
+
+      it 'creates a new state with provided values' do
+        state = user.add_state('test_type', status: 'completed', metadata: metadata)
+
+        expect(state).to be_persisted
+        expect(state.status).to eq 'completed'
+        expect(state.state_type).to eq 'test_type'
+        expect(state.type).to eq 'MetaStates::State'
+        expect(state.metadata).to eq metadata.as_json
+      end
+    end
+
+    context 'with custom state class' do
+      before(:all) do
+        module MetaStates
+          class CustomState < State; end
+        end
+      end
+
+      after(:all) do
+        MetaStates.send(:remove_const, :CustomState)
+      end
+
+      it 'creates a new state with the specified class' do
+        state = user.add_state('test_type', state_class: MetaStates::CustomState)
+
+        expect(state).to be_persisted
+        expect(state.type).to eq 'MetaStates::CustomState'
+      end
+    end
+
+    context 'when validation fails' do
+      before do
+        allow_any_instance_of(MetaStates::Base).to receive(:save!).and_raise(ActiveRecord::RecordInvalid)
+      end
+
+      it 'raises an ActiveRecord::RecordInvalid error' do
+        expect { user.add_state('test_type') }.to raise_error(ActiveRecord::RecordInvalid)
+      end
+    end
+  end
+
+  describe '#current_state' do
+    let!(:latest_state) { user.add_state('test_type', status: 'completed') }
+
+    before do
+      travel_to 1.day.ago do
+        3.times { user.add_state('test_type', status: 'pending') }
+        2.times { user.add_state('other_test_type', status: 'pending') }
+      end
+    end
+
+    it 'returns the most recent state for the given type' do
+      expect(user.current_state('test_type')).to eq latest_state
+    end
+
+    it 'returns nil when no state exists for the given type' do
+      expect(user.current_state('nonexistent')).to be_nil
+    end
+  end
+
+  describe '#current_states' do
+    before do
+      3.times { user.add_state('test_type', status: 'pending') }
+      3.times { user.add_state('other_test_type', status: 'completed') }
+    end
+
+    it 'returns all states for the given type ordered by creation time' do
+      test_types = user.current_states('test_type')
+
+      expect(test_types.size).to eq 3
+      expect(test_types).to eq test_types.sort_by(&:created_at).reverse
+    end
+
+    it 'returns empty relation when no states exist for the given type' do
+      nonexistent_states = user.current_states('nonexistent')
+      expect(nonexistent_states).to be_empty
+      expect(nonexistent_states).to be_a(ActiveRecord::Relation)
+    end
+  end
+
+  describe 'query methods' do
+    before do
+      2.times { user.add_state('test_type', status: 'pending') }
+      2.times { user.add_state('other_test_type', status: 'pending') }
+    end
+
+    context 'find one methods' do
+      it 'defines query one methods for configured states' do
+        expect(user).to respond_to('test_type')
+        expect(user).to respond_to('other_test_type')
+      end
+
+      it 'returns the most recent state for the given status' do
+        expect(user.test_type).to eq user.current_state('test_type')
+        expect(user.other_test_type).to eq user.current_state('other_test_type')
+      end
+    end
+
+    context 'find many methods' do
+      it 'defines query all methods for configured states' do
+        expect(user).to respond_to('test_types')
+        expect(user).to respond_to('other_test_types')
+      end
+
+      it 'returns all states for the given status ordered by creation time' do
+        test_types = user.test_types
+        other_test_types = user.other_test_types
+
+        expect(test_types.size).to eq 2
+        expect(other_test_types.size).to eq 2
+
+        expect(test_types).to eq test_types.sort_by(&:created_at).reverse
+        expect(other_test_types).to eq other_test_types.sort_by(&:created_at).reverse
+      end
+    end
+  end
+
+  # Optional: Test the destruction of associated states
+  describe 'destroying the stateable object' do
+    let!(:state) { user.add_state('test_type') }
+
+    it 'destroys associated states when the user is destroyed' do
+      expect { user.destroy }.to change { MetaStates::Base.count }.by(-1)
+    end
+  end
+end

data/spec/meta_states_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+RSpec.describe MetaStates do
+  it 'has a version number' do
+    expect(MetaStates::VERSION).not_to be_nil
+  end
+
+  it 'has a configuration' do
+    expect(described_class.configuration).to be_a(MetaStates::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

data/spec/rails_helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# Load dummy Rails app if in Rails context
+ENV['RAILS_ENV'] = 'test'
+require File.expand_path('dummy/config/environment.rb', __dir__)
+
+# Load support files
+require_relative 'support/factory_bot'
+require_relative 'support/shoulda_matchers'
+require_relative 'support/database_cleaner'
+
+RSpec.configure do |config|
+  config.include(Shoulda::Matchers::ActiveModel, type: :model)
+  config.include(Shoulda::Matchers::ActiveRecord, type: :model)
+  config.include(ActiveSupport::Testing::TimeHelpers)
+  # ... rest of your RSpec configuration
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'meta_states'
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = '.rspec_status'
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/spec/support/database_cleaner.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'database_cleaner/active_record'
+
+RSpec.configure do |config|
+  # Database Cleaner setup
+  config.before(:suite) do
+    DatabaseCleaner.strategy = :transaction
+    DatabaseCleaner.clean_with(:truncation)
+  end
+
+  config.around do |example|
+    DatabaseCleaner.cleaning do
+      example.run
+    end
+  end
+end

data/spec/support/factory_bot.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'factory_bot'
+require_relative '../factories/meta_states'
+
+RSpec.configure do |config|
+  config.include FactoryBot::Syntax::Methods
+end

data/spec/support/shoulda_matchers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'shoulda-matchers'
+
+Shoulda::Matchers.configure do |config|
+  config.integrate do |with|
+    with.test_framework :rspec
+    with.library :rails
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+MetaStates.configure do |config|
+  # Configure your models here
+  # Example:
+  #
+  # config.configure_model User do |model|
+  #   model.state_type :kyc do |type|
+  #     type.statuses = ['pending', 'completed', 'rejected']
+  #   end
+  # end
+end

data/spec/tmp/db/migrate/20241223004024_create_has_states_states.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateMetaStatesStates < ActiveRecord::Migration[8.0]
+  def change
+    create_table :meta_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 [:status]
+      t.index %i[stateable_type stateable_id]
+    end
+  end
+end