stateful.rb 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7967ca169b2665febfdca466537e2cbd087eda2d2033289ddb485e5b6311fb8
-  data.tar.gz: a9d2c650234ba4657338b61129823f6fbaccad9159827d65ba67e4ccf10a7c98
+  metadata.gz: 64d45e68824b71f7c09cdd74a2c5ee0b24dc8b6a5d56c8382d69db3755f2135b
+  data.tar.gz: cb4c4e148e18cb5fe4792db4f3c7607917bae0d15fde9823200c7dd43e34731a
 SHA512:
-  metadata.gz: c19933b56be3391784e694fecedfb486c9b9f3be79a53d07ac5a0adb7c481aa8e68a5a0204ad48ea5869bf5385de38d0022767f14dbb5d4d247cdc00233e1379
-  data.tar.gz: d8cebec2d02b438a6756cdf297a11ccb1abe5927bf487b283e978df90a0a79eaca6598cccca4f15a55bb654af9b20a8866bb130be7ed887f174cc81ba09ec257
+  metadata.gz: 2ee5b530989c26519491d9575bfdc5cad20f9eda1e1cae0c95186d52891c78e78a765d1eb1b42c194177959979abefd017f2f47edaeb586746556322b89f3f38
+  data.tar.gz: 6e55e936a191bc872594b3a6ad370b1912b03950680eac27ecd9a960592b16129c69c073f0d903d1d5f1c50cfadeb5b08dad0b3a521fe045df4d649854d81b9a

data/CHANGELOG.md

