active_state 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ebbbe4c732963820345cfb88829d080694dd096be118a75d9dec49473326dedd
+  data.tar.gz: 7d420aa35bfb7977fa7a2562cb8e0877bc0d881a9c6296343e504a6da4bdf358
+SHA512:
+  metadata.gz: 39961d4d6fd20f06d087acb2b9db11c10b89a50c69905ecfed4ae6e13e28e23b8a214f0804446b92113dda55b3b35249143b55129d4ddac7a6201a7f15d2b740
+  data.tar.gz: 95f5dfd26a34845aeea6c5ce1a5361aa2532ae896ba4e0d151ab84f71f8247c4568acdd76c372c24ddbe320e2a6f0dcf8e781c1aafb1a749d276cd393eb05b23

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in active_state.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Matouš Vokál
+
+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,141 @@
+# ActiveState
+
+A tiny gem for easily using the state design pattern with ActiveRecord models. State objects will be automatically created when the model is instantiated. States can use the `ActiveModel::Validations` DSL for creating validations, which will be run when the model is validated. Scopes for individual states can easily be created on the model.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_state'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_state
+
+## Usage
+
+Let's assume that we have a model called `Report`. Every `Report` has an author - a `User`. Reports also have a url leading to an attached file (this example simply uses a string).  
+
+Reports are approved or rejected by a `User`. If a `Report` is rejected, the reviewer has to provide a reason for rejecting it. Reports cannot be reviewed by the `User` who created them.
+
+A `Report` can therefore be in one of three states - `Pending`, `Approved` or `Rejected`. In every state, different validations have to be run and methods will behave differently. Instead of polluting the model with many conditionals, the state pattern can be used to split the code into multiple short and readable classes.
+
+#### The migration
+
+```ruby
+class CreateReports < ActiveRecord::Migration[6.0]
+  def change
+    create_table :reports do |t|
+      t.references :author, foreign_key: { to_table: :users }
+      t.references :reviewer, foreign_key: { to_table: :users }
+      t.string :file_url
+      t.datetime :reviewed_at
+      t.text :reason_for_rejection
+      t.string :state_name # This is for ActiveState
+
+      t.timestamps
+    end
+  end
+end
+```
+
+#### The model
+
+```ruby
+class Report < ApplicationRecord
+  include ActiveState::Model
+  self.initial_state = Pending
+
+  belongs_to :author, class_name: 'User'
+  belongs_to :reviewer, class_name: 'User', optional: true
+  
+  # a url has to be present in all states
+  validates_presence_of :file_url
+
+  # create scopes for different states
+  # you can now call Report.pending and Report.approved
+  # custom names for scopes are also possible
+  # Report.thrown_out_the_window will return reports in the Rejected state
+  scope_for_state Pending, Approved, thrown_out_the_window: Rejected
+
+  # delegate methods that will be implemented in the state objects
+  delegate :approve_by, :reject_by, to: :state
+end
+```
+
+#### The states
+
+The states should probably be put inside a namespace to avoid naming collisions. In this case, they are put inside the Report class, but that is not required for ActiveState to work. To satisfy the Rails autoloading mechanism, these files need to be put in `app/*/reports`. It is up to you if you put the `reports` directory into `app/models` or into a new directory in `app` (possibly something like `app/states`).
+
+Pending:
+```ruby
+class Report
+  class Pending < ActiveState::Base
+    def approve_by(user)
+      review_by user
+      context.state = Approved.new context
+    end
+
+    def reject_by(user, reason:)
+      review_by user
+      context.reason_for_rejection = reason
+      context.state = Rejected.new context
+    end
+
+    private
+
+    def review_by(user)
+      context.reviewer = user
+      context.reviewed_at = Time.now
+    end
+  end
+end
+```
+
+Because some validations and implementations of methods will be the same in both `Approved` and `Rejected` states, we can make a common superclass for both. This is done simply to show that such a thing is possible, but it is up to us to make sure that the `Reviewed` state will never actually be assigned to a model. Treat it like an abstract class.
+
+```ruby
+class Report
+  class Reviewed < ActiveState::Base
+    # For validating attributes of the model, we need to get access to them
+    delegate :reviewer, :reviewed_at, to: :context
+    validates_presence_of :reviewer, :reviewed_at
+
+    def approve_by(_user)
+      raise StandardError, 'Report already reviewed'
+    end
+
+    def approve_by(_user, _reason)
+      raise StandardError, 'Report already reviewed'
+    end
+  end
+end
+```
+
+The `Approved` state does not need to do anything more than the `Reviewed` state. However, it would not make sense to have the state representing rejection subclass a state representing approval. This is why creating an empty subclass might be justifiable in this situation. 
+```ruby
+class Report
+  class Approved < Reviewed
+  end
+end
+```
+
+Rejected:
+```ruby
+class Report
+  class Rejected < Reviewed
+    delegate :reason_for_rejection, to: :context
+    validates_presence_of :reason_for_rejection
+  end
+end
+```
+
+## 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,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/active_state.gemspec

