stateful_models 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 140dacad43c4287b2317ab10567b808c4c6c751715a640d04560ea9396f15b11
-  data.tar.gz: b0590f0190d823fad1693ebec1a65e933d465693ac0ecb2688f045fab2f84474
+  metadata.gz: 78629281fcf54961d33cb8c85161df6a357b432b87bff61d5ff769d5491a7667
+  data.tar.gz: 63f984222fb3aad0f086f4d65f263e8134b0243f7186ea5c8818a4ab046890bc
 SHA512:
-  metadata.gz: c0e603d13345f3c36c68dcea633b2d0d37d1de41d5de961b63f81970b572e90e76a2b2f642c2868a94f1b440400f795d4243490159ed58265ab45770a27cb5d2
-  data.tar.gz: dc8688d4ebc992dc7cf32a92dc17d1bda1c2de58ea6747292fd746b529b3a5fdccbe9295090854b252b6b42689fed613b30821655d2a8deb4462b4daabaa13d5
+  metadata.gz: 802ccd260a0560dbb9a4968641230c8d3c4452fd81c856f1dcc500e7f37f0d1e29eb9613f7c4581cdcc18a3ac6e9f1017662cf9790874562228b133d1bd8538b
+  data.tar.gz: 3db09b9db294f748590d3800175512fc555eb84296799b7242479f4727e33088e7d6dd1d0457ef586b1bb043912415ed3cbee95b7210e129802330d6e589d04b

data/CHANGELOG.md

@@ -1,19 +1,36 @@
 ## Released
 
-## [0.0.2] - 2024-12-23
+## [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 `HasStates::Base`
 - Default state class `HasStates::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 `HasStates::Base`
 - Updated `add_state` method to support custom state classes
 - Improved test coverage for inheritance and custom state types
 
-## [0.1.0] - 2024-12-21
+## [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 `HasStates::Base`
+- Default state class `HasStates::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/README.md

@@ -130,6 +130,64 @@ 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
+HasStates.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 })
+# => #<HasStates::State...>
+```
+
+## State Limits
+
+You can optionally limit the number of states a record can have for a specific state type:
+
+```ruby
+HasStates.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:
@@ -171,6 +229,16 @@ HasStates::State.kyc              # All KYC states
 HasStates::State.onboarding      # All onboarding states
 ```
 
+### Class Inheritance
+
+HasStates lets you inherit from the `HasStates::Base` class to create custom state classes. This makes validations and custom methods on specific state types easy.
+
+```ruby
+class MyState < HasStates::Base
+  # Add validations or methods
+end
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/has_states.

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 %= 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,4 +1,4 @@
- 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

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json-schema'
+
 module HasStates
   class Base < ActiveRecord::Base
     self.table_name = 'has_states_states'
@@ -8,6 +10,8 @@ module HasStates
 
     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_save :trigger_callbacks, if: :saved_change_to_status?
 
@@ -32,10 +36,35 @@ module HasStates
       errors.add(:state_type, 'is not configured')
     end
 
+    def state_limit_not_exceeded
+      return unless (limit = HasStates.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 = HasStates.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
       HasStates.configuration.matching_callbacks(self).each do |callback|
         callback.call(self)
       end
     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/configuration/state_type_configuration.rb

@@ -4,11 +4,13 @@ module HasStates
   class Configuration
     class StateTypeConfiguration
       attr_reader :name
-      attr_accessor :statuses
+      attr_accessor :statuses, :limit, :metadata_schema
 
       def initialize(name)
         @name = name
         @statuses = []
+        @limit = nil
+        @metadata_schema = nil
       end
     end
   end

data/lib/has_states/configuration.rb

@@ -12,6 +12,10 @@ module HasStates
       @model_configurations = {}
     end
 
+    # Configure a model to use HasStates
+    # @param model_class [Class] The model class to configure
+    # @return [Configuration::ModelConfiguration] The model configuration
+    # @raise [ArgumentError] If the model class is not an ActiveRecord model
     def configure_model(model_class)
       unless model_class.is_a?(Class) && model_class < ActiveRecord::Base
         raise ArgumentError, "#{model_class} must be an ActiveRecord model"
@@ -25,16 +29,76 @@ module HasStates
       model_class.include(Stateable) unless model_class.included_modules.include?(Stateable)
     end
 
+    # Check if a status is valid for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @param status [String] The status
+    # @return [Boolean] True if the status is valid, false otherwise
     def valid_status?(model_class, state_type, status)
-      return false unless @model_configurations[model_class]&.state_types&.[](state_type.to_s)
+      return false unless @model_configurations[model_class]&.state_types&.dig(state_type.to_s)
 
       @model_configurations[model_class].state_types[state_type.to_s].statuses.include?(status)
     end
 
+    # Check if a state type is valid for a given model
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Boolean] True if the state type is valid, false otherwise
     def valid_state_type?(model_class, state_type)
       @model_configurations[model_class]&.state_types&.key?(state_type.to_s)
     end
 
