circulator 2.1.11 → 2.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9232620710fbfe075e26c0ae3bcf1dea0794cdca188b0a9a0ff8529362573ede
-  data.tar.gz: c45d7ac1bdf89fe21107905811d36d0ef4dca37370ea89686d5433cef1aeaaf5
+  metadata.gz: 8004841370c863fdd0910117bf16212a16b2584b9862fb7521637e817006ac9a
+  data.tar.gz: 49c4c8368037c91f0fd2eeb9f1c69654e0db9334d1b6e2cb8c7f34f4e6aa79c3
 SHA512:
-  metadata.gz: bfbc391566c29b7dd18005c56c37c21c9d976eeebc2705f92ea726074b93807daf47528f34e07bb449be3a38bca797067742abc64e1d862162cc18924049b47d
-  data.tar.gz: 9edd59a4985b266ad4c590d3e4d05bbe41f381e85a149b84de08adeabf9e1ff141d0a2b5d5dee759e1e1ba8d4dd740c8e33036331694614951994fddab6d4448
+  metadata.gz: 34ec6da8f78e953350d3a24dbe609cbb15e7a90a0c204fe7ecb023b98e9b6adcc4edcbb700640f7af157f623a2e020d2cf55b7d3b329b028f942e0208d313f0d
+  data.tar.gz: b31bbb831011ca82e47cbd6c1272f561eaecd41d49e4ddde7abce65d212d2bdb4476274d7e1029c5c03946a54daf8ce3540877aeed1b9fb2e51fca1472c8ba71

data/CHANGELOG.md

@@ -5,17 +5,16 @@ 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.11] - 2026-02-09
+## [2.1.13] - 2026-02-24
 
 ### Added
 
-- action_missing alias for no_action to clarify intent (c576a7c)
+- Flow#dup_for method for deep-copying flows to subclasses (4f75b79)
+- Error on redeclaring inherited flow attributes in subclasses (98ca6a7)
+- Extension support for subclasses that inherit parent flows (d73f231)
+- Lazy application of pending extensions via inherited hook (2ed2787)
 
 ### Changed
 
-- Improved inline documentation for no_action and around methods (c576a7c)
-- Added method documentation for Flow DSL methods (2546989)
-
-### Removed
-
-- @no_action internal instance_variable and switched to @action_missing Version: minor (c576a7c)
+- Subclasses of Circulator classes inherit parent flows Version: major (2a63539)
+- Flow methods use dynamic transition lookup for inherited flows (2ed2787)

data/lib/circulator/flow.rb

@@ -219,6 +219,34 @@ module Circulator
       self
     end
 
+    # Create a deep copy of this flow for a different owning class.
+    # Used when a subclass needs its own copy of a parent's flow
+    # (e.g., when applying extensions to an inherited flow).
+    def dup_for(new_klass)
+      copy = self.class.allocate
+      copy.instance_variable_set(:@klass, new_klass)
+      copy.instance_variable_set(:@attribute_name, @attribute_name)
+      copy.instance_variable_set(:@states, @states.dup)
+      # Procs (@action_missing, @flows_proc, @around) are intentionally shared,
+      # not copied. They are stateless closures that work identically across
+      # parent and child classes.
+      copy.instance_variable_set(:@action_missing, @action_missing)
+      copy.instance_variable_set(:@flows_proc, @flows_proc)
+      copy.instance_variable_set(:@around, @around)
+
+      # Deep copy transition map: action => {from_state => {to:, block:, ...}}
+      new_map = @flows_proc.call
+      @transition_map.each do |action, transitions|
+        new_map[action] = @flows_proc.call
+        transitions.each do |from_state, data|
+          new_map[action][from_state] = data.dup
+        end
+      end
+      copy.instance_variable_set(:@transition_map, new_map)
+
+      copy
+    end
+
     private
 
     def validate_allow_if(allow_if)

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -2,6 +2,8 @@ require "circulator/version"
 require "circulator/flow"
 
 module Circulator
+  class InvalidTransition < StandardError; end
+
   # Global registry for extensions
   @extensions = Hash.new { |h, k| h[k] = [] }
 
@@ -77,46 +79,105 @@ module Circulator
 
     private
 
+    # Walk the ancestor chain of +klass+ to find a Flow for +attribute_name+.
+    # Each ancestor is checked under its own model key, since flows are stored
+    # under the declaring class's name.
+    #
+    # Returns the first matching Flow, or nil.
+    def find_inherited_flow(klass, attribute_name)
+      klass.ancestors.drop(1).lazy.filter_map { |a|
+        next unless a.respond_to?(:flows)
+        a_flows = a.instance_variable_get(:@flows)
+        next unless a_flows
+        a_key = Circulator.model_key(a.to_s)
+        a_flows.dig(a_key, attribute_name.to_sym)
+      }.first
+    end
+
+    # Ensure +klass+ has its own local copy of the flow for +attribute_name+.
+    #
+    # If the class already owns a local flow, returns it. Otherwise, looks up
+    # the ancestor chain, deep-copies the inherited flow, stores it on the
+    # child class, and returns the copy.
+    #
+    # Returns the local Flow, or nil if no flow exists anywhere in the chain.
+    def ensure_local_flow(klass, model_key, attribute_name)
+      local_flows = klass.instance_variable_get(:@flows)
+      existing = local_flows&.dig(model_key, attribute_name.to_sym)
+      return existing if existing
+
+      parent_flow = find_inherited_flow(klass, attribute_name)
+      return unless parent_flow
+
+      # Deep-copy parent flow for this subclass
+      copy = parent_flow.dup_for(klass)
+
+      # Store on the child class
+      flows_proc = copy.instance_variable_get(:@flows_proc) || Circulator.default_flow_proc
+      klass.instance_variable_set(:@flows, klass.instance_variable_get(:@flows) || flows_proc.call)
+      klass.instance_variable_get(:@flows)[model_key] ||= flows_proc.call
+      klass.instance_variable_get(:@flows)[model_key][attribute_name.to_sym] = copy
+
+      copy
+    end
+
     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
+        return # Class doesn't exist yet
       end
 
-      # Check if the class has flows and the specific attribute flow
-      return unless klass.respond_to?(:flows) && klass.flows
+      return unless klass.respond_to?(:flows)
 
       model_key = Circulator.model_key(klass.to_s)
-      existing_flow = klass.flows.dig(model_key, attribute_name.to_sym)
+      existing_flow = ensure_local_flow(klass, model_key, attribute_name)
       return unless existing_flow
 
-      # Merge the extension into the existing flow
+      # Merge the extension into the (possibly copied) flow
       existing_flow.merge(&block)
 
-      # Re-define flow methods for any new actions/states
+      # Re-define flow methods for new/changed actions
       redefine_flow_methods(klass, attribute_name, existing_flow)
     end
 
+    # Re-define flow action and state methods after an extension is merged.
+    #
+    # Side effect: if the FlowMethods module found in the ancestor chain
+    # belongs to a parent class, this method creates a new FlowMethods
+    # module on +klass+ so that the parent's methods are not mutated.
     def redefine_flow_methods(klass, attribute_name, flow)
+      # Find an existing FlowMethods module in the ancestor chain
       flow_module = klass.ancestors.find { |ancestor|
         ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
       }
       return unless flow_module
 
+      # If the FlowMethods module belongs to a parent class, create a new
+      # one on the child so we don't mutate the parent's methods.
+      if klass.const_defined?(FLOW_MODULE_NAME.to_sym, false)
+        flow_module = klass.const_get(FLOW_MODULE_NAME.to_sym, false)
+      else
+        flow_module = Module.new
+        klass.include flow_module
+        klass.const_set(FLOW_MODULE_NAME.to_sym, flow_module)
+      end
+
       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("_")
+        base_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)
+        # Remove existing methods so they can be redefined with updated transitions
+        FLOW_VARIANTS.each_value do |suffix|
+          full_name = "#{base_name}#{suffix}"
+          flow_module.remove_method(full_name) if flow_module.method_defined?(full_name)
         end
 
-        klass.send(:define_flow_method, attribute_name:, action:, transitions:, object:, owner: flow_module)
+        FLOW_VARIANTS.each_key do |variant|
+          klass.send(["define", variant, "flow_method"].compact.join("_"), attribute_name:, action:, transitions:, object:, owner: flow_module)
+        end
       end
 
       # Define predicate methods for any new states
@@ -126,9 +187,34 @@ module Circulator
         klass.send(:define_state_method, attribute_name:, state:, object:, owner: flow_module)
       end
     end
+
+    # Apply any pending extensions that were registered before the class existed.
+    #
+    # When Circulator.extension is called for a class that doesn't exist yet,
+    # the extension block is stored in the global registry. This method checks
+    # the registry for extensions matching the given class name and applies them.
+    #
+    # Called from the inherited hook when a subclass is defined, and also
+    # lazily from the flows accessor when the class name becomes available
+    # after class creation (e.g., after Object.const_set).
+    def apply_pending_extensions(klass)
+      class_name = klass.name
+      return unless class_name
+
+      Circulator.extensions.each_key do |key|
+        ext_class_name, ext_attribute = key.split(":", 2)
+        next unless ext_class_name == class_name
+
+        attribute_name = ext_attribute.to_sym
+        Circulator.extensions[key].each do |ext_block|
+          apply_extension_to_existing_flow(class_name, attribute_name, ext_block)
+        end
+      end
+    end
   end
 
   FLOW_MODULE_NAME = "FlowMethods"
+  FLOW_VARIANTS = {:bang => "!", nil => ""}.freeze
 
   # Declare a flow for an attribute.
   #
@@ -269,12 +355,27 @@ module Circulator
   #  # Will log the flow logic according to the with_logging block behavior
   #
   def flow(attribute_name, model: to_s, flows_proc: Circulator.default_flow_proc, &block)
-    @flows ||= flows_proc.call
     model_key = Circulator.model_key(model)
+
+    # Check if a parent class already defines this flow
+    parent_flow = Circulator.send(:find_inherited_flow, self, attribute_name)
+
+    if parent_flow
+      raise ArgumentError,
+        "#{self} inherits a :#{attribute_name} flow from a parent class. " \
+        "Use Circulator.extension(#{self}, :#{attribute_name}) to customize it."
+    end
+
+    @flows ||= flows_proc.call
     @flows[model_key] ||= flows_proc.call
     # Pass the flows_proc to Flow so it can create transition_maps of the same type
     @flows[model_key][attribute_name] = Flow.new(self, attribute_name, flows_proc:, &block)
 
+    # Define InvalidTransition exception on the host class if not already defined
+    unless const_defined?(:InvalidTransition, false)
+      const_set(:InvalidTransition, Class.new(Circulator::InvalidTransition))
+    end
+
     flow_module = ancestors.find { |ancestor|
       ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
     } || Module.new.tap do |mod|
@@ -298,7 +399,9 @@ module Circulator
           states.add(transition_data[:to])
         end
       end
-      define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
+      FLOW_VARIANTS.each_key do |variant|
+        send(["define", variant, "flow_method"].compact.join("_"), attribute_name:, action:, transitions:, object:, owner: flow_module)
+      end
     end
 
     # Define predicate methods for each state (skip nil)
@@ -306,6 +409,15 @@ module Circulator
       next if state.nil?
       define_state_method(attribute_name:, state:, object:, owner: flow_module)
     end
+
+    # Make the attribute writer private so that state changes must go through
+    # the generated flow methods. This prevents bypassing guards and transition
+    # logic by directly assigning the attribute. The writer is only made private
+    # for self-managed flows (not model-based flows where the attribute belongs
+    # to a different class).
+    if object.nil? && method_defined?("#{attribute_name}=")
+      private "#{attribute_name}="
+    end
   end
   alias_method :circulator, :flow
 
@@ -329,10 +441,17 @@ module Circulator
       flow_logic = -> {
         current_value = flow_target.send(attribute_name)
 
+        # Look up transitions dynamically to support inherited+extended flows.
+        # The closure-captured `transitions` may be stale if an extension was
+        # applied after this method was defined (e.g., early extensions on subclasses).
+        # Fall back to the closure-captured transitions if the flow lookup fails.
+        live_flow = flows&.dig(Circulator.model_key(flow_target), attribute_name)
+        current_transitions = live_flow&.transition_map&.[](action) || transitions
+
         transition = if current_value.respond_to?(:to_sym)
-          transitions[current_value.to_sym]
+          current_transitions[current_value.to_sym]
         else
-          transitions[current_value]
+          current_transitions[current_value]
         end
 
         unless transition
@@ -363,6 +482,34 @@ module Circulator
     end
   end
 
+  def define_bang_flow_method(attribute_name:, action:, transitions:, object:, owner:)
+    bang_method = [object, attribute_name, action].compact.join("_") << "!"
+    return if owner.method_defined?(bang_method)
+
+    non_bang_method = [object, attribute_name, action].compact.join("_")
+    owner.define_method(bang_method) do |*args, flow_target: self, **kwargs, &block|
+      current_value = flow_target.send(attribute_name)
+      current_state = current_value.respond_to?(:to_sym) ? current_value.to_sym : current_value
+
+      # Look up transitions dynamically (same rationale as define_flow_method)
+      live_flow = flows&.dig(Circulator.model_key(flow_target), attribute_name)
+      current_transitions = live_flow&.transition_map&.[](action) || transitions
+
+      transition = current_transitions[current_state]
+      unless transition
+        raise self.class.const_get(:InvalidTransition),
+          "No transition #{action} on #{attribute_name} from #{current_state.inspect}"
+      end
+
+      if transition[:allow_if] && !Circulator.evaluate_guard(flow_target, transition[:allow_if], *args, **kwargs)
+        raise self.class.const_get(:InvalidTransition),
+          "Guard prevented #{action} on #{attribute_name} from #{current_state.inspect}"
+      end
+
+      send(non_bang_method, *args, flow_target:, **kwargs, &block)
+    end
+  end
+
   module_function def evaluate_guard(target, allow_if, *args, **kwargs)
     case allow_if
     when Array
@@ -403,22 +550,57 @@ module Circulator
 
   def self.extended(base)
     base.include(InstanceMethods)
-    base.singleton_class.attr_reader :flows
+
+    # Define flows method that walks ancestor chain
+    base.define_singleton_method(:flows) do
+      @flows || ancestors.drop(1).lazy.filter_map { |a|
+        a.instance_variable_get(:@flows) if a.respond_to?(:flows)
+      }.first
+    end
+
+    base.define_singleton_method(:inherited) do |subclass|
+      super(subclass)
+
+      # Track whether pending extensions have been applied for this subclass.
+      # Since inherited fires before the class body block runs (and before
+      # Object.const_set assigns a name), we use lazy application: the first
+      # time flows is accessed on a named subclass, pending extensions are applied.
+      pending_extensions_applied = false
+
+      subclass.define_singleton_method(:flows) do
+        # Lazily apply pending extensions once the class has a name
+        unless pending_extensions_applied
+          if name
+            pending_extensions_applied = true
+            Circulator.send(:apply_pending_extensions, self)
+          end
+        end
+
+        @flows || ancestors.drop(1).lazy.filter_map { |a|
+          a.instance_variable_get(:@flows) if a.respond_to?(:flows)
+        }.first
+      end
+    end
   end
 
   module InstanceMethods
     # Use this method to call an action on the attribute.
     #
+    # Accepts an optional +variant:+ keyword to select a method variant.
+    # See +FLOW_VARIANTS+ for the available variants and their suffixes.
+    #
     # Example:
     #
     #   test_object.flow(:approve, :status)
     #   test_object.flow(:approve, :status, "arg1", "arg2", key: "value")
-    def flow(action, attribute, *args, flow_target: self, **kwargs, &block)
+    #   test_object.flow(:approve, :status, variant: :bang)
+    def flow(action, attribute, *args, flow_target: self, variant: nil, **kwargs, &block)
       target_name = if flow_target != self
         Circulator.methodize_name(Circulator.model_key(flow_target))
       end
       external_attribute_name = [target_name, attribute].compact.join("_")
-      method_name = "#{external_attribute_name}_#{action}"
+      suffix = Circulator::FLOW_VARIANTS.fetch(variant)
+      method_name = "#{external_attribute_name}_#{action}#{suffix}"
       if respond_to?(method_name)
         send(method_name, *args, flow_target:, **kwargs, &block)
       elsif flow_target.respond_to?(method_name)
@@ -426,6 +608,17 @@ module Circulator
       else
         raise "Invalid action for the current state of #{attribute} (#{flow_target.send(attribute).inspect}): #{action}"
       end
+    rescue KeyError
+      raise ArgumentError, "Invalid variant: #{variant.inspect}"
+    end
+
+    # Bang variant of flow that raises InvalidTransition on failure.
+    #
+    # Example:
+    #
+    #   test_object.flow!(:approve, :status)
+    def flow!(action, attribute, *args, **kwargs, &block)
+      flow(action, attribute, *args, variant: :bang, **kwargs, &block)
     end
 
     # Get available actions for an attribute based on current state
@@ -506,8 +699,31 @@ module Circulator
 
     private
 
+    # Returns the class-level flows hash, aliasing the current instance's
+    # model_key to the parent's flow data when needed.
+    #
+    # Why aliasing is needed: flows are stored under the declaring class's
+    # model_key (e.g. "Parent"), but instance lookups use the instance's own
+    # class key (e.g. "Child"). When a subclass inherits flows without
+    # overriding them, there is no entry for the child's key. We add an alias
+    # entry so that dig(child_key, attribute) resolves correctly.
+    #
+    # The mutation is safe because the alias is idempotent (same value each
+    # time) and just adds a pointer to existing data.
     def flows
-      self.class.flows
+      raw_flows = self.class.flows
+      return nil unless raw_flows
+
+      my_key = Circulator.model_key(self)
+      return raw_flows if raw_flows.key?(my_key)
+
+      # Find the ancestor whose model_key matches a key in the flows hash
+      parent_key = raw_flows.keys.find { |k| raw_flows[k].is_a?(Hash) || raw_flows[k].respond_to?(:dig) }
+      return raw_flows unless parent_key
+
+      # Alias in place — avoids allocating a new Hash on every call.
+      raw_flows[my_key] = raw_flows[parent_key]
+      raw_flows
     end
 
     def check_allow_if(allow_if, *args, **kwargs)

metadata

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