circulator 2.1.4 → 2.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9126192a7ce18956bc8c27842e52765dac25e9436e322ad259100e5138a5b97f
-  data.tar.gz: f1e15524d5806a3f0b0455bd006e8ba5e3914b13e046ab0d2acd1dbcb897ea27
+  metadata.gz: 4c511772e424334259794bfff3d3507e5740fc98f0a130c66bf1d77a41862f6a
+  data.tar.gz: 7ee239ac23cbd6998a6d1689f8d6729983b42a6d6081e092465483ee19013107
 SHA512:
-  metadata.gz: 03ad68c5d43c45fddf1b7d5c3f84dd845363b2bf8cc1a881463efbd1b1e43d233e196e965dae157726b2ac0b90066d9ec05087f12339667ffd1e9effe0213e54
-  data.tar.gz: 7590c58b27a608f4d49f6041c9fed8a4fd5a05526cd5c36eba40a12346ce5a63cd6f9f0a6253c48ec6aa7405e9e4b5ed8121fae276404a1a32f4587118453c2f
+  metadata.gz: 63e6165e93a276d89ac6c469c3e8b5db41e6b184cde3290a9ff1332992e7f27a06cf1cd8f8b93c32100986c27be3761d0cfbc9ef7c69414b0cd379f32813c018
+  data.tar.gz: 586cdd39db8b98b10465e84c02de948a44f39c556ae270ea6a68ea8f90ca8c0b61af37917419dfe599e39e882584101169f932671996edbeeb97d6e9debe806d

data/CHANGELOG.md

@@ -5,24 +5,10 @@ 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.4] - 2025-11-03
+## [2.1.5] - 2025-11-15
 
 ### Added
 
-- Symbol-based allow_if support (a96b794)
-- Documentation for symbol-based allow_if (d3befc1)
-- available_flows method with guard and argument support (122e2ab)
-- available_flow? predicate method (122e2ab)
-- Documentation for query methods (a75507e)
-
-### Changed
-
-- Validate symbol allow_if at definition time (392eac5)
-
-### Removed
-
-- Redundant respond_to? check (40ff669)
-
-### Fixed
-
-- DOT syntax error for states ending with ? (65b503e)
+- Circulator.extension to define changes to existing state machines. (0f0a50f)
+- Circulator.default_flow_proc to allow for custom storage objects. (7ddc442)
+- Test support for custom flows storage with libraries like Contours::BlendedHash. (c7f1f26)

data/lib/circulator/flow.rb

@@ -2,13 +2,19 @@
 
 module Circulator
   class Flow
-    def initialize(klass, attribute_name, states = Set.new, &block)
+    def initialize(klass, attribute_name, states = Set.new, extension: false, flows_proc: Circulator.default_flow_proc, &block)
       @klass = klass
       @attribute_name = attribute_name
       @states = states
       @no_action = ->(attribute_name, action) { raise "No action found for the current state of #{attribute_name} (#{send(attribute_name)}): #{action}" }
-      @transition_map = {}
-      instance_eval(&block)
+      @flows_proc = flows_proc
+      @transition_map = flows_proc.call
+
+      # Execute the main flow block
+      instance_eval(&block) if block
+
+      # Apply any registered extensions (unless explicitly disabled)
+      apply_extensions unless extension
     end
     attr_reader :transition_map
 
@@ -28,7 +34,7 @@ module Circulator
         validate_allow_if(allow_if)
       end
 
-      @transition_map[name] ||= {}
+      @transition_map[name] ||= @flows_proc.call
       selected_state = (from == :__not_specified__) ? @current_state : from
 
       # Handle nil case specially - convert to [nil] instead of []
@@ -48,8 +54,10 @@ module Circulator
           @states.add(to_state)
         end
 
-        @transition_map[name][from_state] = {to:, block:}
-        @transition_map[name][from_state][:allow_if] = allow_if if allow_if
+        # Build transition data hash with all keys at once
+        transition_data = {to:, block:}
+        transition_data[:allow_if] = allow_if if allow_if
+        @transition_map[name][from_state] = transition_data
       end
     end
 
@@ -132,5 +140,33 @@ module Circulator
         raise ArgumentError, "allow_if references invalid states #{invalid_states.inspect} for :#{attribute_name}. Valid states: #{referenced_states.to_a.inspect}"
       end
     end
+
+    def apply_extensions
+      # Look up extensions for this class and attribute
+      class_name = if @klass.is_a?(Class)
+        @klass.name || @klass.to_s
+      else
+        Circulator.model_key(@klass)
+      end
+      key = "#{class_name}:#{@attribute_name}"
+      extensions = Circulator.extensions[key]
+
+      # Apply each extension by creating a new Flow and merging its transition_map
+      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
+      end
+    end
   end
 end

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -2,6 +2,32 @@ require "circulator/version"
 require "circulator/flow"
 
 module Circulator
+  # Global registry for extensions
+  @extensions = Hash.new { |h, k| h[k] = [] }
+
+  @default_flow_proc = ::Hash.method(:new)
+  class << self
+    attr_reader :extensions
+    attr_reader :default_flow_proc
+
+    # Register an extension for a specific class and attribute
+    #
+    # Example:
+    #
+    #   Circulator.extension(:Document, :status) do
+    #     state :pending do
+    #       action :send_to_legal, to: :legal_review
+    #     end
+    #   end
+    #
+    # Extensions are automatically applied when the class defines its flow
+    def extension(class_name, attribute_name, &block)
+      raise ArgumentError, "Block required for extension" unless block_given?
+
+      key = "#{class_name}:#{attribute_name}"
+      @extensions[key] << block
+    end
+  end
   # Declare a flow for an attribute.
   #
   # Specify the attribute to be used for states and actions.
@@ -125,11 +151,12 @@ module Circulator
   #  test_object.flow(:unknown, :status, "signal")
   #  # Will raise an UnhandledSignalError
   #
-  def flow(attribute_name, model: to_s, &block)
-    @flows ||= {}
+  def flow(attribute_name, model: to_s, flows_proc: Circulator.default_flow_proc, &block)
+    @flows ||= flows_proc.call
     model_key = Circulator.model_key(model)
-    @flows[model_key] ||= {}
-    @flows[model_key][attribute_name] = Flow.new(self, attribute_name, &block)
+    @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)
 
     flow_module = ancestors.find { |ancestor|
       ancestor.name.to_s =~ /FlowMethods/

metadata

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