circulator 2.1.6 → 2.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 128d49edd784a3a0cc8ebc72ee4ca9be581bbea4ab57ff795a7c7435a52e3ddb
-  data.tar.gz: ae4a7ca3dd48197e944c95516f862e9f08cbc082ad098d0ef3d589fe351d59c7
+  metadata.gz: 63f6c8044ac3e21dffede73e1345d33d2e1e3f77350bcd6b332df8508d810f1f
+  data.tar.gz: 65ef2f903e7ec29993e1bbf7cf7b522c0d7bcba0cd424c75a7271ff0a89478db
 SHA512:
-  metadata.gz: 5792c5c3fc86dc3a7d75fd619229426a3a8ae8198bee46fe28d7ec54f3d78ca374732c71281177fb53a8e54d5f1ed256af8163cd70420739b4450fb0f5b0589d
-  data.tar.gz: f7fc9e7bf3e10331306a3161c7feff64e09b0dd1933f52f054f98076256c2287e40c6ddd7ac7b6c7eee39bb55442ca3f3045179cc889378d87b9c59eb74dc971
+  metadata.gz: c06f5b31e89fdd3832c8339b6884546b72b651395c2ca0a81cd37767f0a482dac2507ab45120bfe95fcaa950d6359080170859cb6ff1db61c485b165386df99d
+  data.tar.gz: 7a9f34b128d42a5c1ef9c45b806de26ac318bd822df6fbb6d35ffaa3df8384ac0dda2833057076cbb6715a30d98685a4eda03c73e6c2352a2d5682fa8a0c3260

data/CHANGELOG.md

@@ -5,14 +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.6] - 2025-12-08
+## [2.1.7] - 2026-01-06
 
-### Changed
+### Added
 
-- Dependabot config to follow a 14 day cooldown. (6aabc0a)
+- Use an array of mulitple symbols with allow_if guard clauses. (96b66e6)
 
-### Added
+### Changed
 
-- Documentation for extension system and Circulator.extension API (be7c6fc)
-- --all flag to automatically discover and generate diagrams for all classes with Circulator flows (f4dbbfc)
-- Automatic eager loading of Rails application classes when using --all (f4dbbfc)
+- Documentation of lib/circulator.rb and explain extensions in README.md (7a04d58)

data/README.md

@@ -173,6 +173,14 @@ end
 
 This is equivalent to the proc-based approach but cleaner when you have a dedicated method for the condition.
 
+You can also use an array of symbols to represent multiple conditions:
+
+```ruby
+action :publish, to: :published, allow_if: [:ready_to_publish?, :reviewed_by_present?]
+```
+
+This is equivalent to the proc-based approach but cleaner when you have multiple conditions.
+
 **Hash-based guards** check the state of another attribute:
 
 You can make one state machine depend on another using hash-based `allow_if`:
@@ -287,7 +295,9 @@ end
 
 #### Extending Flows
 
