stateful_models 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eb127e7632f183232f299936b44df5fc17f3208decb1da2863c802e8f4f2b69
-  data.tar.gz: bb6062a0184b16afa0a933f8e9c35fd9ca90ad1e8129b6de95ce6d1c1433ffb2
+  metadata.gz: ea223431133002302cf358288dc451d095400476158ae0ec3ecbca053ca83ab9
+  data.tar.gz: 16e622543d2566a058a0d95f5e92fcd40f050639e7e46adf570da7d6d1a2b33c
 SHA512:
-  metadata.gz: b254a3c531422e64ec011fae308ab9999b812f1b85fea61bceb159656091ac9d9fab2723b5b0e8e0802944a1c92d29d3c94822e89f5cbc772cbf06218487f903
-  data.tar.gz: d27742123bce580f7813de17adcee9c5485d5bfc60e2a628fa8f068ce3a6874af8a0e372127b89b86454263738a8563c22e2fb8455fa2c3dda75ef6a6b5d33df
+  metadata.gz: 1833b2d00efb841019aa486993080b7c57fdeb3c521dc0110fd39c9d999bf83b2027f9a256094cfcc0a8a50bf1390c71c1fde0254d0adb24f9c34dcd136f144f
+  data.tar.gz: 50d3df26b5d77592237a73ad84ec68807e2650250c802db1d50e7dd8b90d2753aba1fb021492fe629dbc358f2ea2299898bd6cca91c32098297bb959ea475041

data/CHANGELOG.md

@@ -1,12 +1,19 @@
 ## Released
 
-## [0.0.2] - 2024-12-23
+## [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 `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`
@@ -15,7 +22,7 @@
 
 ## [0.0.3] - 2024-01-14
 
-- Adding current_state method
+- 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`)
 
@@ -23,6 +30,10 @@
 
 - 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
 

data/README.md

@@ -85,8 +85,10 @@ state = user.add_state('kyc', status: 'pending', metadata: {
   notes: 'Awaiting document submission'
 })
 
-# Check current state
+# 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
@@ -130,6 +132,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 +231,20 @@ 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
+
+  def do_something
+    # Custom method on state
+  end
+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

@@ -9,33 +9,33 @@ module HasStates
     TEMPLATES = [
       {
         source: 'create_has_states_states.rb.erb',
-        destination: "db/migrate/%s_create_has_states_states.rb"
+        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"
+        destination: 'db/migrate/%s_create_indexes_on_has_states_states.rb'
       },
       {
         source: 'initializer.rb.erb',
-        destination: "config/initializers/has_states.rb"
+        destination: 'config/initializers/has_states.rb'
       }
     ].freeze
 
     def install
       puts 'Installing HasStates...'
 
-      TEMPLATES.each do |template| 
+      TEMPLATES.each do |template|
         make_template(**template)
       end
 
       puts 'HasStates installed successfully!'
     end
 
-    private 
+    private
 
     def make_template(source:, destination:)
       timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
-      destination = destination % timestamp if destination.include?('%s')
+      destination %= timestamp if destination.include?('%s')
 
       template(source, destination)
     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,8 +10,10 @@ 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?
+    after_commit :trigger_callbacks, if: :saved_change_to_status?
 
     private
 
@@ -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/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/version.rb

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

data/lib/has_states.rb

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