strict_states 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e7eb56411c3e039689e4f965c5a51f28cb66cb51
+  data.tar.gz: b57483f164ce151be42609b08cb9da6edcd62a4e
+SHA512:
+  metadata.gz: 21eb00e217b2c5d2d4e238bd1c064bb52ad53452a7abd04ae314ac2aaea26a6735671c6036959a12474d34ed71e0592068da7ec423c6d04a88cabbaa66537d6b
+  data.tar.gz: 10ed7ed0e33d050fec0d7da660276fbc34174359868f3b355e4656996db8654ceab2ddddd46a46f836c62db4c330f0ea5f69ddb572e3dba6825449ae94f6fc38

data/.gitignore

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

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.7
+  - 2.2.3
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Peter Boling
+
+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,146 @@
+# StrictStates
+
+Provides utility lookup methods to be used to access the states of your state machine to ensure you never typo them.
+Will raise errors on state machine state typos immediately, so if the code runs you know it is correct.
+
+Expected to be compatible with, and support multiple state machines per model, for:
+
+* The venerable [state_machine](https://github.com/pluginaweek/state_machine) gem (Rails 3 max)
+* The [@seuros](https://github.com/seuros) forked [state_machine](https://github.com/seuros/state_machine) repo (Rails 4 compat!)
+* The community-driven rewrite [state_machines](https://github.com/state-machines/state_machines) gem (Rails 4 & 5 compat!)
+* The venerable [aasm](https://github.com/aasm/aasm) gem (formerly "acts_as_state_machine") (Rails 3 & 4)
+  * Both pre and post version 4.3.0 when multiple state machines per model was added.
+
+Please file a bug if compatibility is missing for your state machine.
+
+`:machine_name` as `:state` is so universally common that it has been made the default when not provided.
+
+Most apps only use one state machine implementation, like aasm, or state_machines, however, apps can (and do) use multiple state machine implementations at the same time.  This gem supports that, and keeps all the states per-model, per-machine, per-engine separate!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'strict_states'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install strict_states
+
+## Usage
+
+```ruby
+class MyModel < ActiveRecord::Base
+  # ...
+  # <<<===--- AFTER STATE MACHINE DEFINITION ---===>>>
+  # ...
+  include StrictStates.checker(
+              klass: self,
+              machines: {
+                  state: :pluginaweek,
+                  awesome_level: :pluginaweek,
+                  bogus_level: ->(context, machine_name) {
+                    context.state_machines[machine_name.to_sym].states.map(&:name)
+                  }
+              }
+          )
+end
+```
+
+### strict_state
+
+Given a state return the same state if they are valid for the given state machine,
+otherwise raise an error
+
+Example:
+
+```ruby
+MyModel.strict_state(:good, machine_name: :state)
+=> "good"
+```
+
+```ruby
+MyModel.strict_state(:not_actually_a_thing, machine_name: :drive_status)
+=> KeyError: key not found: :not_actually_a_thing
+```
+
+This is better than creating discrete constants for each potential state string in a state machine,
+because this checks, at app boot, to ensure the states are correct.
+(e.g. "gift card", vs "gift_card").
+      
+### strict_state_array
+
+Given an array of states return the same array of states if they are valid for the given state machine,
+otherwise raise an error.
+
+Example:
+
+```ruby
+MyModel.strict_state_array(:good, :bad, :on_hold, machine_name: :state)
+=> ["good", "bad", "on_hold"]
+```
+
+```ruby
+MyModel.strict_state_array(:good, :bad, :steve_martin, machine_name: :drive_status)
+=> KeyError: key not found: :steve_martin
+```
+
+This is better than creating discrete constants for each potential set of states in a state machine,
+because this checks, at app boot, to ensure the states are correct.
+Raw strings in scopes and queries, not created via this method,
+will not be bound to the state machine's implementation, so they will fail silently.
+e.g. typos like "gift card" vs "gift_card" and no error raised
+
+### strict_all_state_names
+
+Given the name of a state machine, returns all states defined by the state machine, as an array of strings.
+
+```ruby
+MyModel.strict_all_state_names(machine_name: :state)
+=> ["good", "bad", "on_hold"]
+```
+
+### state_lookup
+
+Given a machine name return the StrictStates::StrictHash used to lookup valid states.
+
+```ruby
+MyModel.state_lookup(machine_name: :state)
+=> { :new => "new", :pending => "pending", :goofy => "goofy" }
+```
+
+### strict_state_lookup
+
+Returns a StrictStates::StrictHash representation of all the state machine state definitions in the class.  A class can have more than one state machine.
+
+```ruby
+MyModel.strict_state_lookup
+=>  {
+      :awesome_level =>
+        { :not_awesome => "not_awesome", :awesome_11 => "awesome_11", :bad => "bad", :good => "good" },
+      :bogus_level =>
+        { :new => "new", :pending => "pending", :goofy => "goofy" }
+    }
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/strict_states. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "strict_states"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/strict_states.rb

@@ -0,0 +1,162 @@
+require "strict_states/version"
+require "strict_states/strict_hash"
+require "strict_states/checker"
+
+# The *STRICT* paradigm:
+#
+#   * Will raise an error if states are spelled wrong when lookups happen through this paradigm.
+#   * Typos will be noisy, and many of them will error at app-load, so impossible to miss.
+#
+# Uses the StrictHash to accomplish this.  See lib/strict_states/strict_hash.rb
+#
+# The *INCLUDE WITH ARGUMENTS* paradigm:
+#
+#   * future-proof support for any/all state machines
+#   * easily integrate with any state machine engine not already supported by this gem
+#
+# Uses a method (StrictStates.checker) that returns a module (StrictStates::Checker) to accomplish this.
+module StrictStates
+  # Usage:
+  #
+  #     class MyModel < ActiveRecord::Base
+  #       # ...
+  #       # <<<===--- AFTER STATE MACHINE DEFINITION ---===>>>
+  #       # ...
+  #       include StrictStates.checker(
+  #                   klass: self,
+  #                   machines: {
+  #                       state: :pluginaweek,
+  #                       awesome_level: :pluginaweek,
+  #                       bogus_level: ->(context, machine_name) {
+  #                         context.state_machines[machine_name.to_sym].states.map(&:name)
+  #                       }
+  #                   }
+  #               )
+  #     end
+  #
+  def self.checker(**config)
+    validate_config(config)
+    config[:machines] = states_for_machines(config[:klass], config[:machines])
+    set_strict_state_lookup(config)
+    ::StrictStates::Checker
+  end
+
+  private
+
+  # Supported engines:
+  #
+  #   :pluginaweek    - for pluginaweek/state_machine
+  #   :seuros         - for seuros/state_machine
+  #   :state_machines - for state-machines/state_machines
+  #   :aasm           - for aasm/aasm version < 4.3.0
+  #   :aasm_multiple  - for aasm/aasm version >= 4.3.0
+  #
+  def self.engine_name_apis
+    {
+        pluginaweek:    ->(context, machine_name) { context.state_machines[machine_name.to_sym].states.map(&:name) },
+        seuros:         ->(context, machine_name) { context.state_machines[machine_name.to_sym].states.map(&:name) },
+        state_machines: ->(context, machine_name) { context.state_machines[machine_name.to_sym].states.map(&:name) },
+        aasm:           ->(context, _)            { context.aasm.states.map(&:name) },              # aasm gem version < 4.3.0
+        aasm_multiple:  ->(context, machine_name) { context.aasm(machine_name).states.map(&:name) } # aasm gem version >= 4.3.0
+    }
+  end
+
+  def self.strict_states_to_stings(states)
+    states.map {|state| state.to_s }
+  end
+
+  def self.create_strict_state_lookup(names)
+    default_strict_hash = names.each_with_object({}) do |state, memo|
+      memo[state.to_sym] = state
+    end
+    StrictHash[**default_strict_hash]
+  end
+
+  def self.validate_config(**config)
+    raise ArgumentError, "config must have a :machines key with Hash value  but was #{config[:machines]}" unless config[:machines] && config[:machines].is_a?(Hash)
+    raise ArgumentError, ":machines Hash must have values either from #{engine_name_apis.keys} or as Procs but was #{config[:machines]}" unless test_machines(config[:machines])
+    raise ArgumentError, "config must have a :klass key with a Class value but was #{config[:klass]}" unless config[:klass] && config[:klass].class == Class
+    true
+  end
+
+  def self.test_machines(machines)
+    machines.values.all? do |engine|
+      engine_name_apis.keys.include?(engine) ||
+          engine.respond_to?(:call)
+    end
+  end
+
+  # params:
+  #   klass - any Class object with a state machine
+  #   machines -
+  #     {
+  #         state: :pluginaweek,
+  #         awesome_level: :pluginaweek,
+  #         bogus_level: ->(context, machine_name) {
+  #           context.state_machines[machine_name.to_sym].states.map(&:name)}
+  #     }
+  #
+  # Example result
+  #
+  #     {
+  #         state:          ["one", "two", "three"],
+  #         awesome_level:  ["not_awesome", "awesome_11", "bad", "good"],
+  #         bogus_level:    ["new", "pending", "goofy"]
+  #     }
+  #
+  def self.states_for_machines(klass, machines)
+    machines.inject({}) do |memo, (machine_name, engine)|
+      proc = get_proc_for_engine(engine)
+      memo[machine_name] =
+          strict_states_to_stings(
+              proc.call(klass, machine_name)
+          )
+      memo
+    end
+  end
+
+  def self.get_proc_for_engine(engine)
+    if (proc = engine_name_apis[engine])
+      # Predefined Engine within this gem
+      proc
+    else
+      # Custom state machine name extraction Proc provided by caller
+      engine
+    end
+  end
+
+  # params:
+  #   config -
+  #     {
+  #       klass: Car, # any Class object with a state machine
+  #       machines: { # the machine names, and states defined within each
+  #         state:          ["one", "two", "three"],
+  #         awesome_level:  ["not_awesome", "awesome_11", "bad", "good"],
+  #         bogus_level:    ["new", "pending", "goofy"]
+  #       }
+  #     }
+  #
+  # Result:
+  #
+  #   MyModel.strict_state_lookup
+  #   =>  {
+  #         :state =>
+  #           { :one => "one", :two => "two", :three => "three" }
+  #         :awesome_level =>
+  #           { :not_awesome => "not_awesome", :awesome_11 => "awesome_11", :bad => "bad", :good => "good" },
+  #         :bogus_level =>
+  #           { :new => "new", :pending => "pending", :goofy => "goofy" }
+  #       }
+  def self.set_strict_state_lookup(config)
+    klass = config[:klass]
+    machines = config[:machines]
+    class << klass
+      attr_reader :strict_state_lookup
+    end
+    klass.instance_variable_set(:@strict_state_lookup, StrictStates::StrictHash.new)
+    machines.each do |machine_name, state_array|
+      klass.strict_state_lookup[machine_name.to_sym] = StrictStates.create_strict_state_lookup(state_array).freeze
+    end
+  end
+
+end

data/lib/strict_states/checker.rb

@@ -0,0 +1,79 @@
+module StrictStates
+  module Checker
+    # Usage:
+    #
+    #     class MyModel < ActiveRecord::Base
+    #       # ...
+    #       # <<<===--- AFTER STATE MACHINE DEFINITION ---===>>>
+    #       # ...
+    #       include StrictStates.checker(
+    #                   klass: self,
+    #                   machines: {
+    #                       state: :pluginaweek,
+    #                       awesome_level: :pluginaweek,
+    #                       bogus_level: ->(context, machine_name) {
+    #                         context.state_machines[machine_name.to_sym].states.map(&:name)
+    #                       }
+    #                   }
+    #               )
+    #     end
+    #
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+    end
+
+    module ClassMethods
+      # Given a state return the same state if they are valid for the given state machine,
+      #
+      #   MyModel.state_lookup(machine_name: machine_name)
+      #   => { :new => "new", :pending => "pending", :goofy => "goofy" }
+      #
+      def state_lookup(machine_name: :state)
+        strict_state_lookup[machine_name.to_sym]
+      end
+
+      # Given a state return the same state if they are valid for the given state machine,
+      #   otherwise raise an error
+      #
+      # Example:
+      #
+      #   MyModel.strict_state(:good, machine_name: :state)
+      #   => "good"
+      #   MyModel.strict_state(:not_actually_a_thing, machine_name: :drive_status) # Can support multiple state machines per model
+      #   => KeyError: key not found: :not_actually_a_thing
+      #
+      # This is better than creating discrete constants for each potential state string in a state machine,
+      #   because this checks, at app boot, to ensure the states are correct.
+      #   (e.g. "gift card", vs "gift_card").
+      #
+      def strict_state(state, machine_name: :state)
+        state_lookup(machine_name: machine_name)[state.to_sym] # This will raise an error if the state key is not a valid state
+      end
+
+      # Given an array of states return the same array of states if they are valid for the given state machine,
+      #   otherwise raise an error
+      #
+      # Example:
+      #
+      #   MyModel.strict_state_array(:good, :bad, :on_hold, machine_name: :state)
+      #   => ["good", "bad", "on_hold"]
+      #   MyModel.strict_state_array(:good, :bad, :steve_martin, machine_name: :drive_status) # Can support multiple state machines per model
+      #   => KeyError: key not found: :steve_martin
+      #
+      # This is better than creating discrete constants for each potential set of states in a state machine,
+      #   because this checks, at app boot, to ensure the states are correct.
+      # Raw strings in scopes and queries, not created via this method,
+      #   will not be bound to the state machine's implementation, so they will fail silently.
+      #   e.g. typos like "gift card" vs "gift_card" and no error raised
+      #
+      def strict_state_array(*names, machine_name: :state)
+        names.map {|state| strict_state(state, machine_name: machine_name) }
+      end
+
+      # Given the name of a state machine, returns all states defined by the state machine, as an array of strings.
+      def strict_all_state_names(machine_name: :state)
+        state_lookup(machine_name: machine_name).values # keys would be symbols!
+      end
+    end
+  end
+end

data/lib/strict_states/strict_hash.rb

@@ -0,0 +1,7 @@
+require "hashie/extensions/strict_key_access"
+
+module StrictStates
+  class StrictHash < Hash
+    include Hashie::Extensions::StrictKeyAccess
+  end
+end

data/lib/strict_states/version.rb

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

data/strict_states.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'strict_states/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "strict_states"
+  spec.version       = StrictStates::VERSION
+  spec.authors       = ["Peter Boling"]
+  spec.email         = ["peter.boling@gmail.com"]
+
+  spec.summary       = %q{Safely access state machine states with guarantee that there are no typos.}
+  spec.description   = %q{Safely access state machine states with guarantee that there are no typos.  Compatible with all Ruby state machine libraries.}
+  spec.homepage      = "https://github.com/pboling/strict_states"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "hashie", ">= 3.4.3"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: strict_states
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Peter Boling
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.3
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !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: rspec
+  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: Safely access state machine states with guarantee that there are no typos.  Compatible
+  with all Ruby state machine libraries.
+email:
+- peter.boling@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/strict_states.rb
+- lib/strict_states/checker.rb
+- lib/strict_states/strict_hash.rb
+- lib/strict_states/version.rb
+- strict_states.gemspec
+homepage: https://github.com/pboling/strict_states
+licenses:
+- MIT
+metadata: {}
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Safely access state machine states with guarantee that there are no typos.
+test_files: []