has_state_machine 0.3.3 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 524c408a87a46086495361e76507c6d1eb963acc6d72664c3faf0c8c913fa19f
-  data.tar.gz: 992299b87230582800a63afdf47bd573003481f74e3d521de414d8e20c783bf4
+  metadata.gz: 58bd21a655ff20122628fbc9707b04d77be5a318753cabb721c16073ad9d7edb
+  data.tar.gz: ee6c83c9b070867c9715b9dc3970597f9c5db61ae616839f2bd3841bd397b501
 SHA512:
-  metadata.gz: a49dd7b572ba738ce5c29db2bb9f50100595a47353aa28b8bfb0e814340381202ac2db180efd42dfe9aea691088170eaf7ea266b1da0fc3a4d30ca287c266e44
-  data.tar.gz: 4a6ab1dfca389dcd4eac9d05a826d28cdbe145329dc078370327e76a07a2c8993d5fb470d981717ebec58c70c811501e447d20931d7cee0af8e8109132af6e41
+  metadata.gz: ce2c67a3440e3175693e589188456434ac593c3f219abcdb9607f7f2241a00e51746764c5b17623c66259f9bc6fdb3e1de8547262da27c93d16adefdf090b130
+  data.tar.gz: da2d558bc3dbd3686ce46538bd426956c5664a3f608350007643ae53626eae944f95c5d6180ca42b39459006bbd4084faf7b58d1a6354d262119d64718f16eac

data/README.md

@@ -7,13 +7,16 @@ HasStateMachine uses ruby classes to make creating a finite state machine for yo
 
 ## Contents
 
