use_case_pattern 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a796de4be01c7ff1d29ac4b4a5be9cf14509f647
-  data.tar.gz: 95cbe71afd5dda0f93b6d537e2bbb782fbcab41a
+  metadata.gz: 0197a45aa4b6b6aa27b43d0887d884950636bcb6
+  data.tar.gz: 5441894af403f3c87f1c63127d647528ca84e1c7
 SHA512:
-  metadata.gz: 4878b19038885f4654482ec655aaf340d931edb8a98d9ac280f7830adff2987c8f846981baaca2651b2e1db3121fadada88641ea19b46b02ab8f631877ef0978
-  data.tar.gz: f1e7b6b0ba605777cca19d621f89345aee70bf4135738b0ba2c7b28cba97b96a4d2021e0e843a40c557e61653110995cf3024b9581e2f1d2fbbcdbf0fc7fa499
+  metadata.gz: 7646d2e26a134e69f196366eaa34440bc10bbfc3c0ddf23045156463482fcd01c34ec635671a3fd448e02960f5128524ff566105e966815dab5d988640ed6f0b
+  data.tar.gz: 074c32d9931fb4df34311a999a50acb845aca8b89f964ae901155de40c038d74b4af1b7faea99f857621351a9eabf0a4016dada3ae3f3ccd961580fb4c5bf88a

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/.travis.yml

@@ -1,5 +1,6 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.2.2
+  - 2.2.5
+  - 2.3.1
 before_install: gem install bundler -v 1.13.1

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# AddressFinder 1.0.1 (October 12, 2016) #
+
+* Declare support for activemodel/activesupport version 4.0 or better
+
+# AddressFinder 1.0.0 (September 25, 2016) #
+
+* Initial release

data/README.md

@@ -1,8 +1,10 @@
 # UseCasePattern
 