+    # Get the configuration for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Configuration::StateTypeConfiguration] The state type configuration
+    def config_for(model_class, state_type)
+      @model_configurations[model_class]&.state_types&.dig(state_type.to_s)
+    end
+
+    # Get the state types for a given model
+    # @param model_class [Class] The model class
+    # @return [Hash] The state types for the model
+    def state_types_for(model_class)
+      @model_configurations[model_class]&.state_types
+    end
+
+    # Get the statuses for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Array] The statuses for the state type
+    def statuses_for(model_class, state_type)
+      return nil unless (config = config_for(model_class, state_type))
+
+      config.statuses
+    end
+
+    # Get the limit for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Integer] The limit for the state type
+    def limit_for(model_class, state_type)
+      return nil unless (config = config_for(model_class, state_type))
+
+      config.limit
+    end
+
+    # Get the metadata schema for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Hash] The metadata schema for the state type
+    def metadata_schema_for(model_class, state_type)
+      return nil unless (config = config_for(model_class, state_type))
+
+      config.metadata_schema
+    end
+
+    # Register a callback for a given state type
+    # @param state_type [String] The state type
+    # @param id [Symbol] The callback id
+    # @param conditions [Hash] The conditions for the callback
+    # @param block [Proc] The callback block
+    # @return [Callback] The callback
     def on(state_type, id: nil, **conditions, &block)
       callback = Callback.new(state_type, conditions, block)
       callback_id = id&.to_sym || generate_callback_id
@@ -42,6 +106,9 @@ module HasStates
       callback
     end
 
+    # Remove a callback by id or callback object
+    # @param callback_or_id [Symbol, Callback] The callback id or callback object
+    # @return [Callback] The removed callback
     def off(callback_or_id)
       if callback_or_id.is_a?(Callback)
         @callbacks.delete_if { |_, cb| cb == callback_or_id }
@@ -50,31 +117,23 @@ module HasStates
       end
     end
 
+    # Get the callbacks that match a given state
+    # @param state [State] The state
+    # @return [Array] The matching callbacks
     def matching_callbacks(state)
       @callbacks.values.select { |callback| callback.matches?(state) }
     end
 
+    # Clear all callbacks
+    # @return [void]
     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
 
+    # Generate a unique callback id
+    # @return [Symbol] The generated callback id
     def generate_callback_id
       @next_callback_id += 1
       :"callback_#{@next_callback_id}"

data/lib/has_states/state.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
 module HasStates
-  class State < Base
-  end
+  class State < Base; end
 end

data/lib/has_states/stateable.rb

@@ -6,18 +6,21 @@ module HasStates
 
     included do
       has_many :states, class_name: 'HasStates::Base',
-                       as: :stateable,
-                       dependent: :destroy
+                        as: :stateable,
+                        dependent: :destroy
     end
 
     # Instance methods for managing states
     def add_state(type, status: 'pending', metadata: {}, state_class: HasStates::State)
-      states.create!(
-        type: state_class.name,
-        state_type: type,
-        status: status,
-        metadata: metadata
-      )
+      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.2'
+  VERSION = '0.0.4'
 end

data/lib/has_states.rb

@@ -11,7 +11,7 @@ module HasStates
     def configure
       yield(configuration)
     end
-    
+
     def configuration
       Configuration.instance
     end