circulator 2.1.8 → 2.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad89c887b2b9cb0b3fc2a12bb0a8da92480828f4d8bb594700233f4b1c0ee9fd
-  data.tar.gz: 4400d66545332b1bd4bc09028611efe7ce04a06076520e1f8a860f3089bb8d49
+  metadata.gz: 7d069df555d7f1ac9aa1865cacef2c3bda5373a287c899f23068abe56cf3c379
+  data.tar.gz: c79dbba353dbe721587f3361599385a280a93f9c9655b4fcae01de5359ec8f1e
 SHA512:
-  metadata.gz: 31d7f74c6167dd0c0e51180d8cb585a5da27a9cab543bc32b0ec2da1c819ccd0cff3920446b94496baa36cf2b4005610f535054ce863a08f2ac691ca6ee70ff2
-  data.tar.gz: 4fcf8a370b45aa9d883c5ce4b10f4b714b66c5d5f4f5cdf638281ee01f5636687505c1be94297e5abb072f1de5db8b082edd500cd0b9ccaa769a08a280de743e
+  metadata.gz: ca22e7ae65647826445f17464a74427524bda9fa4d3fa8cb34a1ff47bc8f6c036c5f35a624de6c6853334677add37decd5f27fcbe19bfcb5e4c9edd54606d8f9
+  data.tar.gz: d7c0c520cda68eee6e470a66fa8be95c3f332a3b36bb1314964a2c55f51a763667a2de745c0ea65a319e83eaf5b475cf1303a5961e67877fdbadb4154596ed37

data/CHANGELOG.md

@@ -5,8 +5,12 @@ 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.8] - 2026-01-07
+## [2.1.9] - 2026-01-08
 
 ### Added
 
-- Detailed conditional information display in DOT and PlantUML diagrams (dce5b69)
+- Flow#merge to merge existing flows with extensions (d1eb47d)
+
+### Changed
+
+- Circulator.extension applies immediately to existing flows (d1eb47d)

data/README.md

@@ -338,7 +338,7 @@ doc.status_revise  # => :draft (from extension)
 
 **How Extensions Work:**
 
-Extensions are registered globally using `Circulator.extension(class_name, attribute)` and are automatically applied when the class defines its flow. Multiple extensions can be registered for the same class/attribute and are applied in registration order. Extensions must be registered before the class definition (typically in initializers).
+Extensions are registered globally using `Circulator.extension(class_name, attribute)` and are automatically applied when the class defines its flow. Multiple extensions can be registered for the same class/attribute and are applied in registration order. Extensions can be registered before or after the class definition—if registered after, they are applied immediately to the existing flow.
 
 By default, when an extension defines the same action from the same state as the base flow, the extension completely replaces the base definition (last-defined wins). To implement intelligent composition where extensions add their conditions/blocks additively, your application can configure a custom `flows_proc` that uses a Hash-like object with merge logic. Circulator remains dependency-free and supports any compatible Hash implementation.
 

data/lib/circulator/flow.rb

@@ -88,6 +88,34 @@ module Circulator
       end
     end
 
+    # Merge an extension block into this flow
+    #
+    # Creates an extension flow from the block and merges its transitions
+    # and states into this flow. Returns self for convenience.
+    #
+    # Example:
+    #
+    #   existing_flow.merge do
+    #     state :pending do
+    #       action :send_to_legal, to: :legal_review
+    #     end
+    #   end
+    #
+    def merge(&block)
+      extension_flow = Flow.new(@klass, @attribute_name, @states, extension: true, flows_proc: @flows_proc, &block)
+
+      # Merge transition map
+      extension_flow.transition_map.each do |action, transitions|
+        @transition_map[action] = if @transition_map[action]
+          @transition_map[action].merge(transitions)
+        else
+          transitions
+        end
+      end
+
+      self
+    end
+
     private
 
     def validate_allow_if(allow_if)
@@ -172,21 +200,9 @@ module Circulator
       key = "#{class_name}:#{@attribute_name}"
       extensions = Circulator.extensions[key]
 
-      # Apply each extension by creating a new Flow and merging its transition_map
+      # Apply each extension using merge
       extensions.each do |extension_block|
-        extension_flow = Flow.new(@klass, @attribute_name, @states, extension: true, flows_proc: @flows_proc, &extension_block)
-        extension_flow.transition_map.each do |action, transitions|
-          @transition_map[action] = if @transition_map[action]
-            @transition_map[action].merge(transitions)
-          else
-            transitions
-          end
-        end
-
-        # Merge states from extension
-        extension_flow.instance_variable_get(:@states).each do |state|
-          @states.add(state)
-        end
+        merge(&extension_block)
       end
     end
   end

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -70,8 +70,66 @@ module Circulator
 
       key = "#{class_name}:#{attribute_name}"
       @extensions[key] << block
+
+      # If the class already exists and has flows defined, apply the extension immediately
+      apply_extension_to_existing_flow(class_name, attribute_name, block)
+    end
+
+    private
+
+    def apply_extension_to_existing_flow(class_name, attribute_name, block)
+      # Try to get the class constant
+      klass = begin
+        Object.const_get(class_name.to_s)
+      rescue NameError
+        return # Class doesn't exist yet, extension will be applied when flow is defined
+      end
+
+      # Check if the class has flows and the specific attribute flow
+      return unless klass.respond_to?(:flows) && klass.flows
+
+      model_key = Circulator.model_key(klass.to_s)
+      existing_flow = klass.flows.dig(model_key, attribute_name.to_sym)
+      return unless existing_flow
+
+      # Merge the extension into the existing flow
+      existing_flow.merge(&block)
+
+      # Re-define flow methods for any new actions/states
+      redefine_flow_methods(klass, attribute_name, existing_flow)
+    end
+
+    def redefine_flow_methods(klass, attribute_name, flow)
+      flow_module = klass.ancestors.find { |ancestor|
+        ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
+      }
+      return unless flow_module
+
+      object = nil # Extensions only work on the same class model
+
+      # Define or redefine methods for actions (need to redefine if transitions changed)
+      flow.transition_map.each do |action, transitions|
+        method_name = [object, attribute_name, action].compact.join("_")
+
+        # Remove existing method so it can be redefined with updated transitions
+        if flow_module.method_defined?(method_name)
+          flow_module.remove_method(method_name)
+        end
+
+        klass.send(:define_flow_method, attribute_name: attribute_name, action: action, transitions: transitions, object: object, owner: flow_module)
+      end
+
+      # Define predicate methods for any new states
+      states = flow.instance_variable_get(:@states)
+      states.each do |state|
+        next if state.nil?
+        klass.send(:define_state_method, attribute_name: attribute_name, state: state, object: object, owner: flow_module)
+      end
     end
   end
+
+  FLOW_MODULE_NAME = "FlowMethods"
+
   # Declare a flow for an attribute.
   #
   # Specify the attribute to be used for states and actions.
@@ -203,11 +261,11 @@ module Circulator
     @flows[model_key][attribute_name] = Flow.new(self, attribute_name, flows_proc:, &block)
 
     flow_module = ancestors.find { |ancestor|
-      ancestor.name.to_s =~ /FlowMethods/
+      ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
     } || Module.new.tap do |mod|
       include mod
 
-      const_set(:FlowMethods, mod)
+      const_set(FLOW_MODULE_NAME.to_sym, mod)
     end
 
     object = if model == to_s

metadata

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