feat: add async support with declarative async: true parameter (#144)

release-as: 0.40.0

Author: seuros

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
     ".": "0.31.0"
-}
+}

Gemfile

@@ -12,3 +12,11 @@ gem 'rubocop', require: false
 gem 'rubocop-minitest', require: false
 
 gem 'rubocop-rake', require: false
+
+# Async support dependencies (MRI Ruby only)
+# These gems are required for StateMachines::AsyncMode functionality
+# and are loaded conditionally based on Ruby engine compatibility
+platform :ruby do
+  gem 'async', require: false
+  gem 'concurrent-ruby', require: false
+end

coss.toml

@@ -139,4 +139,4 @@ state_machines-activemodel = "https://github.com/state-machines/state_machines-a
 state_machines-activerecord = "https://github.com/state-machines/state_machines-activerecord"
 state_machines-audit_trail = "https://github.com/state-machines/state_machines-audit_trail"
 state_machines-graphviz = "https://github.com/state-machines/state_machines-graphviz"
-state_machines-yard = "https://github.com/state-machines/state_machines-yard"
+state_machines-yard = "https://github.com/state-machines/state_machines-yard"

lib/state_machines/async_mode.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Ruby Engine Compatibility Check
+# The async gem requires native extensions and Fiber scheduler support
+# which are not available on JRuby or TruffleRuby
+if RUBY_ENGINE == 'jruby' || RUBY_ENGINE == 'truffleruby'
+  raise LoadError, <<~ERROR
+    StateMachines::AsyncMode is not available on #{RUBY_ENGINE}.
+
+    The async gem requires native extensions (io-event) and Fiber scheduler support
+    which are not implemented in #{RUBY_ENGINE}. AsyncMode is only supported on:
+
+    • MRI Ruby (CRuby) 3.2+
+    • Other Ruby engines with full Fiber scheduler support
+
+    If you need async support on #{RUBY_ENGINE}, consider using:
+    • java.util.concurrent classes (JRuby)
+    • Native threading libraries for your platform
+    • Or stick with synchronous state machines
+  ERROR
+end
+
+# Load required gems with version constraints
+gem 'async', '>= 2.25.0'
+gem 'concurrent-ruby', '>= 1.3.5'  # Security is not negotiable - enterprise-grade thread safety required
+
+require 'async'
+require 'concurrent-ruby'
+
+# Load all async mode components
+require_relative 'async_mode/thread_safe_state'
+require_relative 'async_mode/async_events'
+require_relative 'async_mode/async_event_extensions'
+require_relative 'async_mode/async_machine'
+require_relative 'async_mode/async_transition_collection'
+
+module StateMachines
+  # AsyncMode provides asynchronous state machine capabilities using the async gem
+  # This module enables concurrent, thread-safe state operations for high-performance applications
+  #
+  # @example Basic usage
+  #   class AutonomousDrone < StarfleetShip
+  #     state_machine :teleporter_status, async: true do
+  #       event :power_up do
+  #         transition offline: :charging
+  #       end
+  #     end
+  #   end
+  #
+  #   drone = AutonomousDrone.new
+  #   Async do
+  #     result = drone.fire_event_async(:power_up)  # => true
+  #     task = drone.power_up_async!               # => Async::Task
+  #   end
+  #
+  module AsyncMode
+    # All components are loaded from separate files:
+    # - ThreadSafeState: Mutex-based thread safety
+    # - AsyncEvents: Async event firing methods
+    # - AsyncEventExtensions: Event method generation
+    # - AsyncMachine: Machine-level async capabilities
+    # - AsyncTransitionCollection: Concurrent transition execution
+  end
+end

lib/state_machines/async_mode/async_event_extensions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Extensions to Event class for async bang methods
+    module AsyncEventExtensions
+      # Generate async bang methods for events when async mode is enabled
+      def define_helper(scope, method, *args, &block)
+        result = super
+
+        # If this is an async-enabled machine and we're defining an event method
+        if scope == :instance && method !~ /_async[!]?$/ && machine.async_mode_enabled?
+          qualified_name = method.to_s
+
+          # Create async version that returns a task
+          machine.define_helper(scope, "#{qualified_name}_async") do |machine, object, *method_args, **kwargs|
+            # Find the machine that has this event
+            target_machine = object.class.state_machines.values.find { |m| m.events[name] }
+
+            unless defined?(::Async::Task) && ::Async::Task.current?
+              raise RuntimeError, "#{qualified_name}_async must be called within an Async context"
+            end
+
+            Async do
+              target_machine.events[name].fire(object, *method_args, **kwargs)
+            end
+          end
+
+          # Create async bang version that raises exceptions when awaited
+          machine.define_helper(scope, "#{qualified_name}_async!") do |machine, object, *method_args, **kwargs|
+            # Find the machine that has this event
+            target_machine = object.class.state_machines.values.find { |m| m.events[name] }
+
+            unless defined?(::Async::Task) && ::Async::Task.current?
+              raise RuntimeError, "#{qualified_name}_async! must be called within an Async context"
+            end
+
+            Async do
+              # Use fire method which will raise exceptions on invalid transitions
+              target_machine.events[name].fire(object, *method_args, **kwargs) || raise(StateMachines::InvalidTransition.new(object, target_machine, name))
+            end
+          end
+        end
+
+        result
+      end
+    end
+  end
+end