has_state_machine 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 180ea0ce6e3e597405acc08441fe8ee1c0f530ccfd176950e8683196e9232695
-  data.tar.gz: 97944638a358883f302463d830d506149fe169d9cf3a3c20d7ccd615724a4932
+  metadata.gz: 7a7e45d8de5f1bfdeb758a8d6b04668cceb84ef0fe41add93277237b48e0a75f
+  data.tar.gz: 1dcb7de655710c843ccd1a8521c7760bcbcde34e0c64324744a5e2dc2a2047d7
 SHA512:
-  metadata.gz: c4e20717ca8de688ea7c766da83412b7bf0121d06d2cace551dfd1b5210632fd9840ca34d7293381431b2ff4afc27459a33bfd2711ef537ee3ca39c8598d8098
-  data.tar.gz: 973704bfb4403dae0b5ff00a3fe3b2d0d6d84f96a5e706bd0dea8cda113bd7dbfc7bac97ce84ae310b4fb6613f287f257a1dfedea41794e06f7afbd4b5af3834
+  metadata.gz: 99bc942766e3741de93c38ba9fdd06300bb70ba688853b171525517a41c7830a56b144c49b31e129f5055dc3cb2b3d11901cf72cddaa0515df0095f973fc5332
+  data.tar.gz: 23a277ebd986ea496608e51a68a60d0696ae0366443605bc936bcce7481b0ff25ab9f66eeb004017d8dc34bbf320de837764482eb413c74acc582c649e06bcf6

data/README.md

@@ -3,8 +3,7 @@
 [![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.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -23,8 +22,79 @@ 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"
+    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"
+```
+
 ## Contributing
-Contribution directions go here.
+Coming Soon
 
 ## 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
 
     ##
@@ -78,7 +81,7 @@ module HasStateMachine
     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 +89,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,7 +49,7 @@ 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
@@ -102,8 +107,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.1.1"
 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.1.1
 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: 2020-10-30 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.