philiprehberger-state_machine 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9866b1db838f27de8926074d6ab88834f6a2dcf79738257ae626f1deab522386
-  data.tar.gz: fd8688dc4a75f72ce8095c933b5461c15fe8949a40d09f969ecb750bb9f2cf21
+  metadata.gz: 885a98621c6e7398bd5ae50b824fd6cc439c5b009fb26bbd648cf8fe46205127
+  data.tar.gz: 211673e70044114428a3624a5372da6cb5e419bde101b7fd93a98b2d9a7b8244
 SHA512:
-  metadata.gz: 3bf30e72a74ac2709efd90e113bfbe1b034bdbebb82efe6b5f06002502906c7344f48163834d229c5525c8020064a7204d10f620f2e576973bbbcca533b01fc3
-  data.tar.gz: ea1aeeb97241ce622d202522fe26cb17ffeac1b52d4a2bb5ef927a55ae2d6d19b1755c2f11bd6a1bd215d25b0c0b56ca339d7572cf6534ae820ab4feea50a7f5
+  metadata.gz: 8d7e14bbf7d1d91d8052fb0ccb75d1097e928137d88d9965366acd924602299a89f83b7feb0306899b39aaeefdcad5dc00b575d11042b6985ad9249d319a93b7
+  data.tar.gz: c8463b4fede47754b81bf508b82cfaf6a71f84d825b2aaf047fac2f46b8da69de0d199b990206674772797d6f2851e234d7e43e562b314dab2a6858bddd16155

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-05-08
+
+### Added
+- `#can_transition_to?(state, **payload)` — returns `true` when any currently-fireable event would land the machine in `state`. Honours guards (a guarded-out transition reports `false`) and raises `ArgumentError` for unknown states. Useful for UI gating without hand-rolling the per-event lookup.
+
 ## [0.7.0] - 2026-04-24
 
 ### Added

data/README.md

@@ -114,11 +114,13 @@ Query the state machine at runtime:
 ```ruby
 order = Order.new
 
-order.pending?            # => true
-order.paid?               # => false
-order.can_pay?            # => true
-order.can_ship?           # => false
-order.allowed_transitions # => [:pay]
+order.pending?              # => true
+order.paid?                 # => false
+order.can_pay?              # => true
+order.can_ship?             # => false
+order.allowed_transitions   # => [:pay]
+order.can_transition_to?(:paid)     # => true
+order.can_transition_to?(:shipped)  # => false (no event leads there from :pending)
 ```
 
 ### State History
@@ -339,6 +341,7 @@ order.stuck?  # => false
 | `#current_state` | Returns the current state as a symbol |
 | `#can_X?(**payload)` | Returns true if event X can fire from the current state (including guards) |
 | `#allowed_transitions(**payload)` | Returns an array of event names that can fire from the current state |
+| `#can_transition_to?(state, **payload)` | Returns true if any currently-fireable event would land the machine in `state` (honours guards; raises ArgumentError for unknown states) |
 | `#X!(**payload)` | Fire event X with optional payload, or raise `InvalidTransition` |
 | `#X(**payload)` | Fire event X with optional payload, returns true on success, false on failure |
 | `#X?` | Returns true if current state is X |

data/lib/philiprehberger/state_machine/instance_methods.rb

@@ -251,6 +251,36 @@ module Philiprehberger
               true
             end.keys
           end
+
+          # Whether any currently-fireable event would land the machine in `state`.
+          # Honours guards (a guarded-out transition reports false). Useful for UI
+          # gating without hand-rolling the per-event lookup.
+          #
+          # @param state [Symbol] the candidate target state
+          # @param payload [Hash] keyword payload forwarded to guards that accept it
+          # @return [Boolean]
+          # @raise [ArgumentError] if `state` is not declared on the machine
+          klass.define_method(:can_transition_to?) do |state, **payload|
+            unless definition.all_states.include?(state)
+              raise ArgumentError, "Unknown state: #{state.inspect}"
+            end
+
+            definition.events.any? do |_name, transitions|
+              transition = transitions.find { |t| t.matches?(current_state) && t.to == state }
+              next false unless transition
+
+              if transition.guard
+                guard_result = if transition.guard.arity.zero?
+                                 instance_exec(&transition.guard)
+                               else
+                                 instance_exec(**payload, &transition.guard)
+                               end
+                next false unless guard_result
+              end
+
+              true
+            end
+          end
         end
       end
     end

data/lib/philiprehberger/state_machine/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module StateMachine
-    VERSION = '0.7.0'
+    VERSION = '0.8.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-state_machine
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-05-08 00:00:00.000000000 Z
 dependencies: []
 description: A minimal state machine for Ruby objects. Define states, events, transitions,
   guard conditions, and callbacks with a clean DSL. Works with any Ruby class — no