has_state_machine 0.6.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d4ecde120f4c419dfe63154f2e61cbb8459a77aedf0b45cc169a3eeac3bcb29
-  data.tar.gz: df52aa5a5a23abd0d230281e3d124eacbd56e9bbb17cc094a202a02a208fb732
+  metadata.gz: 902498121bd57b97de373beaa68557c3591de8a221d524af5b9033be1cca8a73
+  data.tar.gz: fb4806d204772d488c4fb2bc69360cd989edf4c8a5312508b37868d961adf059
 SHA512:
-  metadata.gz: 6c2e58ee081bdbd77e5b9b04adfc8eff0ff94f2bd50c63ed06317be69ae1ff18f28eb32bb149629f06ab41f285c7a4fa4e18788d7a8140b1d91372d3cc3ce8c1
-  data.tar.gz: f4aefba6c6484abf2dfb0f79a390ca80c8e686637accd18869f3c0991b74496f38bbbe65b47958213ebf12cc48079d3b01ba373a0f9bff16fbe03c11f64a357e
+  metadata.gz: 1baeee9d74f64325427b52e2e867cab05db7848f384316b8175cbb5d49a2c4030dcf905020ac8091c495f6cfa20f8dcae657bcffd78b86987e9c867665f5cf42
+  data.tar.gz: 7e998865b342452f802266b3408bd673b26fb622672ed48ff18cb384259c34a7ec1f591a9ed99efb12f33364e5a1c9bff33d9b95bd4fbac3794ff9d3f2ccdd25

data/README.md

@@ -1,6 +1,6 @@
 # HasStateMachine
 
