stateful_models 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58bd1cdf2dd440bf776a3fd5607b2b965d2dc4a47b03174e2ef542777b62f95d
-  data.tar.gz: 94f8c8473326519ba676df54e010037f699b0985976a68d09832f1a42ebb567a
+  metadata.gz: 8eb127e7632f183232f299936b44df5fc17f3208decb1da2863c802e8f4f2b69
+  data.tar.gz: bb6062a0184b16afa0a933f8e9c35fd9ca90ad1e8129b6de95ce6d1c1433ffb2
 SHA512:
-  metadata.gz: 436f47aaac1ba1216157ed927ea9ba758570b8c36b75f77e6ad3e21d905070f34f9beca5e4065b247306b10898fbf356a99a4935d89917c1ed8df296543f27ba
-  data.tar.gz: 629afd3e4a9280c03571bbcfcb12b9da2d9d7da6c53bbbd2f98d3bc902164e10dcb3fba6a079b29c2d7f7a133895ad8d8f3d56d5645ca9d64198b02e5551690c
+  metadata.gz: b254a3c531422e64ec011fae308ab9999b812f1b85fea61bceb159656091ac9d9fab2723b5b0e8e0802944a1c92d29d3c94822e89f5cbc772cbf06218487f903
+  data.tar.gz: d27742123bce580f7813de17adcee9c5485d5bfc60e2a628fa8f068ce3a6874af8a0e372127b89b86454263738a8563c22e2fb8455fa2c3dda75ef6a6b5d33df

data/CHANGELOG.md

@@ -1,6 +1,30 @@
 ## Released
 
-## [0.1.0] - 2024-12-21
+## [0.0.2] - 2024-12-23
+
+### Added
+- Single Table Inheritance (STI) support for custom state types
+- Ability to create custom state classes by inheriting from `HasStates::Base`
+- Default state class `HasStates::State` for basic state management
+- Example implementation of custom state types in documentation
+
+### Changed
+- Refactored base state functionality into `HasStates::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 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
+
+## [0.0.1] - 2024-12-21
 
 - Initial release
 - See READme.md

data/README.md

@@ -17,7 +17,7 @@ HasStates is a flexible state management gem for Ruby on Rails that allows you t
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'has_states'
+gem 'stateful_models'
 ```
 
 Then execute:

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

@@ -6,20 +6,38 @@ module HasStates
   class InstallGenerator < Rails::Generators::Base
     source_root File.expand_path('templates', __dir__)
 
+    TEMPLATES = [
+      {
+        source: 'create_has_states_states.rb.erb',
+        destination: "db/migrate/%s_create_has_states_states.rb"
+      },
+      {
+        source: 'create_indexes_on_has_states_states.rb.erb',
+        destination: "db/migrate/%s_create_indexes_on_has_states_states.rb"
+      },
+      {
+        source: 'initializer.rb.erb',
+        destination: "config/initializers/has_states.rb"
+      }
+    ].freeze
+
     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'
-      )
+      TEMPLATES.each do |template| 
+        make_template(**template)
+      end
 
       puts 'HasStates installed successfully!'
     end
+
+    private 
+
+    def make_template(source:, destination:)
+      timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
+      destination = destination % timestamp if destination.include?('%s')
+
+      template(source, destination)
+    end
   end
 end

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

@@ -1,6 +1,7 @@
- class CreateHasStatesStates < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+class CreateHasStatesStates < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :has_states_states do |t|
+      t.string :type, null: false
       t.string :state_type
       t.string :status, null: false
 
@@ -8,9 +9,9 @@
 
       t.references :stateable, polymorphic: true, null: false
 
-      t.datetime :completed_at
       t.timestamps
 
+      t.index %i[type stateable_id]
       t.index %i[stateable_type stateable_id]
     end
   end

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

@@ -0,0 +1,11 @@
+class CreateIndexesOnHasStatesStates < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    change_table :has_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/has_states/base.rb

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

@@ -17,8 +17,12 @@ module HasStates
 
         @state_types[name.to_s] = type
 
+        # HasStates::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
 
@@ -36,6 +40,18 @@ module HasStates
         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

data/lib/has_states/state.rb

@@ -1,41 +1,5 @@
 # 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
+  class State < Base; end
 end

data/lib/has_states/stateable.rb

@@ -5,18 +5,22 @@ module HasStates
     extend ActiveSupport::Concern
 
     included do
-      has_many :states, class_name: 'HasStates::State',
+      has_many :states, class_name: 'HasStates::Base',
                         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
-      )
+    def add_state(type, status: 'pending', metadata: {}, state_class: HasStates::State)
+      states.create!(type: state_class.name, state_type: type, status: status, metadata: metadata)
+    end
+
+    def current_state(type)
+      states.where(state_type: type).order(created_at: :desc).first
+    end
+
+    def current_states(type)
+      states.where(state_type: type).order(created_at: :desc)
     end
   end
 end