@@ -0,0 +1,161 @@
+# stateful/CHANGELOG.md
+
+## 2.3.0 (20260418): Extract shared class methods.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. lib/Stateful/ClassMethods.rb: + shared adapter methods extracted from Poro::ClassMethods, ActiveRecord::ClassMethods, Sequel::ClassMethods. All adapters now delegate to stateful\_attribute\_name\_for\_machine.
+  - define\_named\_machine\_methods
+  - define\_event\_method
+  - define\_status\_predicate\_method
+  - define\_next\_state\_method
+  - define\_transitions\_method
+  - define\_initial\_stateQ\_method
+  - define\_final\_stateQ\_method
+2. lib/Stateful/ActiveRecord/ClassMethods.rb:
+  - Extracted shared adapter methods to Stateful::ClassMethods.
+  - /column_name_for_machine/stateful\_attribute_name\_for\_machine/
+3. lib/Stateful/Poro/ClassMethods.rb: Extracted shared adapter methods to Stateful::ClassMethods.
+  - Extracted shared adapter methods to Stateful::ClassMethods.
+  - /variable_name_for_machine/stateful\_attribute_name\_for\_machine/
+4. lib/Stateful/Sequel/ClassMethods.rb: Extracted shared adapter methods to Stateful::ClassMethods.
+  - Extracted shared adapter methods to Stateful::ClassMethods.
+  - /column_name_for_machine/stateful\_attribute_name\_for\_machine/
+5. lib/Stateful/VERSION.rb: /2.2.0/2.3.0/
+
+
+## 2.2.0 (20260418): Add Sequel support.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. lib/Stateful/Sequel.rb: Sequel adapter module, mirroring Stateful::ActiveRecord.
+2. lib/Stateful/Sequel/ClassMethods.rb: Sequel-specific class methods using self[:column] / self[:column]= for persistence.
+3. test/Sequel/test\_helper.rb: Sequel test helper using in-memory SQLite.
+4. test/Sequel.rb: Sequel test runner.
+5. test/Sequel/WithPersistenceNonSpecificExtend.rb
+6. test/Sequel/WithPersistenceNonSpecificExtendAndStatefulBlock.rb
+7. test/Sequel/WithPersistenceSpecificExtend.rb
+8. test/Sequel/WithPersistenceSpecificExtendAndStatefulBlock.rb
+9. test/Sequel/WithInitialStateBlock.rb
+10. test/Sequel/WithColumnName.rb
+11. test/Sequel/WithMultipleFinalStates.rb
+12. test/Sequel/WithMultipleStateMachines.rb
+13. test/Sequel/WithMultipleStateMachinesAndStatefulBlock.rb
+14. test/Sequel/WithExplicitDeterministicEventOrdering.rb
+15. test/Sequel/WithExplicitNonDeterministicEventOrdering.rb
+16. test/Sequel/WithExplicitGlobalNonDeterministicEventOrdering.rb
+17. test/Sequel/WithExplicitGlobalNonDeterministicEventOrderingAndInitialStateBlock.rb
+
+### ~
+1. lib/Stateful.rb: Auto-detect Sequel::Model in Stateful.extended, between ActiveRecord and Poro.
+2. test/Stateful.rb: + Sequel specs; - $LOAD\_PATH.unshift(test\_dir) to avoid case-insensitive collision between test/Sequel.rb and require 'sequel'.
+3. stateful.rb.gemspec: + sequel dev dependency; update description to include Sequel.
+4. lib/Stateful/VERSION.rb: /2.1.0/2.2.0/
+
+
+## 2.1.0 (20260412): Add mRuby support.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. mrbgem.rake: mrbgem specification with spec.rbfiles pointing at lib/ directly.
+2. mruby/stub\_require\_relative.rb: Stub to silence require_relative calls at mRuby build time.
+3. mruby/smoke_test.rb: Smoke test for mRuby compatibility.
+4. TODO (See notes.txt.)
+
+### -
+1. CHANGELOG.txt as it was left empty after creating CHANGELOG.md.
+2. notes.txt (Now TODO.)
+
+### ~
+1. lib/Stateful.rb: + Object.const_defined?(:ActiveRecord) for mRuby compatibility. In mRuby defined?() raises NameError instead of returning nil as with CRuby.
+2. lib/Stateful/VERSION.rb: /2.0.0/2.1.0/
+
+
+## 2.0.0 (20260216): Allow multiple state machines per class.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. Stateful::ClassMethods#state_machines: For indexing named `StateMachine` instances.
+2. Stateful::ClassMethods#state_machine
+3. Poro::ClassMethods#define_named_machine_methods
+4. ActiveRecord::ClassMethods#define_named_machine_methods
+5. StateMachine accepts parameter for `global_non_deterministic_event_ordering
+6. ~/test/ActiveRecord/test_helper.rb
+
+### -
+1. StateMachine#stateful
+
+### ~
+1. Stateful::ClassMethods#stateful: Use class_eval instead of delegating to StateMachine#stateful, which is now removed.
+2. /Stateful::States/Stateful::StateMachine/
+3. /stateful_states/stateful_state_machine/
+4. Test infrastructure migrated from PostgreSQL to SQLite (in-memory)
+5. stateful.rb.gemspec: /pg/sqlite3/
+6. Stateful::StateMachine#final_states: final_state?, final_states? weren't being defined.
+7. lib/Stateful/VERSION.rb: /1.0.2/2.1.0/
+
+
+## 1.0.2 (20260216): Fix non-deterministic event ordering.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. Stateful::State#non_deterministic_event_ordering?: Fixed logic bug where (@options[:deterministic] && !@options[:deterministic])  always evaluated to false.
+2. Stateful::States#global_non_deterministic_event_ordering?: Same fix as above.
+3. Stateful::State: /shuffle/shuffle!/non-deterministic ordering actually mutates the transitions array.
+4. Stateful::State: Removed require_relative for lib/Array/shuffle.rb.
+5. test/ActiveRecord/WithPersistenceSpecificExtend.rb: Fixed delete_all guard to check 'active_record_machine2s' instead of 'active_record_machine1s'.
+6. test/ActiveRecord/WithMultipleFinalStates.rb: Fixed comment header (was Poro/WithMultipleFinalStates.rb).
+7. test/Poro/WithVariableName.rb: Fixed comment header (was ActiveRecord/WithVariableName.rb).
+8. test/Poro/WithExplicitNonDeterministicEventOrdering.rb: Changed transition order assertions to use must_include instead of must_equal.
+9. test/ActiveRecord/WithExplicitNonDeterministicEventOrdering.rb: Same as above.
+10. test/ActiveRecord/WithExplicitGlobalNonDeterministicEventOrdering.rb: Same as above.
+11. test/ActiveRecord/WithExplicitGlobalNonDeterministicEventOrderingAndInitialStateBlock.rb: Same as above.
+12. lib/Stateful/VERSION.rb: /1.0.1/1.0.2/
+
+### -
+1. Array#shuffle: Use stdlib.
+
+
+## 1.0.1 (20260216): Fix date and version.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. stateful.rb.gemspec: Insert the correct date.
+2. lib/Stateful/VERSION.rb: /1.0.0/1.0.1/
+
+
+## 1.0.0 (20260216): Version number bump to 1.0.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. lib/Stateful/VERSION.rb: /0.14.12/1.0.0/
+
+
+## 0.14.12 (20260216): Change file mode on lib/Array/shuffle.rb.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. lib/Array/shuffle.rb: File mode change to read-only from being executable.
+2. lib/Stateful/VERSION.rb: /0.14.11/0.14.12/
+
+
+## 0.14.11 (20200419): Fix copypasta error in README.md.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. README.md: Fixed copypasta error in Installation section (was 'git.rb', now 'stateful.rb')
+2. lib/Stateful/VERSION.rb: /0.14.10/0.14.11/
+
+
+## 0.14.10 (20150207, 20200331): Allow Poro::ClassMethods to handle its own initialisation when extended.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. I finally implemented a change which I'd had sitting in a file never committed named shouldgetthisworking.rb since 2015-02-07 which entails moving the instance method generation methods from each of the application-specific files (lib/Poro.rb and lib/ActiveRecord.rb) to the application-specific class methods files (lib/Poro/ClassMethods.rb and lib/ActiveRecord/ClassMethods.rb).
+2. README.md
+3. CHANGES.txt
+
+### ~
+1. .gitignore: + *.gem
+2. lib/Stateful/VERSION.rb: /0.14.9/0.14.10/
+3. stateful.rb.gemspec to reflect the updated version

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://www.rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,309 @@
+# Stateful
+
+## Description
+
+A Ruby state machine which allows you to easily add state to Poro and ActiveRecord objects. Works with both CRuby and mRuby.
+
+## Installation
+
+### CRuby
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stateful.rb'
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install stateful.rb
+```
+
+### mRuby
+
+Add this to your `build_config.rb`:
+
+```ruby
+conf.gem github: 'thoran/Stateful'
+```
+
+## Usage
+
+### 1. Poro with persistence-specific extend and a stateful block declaration
+
+```ruby
+class PoroMachine
+  extend Stateful::Poro
+
+  stateful do
+    initial_state :initial_state
+
+    state :initial_state do
+      on :an_event => :next_state
+      on :another_event => :final_state
+    end
+
+    state :next_state do
+      on :yet_another_event => :final_state
+    end
+
+    final_state :final_state
+  end
+end
+
+poro_machine = PoroMachine.new
+poro_machine.initial_state.name
+# => :initial_state
+poro_machine.final_state.name
+# => :final_state
+```
+
+### 2. Poro with persistence non-specific extend, without a stateful block declaration, an initial_state block, and multiple final states
+
+```ruby
+class PoroMachine
+  extend Stateful
+
+  initial_state :initial_state do
+    on :an_event => :next_state
+    on :another_event => :final_state0
+  end
+
+  state :next_state do
+    on :yet_another_event => :final_state1
+  end
+
+  final_state :final_state0, :final_state1
+end
+
+poro_machine = PoroMachine.new
+poro_machine.current_state.name
+# => :initial_state
+poro_machine.an_event
+poro_machine.current_state.name
+# => :next_state
+```
+
+### 3. ActiveRecord with persistence-specific extend and a stateful block declaration
+
+```ruby
+class ActiveRecordMachine < ActiveRecord::Base
+  extend Stateful::ActiveRecord
+
+  stateful do
+    initial_state :initial_state
+
+    state :initial_state do
+      on :an_event => :next_state
+      on :another_event => :final_state
+    end
+
+    state :next_state do
+      on :yet_another_event => :final_state
+    end
+
+    final_state :final_state
+  end
+end
+
+active_record_machine = ActiveRecordMachine.new
+active_record_machine.initial_state?
+# => true
+active_record_machine.an_event
+active_record_machine.next_state?
+# => true
+```
+
+### 4. ActiveRecord with persistence non-specific extend, without a stateful block declaration, an initial_state block, and multiple final states
+
+```ruby
+class ActiveRecordMachine < ActiveRecord::Base
+  extend Stateful
+
+  initial_state :initial_state do
+    on :an_event => :next_state
+    on :another_event => :final_state0
+  end
+
+  state :next_state do
+    on :yet_another_event => :final_state0
+    on :and_yet_another_event => :final_state1
+  end
+
+  final_state :final_state0, :final_state1
+end
+
+active_record_machine = ActiveRecordMachine.new
+active_record_machine.an_event
+active_record_machine.final_state?
+# => false
+active_record_machine.yet_another_event
+active_record_machine.final_state?
+# => true
+```
+
+### 5. Custom variable/column name and non-deterministic event ordering
+
+It's also possible to define a state machine (either Poro or ActiveRecord) which has a custom variable (Poro) or column (ActiveRecord) name, which fires off the events in a random or non-deterministic order, and which has no final state.
+
+```ruby
+class ActiveRecordMachine < ActiveRecord::Base
+
+  @stateful_column_name = 'status' # This needs to be set before the class is extended. The default is 'current_state'.
+
+  extend Stateful
+
+  initial_state :initial_state, non_deterministic: true do
+    on :an_event => :another_state
+    on :another_event => :yet_another_state
+  end
+
+  state :another_state do
+    on :another_event => :yet_another_state
+  end
+
+  state :yet_another_state do
+    on :yet_another_event => :another_state
+  end
+end
+
+active_record_machine = ActiveRecordMachine.new
+# Supposing that both :an_event or :another_event messages are able to fire, then if the order of the evaluation of the transitions is non-deterministic, then the state change is also.  Non-deterministic event ordering really only makes sense in the context of the sibling library thoran/Eventful, which will evaluate the transitions automatically and will do so in the order as presented by Stateful.
+active_record_machine.another_event # With non-deterministic event firing it could check for :another_event before checking :an_event.
+active_record_machine.current_state.name
+# => :yet_another_state
+active_record_machine.an_event
+active_record_machine.current_state.name
+# => :yet_another_state
+active_record_machine.final_state?
+# => false
+active_record_machine.yet_another_event
+active_record_machine.final_state?
+# => false
+```
+
+### 6. Multiple state machines per class
+
+A single class can have multiple independent (orthogonal) state machines. Each machine gets its own namespaced methods, while domain predicates and event methods remain unnamespaced.
+
+```ruby
+class Order
+  extend Stateful
+
+  state_machine :fulfilment do
+    initial_state :pending do
+      on :items_collected => :ready
+    end
+
+    state :ready do
+      on :dispatch => :dispatched
+    end
+
+    final_state :dispatched
+  end
+
+  state_machine :payment do
+    initial_state :unpaid do
+      on :pay => :paid
+    end
+
+    state :paid do
+      on :refund => :refunded
+    end
+
+    final_state :refunded
+  end
+end
+
+order = Order.new
+
+order.fulfilment_state.name # state accessors are namespaced.
+# => :pending
+order.payment_state.name
+# => :unpaid
+
+order.fulfilment_initial_state? # General/overlapping predicates are namespaced.
+# => true
+order.payment_final_state?
+# => false
+
+order.fulfilment_transitions.first.event_name # Transitions are namespaced.
+# => :items_collected
+
+order.pending? # Domain predicates are not namespaced.
+# => true
+order.unpaid?
+# => true
+
+order.pay # Event methods are not namespaced.
+order.paid?
+# => true
+
+# State machines are orthogonal
+order.fulfilment_initial_state?
+# => true
+```
+
+Multiple state machines can also be declared inside a stateful block:
+
+```ruby
+class Order
+  extend Stateful
+
+  stateful do
+    state_machine :fulfilment do
+      initial_state :pending do
+        on :items_collected => :ready
+      end
+
+      state :ready do
+        on :dispatch => :dispatched
+      end
+
+      final_state :dispatched
+    end
+
+    state_machine :payment do
+      initial_state :unpaid do
+        on :pay => :paid
+      end
+
+      state :paid do
+        on :refund => :refunded
+      end
+
+      final_state :refunded
+    end
+  end
+end
+```
+
+For ActiveRecord, each machine uses a column named `<machine_name>_state`:
+
+```ruby
+class CreateOrders < ActiveRecord::Migration[6.0]
+  def change
+    create_table :orders do |t|
+      t.string :fulfilment_state
+      t.string :payment_state
+    end
+  end
+end
+```
+
+For Poro, each machine uses an instance variable named `@<machine_name>_state`.
+
+## Contributing
+
+1. Fork it: https://github.com/thoran/Stateful/fork
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Commit your changes: `git commit -am 'Add some feature'`
+4. Push to the branch: `git push origin my-new-feature`
+5. Create a new pull request