@@ -0,0 +1,40 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "active_state/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "active_state"
+  spec.version       = ActiveState::VERSION
+  spec.authors       = ["Matous Vokal"]
+  spec.email         = ["vokalmat@gmail.com"]
+
+  spec.summary       = "State design pattern for ActiveRecord"
+  spec.description   = "A simple gem for easily using the state design pattern in Rails."
+  spec.homepage      = "https://github.com/Sorc96/active_state"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/Sorc96/active_state"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_dependency "activemodel"
+end

data/lib/active_state.rb

@@ -0,0 +1,7 @@
+require 'active_state/version'
+require 'active_state/base'
+require 'active_state/model'
+require 'active_state/state_validator'
+
+module ActiveState
+end

data/lib/active_state/base.rb

@@ -0,0 +1,15 @@
+module ActiveState
+  class Base
+    include ActiveModel::Validations
+
+    attr_reader :context
+
+    def initialize(context)
+      @context = context
+    end
+
+    def state_name
+      self.class.name.demodulize
+    end
+  end
+end

data/lib/active_state/model.rb

@@ -0,0 +1,47 @@
+module ActiveState
+  module Model
+    module ClassMethods
+      attr_accessor :initial_state
+
+      ##
+      # Creates scopes for the given states in this form:
+      # scope :my_state, -> { where state_name: MyState.name }
+      #
+      # Also accepts pairs of scope_name: StateClass pairs:
+      # scope :scope_name, -> { where state_name: StateClass.name }
+      def scope_for_state(*states, **named)
+        states.each do |state|
+          named[state.name.demodulize.underscore] = state
+        end
+        named.each do |k, v|
+          scope k, -> { where state_name: v.name }
+        end
+      end
+    end
+
+    attr_accessor :state
+
+    def self.included(mod)
+      mod.extend ClassMethods
+      mod.validates_with StateValidator
+      mod.after_initialize :create_state_object
+      mod.before_save :synchronize_state_column
+    end
+
+    private
+
+    def create_state_object
+      state_class =
+        if state_name.nil?
+          self.class.initial_state
+        else
+          Object.const_get state_name
+        end
+      @state = state_class.new self
+    end
+
+    def synchronize_state_column
+      self.state_name = state.class.name
+    end
+  end
+end

data/lib/active_state/state_validator.rb

@@ -0,0 +1,16 @@
+module ActiveState
+  class StateValidator < ActiveModel::Validator
+    def validate(record)
+      state = record.state
+      unless state.respond_to? :valid?
+        raise NoMethodError, "State object #{state.inspect} does not respond to :valid?"
+      end
+
+      return if state.valid?
+
+      state.errors.each do |attribute, message|
+        record.errors.add attribute, message
+      end
+    end
+  end
+end

data/lib/active_state/version.rb

@@ -0,0 +1,3 @@
+module ActiveState
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: active_state
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matous Vokal
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A simple gem for easily using the state design pattern in Rails.
+email:
+- vokalmat@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- active_state.gemspec
+- lib/active_state.rb
+- lib/active_state/base.rb
+- lib/active_state/model.rb
+- lib/active_state/state_validator.rb
+- lib/active_state/version.rb
+homepage: https://github.com/Sorc96/active_state
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Sorc96/active_state
+  source_code_uri: https://github.com/Sorc96/active_state
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+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: State design pattern for ActiveRecord
+test_files: []