philiprehberger-state_machine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b03b538804454b46d59bbc7a123e9ba9574cb1f2ad222a7ac8242dfd79d69db5
+  data.tar.gz: 2fa1caa0ebf454e23bd8f4282ddbd4f496de8f6111fb4c56e3e147dcd6cdc79f
+SHA512:
+  metadata.gz: db65dd12012f2db78a47946f2977b0122e417413233e4c458aae79f2de7d500f2a7b90f4b3804deb9dc33a74b7c85b1db32ed8ce4244a1fe7a8d0d0023ddfea5
+  data.tar.gz: ffb15acff6cf3a832c4a02ff5445b2c92ce8b0c665294fb6a652d349fad324baec3a65dded1daf45049173c304a1c8d1427d348d25f60088d6730b224a912d60

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-21
+
+### Added
+- Initial release
+- State machine DSL with `state_machine initial: :state` block syntax
+- Event definitions with `event :name` and `transition from:, to:` DSL
+- Guard conditions via `guard:` lambda on transitions
+- Before and after transition callbacks with `to:` and `from:` filters
+- State predicate methods (`state?`)
+- Transition check methods (`can_event?`)
+- Safe and bang event methods (`event` returns boolean, `event!` raises)
+- `allowed_transitions` introspection method
+- Works with any Ruby class, no framework dependency required

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# philiprehberger-state_machine
+
+[![Tests](https://github.com/philiprehberger/rb-state-machine/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-state-machine/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-state_machine.svg)](https://rubygems.org/gems/philiprehberger-state_machine)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-state-machine)](LICENSE)
+
+Lightweight state machine DSL with transitions, guards, and callbacks
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-state_machine"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-state_machine
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/state_machine"
+
+class Order
+  include Philiprehberger::StateMachine
+
+  state_machine initial: :pending do
+    event :pay do
+      transition from: :pending, to: :paid
+    end
+
+    event :ship do
+      transition from: :paid, to: :shipped
+    end
+
+    event :deliver do
+      transition from: :shipped, to: :delivered
+    end
+  end
+end
+
+order = Order.new
+order.current_state  # => :pending
+order.pay!
+order.current_state  # => :paid
+```
+
+### Guards
+
+Attach a guard lambda to conditionally block transitions:
+
+```ruby
+class Order
+  include Philiprehberger::StateMachine
+
+  attr_accessor :tracking_number
+
+  state_machine initial: :pending do
+    event :pay do
+      transition from: :pending, to: :paid
+    end
+
+    event :ship do
+      transition from: :paid, to: :shipped, guard: -> { !tracking_number.nil? }
+    end
+  end
+end
+
+order = Order.new
+order.pay!
+order.ship              # => false (no tracking number)
+order.tracking_number = "TRACK123"
+order.ship!             # => transitions to :shipped
+```
+
+### Callbacks
+
+Register before and after callbacks with optional state filters:
+
+```ruby
+class Order
+  include Philiprehberger::StateMachine
+
+  state_machine initial: :pending do
+    event :pay do
+      transition from: :pending, to: :paid
+    end
+
+    before_transition to: :paid do |order|
+      puts "About to mark order as paid"
+    end
+
+    after_transition to: :paid do |order|
+      puts "Order is now paid"
+    end
+  end
+end
+```
+
+### Introspection
+
+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]
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `state_machine(initial:, &block)` | Define a state machine on the class with an initial state |
+| `event(name, &block)` | Define an event inside the state machine block |
+| `transition(from:, to:, guard: nil)` | Define a transition inside an event block |
+| `before_transition(to: nil, from: nil, &block)` | Register a callback that fires before a transition |
+| `after_transition(to: nil, from: nil, &block)` | Register a callback that fires after a transition |
+| `#current_state` | Returns the current state as a symbol |
+| `#can_X?` | Returns true if event X can fire from the current state (including guards) |
+| `#allowed_transitions` | Returns an array of event names that can fire from the current state |
+| `#X!` | Fire event X or raise `InvalidTransition` |
+| `#X` | Fire event X, returns true on success, false on failure |
+| `#X?` | Returns true if current state is X |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/philiprehberger/state_machine/callbacks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module StateMachine
+    # Represents a single callback with optional state filters.
+    #
+    # @attr_reader type [:before, :after] callback timing
+    # @attr_reader block [Proc] the callback to execute
+    # @attr_reader conditions [Hash] optional :from and :to filters
+    Callback = Struct.new(:type, :block, :conditions, keyword_init: true)
+
+    # Stores and filters callbacks for state transitions.
+    class CallbackSet
+      def initialize
+        @callbacks = []
+      end
+
+      # Register a callback.
+      #
+      # @param type [:before, :after]
+      # @param conditions [Hash] optional :from and :to state filters
+      # @param block [Proc]
+      def add(type:, conditions: {}, &block)
+        @callbacks << Callback.new(type: type, block: block, conditions: conditions)
+      end
+
+      # Execute all matching callbacks for the given transition.
+      #
+      # @param type [:before, :after]
+      # @param from [Symbol] source state
+      # @param to [Symbol] target state
+      # @param context [Object] the object to pass to the callback
+      def execute(type:, from:, to:, context:)
+        matching(type: type, from: from, to: to).each do |callback|
+          callback.block.call(context)
+        end
+      end
+
+      private
+
+      def matching(type:, from:, to:)
+        @callbacks.select do |cb|
+          next false unless cb.type == type
+
+          matches_condition?(cb.conditions[:from], from) &&
+            matches_condition?(cb.conditions[:to], to)
+        end
+      end
+
+      def matches_condition?(condition, state)
+        return true if condition.nil?
+
+        if condition.is_a?(Array)
+          condition.include?(state)
+        else
+          condition == state
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/state_machine/definition.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module StateMachine
+    # DSL class used inside the `state_machine` block to define events,
+    # transitions, and callbacks.
+    class Definition
+      attr_reader :initial, :events, :callback_set
+
+      # @param initial [Symbol] the initial state
+      def initialize(initial:)
+        @initial = initial
+        @events = {}
+        @callback_set = CallbackSet.new
+      end
+
+      # Define an event with transitions.
+      #
+      # @param name [Symbol] event name
+      # @yield block evaluated via TransitionBuilder
+      def event(name, &block)
+        builder = TransitionBuilder.new
+        builder.instance_eval(&block)
+        @events[name] = builder.transitions
+      end
+
+      # Register a before_transition callback.
+      #
+      # @param opts [Hash] optional :from and :to state filters
+      # @yield [Object] block receives the host object
+      def before_transition(opts = {}, &block)
+        @callback_set.add(type: :before, conditions: opts, &block)
+      end
+
+      # Register an after_transition callback.
+      #
+      # @param opts [Hash] optional :from and :to state filters
+      # @yield [Object] block receives the host object
+      def after_transition(opts = {}, &block)
+        @callback_set.add(type: :after, conditions: opts, &block)
+      end
+
+      # Returns all unique states referenced in the definition.
+      #
+      # @return [Array<Symbol>]
+      def all_states
+        states = [initial]
+        events.each_value do |transitions|
+          transitions.each do |t|
+            states.concat(Array(t.from))
+            states << t.to
+          end
+        end
+        states.uniq
+      end
+    end
+  end
+end

data/lib/philiprehberger/state_machine/instance_methods.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module StateMachine
+    # Defines and mixes in instance methods on the host class.
+    module InstanceMethods
+      class << self
+        # Define all state machine methods on the host class.
+        #
+        # @param klass [Class] the host class
+        # @param definition [Definition] the state machine definition
+        def define_methods(klass, definition)
+          define_initializer(klass, definition)
+          define_state_accessors(klass)
+          define_event_methods(klass, definition)
+          define_state_predicates(klass, definition)
+          define_introspection(klass, definition)
+        end
+
+        private
+
+        def define_initializer(klass, definition)
+          initial = definition.initial
+          initializer = Module.new do
+            define_method(:initialize) do |*args, **kwargs, &block|
+              @_sm_state = initial
+              return unless method(:initialize).super_method
+
+              if kwargs.empty?
+                super(*args, &block)
+              else
+                super(*args, **kwargs, &block)
+              end
+            end
+          end
+          klass.prepend(initializer)
+        end
+
+        def define_state_accessors(klass)
+          klass.define_method(:current_state) { @_sm_state }
+          klass.send(:define_method, :_sm_set_state) { |state| @_sm_state = state }
+          klass.send(:private, :_sm_set_state)
+        end
+
+        def define_event_methods(klass, definition)
+          definition.events.each do |event_name, transitions|
+            define_bang_method(klass, event_name, transitions, definition)
+            define_safe_method(klass, event_name, transitions, definition)
+            define_can_method(klass, event_name, transitions)
+          end
+        end
+
+        def define_bang_method(klass, event_name, transitions, definition)
+          klass.define_method(:"#{event_name}!") do
+            transition = transitions.find { |t| t.matches?(current_state) }
+            unless transition
+              raise InvalidTransition,
+                    "Cannot #{event_name} from #{current_state}"
+            end
+
+            if transition.guard && !instance_exec(&transition.guard)
+              raise InvalidTransition,
+                    "Guard condition failed for #{event_name} from #{current_state}"
+            end
+
+            from = current_state
+            to = transition.to
+
+            definition.callback_set.execute(type: :before, from: from, to: to, context: self)
+            _sm_set_state(to)
+            definition.callback_set.execute(type: :after, from: from, to: to, context: self)
+
+            true
+          end
+        end
+
+        def define_safe_method(klass, event_name, transitions, definition)
+          klass.define_method(event_name) do
+            transition = transitions.find { |t| t.matches?(current_state) }
+            return false unless transition
+            return false if transition.guard && !instance_exec(&transition.guard)
+
+            from = current_state
+            to = transition.to
+
+            definition.callback_set.execute(type: :before, from: from, to: to, context: self)
+            _sm_set_state(to)
+            definition.callback_set.execute(type: :after, from: from, to: to, context: self)
+
+            true
+          end
+        end
+
+        def define_can_method(klass, event_name, transitions)
+          klass.define_method(:"can_#{event_name}?") do
+            transition = transitions.find { |t| t.matches?(current_state) }
+            return false unless transition
+            return false if transition.guard && !instance_exec(&transition.guard)
+
+            true
+          end
+        end
+
+        def define_state_predicates(klass, definition)
+          definition.all_states.each do |state|
+            klass.define_method(:"#{state}?") { current_state == state }
+          end
+        end
+
+        def define_introspection(klass, definition)
+          klass.define_method(:allowed_transitions) do
+            definition.events.select do |_name, transitions|
+              transition = transitions.find { |t| t.matches?(current_state) }
+              next false unless transition
+              next false if transition.guard && !instance_exec(&transition.guard)
+
+              true
+            end.keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/state_machine/transition.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module StateMachine
+    # Represents a single transition from one or more states to a target state.
+    #
+    # @attr_reader from [Symbol, Array<Symbol>] source state(s)
+    # @attr_reader to [Symbol] target state
+    # @attr_reader guard [Proc, nil] optional guard condition
+    Transition = Struct.new(:from, :to, :guard, keyword_init: true) do
+      # Check if this transition matches the given current state.
+      #
+      # @param current_state [Symbol]
+      # @return [Boolean]
+      def matches?(current_state)
+        if from.is_a?(Array)
+          from.include?(current_state)
+        else
+          from == current_state
+        end
+      end
+
+      # Returns all source states as an array.
+      #
+      # @return [Array<Symbol>]
+      def from_states
+        Array(from)
+      end
+    end
+
+    # Collects transitions for a single event via the DSL.
+    class TransitionBuilder
+      attr_reader :transitions
+
+      def initialize
+        @transitions = []
+      end
+
+      # Define a transition within an event block.
+      #
+      # @param from [Symbol, Array<Symbol>] source state(s)
+      # @param to [Symbol] target state
+      # @param guard [Proc, nil] optional guard lambda
+      def transition(from:, to:, guard: nil)
+        @transitions << Transition.new(from: from, to: to, guard: guard)
+      end
+    end
+  end
+end

data/lib/philiprehberger/state_machine/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module StateMachine
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/state_machine.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'state_machine/version'
+require_relative 'state_machine/transition'
+require_relative 'state_machine/callbacks'
+require_relative 'state_machine/definition'
+require_relative 'state_machine/instance_methods'
+
+module Philiprehberger
+  module StateMachine
+    class Error < StandardError; end
+    class InvalidTransition < Error; end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Define a state machine on the class.
+      #
+      # @param initial [Symbol] the initial state
+      # @yield block evaluated via Definition DSL
+      def state_machine(initial:, &block)
+        definition = Definition.new(initial: initial)
+        definition.instance_eval(&block)
+
+        @_sm_definition = definition
+
+        InstanceMethods.define_methods(self, definition)
+      end
+
+      # @return [Definition] the state machine definition
+      def _sm_definition
+        @_sm_definition
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-state_machine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 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
+  framework dependency required.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/state_machine.rb
+- lib/philiprehberger/state_machine/callbacks.rb
+- lib/philiprehberger/state_machine/definition.rb
+- lib/philiprehberger/state_machine/instance_methods.rb
+- lib/philiprehberger/state_machine/transition.rb
+- lib/philiprehberger/state_machine/version.rb
+homepage: https://github.com/philiprehberger/rb-state-machine
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-state-machine
+  source_code_uri: https://github.com/philiprehberger/rb-state-machine
+  changelog_uri: https://github.com/philiprehberger/rb-state-machine/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-state-machine/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Lightweight state machine DSL with transitions, guards, and callbacks
+test_files: []