has_state_machine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 180ea0ce6e3e597405acc08441fe8ee1c0f530ccfd176950e8683196e9232695
+  data.tar.gz: 97944638a358883f302463d830d506149fe169d9cf3a3c20d7ccd615724a4932
+SHA512:
+  metadata.gz: c4e20717ca8de688ea7c766da83412b7bf0121d06d2cace551dfd1b5210632fd9840ca34d7293381431b2ff4afc27459a33bfd2711ef537ee3ca39c8598d8098
+  data.tar.gz: 973704bfb4403dae0b5ff00a3fe3b2d0d6d84f96a5e706bd0dea8cda113bd7dbfc7bac97ce84ae310b4fb6613f287f257a1dfedea41794e06f7afbd4b5af3834

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 Benjamin Hargett
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,30 @@
+# HasStateMachine
+
+[![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.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'has_state_machine'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install has_state_machine
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+task default: %i[lint test]
+
+namespace :test do
+  task :refresh do
+    sh "bin/appraisal clean"
+    sh "bin/appraisal generate"
+  end
+
+  task :all do
+    sh "bin/appraisal install"
+    sh "bin/appraisal bin/rake test"
+  end
+end
+
+task :test do
+  sh "bin/test"
+end
+
+task :lint do
+  sh "bin/standardrb --no-fix"
+end
+
+namespace :changelog do
+  task :refresh do
+    sh "bin/refresh_changelog"
+  end
+end

data/lib/has_state_machine.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "has_state_machine/railtie"
+require "has_state_machine/core_ext/string"
+require "has_state_machine/definition"
+
+module HasStateMachine
+end
+
+ActiveRecord::Base.include HasStateMachine::Definition if defined?(ActiveRecord)

data/lib/has_state_machine/core_ext/string.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class String
+  ##
+  # Adding our transition method to the default String class to prevent
+  # exceptions while transitioning from an invalid state. This method
+  # gets overwritten by valid HasStateMachine::State classes.
+  #
+  # @return [Boolean] false
+  #
+  # @example
+  #   "some random string".transition_to("draft") #=> false
+  def transition_to(_desired_state)
+    false
+  end
+end

data/lib/has_state_machine/definition.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "has_state_machine/state"
+require "has_state_machine/state_helpers"
+
+module HasStateMachine
+  module Definition
+    extend ActiveSupport::Concern
+
+    class_methods do
+      ##
+      # Configures the state machine for the ActiveRecord object and adds some
+      # useful helper methods such as scopes, boolean checks, etc.
+      #
+      # @param states [Array<Symbol>] the list of possible states in a state machine
+      #   @note the first state is used as the initial state
+      # @param options [Hash] a hash of additional options for the state machine
+      #
+      # @example
+      #   class Post < ApplicationRecord
+      #     has_state_machine states: %i(draft published archived)
+      #   end
+      def has_state_machine(states: [], **options)
+        raise ArgumentError, "Please define at least one state to use has_state_machine." if states.empty?
+
+        define_helper_methods(
+          states: states.map(&:to_s),
+          options: options.with_indifferent_access
+        )
+
+        include HasStateMachine::StateHelpers
+      end
+
+      private
+
+      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
+
+        ##
+        # Defines the column name for the attribute holding the current status.
+        # Can be overwritten to use a different column name.
+        define_singleton_method "state_attribute" do
+          options[:state_attribute]&.to_sym || :status
+        end
+
+        ##
+        # Defines the namespace of the models possible states.
+        # Can be overwritten to use a different namespace.
+        define_singleton_method "workflow_namespace" do
+          (options[:workflow_namespace] || "Workflow::#{self}")
+        end
+
+        ##
+        # Determines whether or not the state validations should be run
+        # as part of the object validations.
+        define_singleton_method "state_validations_on_object?" do
+          return true unless options.key?(:state_validations_on_object)
+
+          options[:state_validations_on_object]
+        end
+      end
+    end
+  end
+end

data/lib/has_state_machine/railtie.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module HasStateMachine
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/has_state_machine/state.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string"
+
+module HasStateMachine
+  class State < String
+    extend ActiveModel::Model
+    extend ActiveModel::Callbacks
+    include ActiveModel::Validations
+
+    attr_reader :object, :state, :options
+
+    ##
+    # Defines the before_transition and after_transition callbacks
+    # for use on a HasStateMachine::State instance.
+    define_model_callbacks :transition, only: %i[before after]
+
+    ##
+    # Retrieves the next available transitions for a given state.
+    delegate :possible_transitions, :state, to: "self.class"
+
+    ##
+    # Add errors to the ActiveRecord object rather than the HasStateMachine::State
+    # class.
+    delegate :errors, to: :object
+
+    ##
+    # Initializes the HasStateMachine::State instance.
+    #
+    # @example
+    #   state = HasStateMachine::State.new(post) #=> "draft"
+    #   state.class #=> Workflow::Post::Draft
+    def initialize(object)
+      @object = object
+
+      super state
+    end
+
+    ##
+    # Checks to see if the desired state is valid and then gives
+    # responsibility to the desired state's instance to make the
+    # transition.
+    #
+    # @param desired_state [String] the state to transition to
+    # @param options [Hash] a hash of additional options for
+    #   transitioning the object
+    #
+    # @return [Boolean] whether or not the transition took place
+    def transition_to(desired_state, **options)
+      with_transition_options(options) do
+        return false unless valid_transition?(desired_state.to_s)
+
+        state_instance(desired_state.to_s).perform_transition!
+      end
+    end
+
+    ##
+    # Makes the actual transition from one state to the next and
+    # runs the before and after transition callbacks.
+    def perform_transition!
+      run_callbacks :transition do
+        object.update("#{object.state_attribute}": state)
+      end
+    end
+
+    private
+
+    ##
+    # 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
+
+    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]
+
+      object.valid? &&
+        can_transition?(desired_state) &&
+        state_instance(desired_state)&.valid?
+    end
+
+    def with_transition_options(options, &block)
+      @options = options
+      object.skip_state_validations = options[:skip_validations]
+      yield
+      object.skip_state_validations = false
+    end
+
+    class << self
+      def possible_transitions
+        @possible_transitions || []
+      end
+
+      def state
+        to_s.demodulize.underscore
+      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)
+      end
+    end
+  end
+end

