has_state_machine 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 524c408a87a46086495361e76507c6d1eb963acc6d72664c3faf0c8c913fa19f
-  data.tar.gz: 992299b87230582800a63afdf47bd573003481f74e3d521de414d8e20c783bf4
+  metadata.gz: eb504bbd9b6e978b3a62551273a74624cdb4d189545cb32bf45a7f060983e888
+  data.tar.gz: ac89964cd89cec827ac60c8fae3970d94329c0141c0078da7a409ff2f63547ff
 SHA512:
-  metadata.gz: a49dd7b572ba738ce5c29db2bb9f50100595a47353aa28b8bfb0e814340381202ac2db180efd42dfe9aea691088170eaf7ea266b1da0fc3a4d30ca287c266e44
-  data.tar.gz: 4a6ab1dfca389dcd4eac9d05a826d28cdbe145329dc078370327e76a07a2c8993d5fb470d981717ebec58c70c811501e447d20931d7cee0af8e8109132af6e41
+  metadata.gz: e62938a674ba7e8bea155e536724220280458a32bfa4dc3bdeed402bba4067a54b253b76f017fec7a25b361e349b92d88daf00d8071464bc72814f96e1ae152d
+  data.tar.gz: cfc4cf9a5b21dc548cc4207979ac1325e5134dfe6d4fd3114ca6d623ac22ca8afcdc899cfea192030986f7ab42268405ebd6edc7201fab976752d9d6447879f9

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.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

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HasStateMachine
-  VERSION = "0.3.3"
+  VERSION = "0.4.0"
 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.0
 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: 2021-04-03 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