data/lib/has_states/version.rb

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

data/lib/has_states.rb

@@ -11,13 +11,14 @@ module HasStates
     def configure
       yield(configuration)
     end
-
+    
     def configuration
       Configuration.instance
     end
   end
 end
 
+require 'has_states/base'
 require 'has_states/state'
 require 'has_states/callback'
 require 'has_states/stateable'

data/spec/dummy/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    has_state (0.0.1)
+    stateful_models (0.0.2)
 
 GEM
   remote: https://rubygems.org/
@@ -272,13 +272,13 @@ PLATFORMS
 DEPENDENCIES
   brakeman
   debug
-  has_state!
   kamal
   puma (>= 5.0)
   rails (~> 8.0.1)
   solid_cache
   solid_queue
   sqlite3 (>= 2.1)
+  stateful_models!
   thruster
   tzinfo-data
 

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

@@ -0,0 +1,45 @@
+ # frozen_string_literal: true
+
+# Configure after the application is initialized
+Rails.application.config.after_initialize do
+  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
+end

data/spec/{generators/tmp/db/migrate/20241223020432_create_has_states_states.rb → dummy/db/migrate/20241223212128_create_has_states_states.rb}

@@ -1,6 +1,7 @@
  class CreateHasStatesStates < ActiveRecord::Migration[8.0]
   def change
     create_table :has_states_states do |t|
+      t.string :type, null: false
       t.string :state_type
       t.string :status, null: false
 
@@ -8,9 +9,9 @@
 
       t.references :stateable, polymorphic: true, null: false
 
-      t.datetime :completed_at
       t.timestamps
 
+      t.index %i[type stateable_id]
       t.index %i[stateable_type stateable_id]
     end
   end

data/spec/dummy/db/migrate/20250114175939_create_indexes_on_has_states_states.rb

@@ -0,0 +1,10 @@
+class CreateIndexesOnHasStatesStates < ActiveRecord::Migration[8.0]
+  def change
+    change_table :has_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] 
+    end
+  end
+end

data/spec/dummy/db/schema.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 # This file is auto-generated from the current state of the database. Instead
 # of editing this file, please use the migrations feature of Active Record to
 # incrementally modify your database, and then regenerate this schema definition.
@@ -12,29 +10,35 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[8.0].define(version: 20_241_221_183_116) do
-  create_table 'companies', force: :cascade do |t|
-    t.string 'name'
-    t.datetime 'created_at', null: false
-    t.datetime 'updated_at', null: false
+ActiveRecord::Schema[8.0].define(version: 2025_01_14_175939) do
+  create_table "companies", force: :cascade do |t|
+    t.string "name"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
   end
 
-  create_table 'has_states_states', force: :cascade do |t|
-    t.string 'state_type'
-    t.string 'status', null: false
-    t.json 'metadata', default: {}, null: false
-    t.string 'stateable_type', null: false
-    t.integer 'stateable_id', null: false
-    t.datetime 'completed_at'
-    t.datetime 'created_at', null: false
-    t.datetime 'updated_at', null: false
-    t.index %w[stateable_type stateable_id], name: 'index_has_states_states_on_stateable'
-    t.index %w[stateable_type stateable_id], name: 'index_has_states_states_on_stateable_type_and_stateable_id'
+  create_table "has_states_states", force: :cascade do |t|
+    t.string "type", null: false
+    t.string "state_type"
+    t.string "status", null: false
+    t.json "metadata", default: {}, null: false
+    t.string "stateable_type", null: false
+    t.integer "stateable_id", null: false
+    t.datetime "completed_at"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.index ["stateable_id", "state_type", "created_at"], name: "idx_on_stateable_id_state_type_created_at_b5d09fb6ee"
+    t.index ["stateable_id", "state_type", "status", "created_at"], name: "idx_on_stateable_id_state_type_status_created_at_19e1cf37c2"
+    t.index ["stateable_id", "state_type", "status"], name: "idx_on_stateable_id_state_type_status_6d3d026e4d"
+    t.index ["stateable_id", "state_type"], name: "index_has_states_states_on_stateable_id_and_state_type"
+    t.index ["stateable_type", "stateable_id"], name: "index_has_states_states_on_stateable"
+    t.index ["stateable_type", "stateable_id"], name: "index_has_states_states_on_stateable_type_and_stateable_id"
+    t.index ["type", "stateable_id"], name: "index_has_states_states_on_type_and_stateable_id"
   end
 
-  create_table 'users', force: :cascade do |t|
-    t.string 'name'
-    t.datetime 'created_at', null: false
-    t.datetime 'updated_at', null: false
+  create_table "users", force: :cascade do |t|
+    t.string "name"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
   end
 end