meta_states 0.1.0

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/meta_states.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# spec/factories/meta_states.rb
+FactoryBot.define do
+  factory :state, class: 'MetaStates::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/meta_states/install_generator_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require 'generators/meta_states/install/install_generator'
+
+RSpec.describe MetaStates::InstallGenerator do
+  let(:destination) { File.expand_path('../templates', __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_meta_states_states.rb')].first
+    expect(migration).to be_present
+
+    # Check initializer exists
+    initializer = File.join(destination, 'config/initializers/meta_states.rb')
+    expect(File.exist?(initializer)).to be true
+  end
+end

data/spec/generators/templates/config/initializers/meta_states.rb

@@ -0,0 +1,42 @@
+ # frozen_string_literal: true
+
+MetaStates.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/templates/db/migrate/20250605170637_create_indexes_on_meta_states_states.rb

@@ -0,0 +1,11 @@
+class CreateIndexesOnMetaStatesStates < ActiveRecord::Migration[8.0]
+  def change
+    change_table :meta_states_states do |t|
+      t.index %i[stateable_id state_type]
+      t.index %i[stateable_id state_type status]
+      t.index %i[stateable_id state_type created_at]    
+      t.index %i[stateable_id state_type status created_at] 
+      t.index %i[stateable_type stateable_id]
+    end
+  end
+end

data/spec/generators/templates/db/migrate/20250605170637_create_meta_states_states.rb

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

data/spec/meta_states/callback_spec.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+# spec/meta_states/callback_spec.rb
+RSpec.describe MetaStates::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/meta_states/configuration_spec.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+# spec/meta_states/configuration_spec.rb
+require 'rails_helper'
+
+RSpec.describe MetaStates::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(MetaStates::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
+
+    it 'allows setting a limit on the number of states' do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending completed]
+          type.limit = 2
+        end
+      end
+
+      expect(configuration.limit_for(User, 'kyc')).to eq(2)
+    end
+
+    it 'returns nil for limit when no limit is set' do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending completed]
+        end
+      end
+
+      expect(configuration.limit_for(User, 'kyc')).to be_nil
+    end
+
+    context 'when a metadata schema is set' do
+      let(:schema) do
+        {
+          type: :object,
+          properties: {
+            name: { type: :string },
+            age: { type: :integer, minimum: 18 }
+          },
+          required: %i[name age]
+        }
+      end
+
+      before do
+        configuration.configure_model User do |model|
+          model.state_type :kyc do |type|
+            type.statuses = %w[pending completed]
+            type.metadata_schema = schema
+          end
+        end
+      end
+
+      it 'allows setting a metadata schema for validation' do
+        expect(configuration.metadata_schema_for(User, 'kyc')).to eq(schema)
+      end
+    end
+
+    it 'returns nil for metadata_schema when no schema is set' do
+      configuration.configure_model User do |model|
+        model.state_type :kyc do |type|
+          type.statuses = %w[pending completed]
+        end
+      end
+
+      expect(configuration.metadata_schema_for(User, 'kyc')).to be_nil
+    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/meta_states/state_limit_spec.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe 'State Limit Feature', type: :model do
+  before do
+    MetaStates.configuration.clear_callbacks!
+    MetaStates.configuration.model_configurations.clear
+
+    MetaStates.configure do |config|
+      config.configure_model User do |model|
+        model.state_type :double_limit_state do |type|
+          type.statuses = %w[pending completed]
+          type.limit = 2
+        end
+
+        model.state_type :no_limit_state do |type|
+          type.statuses = %w[pending completed]
+          # No limit set for this type
+        end
+
+        model.state_type :single_limit_state do |type|
+          type.statuses = %w[pending completed]
+          type.limit = 1
+        end
+      end
+    end
+  end
+
+  describe 'state limit validation' do
+    let(:user) { create(:user) }
+
+    context 'with no limit set' do
+      it 'allows creating multiple states of the same type' do
+        # Create multiple onboarding states (no limit)
+        expect do
+          3.times { user.add_state('no_limit_state', status: 'pending') }
+        end.not_to raise_error
+
+        expect(user.states.where(state_type: 'no_limit_state').count).to eq(3)
+      end
+    end
+
+    context 'with a limit set' do
+      it 'allows creating states up to the limit' do
+        # Create double_limit_state states up to the limit (2)
+        expect do
+          2.times { user.add_state('double_limit_state', status: 'pending') }
+        end.not_to raise_error
+
+        expect(user.states.where(state_type: 'double_limit_state').count).to eq(2)
+      end
+
+      it 'prevents creating states beyond the limit' do
+        # Create double_limit_state states up to the limit
+        2.times { user.add_state('double_limit_state', status: 'pending') }
+
+        # Try to create one more (exceeding the limit)
+        expect do
+          user.add_state('double_limit_state', status: 'pending')
+        end.to raise_error(ActiveRecord::RecordInvalid, /maximum number of double_limit_state states/)
+      end
+
+      it 'enforces a limit of 1 correctly' do
+        # Create one state
+        user.add_state('single_limit_state', status: 'pending')
+
+        # Try to create another one (exceeding the limit of 1)
+        expect do
+          user.add_state('single_limit_state', status: 'completed')
+        end.to raise_error(ActiveRecord::RecordInvalid, /maximum number of single_limit_state states/)
+      end
+    end
+
+    context 'with different state types' do
+      it 'applies limits independently to each state type' do
+        # Create states up to the limit for double_limit_state
+        2.times { user.add_state('double_limit_state', status: 'pending') }
+
+        # Create states for no_limit_state (no limit)
+        3.times { user.add_state('no_limit_state', status: 'pending') }
+
+        # Create one state for single_limit_state (limit 1)
+        user.add_state('single_limit_state', status: 'pending')
+
+        # Verify counts
+        expect(user.states.where(state_type: 'double_limit_state').count).to eq(2)
+        expect(user.states.where(state_type: 'no_limit_state').count).to eq(3)
+        expect(user.states.where(state_type: 'single_limit_state').count).to eq(1)
+
+        # Try to exceed limits
+        expect do
+          user.add_state('double_limit_state', status: 'completed')
+        end.to raise_error(ActiveRecord::RecordInvalid, /maximum number of double_limit_state states/)
+
+        expect do
+          user.add_state('single_limit_state', status: 'completed')
+        end.to raise_error(ActiveRecord::RecordInvalid, /maximum number of single_limit_state states/)
+
+        # But can still add more no_limit_state states
+        expect do
+          user.add_state('no_limit_state', status: 'completed')
+        end.not_to raise_error
+      end
+    end
+  end
+end

data/spec/meta_states/state_metadata_schema_spec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe 'Metadata Schema Validation', type: :model do
+  let(:user) { create(:user) }
+  let(:schema) do
+    {
+      type: :object,
+      properties: {
+        name: { type: :string },
+        age: {
+          type: :integer,
+          minimum: 18
+        }
+      },
+      required: %i[name age]
+    }
+  end
+
+  before do
+    MetaStates.configuration.clear_callbacks!
+    MetaStates.configuration.model_configurations.clear
+
+    MetaStates.configure do |config|
+      config.configure_model User do |model|
+        model.state_type :schema_enabled_state do |type|
+          type.statuses = %w[pending completed rejected]
+          type.metadata_schema = schema
+        end
+
+        model.state_type :no_schema_state do |type|
+          type.statuses = %w[active inactive]
+        end
+      end
+    end
+  end
+
+  describe 'validation' do
+    context 'with a valid schema' do
+      it 'validates valid metadata' do
+        # Invalid metadata (too young < 18)
+        expect do
+          user.add_state('schema_enabled_state', status: 'pending', metadata: { name: 'John Doe', age: 17 })
+        end.to raise_error(ActiveRecord::RecordInvalid, /did not have a minimum value of 18/)
+
+        # Invalid metadata (missing required fields)
+        expect do
+          user.add_state('schema_enabled_state', status: 'pending', metadata: { age: 25 })
+        end.to raise_error(ActiveRecord::RecordInvalid, /did not contain a required property of 'name'/)
+
+        # Valid metadata
+        state = user.add_state('schema_enabled_state', status: 'pending', metadata: { name: 'John Doe', age: 25 })
+
+        expect(state).to be_valid
+        expect(state.persisted?).to be true
+      end
+    end
+
+    context 'with no schema defined' do
+      it 'accepts any metadata for state types without a schema' do
+        state = user.add_state('no_schema_state', status: 'active', metadata: {
+                                 anything: 'goes',
+                                 nested: {
+                                   data: 'is fine too'
+                                 },
+                                 numbers: [1, 2, 3]
+                               })
+
+        expect(state).to be_valid
+        expect(state.persisted?).to be true
+      end
+    end
+  end
+end