data/lib/Stateful/ActiveRecord/ClassMethods.rb

@@ -6,8 +6,8 @@ module Stateful
     module ClassMethods
       class << self
         def extended(klass)
-          klass.define_stateful_column_name_setter_method
-          klass.define_stateful_column_name_getter_method
+          klass.define_stateful_attribute_setter_method
+          klass.define_stateful_attribute_getter_method
           klass.define_next_state_method
           klass.define_transitions_method
           klass.define_initial_stateQ_method
@@ -15,15 +15,6 @@ module Stateful
         end
       end # class << self
 
-      def define_named_machine_methods(machine_name)
-        define_stateful_column_name_setter_method(machine_name: machine_name)
-        define_stateful_column_name_getter_method(machine_name: machine_name)
-        define_next_state_method(machine_name: machine_name)
-        define_transitions_method(machine_name: machine_name)
-        define_initial_stateQ_method(machine_name: machine_name)
-        define_final_stateQ_method(machine_name: machine_name)
-      end
-
       def stateful_column_name=(stateful_column_name)
         @stateful_column_name = stateful_column_name
       end
@@ -32,7 +23,7 @@ module Stateful
         @stateful_column_name
       end
 
-      def column_name_for_machine(machine_name = nil)
+      def stateful_attribute_name_for_machine(machine_name = nil)
         if machine_name
           "#{machine_name}_state"
         else