-- [Installation](#installation)
-- [Usage](#usage)
-- [Changelog](https://github.com/encampment/has_state_machine/blob/master/CHANGELOG.md)
-- [Contributing](#contributing)
-- [License](#license)
+- [HasStateMachine](#hasstatemachine)
+  - [Contents](#contents)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Advanced Usage](#advanced-usage)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -21,11 +24,13 @@ gem 'has_state_machine'
 ```
 
 And then execute:
+
 ```bash
 $ bundle
 ```
 
 Or install it yourself as:
+
 ```bash
 $ gem install has_state_machine
 ```
@@ -36,6 +41,7 @@ You must first use the `has_state_machine` macro to define your state machine at
 a high level. This includes defining the possible states for your object as well
 as some optional configuration should you want to change the default behavior of
 the state machine.
+
 ```ruby
 # By default, it is assumed that the "state" of the object is
 # stored in a string column named "status".
@@ -53,13 +59,13 @@ from `HasStateMachine::State`.
 module Workflow
   class Post::Draft < HasStateMachine::State
     # Define the possible transitions from the "draft" state
-    transitions_to %i[published archived]
+    state_options transitions_to: %i[published archived]
   end
 end
 
 module Workflow
   class Post::Published < HasStateMachine::State
-    transitions_to %i[archived]
+    state_options transitions_to: %i[archived]
 
     # Custom validations can be added to the state to ensure a transition is "valid"
     validate :title_exists?
@@ -111,6 +117,28 @@ post.status.transition_to(:archived)
 # => true
 ```
 
+### Advanced Usage
+
+Sometimes there may be a situation where you want to manually roll back a state change in one of the provided callbacks. To do this, add the `transactional: true` option to the `state_options` declaration and use the `rollback_transition` method in your callback. This will allow you to prevent the transition from persisting if something further down the line fails.
+
+```ruby
+module Workflow
+  class Post::Archived < HasStateMachine::State
+    state_options transactional: true
+
+    after_transition do
+      rollback_transition unless notified_watchers?
+    end
+
+    private
+
+    def notified_watchers?
+      #...
+    end
+  end
+end
+```
+
 ## Contributing
 
 Anyone is encouraged to help improve this project. Here are a few ways you can help:
@@ -130,4 +158,5 @@ bundle exec rake test
 ```
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/has_state_machine/definition.rb

@@ -36,28 +36,28 @@ module HasStateMachine
       def define_helper_methods(states:, options:)
         ##
         # The list of possible states in the state machine.
-        define_singleton_method "workflow_states" do
+        define_singleton_method :workflow_states do
           states
         end
 
         ##
         # Defines the column name for the attribute holding the current status.
         # Can be overwritten to use a different column name.
-        define_singleton_method "state_attribute" do
+        define_singleton_method :state_attribute do
           options[:state_attribute]&.to_sym || :status
         end
 
         ##
         # Defines the namespace of the models possible states.
         # Can be overwritten to use a different namespace.
-        define_singleton_method "workflow_namespace" do
+        define_singleton_method :workflow_namespace do
           (options[:workflow_namespace] || "Workflow::#{self}")
         end
 
         ##
         # Determines whether or not the state validations should be run
         # as part of the object validations; they are by default.
-        define_singleton_method "state_validations_on_object?" do
+        define_singleton_method :state_validations_on_object? do
           return true unless options.key?(:state_validations_on_object)
 
           options[:state_validations_on_object]

data/lib/has_state_machine/deprecation.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "active_support/deprecation"
+
+module HasStateMachine
+  Deprecation = ActiveSupport::Deprecation.new("1.0", "HasStateMachine")
+end

data/lib/has_state_machine/state.rb

@@ -16,8 +16,9 @@ module HasStateMachine
     define_model_callbacks :transition, only: %i[before after]
 
     ##
-    # Retrieves the next available transitions for a given state.
-    delegate :possible_transitions, :state, to: "self.class"
+    # possible_transitions - Retrieves the next available transitions for a given state.
+    # transactional? - Determines whether or not the transition should happen with a transactional block.
+    delegate :possible_transitions, :transactional?, :state, to: "self.class"
 
     ##
     # Add errors to the ActiveRecord object rather than the HasStateMachine::State
@@ -51,7 +52,13 @@ module HasStateMachine
       with_transition_options(options) do
         return false unless valid_transition?(desired_state.to_s)
 
-        transitioned = state_instance(desired_state.to_s).perform_transition!
+        desired_state = state_instance(desired_state.to_s)
+
+        transitioned = if desired_state.transactional?
+          desired_state.perform_transactional_transition!
+        else
+          desired_state.perform_transition!
+        end
       end
 
       transitioned
@@ -66,8 +73,24 @@ module HasStateMachine
       end
     end
 
+    ##
+    # Makes the actual transition from one state to the next and
+    # runs the before and after transition callbacks in a transaction
+    # to allow for roll backs.
+    def perform_transactional_transition!
+      ActiveRecord::Base.transaction(requires_new: true, joinable: false) do
+        run_callbacks :transition do
+          rollback_transition unless object.update("#{object.state_attribute}": state)
+        end
+      end
+    end
+
     private
 
+    def rollback_transition
+      raise ActiveRecord::Rollback
+    end
+
     ##
     # Determines if the given desired state exists in the predetermined
     # list of allowed transitions.
@@ -111,11 +134,25 @@ module HasStateMachine
         to_s.demodulize.underscore
       end
 
+      def transactional?
+        @transactional || false
+      end
+
       ##
       # Setter for the HasStateMachine::State classes to define the possible
       # states the current state can transition to.
       def transitions_to(states)
-        @possible_transitions = states.map(&:to_s)
+        state_options(transitions_to: states)
+        HasStateMachine::Deprecation.deprecation_warning(:transitions_to, "use state_options instead")
+      end
+
+      ##
+      # Set the options for the HasStateMachine::State classes to define the possible
+      # states the current state can transition to and whether or not transitioning
+      # to the state should be performed within a transaction.
+      def state_options(transitions_to: [], transactional: false)
+        @possible_transitions = transitions_to.map(&:to_s)
+        @transactional = transactional
       end
     end
   end

data/lib/has_state_machine/state_helpers.rb

@@ -56,7 +56,7 @@ module HasStateMachine
         #   > Post.published.where(user: user)
         #   #=> [#<Post>]
         if defined?(ActiveRecord) && (self < ActiveRecord::Base)
-          scope state, -> { where("#{state_attribute} = ?", state) }
+          scope state, -> { where("#{table_name}.#{state_attribute} = ?", state) }
         end
 
         ##

data/lib/has_state_machine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HasStateMachine
-  VERSION = "0.3.3"
+  VERSION = "0.4.1"
 end

data/lib/has_state_machine.rb

@@ -3,6 +3,7 @@
 require "has_state_machine/railtie"
 require "has_state_machine/core_ext/string"
 require "has_state_machine/definition"
+require "has_state_machine/deprecation"
 
 module HasStateMachine
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_state_machine
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.1
 platform: ruby
 authors:
 - Benjamin Hargett
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-22 00:00:00.000000000 Z
+date: 2023-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -110,6 +110,7 @@ files:
 - lib/has_state_machine.rb
 - lib/has_state_machine/core_ext/string.rb
 - lib/has_state_machine/definition.rb
+- lib/has_state_machine/deprecation.rb
 - lib/has_state_machine/railtie.rb
 - lib/has_state_machine/state.rb
 - lib/has_state_machine/state_helpers.rb
@@ -133,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Class based state machine for ActiveRecord models.