has_state_machine 0.6.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d4ecde120f4c419dfe63154f2e61cbb8459a77aedf0b45cc169a3eeac3bcb29
-  data.tar.gz: df52aa5a5a23abd0d230281e3d124eacbd56e9bbb17cc094a202a02a208fb732
+  metadata.gz: 7aad95d7b489183fa7a7c49af178871cb5cc169dbc3a9ae6bd4a93f7ce48ebea
+  data.tar.gz: 180dbc281d868326a908955013b17fcc935e54de43dbb367212f017e642b994d
 SHA512:
-  metadata.gz: 6c2e58ee081bdbd77e5b9b04adfc8eff0ff94f2bd50c63ed06317be69ae1ff18f28eb32bb149629f06ab41f285c7a4fa4e18788d7a8140b1d91372d3cc3ce8c1
-  data.tar.gz: f4aefba6c6484abf2dfb0f79a390ca80c8e686637accd18869f3c0991b74496f38bbbe65b47958213ebf12cc48079d3b01ba373a0f9bff16fbe03c11f64a357e
+  metadata.gz: 1eca09471018292e2cc4f41a6a53ec2cf12bc087de32af80595901099a4b589131b529bbf53891de89eacc86c5a9a3c16ca7102f31faec63443003c697c45a7e
+  data.tar.gz: 1b5a1e0a93e9f0648deac92b4fcba653ffeec037e9b3959092e71b5f9b391c93118e352ced5e7c1f44f385ceed1130ab62f1fde11dc4282ea2fb17097e66d47a

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
@@ -117,9 +119,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
@@ -139,6 +215,29 @@ module Workflow
 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

@@ -18,19 +18,34 @@ module HasStateMachine
     ##
     # 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,20 +58,24 @@ 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)
+        return false unless valid_transition?(desired_state_instance)
 
-        desired_state = state_instance(desired_state.to_s)
-
-        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
 
     ##
@@ -88,13 +107,6 @@ 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
@@ -103,17 +115,17 @@ module HasStateMachine
       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 +147,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.0.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.0.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
@@ -119,7 +118,6 @@ homepage: https://www.github.com/encampment/has_state_machine
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -134,8 +132,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: []