meta_states 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 48579ba5da3df5f8b0d86db0991a0a6cbed1d1139504373f10490147a7f26d97
+  data.tar.gz: 84df5ed976adf93421e3fac0f27c2f9d43265283c0338d1f5541e08e0f876860
+SHA512:
+  metadata.gz: 4d796e212f4476184e6d9b02b7661245215ad80ac4635477bcc9d30db7d13160948ea934fc8084771cf7dc10be1ce46397212fdcfdf514cdc820e9cf6cbf0408
+  data.tar.gz: 92257aede1c5829d5d1dc1de19653664f642cb59fcf7e0fa3edd4e8634ae4a871992f64b8a8f48736039d58404a1cff7749993a6cd00848734cb9a012c8c6f45

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+## Released
+
+## [0.1.0] - 2025-06-05
+
+### Change
+- Renaming gem from `meta_states` to `meta_states`.
+
+## [0.0.5] - 2025-04-14
+
+## Change
+- Changed callback action on base class from `after_save` to `after_commit` 
+
+## [0.0.4] - 2025-03-21
+
+### Added
+- Single Table Inheritance (STI) support for custom state types
+- Ability to create custom state classes by inheriting from `MetaStates::Base`
+- Default state class `MetaStates::State` for basic state management
+- Example implementation of custom state types in documentation
+- `limit` option for state types to limit the number of states on a record
+- `metadata_schema` option for state types to validate metadata
+
+### Changed
+- Refactored base state functionality into `MetaStates::Base`
+- Updated `add_state` method to support custom state classes
+- Improved test coverage for inheritance and custom state types
+
+## [0.0.3] - 2024-01-14
+
+- Adding `current_state(state_name)` method
+- Adding DB indexes for state lookups
+- Adding query methods for state types on stateable (`stateable.state_type` and `stateable.state_types`)
+
+## [0.0.2] - 2024-12-23
+
+- Added test coverage
+- Refactor of State model into a inheritable Base class
+- Single Table Inheritance (STI) support for custom state types
+- Ability to create custom state classes by inheriting from `MetaStates::Base`
+- Default state class `MetaStates::State` for basic state management
+- Example implementation of custom state types in documentation
+
+## [0.0.1] - 2024-12-21
+
+- Initial release
+- See READme.md

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Sebastian Scholl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,255 @@
+# MetaStates
+
+MetaStates is a flexible state management gem for Ruby on Rails that allows you to add multiple state machines to your models. It provides a simple way to track state transitions, add metadata, and execute callbacks.
+
+## Features
+
+- Multiple state types per model
+- Model-specific state configurations
+- JSON metadata storage for each state
+- Configurable callbacks with conditions
+- Limited execution callbacks
+- Automatic scope generation
+- Simple state transition tracking
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stateful_models'
+```
+
+Then execute:
+```bash
+$ bundle install
+```
+
+Generate the required migration and initializer:
+```bash
+$ rails generate meta_states:install
+```
+
+Finally, run the migration:
+```bash
+$ rails db:migrate
+```
+
+## Configuration
+
+Configure your models and their state types in `config/initializers/meta_states.rb`:
+
+```ruby
+MetaStates.configure do |config|
+  # Configure states on any model
+  config.configure_model User do |model|
+    # Define state type and its allowed statuses
+    model.state_type :kyc do |type|
+      type.statuses = [
+        'pending',              # Initial state
+        'documents_required',   # Waiting for documents
+        'under_review',        # Documents being reviewed
+        'approved',            # KYC completed successfully
+        'rejected'             # KYC failed
+      ]
+    end
+
+    # Define multiple state types per model with different statuses
+    model.state_type :onboarding do |type|
+      type.statuses = [
+        'pending',          # Just started
+        'email_verified',   # Email verification complete
+        'completed'         # Onboarding finished
+      ]
+    end
+  end
+
+  # Configure multiple models
+  config.configure_model Company do |model|
+    model.state_type :verification do |type|
+      type.statuses = ['pending', 'verified', 'rejected']
+    end
+  end
+end
+```
+
+## Usage
+
+### Basic State Management
+
+```ruby
+user = User.create!(name: 'John')
+# Add a new state
+state = user.add_state('kyc', status: 'pending', metadata: {
+  documents: ['passport', 'utility_bill'],
+  notes: 'Awaiting document submission'
+})
+
+# Load state(s) also by name as methods on the record
+current_kyc = user.current_state('kyc')
+current_kyc = user.kyc # Returns most recent state of type kyc if multiple states of the same type exist
+all_kyc = user.kycs
+
+# Predicate methods are generated for every status.
+current_kyc.pending?  # => true
+current_kyc.approved? # => false
+
+# Update state
+current_kyc.update!(status: 'under_review')
+
+# Check state for record 
+user.kyc_pending? # => true
+user.kyc_completed? # => false
+
+# See all states for record
+user.states # => [#<MetaStates::State...>]
+```
+
+### Working with Metadata
+
+Each state can store arbitrary metadata as JSON:
+
+```ruby
+# Store complex metadata
+state = user.add_state('kyc', metadata: {
+  documents: {
+    passport: { 
+      status: 'verified',
+      verified_at: Time.current,
+      verified_by: 'admin@example.com'
+    },
+    utility_bill: { 
+      status: 'rejected',
+      reason: 'Document expired'
+    }
+  },
+  risk_score: 85,
+  notes: ['Requires additional verification', 'High-risk jurisdiction']
+})
+
+# Access metadata
+state.metadata['documents']['passport']['status'] # => "verified"
+state.metadata['risk_score'] # => 85
+```
+
+## Metadata Validations
+
+You can define a JSON Schema for validating the metadata of states. This allows you to ensure that the metadata follows a specific structure and contains required fields, leveraging the power of JSON Schema.
+
+```ruby
+MetaStates.configure do |config|
+  config.configure_model User do |model|
+    model.state_type :kyc do |type|
+      type.statuses = [
+        'pending',         
+        'approved',    
+        'rejected'  
+      ]
+
+      type.metadata_schema = {
+        type: :object,
+        properties: {
+          name: { type: :string },
+          age: { 
+            type: :integer,
+            minimum: 18
+          },
+        },
+        required: [:name, :age],
+        additionalProperties: false,
+      }
+    end
+  end
+end
+
+user = User.create!
+
+# Invalid metadata (too young < 18)
+user.add_state('kyc', status: 'pending', metadata: { name: 'John Doe', age: 17 })
+# ActiveRecord::RecordInvalid: Validation failed: Metadata is invalid (minimum value of 18)
+
+# Valid metadata
+user.add_state('kyc', status: 'pending', metadata: { name: 'John Doe', age: 25 })
+# => #<MetaStates::State...>
+```
+
+## State Limits
+
+You can optionally limit the number of states a record can have for a specific state type:
+
+```ruby
+MetaStates.configure do |config|
+  config.configure_model User do |model|
+    model.state_type :kyc do |type|
+      type.statuses = %w[pending completed]
+      type.limit = 1  # Limit to only one KYC state per user
+    end
+  end
+end
+```
+
+When set, the limit is checked when a new state is added. If the limit is exceeded, an ActiveRecord::RecordInvalid error is raised.
+
+### Callbacks
+
+Register callbacks that execute when states change:
+
+```ruby
+MetaStates.configure do |config|
+  # Basic callback
+  config.on(:kyc, to: 'completed') do |state|
+    UserMailer.kyc_completed(state.stateable).deliver_later
+  end
+
+  # Callback with custom ID for easy removal
+  config.on(:kyc, id: :notify_admin, to: 'rejected') do |state|
+    AdminNotifier.kyc_rejected(state)
+  end
+
+  # Callback that runs only once
+  config.on(:onboarding, to: 'completed', times: 1) do |state|
+    WelcomeMailer.send_welcome(state.stateable)
+  end
+
+  # Callback with from/to conditions
+  config.on(:kyc, from: 'pending', to: 'under_review') do |state|
+    NotificationService.notify_review_started(state)
+  end
+end
+
+# Remove callbacks
+MetaStates.configuration.off(:notify_admin)  # Remove by ID
+MetaStates.configuration.off(callback)       # Remove by callback object
+```
+
+### Scopes
+
+MetaStates automatically generates scopes for your state types:
+
+```ruby
+MetaStates::State.kyc              # All KYC states
+MetaStates::State.onboarding      # All onboarding states
+```
+
+### Class Inheritance
+
+MetaStates lets you inherit from the `MetaStates::Base` class to create custom state classes. This makes validations and custom methods on specific state types easy.
+
+```ruby
+class MyState < MetaStates::Base
+  # Add validations or methods
+
+  def do_something
+    # Custom method on state
+  end
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/meta_states.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/lib/generators/meta_states/install/install_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MetaStates
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    TEMPLATES = [
+      {
+        source: 'create_meta_states_states.rb.erb',
+        destination: 'db/migrate/%s_create_meta_states_states.rb'
+      },
+      {
+        source: 'create_indexes_on_meta_states_states.rb.erb',
+        destination: 'db/migrate/%s_create_indexes_on_meta_states_states.rb'
+      },
+      {
+        source: 'initializer.rb.erb',
+        destination: 'config/initializers/meta_states.rb'
+      }
+    ].freeze
+
+    def install
+      puts 'Installing MetaStates...'
+
+      TEMPLATES.each do |template|
+        make_template(**template)
+      end
+
+      puts 'MetaStates installed successfully!'
+    end
+
+    private
+
+    def make_template(source:, destination:)
+      timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
+      destination %= timestamp if destination.include?('%s')
+
+      template(source, destination)
+    end
+  end
+end

