stateful_models 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58bd1cdf2dd440bf776a3fd5607b2b965d2dc4a47b03174e2ef542777b62f95d
+  data.tar.gz: 94f8c8473326519ba676df54e010037f699b0985976a68d09832f1a42ebb567a
+SHA512:
+  metadata.gz: 436f47aaac1ba1216157ed927ea9ba758570b8c36b75f77e6ad3e21d905070f34f9beca5e4065b247306b10898fbf356a99a4935d89917c1ed8df296543f27ba
+  data.tar.gz: 629afd3e4a9280c03571bbcfcb12b9da2d9d7da6c53bbbd2f98d3bc902164e10dcb3fba6a079b29c2d7f7a133895ad8d8f3d56d5645ca9d64198b02e5551690c

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## Released
+
+## [0.1.0] - 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,181 @@
+# HasStates
+
+HasStates 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 'has_states'
+```
+
+Then execute:
+```bash
+$ bundle install
+```
+
+Generate the required migration and initializer:
+```bash
+$ rails generate has_states:install
+```
+
+Finally, run the migration:
+```bash
+$ rails db:migrate
+```
+
+## Configuration
+
+Configure your models and their state types in `config/initializers/has_states.rb`:
+
+```ruby
+HasStates.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'
+})
+
+# Check current state
+current_kyc = user.current_state('kyc')
+
+# 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 # => [#<HasStates::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
+```
+
+### Callbacks
+
+Register callbacks that execute when states change:
+
+```ruby
+HasStates.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
+HasStates.configuration.off(:notify_admin)  # Remove by ID
+HasStates.configuration.off(callback)       # Remove by callback object
+```
+
+### Scopes
+
+HasStates automatically generates scopes for your state types:
+
+```ruby
+HasStates::State.kyc              # All KYC states
+HasStates::State.onboarding      # All onboarding states
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/has_states.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module HasStates
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    def install
+      puts 'Installing HasStates...'
+
+      template(
+        'create_has_states_states.rb.erb',
+        "db/migrate/#{Time.now.utc.strftime('%Y%m%d%H%M%S')}_create_has_states_states.rb"
+      )
+
+      template(
+        'initializer.rb.erb',
+        'config/initializers/has_states.rb'
+      )
+
+      puts 'HasStates installed successfully!'
+    end
+  end
+end

data/lib/generators/has_states/install/templates/create_has_states_states.rb.erb

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

@@ -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/lib/has_states/callback.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module HasStates
+  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
+      HasStates.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/has_states/configuration/model_configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module HasStates
+  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
+
+        generate_state_type_scope(name)
+        generate_status_predicates(type.statuses)
+        generate_state_type_status_predicates(name, type.statuses)
+      end
+
+      private
+
+      def generate_state_type_scope(state_type)
+        HasStates::State.scope state_type, -> { where(state_type: state_type) }
+      end
+
+      def generate_status_predicates(statuses)
+        statuses.each do |status_name|
+          HasStates::State.define_method(:"#{status_name}?") do
+            status == status_name
+          end
+        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/has_states/configuration/state_type_configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module HasStates
+  class Configuration
+    class StateTypeConfiguration
+      attr_reader :name
+      attr_accessor :statuses
+
+      def initialize(name)
+        @name = name
+        @statuses = []
+      end
+    end
+  end
+end

