circulator 2.1.1 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31b604ea699b2cbe133905f3078e81aa7860bc4e70e52cfd928611b92140b3f8
-  data.tar.gz: e264bd9c50f93fb1ab9f606a0d6b670ce4708304ccdf4a04a67a3a2e588b5bf5
+  metadata.gz: 1a3d83bc194cf2440d13e088b1b23e72cf3ec89071ae9d046d575a7e5d1014c7
+  data.tar.gz: 4c1afec2234a2edf3675048519aac13e4b64f2c8bbb08b98387603fc5f354ea8
 SHA512:
-  metadata.gz: 80262bad01b9861f1f20459a67c80fbbd77c1f4cf4bc661d5b5918bd727582e8e099871cfd63b29a973fc5998a0c942a0f63aa2ced5894d41de91b5722517b19
-  data.tar.gz: fcbd512e14e020ee4ede8cb34b0432b46c38fbfee246c43a14906f0711302825e633376e8bb1b98c00eee55a24396c5e5814e1fd394dbc8f5a106737a615cb39
+  metadata.gz: a5bf023b56fe2f8352fbb2fadce2c8a29cb9a47cfd5b011c80c098646696b9dcd5735c2b027c8f4a126c285005f11c8b46e9c009ac8ad243df3e1bc8a5979523
+  data.tar.gz: e4f99d8cd3e1cdbf87a15eb0b588ffc778f0fdf412c897fb5bf6796ff1295351fcf542c6ea80d1f883b1c3fa6afd817925ecddbda39ac1e16ffc9a59665754cb

data/CHANGELOG.md

@@ -5,9 +5,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.1.1] - 2025-10-06
+## [2.1.2] - 2025-10-17
 
 ### Added
 
-- Visual organization for separate flows in generated diagrams
-- Ability to generate separate diagrams for each flow in a class.
+- Hash-based allow_if for nested state dependencies (411a6b5)

data/README.md

@@ -8,6 +8,7 @@ A lightweight and flexible state machine implementation for Ruby that allows you
 - **Flexible DSL**: Intuitive syntax for defining states and transitions
 - **Dynamic Method Generation**: Automatically creates helper methods for state transitions
 - **Conditional Transitions**: Support for guards and conditional logic
+- **Nested State Dependencies**: State machines can depend on the state of other attributes
 - **Transition Callbacks**: Execute code before, during, or after transitions
 - **Multiple State Machines**: Define multiple independent state machines per class
 - **Framework Agnostic**: Works with plain Ruby objects, no Rails or ActiveRecord required
@@ -93,6 +94,43 @@ class Document
 end
 ```
 
+#### Nested State Dependencies
+
+You can make one state machine depend on another using hash-based `allow_if`:
+
+```ruby
+class Document
+  extend Circulator
+
+  attr_accessor :status, :review_status
+
+  # Review must be completed first
+  flow :review_status do
+    state :pending do
+      action :approve, to: :approved
+    end
+    state :approved
+  end
+
+  # Document status depends on review status
+  flow :status do
+    state :draft do
+      # Can only publish if review is approved
+      action :publish, to: :published, allow_if: {review_status: [:approved]}
+    end
+  end
+end
+
+doc = Document.new
+doc.status = :draft
+doc.review_status = :pending
+
+doc.status_publish  # => blocked, status remains :draft
+
+doc.review_status_approve  # => :approved
+doc.status_publish         # => :published ✓
+```
+
 #### Dynamic Destination States
 
 ```ruby

data/lib/circulator/flow.rb

@@ -23,6 +23,11 @@ module Circulator
     def action(name, to:, from: :__not_specified__, allow_if: nil, &block)
       raise "You must be in a state block or have a `from` option to declare an action" unless defined?(@current_state) || from != :__not_specified__
 
+      # Validate allow_if parameter
+      if allow_if
+        validate_allow_if(allow_if)
+      end
+
       @transition_map[name] ||= {}
       selected_state = (from == :__not_specified__) ? @current_state : from
 