data/lib/generators/meta_states/install/templates/create_indexes_on_meta_states_states.rb.erb

@@ -0,0 +1,11 @@
+class CreateIndexesOnMetaStatesStates < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  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/lib/generators/meta_states/install/templates/create_meta_states_states.rb.erb

@@ -0,0 +1,18 @@
+class CreateMetaStatesStates < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  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/lib/generators/meta_states/install/templates/initializer.rb.erb

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module MetaStates
+  class Base < ActiveRecord::Base
+    self.table_name = 'meta_states_states'
+
+    belongs_to :stateable, polymorphic: true
+
+    validate :status_is_configured
+    validate :state_type_is_configured
+    validate :state_limit_not_exceeded, on: :create
+    validate :metadata_conforms_to_schema, if: -> { metadata.present? }
+
+    after_commit :trigger_callbacks, if: :saved_change_to_status?
+
+    private
+
+    def status_is_configured
+      return if MetaStates.configuration.valid_status?(
+        stateable_type.constantize,
+        state_type,
+        status
+      )
+
+      errors.add(:status, 'is not configured')
+    end
+
+    def state_type_is_configured
+      return if MetaStates.configuration.valid_state_type?(
+        stateable_type.constantize,
+        state_type
+      )
+
+      errors.add(:state_type, 'is not configured')
+    end
+
+    def state_limit_not_exceeded
+      return unless (limit = MetaStates.configuration.limit_for(
+        stateable_type.constantize,
+        state_type
+      ))
+
+      return unless stateable
+
+      current_count = stateable.states.where(state_type: state_type).count
+      return if current_count < limit
+
+      errors.add(:base, "maximum number of #{state_type} states (#{limit}) reached")
+    end
+
+    def metadata_conforms_to_schema
+      return unless (schema = MetaStates.configuration.metadata_schema_for(
+        stateable_type.constantize,
+        state_type
+      ))
+
+      JSON::Validator.validate!(schema, metadata, strict: true)
+    rescue JSON::Schema::ValidationError => e
+      errors.add(:metadata, "does not conform to schema: #{e.message}")
+    end
+
+    def trigger_callbacks
+      MetaStates.configuration.matching_callbacks(self).each do |callback|
+        callback.call(self)
+      end
+    end
+  end
+end