-[![Build Status](https://github.com/bharget/has_state_machine/workflows/Tests/badge.svg)](https://github.com/bharget/has_state_machine/actions)
+[![CI](https://github.com/beehiiv/has_state_machine/actions/workflows/ci.yml/badge.svg)](https://github.com/beehiiv/has_state_machine/actions/workflows/ci.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 
 HasStateMachine uses ruby classes to make creating a finite state machine for your ActiveRecord models a breeze.
@@ -10,7 +10,9 @@ HasStateMachine uses ruby classes to make creating a finite state machine for yo
 - [HasStateMachine](#hasstatemachine)
   - [Contents](#contents)
   - [Installation](#installation)
-  - [Usage](#usage)
+  - [Usage](#basic-usage)
+    - [Basic Usage](#basic-usage)
+    - [Validations & Error Handling](#validations-and-error-handling)
     - [Advanced Usage](#advanced-usage)
   - [Contributing](#contributing)
   - [License](#license)
@@ -35,12 +37,12 @@ Or install it yourself as:
 $ gem install has_state_machine
 ```
 
-## Usage
+## Basic Usage
 
 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.
+the state machine (more on this later).
 
 ```ruby
 # By default, it is assumed that the "state" of the object is
@@ -52,7 +54,7 @@ end
 
 Now you must define the classes for the states in your state machine. By default,
 `HasStateMachine` assumes that these will be under the `Workflow` namespace following
-the pattern of `Workflow::#{ObjectClass}::#{State}`. The state objects must inherit
+the pattern of `Workflow::#{ObjectClass}::#{State}`. The state classes must inherit
 from `HasStateMachine::State`.
 
 ```ruby
@@ -94,6 +96,13 @@ module Workflow
       # after_transition callbacks as well.
       Rails.logger.info "== Transitioned from #{previous_state} ==\n"
     end
+
+    # after_transition_commit runs only once the transition has been
+    # committed: after the record is saved for normal transitions, and
+    # outside the transaction for transactional transitions (see below).
+    after_transition_commit do
+      MyJob.perform_later(object)
+    end
   end
 end
 ```
@@ -117,9 +126,83 @@ post.status.transition_to(:archived)
 # => true
 ```
 
+If you'd like to check that an object can be transitioned into a new state, use the `can_transition?` method. This checks to see if the provided argument is in the `transitions_to` array defined on the object's current state. (This does not run any validations that may be defined on the new state)
+
+Example:
+```ruby
+post = Post.create(status: "draft")
+
+post.status.can_transition?(:published) # => true
+post.status.can_transition?(:other_state) # => false
+```
+
+### Validations and Error Handling
+
+You can define custom validations on a given state to determine whether an object in that state or a transition to that state is valid.
+
+By default, validations defined on the state will be run as part of the object validations if the object is in that state.
+
+```ruby
+post = Post.create(status: "published", title: "Title")
+
+post.valid?
+# => true
+
+post.title = nil
+post.valid?
+# => false
+```
+
+If you wish to change this behavior and not have the state validations run on the object, you can specify that with the `state_validations_on_object` option when defining your state machine.
+
+```ruby
+class Post < ApplicationRecord
+  has_state_machine states: %i[draft published, archived], state_validations_on_object: false
+end
+
+post = Post.create(status: "published", title: "Title")
+
+post.valid?
+# => true
+
+post.title = nil
+post.valid?
+# => true
+```
+
+By default, when attempting to transition an object to another state, it checks:
+  * Validations defined on the object
+  * That the new state is one of the allowed transitions from the current state
+  * Any validations defined on the new state
+
+If any are found to be invalid, the transition will fail. Any errors from validations on the new state will be added to the object.
+
+```ruby
+post = Post.create(status: "draft")
+
+post.title = nil
+post.status.transition_to(:published)
+# => false
+
+post.errors.full_messages
+# => ["Title can't be blank"]
+```
+
+If you wish to bypass this behavior and skip validations during a transition, you can do that:
+
+```ruby
+post = Post.create(status: "draft")
+
+post.title = nil
+post.status.transition_to(:published, skip_validations: true)
+# => 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.
+#### Transactional Transitions
+
+There may be a situation where you want to manually rollback a state change in one of the provided transition callbacks. To do this, add the `transactional: true` option to the `state_options` declaration. This results in the transition being wrapped in a transaction. You can then use the `rollback_transition` method in your callback when you want to trigger a rollback of the transaction. This will allow you to prevent the transition from persisting if something further down the line fails.
 
 ```ruby
 module Workflow
@@ -130,15 +213,48 @@ module Workflow
       rollback_transition unless notified_watchers?
     end
 
+    after_transition_commit do
+      enqueue_external_work
+    end
+
     private
 
+    def enqueue_external_work
+      # Any work you want to happen only after the transition is committed.
+      # Enqueuing a job, calling an external API, sending a webhook, etc.
+    end
+
     def notified_watchers?
-      #...
+      # Any dependent work that you want to run that should play a part in determining
+      # whether the transition was successful or not and needs to be rolled back.
     end
   end
 end
 ```
 
+#### Transient Transition Variables
+
+Sometimes you may may want to pass additional arguments to a state transition for additional context in your transition callbacks. To do this, add the `transients` option to the `state_options` declaration. This allows you to define any additional attributes you want to be able to pass along during a state transition to that state.
+
+```ruby
+module Workflow
+  class Post::Archived < HasStateMachine::State
+    state_options transients: %i[user]
+
+    after_transition do
+      puts "== Post archived by #{user.name} =="
+    end
+  end
+end
+
+current_user = User.create(name: "John Doe")
+post = Post.create(status: "published")
+
+post.status.transition_to(:archived, user: current_user)
+# == Post archived by John Doe ==
+# => true
+```
+
 ## Contributing
 
 Anyone is encouraged to help improve this project. Here are a few ways you can help:

data/lib/has_state_machine/state.rb

@@ -15,22 +15,42 @@ module HasStateMachine
     # for use on a HasStateMachine::State instance.
     define_model_callbacks :transition, only: %i[before after]
 
+    ##
+    # Defines the after_transition_commit callback. It runs only after a
+    # transition has committed.
+    define_model_callbacks :transition_commit, only: %i[after]
+
     ##
     # 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"
+    # state - The underscored name of the state
+    # transients - Specified list of optional transient attributes on this state
+    delegate :possible_transitions, :transactional?, :state, :transients, to: "self.class"
 
     ##
     # Initializes the HasStateMachine::State instance.
     #
     # @example
     #   state = Workflow::Post::Draft.new(post) #=> "draft"
-    def initialize(object)
+    def initialize(object, transient_values = {})
       @object = object
 
+      transient_values.to_h.slice(*transients).each do |transient, value|
+        instance_variable_set(:"@#{transient}", value)
+      end
+
       super(state)
     end
 
+    ##
+    # Determines if the given desired state exists in the predetermined
+    # list of allowed transitions.
+    # @param desired_state [String, Symbol] the state to check if the object can transition to
+    # @return [Boolean] whether or not the object can transition to the desired state
+    def can_transition?(desired_state)
+      possible_transitions.include? desired_state.to_s
+    end
+
     ##
     # Checks to see if the desired state is valid and then gives
     # responsibility to the desired state's instance to make the
@@ -43,43 +63,56 @@ module HasStateMachine
     # @return [Boolean] whether or not the transition took place
     def transition_to(desired_state, **options)
       transitioned = false
+      options = options.transform_keys(&:to_sym)
+      desired_state_instance = state_instance(desired_state, options)
 
       with_transition_options(options) do
-        return false unless valid_transition?(desired_state.to_s)
-
-        desired_state = state_instance(desired_state.to_s)
+        return false unless valid_transition?(desired_state_instance)
 
-        transitioned = if desired_state.transactional?
-          desired_state.perform_transactional_transition!
+        transitioned = if desired_state_instance.transactional?
+          desired_state_instance.perform_transactional_transition!
         else
-          desired_state.perform_transition!
+          desired_state_instance.perform_transition!
         end
       end
 
       transitioned
+    ensure
+      (desired_state_instance&.errors || []).each do |error|
+        object.errors.add(error.attribute, error.type)
+      end
     end
 
     ##
     # Makes the actual transition from one state to the next and
-    # runs the before and after transition callbacks.
+    # runs the before and after transition callbacks. The
+    # after_transition_commit callbacks run after the update completes
+    # and only when it succeeds.
     def perform_transition!
-      run_callbacks :transition do
-        object.update("#{object.state_attribute}": state)
+      run_callbacks :transition_commit do
+        run_callbacks :transition do
+          object.update("#{object.state_attribute}": state)
+        end
       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.
+    # to allow for roll backs. The after_transition_commit callbacks run
+    # outside the transaction and only when it commits (not on rollback).
     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)
+      run_callbacks :transition_commit do
+        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
 
-      object.reload.public_send(object.state_attribute) == state
+        @previous_state = previous_state
+
+        object.reload.public_send(object.state_attribute) == state
+      end
     end
 
     private
@@ -88,32 +121,25 @@ module HasStateMachine
       raise ActiveRecord::Rollback
     end
 
-    ##
-    # Determines if the given desired state exists in the predetermined
-    # list of allowed transitions.
-    def can_transition?(desired_state)
-      possible_transitions.include? desired_state
-    end
-
     ##
     # Helper method for grabbing the previous state of the object after
     # it has been transitioned to the new state. Useful in
     # after_transition blocks
     def previous_state
-      object.previous_changes[object.state_attribute]&.first
+      @previous_state.presence || object.previous_changes[object.state_attribute]&.first
     end
 
-    def state_instance(desired_state)
+    def state_instance(desired_state, transient_values)
       klass = "#{object.workflow_namespace}::#{desired_state.to_s.classify}".safe_constantize
-      klass&.new(object)
+      klass&.new(object, transient_values)
     end
 
-    def valid_transition?(desired_state)
+    def valid_transition?(desired_state_instance)
       return true if object.skip_state_validations
 
       object.valid? &&
-        can_transition?(desired_state) &&
-        state_instance(desired_state)&.valid?
+        can_transition?(desired_state_instance) &&
+        desired_state_instance&.valid?
     end
 
     def with_transition_options(options, &block)
@@ -135,21 +161,24 @@ module HasStateMachine
         @transactional || false
       end
 
-      ##
-      # Setter for the HasStateMachine::State classes to define the possible
-      # states the current state can transition to.
-      def transitions_to(states)
-        state_options(transitions_to: states)
-        HasStateMachine::Deprecation.deprecation_warning(:transitions_to, "use state_options instead")
+      def transients
+        @transients || []
       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)
+      def state_options(transitions_to: [], transactional: false, transients: [])
         @possible_transitions = transitions_to.map(&:to_s)
         @transactional = transactional
+        @transients = transients.map(&:to_sym)
+
+        transients.each do |transient_name|
+          define_method(transient_name) do
+            instance_variable_get(:"@#{transient_name}")
+          end
+        end
       end
     end
   end

data/lib/has_state_machine/state_helpers.rb

@@ -114,10 +114,10 @@ module HasStateMachine
       def state_instance_validations
         return unless state_class.present?
 
-        state_instance = public_send(state_attribute.to_s)
-        return if state_instance.valid?
+        current_state_instance = public_send(state_attribute.to_s)
+        return if current_state_instance.valid?
 
-        state_instance.errors.each do |error|
+        current_state_instance.errors.each do |error|
           errors.add(error.attribute, error.type)
         end
       end

data/lib/has_state_machine/version.rb

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

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: has_state_machine
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Benjamin Hargett
 - Jake Hurd
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -29,16 +28,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -95,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
 description: HasStateMachine uses ruby classes to make creating a finite state machine
   in your ActiveRecord models a breeze.
 email:
@@ -119,7 +132,6 @@ homepage: https://www.github.com/encampment/has_state_machine
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -134,8 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Class based state machine for ActiveRecord models.
 test_files: []