has_state_machine 0.1.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 180ea0ce6e3e597405acc08441fe8ee1c0f530ccfd176950e8683196e9232695
-  data.tar.gz: 97944638a358883f302463d830d506149fe169d9cf3a3c20d7ccd615724a4932
+  metadata.gz: 16d6a43019c37f17fc0efac4e344f1e9914b0cb923a439d1e799d690018dd0e6
+  data.tar.gz: 8bd1d5d4f6b72dcb9931ccbd0987b0fe2d4970e2476867fe930cf21a9b5d0da2
 SHA512:
-  metadata.gz: c4e20717ca8de688ea7c766da83412b7bf0121d06d2cace551dfd1b5210632fd9840ca34d7293381431b2ff4afc27459a33bfd2711ef537ee3ca39c8598d8098
-  data.tar.gz: 973704bfb4403dae0b5ff00a3fe3b2d0d6d84f96a5e706bd0dea8cda113bd7dbfc7bac97ce84ae310b4fb6613f287f257a1dfedea41794e06f7afbd4b5af3834
+  metadata.gz: 7c7bb13405d5f0ee66af21594e0e0633e7c5f746ea7b038e2c28f4d53670b138b702bbd85737eadf952cb2871a234374597a10279f6fd0b026d7465b3721de79
+  data.tar.gz: ecb5c2c8ad0f00d1eb1c3ddd709598aa8ac29210dbaffe722461ba02bd8c7bc5c328ff7c4e90bbd8fdae8cbea91d5efe50d79b2874ed84035bc6bdf9d5a42421

data/README.md

@@ -3,8 +3,15 @@
 [![Build Status](https://github.com/bharget/has_state_machine/workflows/Tests/badge.svg)](https://github.com/bharget/has_state_machine/actions)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 
-## Usage
-How to use my plugin.
+HasStateMachine uses ruby classes to make creating a finite state machine for your ActiveRecord models a breeze.
+
+## Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Changelog](https://github.com/encampment/has_state_machine/blob/master/CHANGELOG.md)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -23,8 +30,104 @@ Or install it yourself as:
 $ gem install has_state_machine
 ```
 
+## 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.
+```ruby
+# By default, it is assumed that the "state" of the object is
+# stored in a string column named "status".
+class Post < ApplicationRecord
+  has_state_machine states: %i[draft published archived]
+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
+from `HasStateMachine::State`.
+
+```ruby
+module Workflow
+  class Post::Draft < HasStateMachine::State
+    # Define the possible transitions from the "draft" state
+    transitions_to %i[published archived]
+  end
+end
+
+module Workflow
+  class Post::Published < HasStateMachine::State
+    transitions_to %i[archived]
+
+    # Custom validations can be added to the state to ensure a transition is "valid"
+    validate :title_exists?
+
+    def title_exists?
+      return if object.title.present?
+
+      # Errors get added to the ActiveRecord object
+      errors.add(:title, "can't be blank")
+    end
+  end
+end
+
+module Workflow
+  class Post::Archived < HasStateMachine::State
+    # There are callbacks for running logic before and after
+    # a transition occurs.
+    before_transition do
+      Rails.logger.info "== Post is being archived ==\n"
+    end
+
+    after_transition do
+      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"
+    end
+  end
+end
+```
+
+Some examples:
+
+```ruby
+post = Post.create(status: "draft")
+
+post.status.transition_to(:published) # => false
+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
+```
+
 ## Contributing
-Contribution directions go here.
+
+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/definition.rb

@@ -36,7 +36,6 @@ module HasStateMachine
       def define_helper_methods(states:, options:)
         ##
         # The list of possible states in the state machine.
-        # Can be overwritten to use a different column name.
         define_singleton_method "workflow_states" do
           states
         end
@@ -57,7 +56,7 @@ module HasStateMachine
 
         ##
         # Determines whether or not the state validations should be run
-        # as part of the object validations.
+        # as part of the object validations; they are by default.
         define_singleton_method "state_validations_on_object?" do
           return true unless options.key?(:state_validations_on_object)
 

data/lib/has_state_machine/state.rb

@@ -8,7 +8,7 @@ module HasStateMachine
     extend ActiveModel::Callbacks
     include ActiveModel::Validations
 
-    attr_reader :object, :state, :options
+    attr_reader :object, :state
 
     ##
     # Defines the before_transition and after_transition callbacks
@@ -28,8 +28,7 @@ module HasStateMachine
     # Initializes the HasStateMachine::State instance.
     #
     # @example
-    #   state = HasStateMachine::State.new(post) #=> "draft"
-    #   state.class #=> Workflow::Post::Draft
+    #   state = Workflow::Post::Draft.new(post) #=> "draft"
     def initialize(object)
       @object = object
 
@@ -47,11 +46,15 @@ module HasStateMachine
     #
     # @return [Boolean] whether or not the transition took place
     def transition_to(desired_state, **options)
+      transitioned = false
+
       with_transition_options(options) do
         return false unless valid_transition?(desired_state.to_s)
 
-        state_instance(desired_state.to_s).perform_transition!
+        transitioned = state_instance(desired_state.to_s).perform_transition!
       end
+
+      transitioned
     end
 
     ##
@@ -72,13 +75,21 @@ module HasStateMachine
       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
+    end
+
     def state_instance(desired_state)
       klass = "#{object.workflow_namespace}::#{desired_state.to_s.classify}".safe_constantize
       klass&.new(object)
     end
 
     def valid_transition?(desired_state)
-      return true if options[:skip_validations]
+      return true if object.skip_state_validations
 
       object.valid? &&
         can_transition?(desired_state) &&
@@ -86,7 +97,6 @@ module HasStateMachine
     end
 
     def with_transition_options(options, &block)
-      @options = options
       object.skip_state_validations = options[:skip_validations]
       yield
       object.skip_state_validations = false

data/lib/has_state_machine/state_helpers.rb

@@ -5,6 +5,10 @@ module HasStateMachine
     extend ActiveSupport::Concern
 
     included do
+      ##
+      # Sometimes you may want to skip the validations defined on
+      # the state when validating your object; set this accessor
+      # to true to do so.
       attr_accessor :skip_state_validations
 
       delegate \
@@ -20,8 +24,9 @@ module HasStateMachine
       attribute state_attribute, :string, default: initial_state
 
       ##
-      # Validating any changes to the status attribute are represented by
-      # classes within the state machine and have a valid HasStateMachine::State class.
+      # Validate that the current state is a possible state, that there is a
+      # state class defined for it, and run the validations from the state
+      # class instance if need be.
       validates state_attribute, inclusion: {in: workflow_states}, presence: true
       validate :state_class_defined?
       validate :state_instance_validations, if: :should_validate_state?
@@ -44,13 +49,15 @@ module HasStateMachine
 
       workflow_states.each do |state|
         ##
-        # Defines scopes based on the state machine possible states
+        # Defines scopes based on the state machine's possible states
         #
         # @return [ActiveRecord_Relation]
         # @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
@@ -71,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
 
       ##
@@ -102,8 +109,8 @@ module HasStateMachine
       end
 
       ##
-      # Runs the validations defined on the current HasStateMachine::State when calling
-      # model.valid?
+      # Run the validations defined on the current HasStateMachine::State. Errors found there
+      # should be added to this object.
       def state_instance_validations
         return unless state_class.present?
 

data/lib/has_state_machine/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_state_machine
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Benjamin Hargett
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-22 00:00:00.000000000 Z
+date: 2021-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -133,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Class based state machine for ActiveRecord models.