-You can extend existing flows using `Circulator.extension`:
+You can extend existing flows using `Circulator.extension`. This is useful for plugins, multi-tenant applications, or conditional feature enhancement. Extensions are registered globally and automatically applied when a class defines its flow.
+
+**Basic Extension Example:**
 
 ```ruby
 class Document
@@ -308,7 +318,7 @@ class Document
   end
 end
 
-# Add additional states and transitions
+# Register extension - can be in a separate file or initializer
 Circulator.extension(:Document, :status) do
   state :review do
     action :reject, to: :rejected
@@ -319,12 +329,89 @@ Circulator.extension(:Document, :status) do
   end
 end
 
+# Extensions are automatically applied when class is loaded
 doc = Document.new
 doc.status = :review
 doc.status_reject  # => :rejected (from extension)
 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).
+
+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.
+
+**Plugin-Style Extensions:**
+
+Extensions are perfect for gems that want to extend Circulator workflows without modifying the host application:
+
+```ruby
+# gem_name/lib/gem_name.rb
+Circulator.extension(:BlogPost, :status) do
+  state :draft do
+    action :generate_seo, to: :draft do
+      generate_meta_tags
+    end
+  end
+
+  state :published do
+    action :schedule_social, to: :published do
+      queue_social_sharing
+    end
+  end
+end
+
+# Host application doesn't need to know about the plugin's extensions
+class BlogPost
+  extend Circulator
+
+  flow :status do
+    state :draft do
+      action :publish, to: :published
+    end
+    state :published
+  end
+end
+
+# Plugin actions are automatically available
+post = BlogPost.new
+post.status = :draft
+post.status_generate_seo  # From plugin extension
+post.status_publish       # From base flow
+```
+
+**Conditional Extensions Based on Feature Flags:**
+
+```ruby
+# config/initializers/circulator_extensions.rb
+if ENV['ENABLE_APPROVAL_WORKFLOW']
+  Circulator.extension(:Document, :status) do
+    state :draft do
+      action :submit_for_approval, to: :approval
+    end
+
+    state :approval do
+      action :approve, to: :approved
+      action :reject, to: :draft
+    end
+
+    state :approved
+  end
+end
+
+# Base flow always available, additional workflow only when enabled
+class Document
+  extend Circulator
+
+  flow :status do
+    state :draft do
+      action :save, to: :draft
+    end
+  end
+end
+```
+
 ### Generating Diagrams
 
 You can generate diagrams for your Circulator models using the `circulator-diagram` executable. By default, it will generate a DOT file. You can also generate a PlantUML file by passing the `-f plantuml` option.

data/lib/circulator/flow.rb

@@ -98,8 +98,10 @@ module Circulator
         validate_symbol_allow_if(allow_if)
       in Hash
         validate_hash_allow_if(allow_if)
+      in Array
+        validate_array_allow_if(allow_if)
       else
-        raise ArgumentError, "allow_if must be a Proc, Hash, or Symbol, got: #{allow_if.class}"
+        raise ArgumentError, "allow_if must be a Proc, Hash, Symbol, or Array, got: #{allow_if.class}"
       end
     end
 
@@ -141,6 +143,25 @@ module Circulator
       end
     end
 
+    def validate_array_allow_if(allow_if_array)
+      # Array must not be empty
+      if allow_if_array.empty?
+        raise ArgumentError, "allow_if array must not be empty"
+      end
+
+      # First, validate all element types
+      allow_if_array.each do |element|
+        unless element.is_a?(Symbol) || element.is_a?(Proc)
+          raise ArgumentError, "allow_if array elements must be Symbols or Procs, got: #{element.class}"
+        end
+      end
+
+      # Then, validate that Symbol methods exist
+      allow_if_array.each do |element|
+        validate_symbol_allow_if(element) if element.is_a?(Symbol)
+      end
+    end
+
     def apply_extensions
       # Look up extensions for this class and attribute
       class_name = if @klass.is_a?(Class)

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -7,20 +7,64 @@ module Circulator
 
   @default_flow_proc = ::Hash.method(:new)
   class << self
+    # Returns the global registry of registered extensions
+    #
+    # The registry is a Hash where keys are "ClassName:attribute_name" strings
+    # and values are Arrays of extension blocks.
+    #
+    # Example:
+    #
+    #   Circulator.extensions["Document:status"]
+    #   # => [<Proc>, <Proc>]  # Array of extension blocks
     attr_reader :extensions
+
+    # The default Proc used to create transition_maps for flows
+    #
+    # By default, this returns Hash.method(:new), which creates regular Hashes.
+    # Can be overridden to use custom storage implementations (e.g., any Hash-like object
+    # with custom merge behavior) by setting @default_flow_proc before defining flows.
     attr_reader :default_flow_proc
 
     # Register an extension for a specific class and attribute
     #
+    # Extensions allow you to add additional states and transitions to existing flows
+    # without modifying the original class definition. This is useful for:
+    # - Plugin gems extending host application workflows
+    # - Multi-tenant applications with customer-specific flows
+    # - Conditional feature enhancement based on configuration
+    #
+    # Extensions are registered globally and automatically applied when the class
+    # defines its flow. Multiple extensions can be registered for the same class/attribute.
+    #
     # Example:
     #
     #   Circulator.extension(:Document, :status) do
     #     state :pending do
     #       action :send_to_legal, to: :legal_review
     #     end
+    #
+    #     state :legal_review do
+    #       action :approve, to: :approved
+    #     end
     #   end
     #
-    # Extensions are automatically applied when the class defines its flow
+    # Merging behavior (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).
+    #
+    # Custom merging:
+    # To implement intelligent composition where extensions add conditions/blocks additively,
+    # pass a custom flows_proc parameter to your flow() definition that creates a Hash-like
+    # object with custom merge logic.
+    #
+    # Extension registration must happen before class definition (typically in initializers).
+    #
+    # Arguments:
+    # - class_name: Symbol or String - Name of class being extended
+    # - attribute_name: Symbol or String - Name of the flow attribute
+    # - block: Required block containing state and action definitions
+    #
+    # Raises ArgumentError if no block provided.
     def extension(class_name, attribute_name, &block)
       raise ArgumentError, "Block required for extension" unless block_given?
 
@@ -223,8 +267,18 @@ module Circulator
       end
 
       if transition[:allow_if]
+        # Handle array-based allow_if (array of symbols and/or procs)
+        if transition[:allow_if].is_a?(Array)
+          return unless transition[:allow_if].all? do |guard|
+            case guard
+            when Symbol
+              flow_target.send(guard, *args, **kwargs)
+            when Proc
+              flow_target.instance_exec(*args, **kwargs, &guard)
+            end
+          end
         # Handle hash-based allow_if (checking other attribute states)
-        if transition[:allow_if].is_a?(Hash)
+        elsif 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)
 
@@ -341,6 +395,45 @@ module Circulator
       available_flows(attribute, *args, **kwargs).include?(action)
     end
 
+    # Get the guard methods for a specific transition
+    #
+    # Returns an array of Symbol method names if the guard is an array of symbols,
+    # or nil if no guard or guard is not an array.
+    #
+    # Example:
+    #
+    #   class Order
+    #     extend Circulator
+    #     flow(:status) do
+    #       state :pending do
+    #         action :approve, to: :approved, allow_if: [:approved?, :in_budget?]
+    #       end
+    #     end
+    #   end
+    #
+    #   order = Order.new
+    #   order.guards_for(:status, :approve)
+    #   # => [:approved?, :in_budget?]
+    def guards_for(attribute, action)
+      model_key = Circulator.model_key(self)
+      flow = flows.dig(model_key, attribute)
+      return nil unless flow
+
+      current_value = send(attribute)
+      current_state = current_value.respond_to?(:to_sym) ? current_value.to_sym : current_value
+
+      transition = flow.transition_map.dig(action, current_state)
+      return nil unless transition
+
+      guard = transition[:allow_if]
+      return nil unless guard
+
+      # If guard is an array, return only the Symbol elements
+      if guard.is_a?(Array)
+        guard.select { |g| g.is_a?(Symbol) }
+      end
+    end
+
     private
 
     def flows
@@ -349,6 +442,16 @@ module Circulator
 
     def check_allow_if(allow_if, *args, **kwargs)
       case allow_if
+      when Array
+        # All guards in array must be true (AND logic)
+        allow_if.all? do |guard|
+          case guard
+          when Symbol
+            send(guard, *args, **kwargs)
+          when Proc
+            instance_exec(*args, **kwargs, &guard)
+          end
+        end
       when Hash
         attribute_name, valid_states = allow_if.first
         current_state = send(attribute_name)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.1.6
+  version: 2.1.7
 platform: ruby
 authors:
 - Jim Gay
@@ -46,7 +46,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Simple state machine
 test_files: []