@@ -36,6 +41,13 @@ module Circulator
       states_to_process.each do |from_state|
         from_state = from_state.to_sym if from_state.respond_to?(:to_sym)
         @states.add(from_state)
+
+        # Add the target state to @states if it's not a callable
+        unless to.respond_to?(:call)
+          to_state = to.respond_to?(:to_sym) ? to.to_sym : to
+          @states.add(to_state)
+        end
+
         @transition_map[name][from_state] = {to:, block:}
         @transition_map[name][from_state][:allow_if] = allow_if if allow_if
       end
@@ -67,5 +79,51 @@ module Circulator
         @no_action
       end
     end
+
+    private
+
+    def validate_allow_if(allow_if)
+      # Must be either a Proc or a Hash
+      unless allow_if.is_a?(Proc) || allow_if.is_a?(Hash)
+        raise ArgumentError, "allow_if must be a Proc or Hash, got: #{allow_if.class}"
+      end
+
+      # If it's a Hash, validate the structure
+      if allow_if.is_a?(Hash)
+        validate_hash_allow_if(allow_if)
+      end
+    end
+
+    def validate_hash_allow_if(allow_if_hash)
+      # Must have exactly one key
+      if allow_if_hash.size != 1
+        raise ArgumentError, "allow_if hash must contain exactly one attribute, got: #{allow_if_hash.keys.inspect}"
+      end
+
+      attribute_name, valid_states = allow_if_hash.first
+
+      # Convert attribute name to symbol
+      attribute_name = attribute_name.to_sym if attribute_name.respond_to?(:to_sym)
+
+      # Get model_key from the class name string, not the Class object
+      model_key = Circulator.model_key(@klass.to_s)
+      unless @klass.flows&.dig(model_key, attribute_name)
+        available_flows = @klass.flows&.dig(model_key)&.keys || []
+        raise ArgumentError, "allow_if references undefined flow attribute :#{attribute_name}. Available flows: #{available_flows.inspect}"
+      end
+
+      # Get the states from the referenced flow
+      referenced_flow = @klass.flows.dig(model_key, attribute_name)
+      referenced_states = referenced_flow.instance_variable_get(:@states)
+
+      # Convert valid_states to array of symbols
+      valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
+
+      # Check if all specified states exist in the referenced flow
+      invalid_states = valid_states_array - referenced_states.to_a
+      if invalid_states.any?
+        raise ArgumentError, "allow_if references invalid states #{invalid_states.inspect} for :#{attribute_name}. Valid states: #{referenced_states.to_a.inspect}"
+      end
+    end
   end
 end

data/lib/circulator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Circulator
-  VERSION = "2.1.1"
+  VERSION = "2.1.2"
 end

data/lib/circulator.rb

@@ -129,7 +129,7 @@ module Circulator
     @flows ||= {}
     model_key = Circulator.model_key(model)
     @flows[model_key] ||= {}
-    @flows[model_key][attribute_name] = Flow.new(model, attribute_name, &block)
+    @flows[model_key][attribute_name] = Flow.new(self, attribute_name, &block)
 
     flow_module = ancestors.find { |ancestor|
       ancestor.name.to_s =~ /FlowMethods/
@@ -170,7 +170,23 @@ module Circulator
       end
 
       if transition[:allow_if]
-        return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+        # Handle hash-based allow_if (checking other attribute states)
+        if transition[:allow_if].is_a?(Hash)
+          attribute_name_to_check, valid_states = transition[:allow_if].first
+          current_state = flow_target.send(attribute_name_to_check)
+
+          # Convert current state to symbol if possible
+          current_state = current_state.to_sym if current_state.respond_to?(:to_sym)
+
+          # Convert valid_states to array of symbols
+          valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
+
+          # Return early if current state is not in the valid states
+          return unless valid_states_array.include?(current_state)
+        else
+          # Handle proc-based allow_if (original behavior)
+          return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+        end
       end
 
       if transition[:block]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.1.2
 platform: ruby
 authors:
 - Jim Gay