interaction 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 24abdee95d1dcb71e2f8fcff831c58fbc7eecd56
+  data.tar.gz: ce0165495f7ab28fe43bc63055f90816167cc7a4
+SHA512:
+  metadata.gz: 53f4b4878a61bcaff9faf77e6a7ae55436d9aab5f31d9982ae8cedd951745eaa8016c769ff60e745fb2c79970573d0964bae22d15631c2ff52f65afa42c859e5
+  data.tar.gz: 87e8aea24284006a64b866b9bf5738c6a62ab45458141b526a67346455ae5ddabac091eabd0917fc1fd8ebcf7e18b48f12eb4aa1196497cd9596d78c2516d4d4

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Steve Hodgkiss
+
+MIT License
+
+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,52 @@
+# Interaction
+
+Provides a convention for modelling user interactions as use case classes. A
+use case class represents and is named after something a user does with your
+application `SignUp`, `RequestResetPasswordEmail` etc.
+
+Attributes are whitelisted and coerced into an expected type using Virtus. An
+attribute will either be the specified type or nil.
+
+Take a look at the [code itself](https://github.com/stevehodgkiss/use_case/blob/master/lib/use_case.rb) for full details of the API provided.
+
+## A simple example
+
+```ruby
+class SignUp
+  include Interaction
+  include Interaction::ValidationHelpers
+  include ActiveModel::Validations
+
+  # Virtus
+  attribute :email, String
+  attribute :password, String
+
+  # ActiveModel validations
+  validates :email, :password, presence: true
+
+  attr_reader :user
+
+  def perform
+    validate!
+    create_user
+    deliver_welcome_email
+  end
+
+  private
+
+  def create_user
+    @user = User.create(attributes)
+    failure! unless @user.persisted?
+  end
+
+  def deliver_welcome_email
+    # ...
+  end
+end
+
+sign_up = SignUp.perform(username: 'john', password: 'j0hn')
+sign_up.success?
+# => true
+sign_up.user
+# => #<User id:...>
+```

data/Rakefile

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

data/interaction.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'interaction/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "interaction"
+  spec.version       = Interaction::VERSION
+  spec.authors       = ["Steve Hodgkiss"]
+  spec.email         = ["steve@hodgkiss.me"]
+  spec.summary       = %q{Provides a convention for modelling user interactions as use case classes.}
+  spec.description   = %q{}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "activemodel"
+  spec.add_dependency "virtus", ">= 1.0.4"
+end

data/lib/interaction.rb

@@ -0,0 +1,113 @@
+require "interaction/version"
+require "interaction/params"
+require "interaction/validation_helpers"
+
+module Interaction
+  # Override Ruby's module inclusion hook to prepend base with our #perform
+  # method, extend base with a .perform method, include Params for Virtus and
+  # ActiveSupport::Validation.
+  #
+  # @api private
+  def self.included(base)
+    base.class_eval do
+      prepend Perform
+      extend ClassMethods
+      include Params
+    end
+  end
+
+  module Perform
+    # Executes use case logic
+    #
+    # Use cases must implement this method. Assumes success if failure is not
+    # called.
+    #
+    # @since 0.0.1
+    # @api public
+    def perform
+      catch :halt do
+        super.tap do
+          success unless result_specified?
+        end
+      end
+    end
+  end
+
+  module ClassMethods
+    # Executes and returns the use case
+    #
+    # A use case object is instantiated with the supplied
+    # arguments, perform is called and the object is returned.
+    #
+    # @param args [*args] Arguments to initialize the use case with
+    #
+    # @return [Object] returns the use case object
+    #
+    # @since 0.0.1
+    # @api public
+    def perform(*args)
+      new(*args).tap do |use_case|
+        use_case.perform
+      end
+    end
+  end
+
+  # Indicates if the use case was successful
+  #
+  # @return [TrueClass, FalseClass]
+  #
+  # @since 0.0.1
+  # @api public
+  def success?
+    !!@success
+  end
+
+  # Indicates whether the use case failed
+  #
+  # @return [TrueClass, FalseClass]
+  #
+  # @since 0.0.1
+  # @api public
+  def failed?
+    !success?
+  end
+
+  private
+
+  # Mark the use case as successful.
+  #
+  # @return [TrueClass]
+  #
+  # @since 0.0.1
+  # @api public
+  def success
+    @success = true
+  end
+
+  # Mark the use case as failed.
+  #
+  # @since 0.0.1
+  # @api public
+  def failure
+    @success = false
+  end
+
+  # Mark the use case as failed and exits the use case.
+  #
+  # @since 0.0.1
+  # @api public
+  def failure!
+    failure
+    throw :halt
+  end
+
+  # Indicates whether the use case called success or failure
+  #
+  # @return [TrueClass, FalseClass]
+  #
+  # @api private
+  # @since 0.0.1
+  def result_specified?
+    defined?(@success)
+  end
+end

data/lib/interaction/params.rb

@@ -0,0 +1,30 @@
+require 'virtus'
+
+module Interaction
+  # Uses Virtus for whitelisting and type coercion.
+  #
+  # Virtus is configured in strict mode to ensure input is coerced to either
+  # the specified type or nil.
+  #
+  # @example
+  #   class SignUpForm
+  #     include Interaction::Params
+  #
+  #     attribute :name, String
+  #   end
+  #
+  #   SignUpForm.new(name: 'John Smith').name
+  #   # => "John Smith"
+  #
+  #   SignUpForm.new(name: ['a']) # => Virtus::CoercionError
+  #
+  #   SignUpForm.new.name
+  #   # => nil
+  module Params
+    def self.included(base)
+      base.class_eval do
+        include Virtus.model(strict: true, required: false)
+      end
+    end
+  end
+end

data/lib/interaction/validation_helpers.rb

@@ -0,0 +1,25 @@
+# Validation helpers intended to be used with
+# ActiveModel::Validations
+module Interaction::ValidationHelpers
+  private
+
+  # Halts execution of the use case if validation fails.
+  #
+  # @since 0.0.1
+  # @api public
+  def validate!
+    failure unless valid?
+  end
+
+  # Merges errors from another
+  # ActiveModel::Validations object with itself.
+  #
+  # @param object [ActiveModel::Validations]
+  #
+  # @api public
+  def merge_errors(object)
+    object.errors.each do |attribute, value|
+      errors.add(attribute, value)
+    end
+  end
+end

data/lib/interaction/version.rb

@@ -0,0 +1,3 @@
+module Interaction
+  VERSION = "0.0.1"
+end

data/spec/interaction/params_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe Interaction::Params do
+  it 'defaults attributes to not required so that nil or the given type is an acceptable value' do
+    params = Class.new do
+      include Interaction::Params
+      attribute :name, String
+    end.new
+    expect(params.name).to be_nil
+  end
+
+  context 'type coercion' do
+    let(:klass) {
+      Class.new do
+        include Interaction::Params
+
+        attribute :name, String
+      end
+    }
+
+    it 'fails loudly when given an incorrect type' do
+      expect {
+        klass.new(name: [])
+      }.to raise_error(Virtus::CoercionError)
+    end
+
+    it 'does not fail on nil or missing attributes' do
+      expect {
+        klass.new
+      }.not_to raise_error
+    end
+  end
+end

data/spec/interaction/validation_helpers_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+require 'active_model'
+
+describe Interaction::ValidationHelpers do
+  subject(:use_case) {
+    Class.new {
+      include Interaction
+      include Interaction::ValidationHelpers
+      include ActiveModel::Validations
+
+      def self.model_name
+        ActiveModel::Name.new(self, nil, "Test")
+      end
+
+      attr_accessor :name
+      validates :name, presence: true
+
+      def perform
+        validate!
+      end
+
+      public :merge_errors
+    }.new(params)
+  }
+  let(:params) { {} }
+
+  describe '#merge_errors' do
+    let(:object) { double(errors: errors) }
+    let(:errors) { ActiveModel::Errors.new(Object.new) }
+
+    before do
+      errors.add(:name, 'Test error')
+    end
+
+    it 'merges errors from the given object' do
+      use_case.merge_errors(object)
+      expect(use_case.errors[:name]).to eq ['Test error']
+    end
+  end
+
+  describe '#validate' do
+    before { use_case.perform }
+
+    context 'when validation fails' do
+      let(:params) { {} }
+
+      it { should_not be_success }
+    end
+
+    context 'when validation succeeds' do
+      let(:params) { { name: 'Test' } }
+
+      it { should be_success }
+    end
+  end
+end

data/spec/interaction_spec.rb

@@ -0,0 +1,159 @@
+require 'spec_helper'
+
+describe Interaction do
+  describe '.perform' do
+    let(:use_case_class) do
+      Class.new do
+        include Interaction
+
+        def initialize(*args)
+          @args = args
+        end
+
+        def perform
+          @performed = true
+        end
+
+        def performed?
+          @performed
+        end
+
+        attr_reader :args
+      end
+    end
+
+    it 'returns the new use case' do
+      use_case = use_case_class.perform
+      expect(use_case).to be_instance_of(use_case_class)
+    end
+
+    it 'calls #perform' do
+      use_case = use_case_class.perform
+      expect(use_case).to be_performed
+    end
+
+    it 'passes on args to initialize' do
+      use_case = use_case_class.perform(1, 2)
+      expect(use_case.args).to eq [1, 2]
+    end
+
+    context "when success or failure isn't indicated" do
+      subject(:use_case) { use_case_class.perform }
+
+      it 'defaults to success' do
+        expect(use_case).to be_success
+        expect(use_case).to_not be_failed
+      end
+    end
+  end
+
+  describe '#failure' do
+    let(:use_case_class) {
+      Class.new do
+        include Interaction
+
+        def initialize(*args)
+          @args = args
+        end
+
+        def perform
+          failure
+          @performed = true
+        end
+
+        def performed?
+          @performed
+        end
+      end
+    }
+    subject(:use_case) { use_case_class.perform }
+
+    it 'does not halt execution of the use case' do
+      expect(use_case).to be_performed
+    end
+
+    it 'marks the use case as failed' do
+      expect(use_case).to be_failed
+      expect(use_case).to_not be_success
+    end
+  end
+
+  describe '#failure!' do
+    let(:use_case_class) {
+      Class.new do
+        include Interaction
+
+        def initialize(*args)
+          @args = args
+        end
+
+        def perform
+          failure!
+          @performed = true
+        end
+
+        def performed?
+          @performed
+        end
+      end
+    }
+    subject(:use_case) { use_case_class.perform }
+
+    it 'halts execution of the use case' do
+      expect(use_case).to_not be_performed
+    end
+
+    it 'marks the use case as failed' do
+      expect(use_case).to be_failed
+      expect(use_case).to_not be_success
+    end
+  end
+
+  context 'on exception' do
+    let(:my_error) { Class.new(StandardError) }
+    let(:use_case_class) {
+      Class.new do
+        include Interaction
+
+        def perform
+          raise RuntimeError
+        end
+      end
+    }
+
+    it "marks the use case as failed" do
+      use_case = use_case_class.new
+      use_case.perform rescue RuntimeError
+      expect(use_case).to be_failed
+      expect(use_case).to_not be_success
+    end
+  end
+
+  describe '#success' do
+    let(:use_case_class) {
+      Class.new do
+        include Interaction
+
+        def initialize(*args)
+          @args = args
+        end
+
+        def perform
+          success(*@args)
+          @performed = true
+        end
+
+        def performed?
+          @performed
+        end
+      end
+    }
+    subject(:test) { klass.new(params) }
+    let(:params) { {} }
+
+    it 'marks the use case as success' do
+      use_case = use_case_class.perform
+      expect(use_case).to be_success
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,90 @@
+require 'interaction'
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause this
+# file to always be loaded, without a need to explicitly require it in any files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    # be_bigger_than(2).and_smaller_than(4).description
+    #   # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #   # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Limits the available syntax to the non-monkey patched syntax that is recommended.
+  # For more details, see:
+  #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: interaction
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Steve Hodgkiss
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: 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'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  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: virtus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.4
+description: ''
+email:
+- steve@hodgkiss.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- interaction.gemspec
+- lib/interaction.rb
+- lib/interaction/params.rb
+- lib/interaction/validation_helpers.rb
+- lib/interaction/version.rb
+- spec/interaction/params_spec.rb
+- spec/interaction/validation_helpers_spec.rb
+- spec/interaction_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Provides a convention for modelling user interactions as use case classes.
+test_files:
+- spec/interaction/params_spec.rb
+- spec/interaction/validation_helpers_spec.rb
+- spec/interaction_spec.rb
+- spec/spec_helper.rb
+has_rdoc: