circulator 2.1.11 → 2.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9232620710fbfe075e26c0ae3bcf1dea0794cdca188b0a9a0ff8529362573ede
-  data.tar.gz: c45d7ac1bdf89fe21107905811d36d0ef4dca37370ea89686d5433cef1aeaaf5
+  metadata.gz: d7dbf52b54ebf9536c2d5cac336376e6fa1fadbdd614794bd7322349c714bbc0
+  data.tar.gz: c81382ec182f2d2b2b4f13d73c8228675efed7f5f5ee80886a58d8b77820db76
 SHA512:
-  metadata.gz: bfbc391566c29b7dd18005c56c37c21c9d976eeebc2705f92ea726074b93807daf47528f34e07bb449be3a38bca797067742abc64e1d862162cc18924049b47d
-  data.tar.gz: 9edd59a4985b266ad4c590d3e4d05bbe41f381e85a149b84de08adeabf9e1ff141d0a2b5d5dee759e1e1ba8d4dd740c8e33036331694614951994fddab6d4448
+  metadata.gz: c996bdd7a378930fbf14cdfabad9b83b099db386932ea6fab946c38bcd5d649dce25bbc2730b87747b5f46937b55727a06964e8930154b4da23745cf27cdb757
+  data.tar.gz: 24cd2abfe4e710269d4a3a39ed9606bb158b395fa66fa83c5892e9cc060850131c9d9704693a214762eed2efe97ec39a64e4b97378f2e6bda98a1f52ef5adcdf

data/CHANGELOG.md

@@ -5,17 +5,17 @@ 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.12] - 2026-02-17
 
 ### Added
 
-- action_missing alias for no_action to clarify intent (c576a7c)
+- Named test sampler classes for reuse across test files (b6bcb4e)
+- bang method variants for flow actions (673d8a0)
+- Circulator::InvalidTransition exception class (673d8a0)
+- host-namespaced InvalidTransition subclass per class with flows (673d8a0)
+- flow! instance method and variant: keyword on flow (673d8a0)
+- FLOW_VARIANTS registry that drives method definition (673d8a0)
 
 ### 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)
+- Flow attribute writers are private after flow definition Version: minor (35ea18f)

data/lib/circulator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Circulator
-  VERSION = "2.1.11"
+  VERSION = "2.1.12"
 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] = [] }
 
@@ -109,14 +111,17 @@ module Circulator
 
       # 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
@@ -129,6 +134,7 @@ module Circulator
   end
 
   FLOW_MODULE_NAME = "FlowMethods"
+  FLOW_VARIANTS = {:bang => "!", nil => ""}.freeze
 
   # Declare a flow for an attribute.
   #
@@ -275,6 +281,11 @@ module Circulator
     # 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 +309,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 +319,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
 
@@ -363,6 +385,30 @@ 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
+
+      transition = 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
@@ -409,16 +455,21 @@ module Circulator
   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 +477,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

metadata

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