data/lib/has_states/configuration.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module HasStates
+  class Configuration
+    include Singleton
+
+    attr_reader :callbacks, :model_configurations
+
+    def initialize
+      @callbacks = {}
+      @next_callback_id = 0
+      @model_configurations = {}
+    end
+
+    def configure_model(model_class)
+      unless model_class.is_a?(Class) && model_class < ActiveRecord::Base
+        raise ArgumentError, "#{model_class} must be an ActiveRecord model"
+      end
+
+      model_config = Configuration::ModelConfiguration.new(model_class)
+
+      yield(model_config)
+
+      @model_configurations[model_class] = model_config
+      model_class.include(Stateable) unless model_class.included_modules.include?(Stateable)
+    end
+
+    def valid_status?(model_class, state_type, status)
+      return false unless @model_configurations[model_class]&.state_types&.[](state_type.to_s)
+
+      @model_configurations[model_class].state_types[state_type.to_s].statuses.include?(status)
+    end
+
+    def valid_state_type?(model_class, state_type)
+      @model_configurations[model_class]&.state_types&.key?(state_type.to_s)
+    end
+
+    def on(state_type, id: nil, **conditions, &block)
+      callback = Callback.new(state_type, conditions, block)
+      callback_id = id&.to_sym || generate_callback_id
+      @callbacks[callback_id] = callback
+      callback
+    end
+
+    def off(callback_or_id)
+      if callback_or_id.is_a?(Callback)
+        @callbacks.delete_if { |_, cb| cb == callback_or_id }
+      else
+        @callbacks.delete(callback_or_id)
+      end
+    end
+
+    def matching_callbacks(state)
+      @callbacks.values.select { |callback| callback.matches?(state) }
+    end
+
+    def clear_callbacks!
+      @callbacks = {}
+    end
+
+    def state_types_for(model_class)
+      @model_configurations[model_class]&.state_types
+    end
+
+    def statuses_for(model_class, state_type)
+      config = @model_configurations[model_class]
+      return nil unless config
+
+      state_types = config.state_types
+      return nil unless state_types
+
+      state_type_config = state_types[state_type.to_s]
+      state_type_config&.statuses
+    end
+
+    private
+
+    def generate_callback_id
+      @next_callback_id += 1
+      :"callback_#{@next_callback_id}"
+    end
+  end
+end

data/lib/has_states/railtie.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module HasStates
+  class Railtie < Rails::Railtie
+  end
+end
+
+require 'generators/has_states/install/install_generator'

data/lib/has_states/state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module HasStates
+  class State < ActiveRecord::Base
+    self.table_name = 'has_states_states'
+
+    belongs_to :stateable, polymorphic: true
+
+    validate :status_is_configured
+    validate :state_type_is_configured
+
+    after_save :trigger_callbacks, if: :saved_change_to_status?
+
+    private
+
+    def status_is_configured
+      return if HasStates.configuration.valid_status?(
+        stateable_type.constantize,
+        state_type,
+        status
+      )
+
+      errors.add(:status, 'is not configured')
+    end
+
+    def state_type_is_configured
+      return if HasStates.configuration.valid_state_type?(
+        stateable_type.constantize,
+        state_type
+      )
+
+      errors.add(:state_type, 'is not configured')
+    end
+
+    def trigger_callbacks
+      HasStates.configuration.matching_callbacks(self).each do |callback|
+        callback.call(self)
+      end
+    end
+  end
+end

data/lib/has_states/stateable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module HasStates
+  module Stateable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :states, class_name: 'HasStates::State',
+                        as: :stateable,
+                        dependent: :destroy
+    end
+
+    # Instance methods for managing states
+    def add_state(type, status: 'pending', metadata: {})
+      states.create!(
+        state_type: type,
+        status: status,
+        metadata: metadata
+      )
+    end
+  end
+end

data/lib/has_states/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HasStates
+  VERSION = '0.0.1'
+end

data/lib/has_states.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'has_states/version'
+require 'has_states/configuration'
+require 'has_states/configuration/model_configuration'
+require 'has_states/configuration/state_type_configuration'
+
+module HasStates
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      Configuration.instance
+    end
+  end
+end
+
+require 'has_states/state'
+require 'has_states/callback'
+require 'has_states/stateable'
+require 'has_states/railtie' if defined?(Rails)

data/spec/dummy/Gemfile

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem 'rails', '~> 8.0.1'
+# Use sqlite3 as the database for Active Record
+gem 'sqlite3', '>= 2.1'
+# Use the Puma web server [https://github.com/puma/puma]
+gem 'puma', '>= 5.0'
+
+# Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
+# gem "bcrypt", "~> 3.1.7"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem 'tzinfo-data', platforms: %i[windows jruby]
+
+# Use the database-backed adapters for Rails.cache and Active Job
+gem 'solid_cache'
+gem 'solid_queue'
+
+# Deploy this application anywhere as a Docker container [https://kamal-deploy.org]
+gem 'kamal', require: false
+
+# Add HTTP asset caching/compression and X-Sendfile acceleration to Puma [https://github.com/basecamp/thruster/]
+gem 'thruster', require: false
+
+# Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin Ajax possible
+# gem "rack-cors"
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem 'debug', platforms: %i[mri windows], require: 'debug/prelude'
+
+  # Static analysis for security vulnerabilities [https://brakemanscanner.org/]
+  gem 'brakeman', require: false
+end
+
+# HasStates gem for state management and event system capabilities
+gem 'stateful_models', path: '../..' # This points to the root of your gem