+[![Build Status](https://travis-ci.org/AbleTech/use_case_pattern.svg?branch=master)](https://travis-ci.org/AbleTech/use_case_pattern)
+
 A module that helps you to implement the Use Case design pattern.
 
-This pattern is widely used by the teams at Abletech. We were first introduced to this pattern by Shevaun Coker at RubyConf AU 2015 in Melbourne, Australia. You can read more about this pattern in her blog post A [Case for Use Cases](http://webuild.envato.com/blog/a-case-for-use-cases/), and also in the [video of the presentation](https://rubyconf.eventer.com/rubyconf-australia-2015-1223/a-case-for-use-cases-by-shevaun-coker-1734) that she gave. 
+This pattern is widely used by the teams at Abletech. We were first introduced to this pattern by Shevaun Coker at RubyConf AU 2015 in Melbourne, Australia. You can read more about this pattern in her blog post A [Case for Use Cases](http://webuild.envato.com/blog/a-case-for-use-cases/), and also in the [video of the presentation](https://rubyconf.eventer.com/rubyconf-australia-2015-1223/a-case-for-use-cases-by-shevaun-coker-1734) that she gave.
 
 ## Installation
 
@@ -24,28 +26,22 @@ Or install it yourself as:
 
 When you follow the use case design pattern, you normally define a class with a constructor, and a perform method. You should include the `UseCasePattern` module. Here is a simple example:
 
-```ruby 
+```ruby
 class NumberMultiplier
   include UseCasePattern
 
   attr_reader :product
-  
+
   validates :number1, :number2, presence: true
 
   def initialize(number1, number2)
     @number1 = number1
     @number2 = number2
   end
-  
+
   def perform
-    if valid?
-      @product = number1 * number2
-    end
+    @product = @number1 * @number2
   end
-  
-  private
-  
-  attr_reader :number1, :number2
 end
 ```
 
@@ -54,7 +50,7 @@ You could call this simple example from a Rails Controller, or anywhere else rea
 ```ruby
   def multiply
     multiplier = NumberMultiplier.perform(params[:number1], params[:number2])
-    
+
     if multiplier.success?
       @result = multiplier.result
     else
@@ -63,6 +59,40 @@ You could call this simple example from a Rails Controller, or anywhere else rea
   end
 ```
 
+## Normal workflow
+
+This section defines the expected approach to implementing a class which uses the use case pattern.
+
+### Initialisation
+
+You would normally define a constructor for your use case. The constructor should store any supplied parameters as instance variables. You shouldn't perform any processing or business logic in the constructor.
+
+The constructor is called with the parameters that are passed to the `perform` class method. For example, using the NumberMultiplier defined above, making a call to `NumberMultiplier.perform(1, 2)` will result in the initialiser being called as `initialize(1, 2)`.
+
+### Validation
+
+You should use ActiveModel validators to check that supplied parameters and any other dependencies are correct. You can also write custom validation methods using the [validate method](http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validate). Following the standard validation approach, you should add to the `errors` collection if validation fails.
+
+### Execution
+
+The `perform` method is where the execution of the use case should happen. In this method, you should perform all of the processing and business logic of your use case. Results of the execution should be stored as instance variables.
+
+Sometimes during the execution of the `perform` method, an error may occur. You could choose to add to the errors collection or alternatively raise an exception. You should only add to the errors collection if you expect the caller to handle the error.
+
+You should note that the value returned from the perform method is discarded. This encourages the caller to make use of the public accessor methods to access the results of the operation.
+
+#### The alternative `perform!` method
+
+The `perform!` method works in a similar manner to the ActiveRecord `save!` method. Should a validation or other error occur, an exception is raised. This method should be used in scenarios where the caller does not expect any errors to occur. One example of this is when the parameters have been pre-checked by a controller class or similar.
+
+### Post-execution
+
+During the `perform` method, you should have stored the results as instance variables. You would normally make these publicly accessible using a `attr_reader` method declaration. You should avoid declaring public methods that further process the output of the `perform` method.
+
+#### Checking for errors
+
+The caller can check the success or failure of the use case by calling the `success?` and `failure?` helper methods. If the use case has had a failure, the errors will be available on the standard `errors` collection.
+
 ## 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.

data/examples/harvest.rb

@@ -1,8 +1,11 @@
 require 'nokogiri'
 
+# Queries weather station data provided by harvestelectronics.com
 class Harvest
   include UseCasePattern
 
+  validates :station_id, presence: true
+
   def initialize(station_id:)
     @station_id = station_id.to_i
   end

data/examples/thing_speak_reporter.rb

@@ -30,3 +30,13 @@ class ThingSpeakReporter
     params.merge(api_key: api_key)
   end
 end
+
+# example usage
+
+reporter = ThingSpeakReporter.perform(api_key: 'XZY123', params: {indoor_temperature: 22, outdoor_temperature: 15})
+
+if reporter.success?
+  puts "Temperature saved"
+else
+  puts "Oh dear, there is a problem: #{reporter.errors.full_messages.join('; ')}"
+end

data/lib/use_case_pattern/base.rb

@@ -9,10 +9,14 @@ module UseCasePattern
     module ClassMethods
       # The perform method of a UseCase should always return itself
       def perform(*args)
-        new(*args).tap { |use_case| use_case.perform }
+        new(*args).tap do |use_case|
+          if use_case.valid?
+            use_case.perform
+          end
+        end
       end
 
-      # Raise an exception if perform generates any errors
+      # Raise a validation error if perform has created any errors
       def perform!(*args)
         new(*args).tap { |use_case| use_case.perform! }
       end
@@ -24,19 +28,21 @@ module UseCasePattern
     end
 
     def perform!
-      perform
+      if valid?
+        perform
+      end
 
       if failure?
         raise_validation_error
       end
     end
 
-    # Has this use case performed its task successfully?
+    # Did the use case performed its task without errors?
     def success?
       errors.none?
     end
 
-    # Did this use case have any errors?
+    # Did the use case have any errors?
     def failure?
       errors.any?
     end

data/lib/use_case_pattern/version.rb

@@ -1,3 +1,3 @@
 module UseCasePattern
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/use_case_pattern.gemspec

@@ -20,10 +20,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = '~> 2.0'
+  spec.required_ruby_version = '~> 2.2'
 
-  spec.add_runtime_dependency "activemodel", [">= 4.0.0", "~> 5.0.0"]
-  spec.add_runtime_dependency "activesupport", [">= 4.0.0", "~> 5.0.0"]
+  spec.add_runtime_dependency "activemodel", [">= 4.0.0"]
+  spec.add_runtime_dependency "activesupport", [">= 4.0.0"]
 
   spec.add_development_dependency "bundler", "~> 1.13"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: use_case_pattern
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Nigel Ramsay
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-25 00:00:00.000000000 Z
+date: 2016-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -17,9 +17,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 4.0.0
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -27,9 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 4.0.0
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.0.0
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -37,9 +31,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 4.0.0
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -47,9 +38,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 4.0.0
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -102,6 +90,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile
@@ -125,7 +114,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: '2.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -133,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A module that helps you to implement the Use Case design pattern