data/lib/has_state_machine/state_helpers.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module HasStateMachine
+  module StateHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :skip_state_validations
+
+      delegate \
+        :state_attribute,
+        :state_validations_on_object?,
+        :workflow_namespace,
+        :workflow_states,
+        to: "self.class"
+
+      ##
+      # Sets the default value of the state method to the initial state
+      # defined in the state machine.
+      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.
+      validates state_attribute, inclusion: {in: workflow_states}, presence: true
+      validate :state_class_defined?
+      validate :state_instance_validations, if: :should_validate_state?
+
+      ##
+      # Overwrites the default getter for the state attribute to
+      # instantiate a HasStateMachine::State instance instead. If the state
+      # class does not exist, it simply returns a string.
+      #
+      # @return [HasStateMachine::State] the current state represented by a instance
+      #
+      # @example
+      #   post = Post.new(status: "draft")
+      #   post.status.class #=> Workflow::Post::Draft
+      define_method state_attribute.to_s do
+        return state_class.new(self) if state_class.present?
+
+        current_state
+      end
+
+      workflow_states.each do |state|
+        ##
+        # Defines scopes based on the state machine possible states
+        #
+        # @return [ActiveRecord_Relation]
+        # @example Retreiving a users published posts
+        #   > Post.published.where(user: user)
+        #   #=> [#<Post>]
+        scope state, -> { where("#{state_attribute} = ?", state) }
+
+        ##
+        # Defines boolean helpers to determine if the active state matches
+        # the specified state.
+        #
+        # @return [Boolean] whether or not the active state matches the call
+        # @example Check if a post is published
+        #   > post.published?
+        #   #=> true
+        define_method "#{state}?" do
+          current_state == state
+        end
+      end
+
+      private
+
+      ##
+      # Getter for the current state of the model based on the configured state
+      # attribute.
+      def current_state
+        self[state_attribute]
+      end
+
+      ##
+      # Predicate method for determining whether or not the state validations
+      # should be run as part of the object validations.
+      def should_validate_state?
+        return false unless state_validations_on_object?
+
+        !skip_state_validations
+      end
+
+      ##
+      # Gets the HasStateMachine::State class that represents the current state
+      # of the model.
+      def state_class
+        return unless current_state.present?
+
+        "#{workflow_namespace}::#{current_state.classify}".safe_constantize
+      end
+
+      ##
+      # True unless unable to find the HasStateMachine::State class for the current
+      # state.
+      def state_class_defined?
+        return if state_class.present?
+
+        errors.add(state_attribute, :not_implemented, message: "class must be implemented")
+      end
+
+      ##
+      # Runs the validations defined on the current HasStateMachine::State when calling
+      # model.valid?
+      def state_instance_validations
+        return unless state_class.present?
+
+        public_send(state_attribute.to_s).valid?
+      end
+    end
+
+    class_methods do
+      private
+
+      ##
+      # The initial state of the workflow based on the first state defined in the model
+      # has_state_machine states array.
+      def initial_state
+        workflow_states.first
+      end
+    end
+  end
+end

data/lib/has_state_machine/version.rb

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

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: has_state_machine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Benjamin Hargett
+- Jake Hurd
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: HasStateMachine uses ruby classes to make creating a finite state machine
+  in your ActiveRecord models a breeze.
+email:
+- hargettbenjamin@gmail.com
+- jake.hurd@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/has_state_machine.rb
+- lib/has_state_machine/core_ext/string.rb
+- lib/has_state_machine/definition.rb
+- lib/has_state_machine/railtie.rb
+- lib/has_state_machine/state.rb
+- lib/has_state_machine/state_helpers.rb
+- lib/has_state_machine/version.rb
+homepage: https://www.github.com/encampment/has_state_machine
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Class based state machine for ActiveRecord models.
+test_files: []