has_state_machine 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 825270788dd41e2ffaee9573eea5e6bda6b63a21d9520cfd7805070feff0fac3
-  data.tar.gz: fd7679aafbd2aa7a21b522b99b13d7481d3b7bb8a345c4602380fdab581215d8
+  metadata.gz: eb504bbd9b6e978b3a62551273a74624cdb4d189545cb32bf45a7f060983e888
+  data.tar.gz: ac89964cd89cec827ac60c8fae3970d94329c0141c0078da7a409ff2f63547ff
 SHA512:
-  metadata.gz: 5a6251974a28867af9fd6f589f6680e231ad3e6e864e44e0f7303677e3d82ea492956c2bb48adc9c04ed56308158f13bd54ab63cdb11f6f995525adc42b0da27
-  data.tar.gz: 0a5db9a428f4c8f71f129c1c3133f50874f81be8933f5bc1177e0a2fb268c7ad1cd38427a2f2a398f91e721f71fdbf3ceaab094972953f3d2da4e16bb887e3d2
+  metadata.gz: e62938a674ba7e8bea155e536724220280458a32bfa4dc3bdeed402bba4067a54b253b76f017fec7a25b361e349b92d88daf00d8071464bc72814f96e1ae152d
+  data.tar.gz: cfc4cf9a5b21dc548cc4207979ac1325e5134dfe6d4fd3114ca6d623ac22ca8afcdc899cfea192030986f7ab42268405ebd6edc7201fab976752d9d6447879f9

data/README.md

@@ -5,7 +5,18 @@
 
 HasStateMachine uses ruby classes to make creating a finite state machine for your ActiveRecord models a breeze.
 
+## Contents
+
+- [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
@@ -13,11 +24,13 @@ gem 'has_state_machine'
 ```
 
 And then execute:
+
 ```bash
 $ bundle
 ```
 
 Or install it yourself as:
+
 ```bash
 $ gem install has_state_machine
 ```
@@ -28,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".
@@ -45,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?
@@ -70,15 +84,15 @@ module Workflow
     # There are callbacks for running logic before and after
     # a transition occurs.
     before_transition do
-      Rails.logger.info "Post is being archived\n"
+      Rails.logger.info "== Post is being archived ==\n"
     end
 
     after_transition do
-      Rails.logger.info "Post has been archived\n"
+      Rails.logger.info "== Post has been archived ==\n"
 
       # You can access the previous state of the object in
       # after_transition callbacks as well.
-      Rails.logger.info "Transitioned from #{previous_state}\n"
+      Rails.logger.info "== Transitioned from #{previous_state} ==\n"
     end
   end
 end
@@ -95,10 +109,54 @@ post.status                           # => "draft"
 post.title = "Foobar"
 post.status.transition_to(:published) # => true
 post.status                           # => "published"
+
+post.status.transition_to(:archived)
+# == Post is being archived ==
+# == Post has been archived ==
+# == Transitioned from published ==
+# => 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
-Coming Soon
+
+Anyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/encampment/has_state_machine/issues)
+- Fix bugs and [submit pull requests](https://github.com/encampment/has_state_machine/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+To get started with development:
+
+```
+git clone https://github.com/encampment/has_state_machine.git
+cd has_state_machine
+bundle install
+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/state_helpers.rb

@@ -55,7 +55,9 @@ module HasStateMachine
         # @example Retreiving a users published posts
         #   > Post.published.where(user: user)
         #   #=> [#<Post>]
-        scope state, -> { where("#{state_attribute} = ?", state) }
+        if defined?(ActiveRecord) && (self < ActiveRecord::Base)
+          scope state, -> { where("#{state_attribute} = ?", state) }
+        end
 
         ##
         # Defines boolean helpers to determine if the active state matches
@@ -76,7 +78,7 @@ module HasStateMachine
       # Getter for the current state of the model based on the configured state
       # attribute.
       def current_state
-        self[state_attribute]
+        attributes.with_indifferent_access[state_attribute]
       end
 
       ##

data/lib/has_state_machine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HasStateMachine
-  VERSION = "0.2.0"
+  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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Benjamin Hargett
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-05 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