@@ -40,24 +31,8 @@ module Stateful
         end
       end
 
-      def define_event_method(transition, machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
-        define_method(transition.event_name) do
-          next_state_name = self.send(stateful_column_name).next_state_name(transition.event_name)
-          next_state = self.class.stateful_state_machine(machine_name).find(next_state_name)
-          self.send("#{stateful_column_name}=", next_state)
-        end
-      end
-
-      def define_status_predicate_method(state_name, machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
-        define_method("#{state_name}?") do
-          self.send(stateful_column_name).name == state_name
-        end
-      end
-
-      def define_stateful_column_name_setter_method(machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
+      def define_stateful_attribute_setter_method(machine_name: nil)
+        stateful_column_name = stateful_attribute_name_for_machine(machine_name)
         define_method("#{stateful_column_name}=") do |state|
           instance_variable_set("@#{stateful_column_name}", self.class.stateful_state_machine(machine_name).find(state))
           write_attribute(stateful_column_name, instance_variable_get("@#{stateful_column_name}").name)
@@ -66,8 +41,8 @@ module Stateful
         end
       end
 
-      def define_stateful_column_name_getter_method(machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
+      def define_stateful_attribute_getter_method(machine_name: nil)
+        stateful_column_name = stateful_attribute_name_for_machine(machine_name)
         define_method(stateful_column_name) do
           instance_variable_set("@#{stateful_column_name}", self.class.stateful_state_machine(machine_name).find(read_attribute(stateful_column_name)))
           if state = instance_variable_get("@#{stateful_column_name}")
@@ -79,39 +54,6 @@ module Stateful
           end
         end
       end
-
-      def define_next_state_method(machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
-        method_name = machine_name ? "#{machine_name}_next_state" : :next_state
-        define_method(method_name) do |event_name|
-          next_state_name = self.send(stateful_column_name).next_state_name(event_name)
-          self.class.stateful_state_machine(machine_name).find(next_state_name)
-        end
-      end
-
-      def define_transitions_method(machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
-        method_name = machine_name ? "#{machine_name}_transitions" : :transitions
-        define_method(method_name) do
-          self.send(stateful_column_name).transitions
-        end
-      end
-
-      def define_initial_stateQ_method(machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
-        method_name = machine_name ? "#{machine_name}_initial_state?" : :initial_state?
-        define_method(method_name) do
-          self.send(stateful_column_name) == self.class.stateful_state_machine(machine_name).initial_state
-        end
-      end
-
-      def define_final_stateQ_method(machine_name: nil)
-        stateful_column_name = column_name_for_machine(machine_name)
-        method_name = machine_name ? "#{machine_name}_final_state?" : :final_state?
-        define_method(method_name) do
-          self.class.stateful_state_machine(machine_name).final_states.include?(self.send(stateful_column_name))
-        end
-      end
     end
   end
 end

data/lib/Stateful/ClassMethods.rb

@@ -51,6 +51,66 @@ module Stateful
 
     # end DSL
 
+    # adapter methods
+
+    def define_named_machine_methods(machine_name)
+      define_stateful_attribute_setter_method(machine_name: machine_name)
+      define_stateful_attribute_getter_method(machine_name: machine_name)
+      define_next_state_method(machine_name: machine_name)
+      define_transitions_method(machine_name: machine_name)
+      define_initial_stateQ_method(machine_name: machine_name)
+      define_final_stateQ_method(machine_name: machine_name)
+    end
+
+    def define_event_method(transition, machine_name: nil)
+      attribute_name = stateful_attribute_name_for_machine(machine_name)
+      define_method(transition.event_name) do
+        next_state_name = self.send(attribute_name).next_state_name(transition.event_name)
+        next_state = self.class.stateful_state_machine(machine_name).find(next_state_name)
+        self.send("#{attribute_name}=", next_state)
+      end
+    end
+
+    def define_status_predicate_method(state_name, machine_name: nil)
+      attribute_name = stateful_attribute_name_for_machine(machine_name)
+      define_method("#{state_name}?") do
+        self.send(attribute_name).name == state_name
+      end
+    end
+
+    def define_next_state_method(machine_name: nil)
+      attribute_name = stateful_attribute_name_for_machine(machine_name)
+      method_name = machine_name ? "#{machine_name}_next_state" : :next_state
+      define_method(method_name) do |event_name|
+        next_state_name = self.send(attribute_name).next_state_name(event_name)
+        self.class.stateful_state_machine(machine_name).find(next_state_name)
+      end
+    end
+
+    def define_transitions_method(machine_name: nil)
+      attribute_name = stateful_attribute_name_for_machine(machine_name)
+      method_name = machine_name ? "#{machine_name}_transitions" : :transitions
+      define_method(method_name) do
+        self.send(attribute_name).transitions
+      end
+    end
+
+    def define_initial_stateQ_method(machine_name: nil)
+      attribute_name = stateful_attribute_name_for_machine(machine_name)
+      method_name = machine_name ? "#{machine_name}_initial_state?" : :initial_state?
+      define_method(method_name) do
+        self.send(attribute_name) == self.class.stateful_state_machine(machine_name).initial_state
+      end
+    end
+
+    def define_final_stateQ_method(machine_name: nil)
+      attribute_name = stateful_attribute_name_for_machine(machine_name)
+      method_name = machine_name ? "#{machine_name}_final_state?" : :final_state?
+      define_method(method_name) do
+        self.class.stateful_state_machine(machine_name).final_states.include?(self.send(attribute_name))
+      end
+    end
+
     # predicate methods
 
     def final_state?