data/lib/meta_states/callback.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MetaStates
+  class Callback
+    attr_reader :state_type, :conditions, :block, :max_executions
+    attr_accessor :execution_count
+
+    def initialize(state_type, conditions, block)
+      @state_type = state_type
+      @conditions = conditions
+      @block = block
+      @max_executions = conditions.delete(:times)
+      @execution_count = 0
+    end
+
+    def matches?(state)
+      return false unless state.state_type == state_type.to_s
+
+      conditions.all? do |key, expected_value|
+        case key
+        when :to
+          state.status == expected_value
+        when :from
+          state.status_before_last_save == expected_value
+        else
+          state.public_send(key) == expected_value
+        end
+      end
+    end
+
+    def call(state)
+      result = block.call(state)
+      @execution_count += 1
+
+      # Remove self from configuration if this was the last execution
+      MetaStates.configuration.off(self) if expired?
+
+      result
+    end
+
+    def expired?
+      max_executions && execution_count >= max_executions
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        other.state_type == state_type &&
+        other.conditions == conditions &&
+        other.block == block
+    end
+
+    alias eql? ==
+
+    def hash
+      [state_type, conditions, block].hash
+    end
+  end
+end

data/lib/meta_states/configuration/model_configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module MetaStates
+  class Configuration
+    class ModelConfiguration
+      attr_reader :model_class, :state_types
+
+      def initialize(model_class)
+        @model_class = model_class
+        @state_types = {}
+      end
+
+      def state_type(name)
+        type = StateTypeConfiguration.new(name)
+
+        yield(type) if block_given?
+
+        @state_types[name.to_s] = type
+
+        # MetaStates::State model method generators
+        generate_state_type_scope(name)
+        generate_status_predicates(type.statuses)
+
+        # Included model method generators
+        generate_state_type_queries(name)
+        generate_state_type_status_predicates(name, type.statuses)
+      end
+
+      private
+
+      def generate_state_type_scope(state_type)
+        MetaStates::State.scope state_type, -> { where(state_type: state_type) }
+      end
+
+      def generate_status_predicates(statuses)
+        statuses.each do |status_name|
+          MetaStates::State.define_method(:"#{status_name}?") do
+            status == status_name
+          end
+        end
+      end
+
+      def generate_state_type_queries(state_type)
+        # Singular for finding the most recent state of a given type and status
+        @model_class.define_method(:"#{state_type}") do
+          states.where(state_type: state_type).order(created_at: :desc).first
+        end
+
+        # Plural for finding all states of a given type and status
+        @model_class.define_method(:"#{ActiveSupport::Inflector.pluralize(state_type)}") do
+          states.where(state_type: state_type).order(created_at: :desc)
+        end
+      end
+
+      def generate_state_type_status_predicates(state_type, statuses)
+        statuses.each do |status_name|
+          @model_class.define_method(:"#{state_type}_#{status_name}?") do
+            states.where(state_type: state_type, status: status_name).exists?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/meta_states/configuration/state_type_configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module MetaStates
+  class Configuration
+    class StateTypeConfiguration
+      attr_reader :name
+      attr_accessor :statuses, :limit, :metadata_schema
+
+      def initialize(name)
+        @name = name
+        @statuses = []
+        @limit = nil
+        @metadata_schema = nil
+      end
+    end
+  end
+end