the_help 1.4.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16fd1e45c719b154afcdca402e8c5a049fd521e9a11c6a1c54f7abc9fc3e13fc
-  data.tar.gz: 9b9cac4ed3fdfcb4ad9f5359aa76f9a3298592017a9a7733be5d64d1712e6a0b
+  metadata.gz: 6fdee5c4c5d8c3c2d67bbb8abf7fb42379961924c59faa7f36da7575a085d325
+  data.tar.gz: 96464f2494174451d4581f984050fc258901b010a27556a3dc19a555ba2d99ab
 SHA512:
-  metadata.gz: ea9b7907840050fa2017b2bc4d055f948524d52141c71d70dcbbd04800eb0a911ff2744f4278a777a6a4509f5273cb68f8c9685079b14cc027bdaa6ed5c687c5
-  data.tar.gz: ca5962b02c675ae30a2de84c1c3b782ed56f1a672f0be39256af50273eca28fa6ac8e488e336ab705bf42ccc9501a70dec73ceaca0b774f52d4713d32181ba7d
+  metadata.gz: 800152351fd6ca49eab793748e48030cdb73f14c53f8ad4cd419be8a28e1fc20291a40948ee764744b924b53b7a96a0f13c109024cd1f5ebf0cb2bc09326c1bc
+  data.tar.gz: 3c11bcb7dbcf769a5045f3a42bcf52cec4b5a06ecee8015eda56554ae67d7f4604bb1df15914f09bf4c4991eb74201bc47120c675659f85e0c4c05b6cb576b2b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    the_help (1.4.2)
+    the_help (1.5.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,8 +1,8 @@
 # TheHelp
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/the_help`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+TheHelp is a framework for developing service objects in a way that encourages
+adherence to the [Single Responsibility Principle][SRP] and [Tell Don't
+Ask][TDA]
 
 ## Installation
 
@@ -22,7 +22,122 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Create subclasses of [`TheHelp::Service`][lib/the_help/service.rb] and call
+them.
+
+Make it easier to call a service by including
+[`TheHelp::ServiceCaller`][lib/the_help/service_caller.rb].
+
+### Running Callbacks
+
+This library encourages you to pass in callbacks to a service rather than
+relying on a return value from the service call. For example:
+
+```ruby
+class Foo < TheHelp::Service
+  authorization_policy allow_all: true
+
+  main do
+    call_service(GetSomeWidgets,
+                 customer_id: 12345,
+                 each_widget: method(:process_widget),
+                 invalid_customer: method(:no_customer),
+                 no_widgets_found: method(:no_widgets))
+    do_something_else
+  end
+
+  private
+
+  def process_widget(widget)
+    # do something with it
+  end
+
+  def invalid_customer
+    # handle this case
+    stop!
+  end
+
+  def no_widgets
+    # handle this case
+  end
+
+  def do_something_else
+    # ...
+  end
+end
+```
+
+When writing a service that accepts callbacks like this, do not simply run
+`#call` on the callback that was passed in. Instead you must use the
+`#run_callback` method. This ensures that, if the callback method you pass in
+tries to halt the execution of the service, it will behave as expected.
+
+In the above service, it is clear that the intention is to stop executing the
+`Foo` service in the case where `GetSomeWidgets` reports back that the customer
+was invalid. However, if `GetSomeWidgets` is implemented as:
+
+```ruby
+class GetSomeWidgets < TheHelp::Service
+  input :customer_id
+  input :each_widget
+  input :invalid_customer
+  input :no_widgets_found
+
+  authorization_policy allow_all: true
+
+  main do
+    set_some_stuff_up
+    if customer_invalid?
+      invalid_customer.call
+      no_widgets_found.call
+      do_some_important_cleanup_for_invalid_customers
+    else
+      #...
+    end
+  end
+
+  #...
+end
+```
+
+then the problem is that the call to `#stop!` in the `Foo#invalid_customer`
+callback will not just stop the `Foo` service, it will also stop the
+`GetSomeWidgets` service at the point where the callback is executed (because it
+uses `throw` behind the scenes.) This would cause the
+`do_some_important_cleanup_for_invalid_customers` method to never be called.
+
+You can protect yourself from this by implementing `GetSomeWidgets` like this,
+instead:
+
+```ruby
+class GetSomeWidgets < TheHelp::Service
+  input :customer_id
+  input :each_widget
+  input :invalid_customer
+  input :no_widgets_found
+
+  authorization_policy allow_all: true
+
+  main do
+    set_some_stuff_up
+    if customer_invalid?
+      run_callback(invalid_customer)
+      run_callback(no_widgets_found)
+      do_some_important_cleanup_for_invalid_customers
+    else
+      #...
+    end
+  end
+
+  #...
+end
+```
+
+This will ensure that callbacks only stop the service that provides them, not
+the service that calls them. (If you really do need to allow the calling service
+to stop the execution of the inner service, you could raise an exception or
+throw a symbol other than `:stop`; but do so with caution, since it may have
+unintended consequences further down the stack.)
 
 ## Development
 
@@ -41,3 +156,6 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the TheHelp project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jwilger/the_help/blob/master/CODE_OF_CONDUCT.md).
+
+[SRP]: https://en.wikipedia.org/wiki/Single_responsibility_principle
+[TDA]: https://martinfowler.com/bliki/TellDontAsk.html

data/lib/the_help/service.rb

@@ -29,8 +29,8 @@ module TheHelp
   #       end
   #     end
   #
-  #     callback(:message_sent) do
-  #       # do something really important, I'm sure
+  #     callback(:message_sent) do |message|
+  #       # do something really important with `message`, I'm sure
   #     end
   #   end
   #
@@ -49,11 +49,12 @@ module TheHelp
   #
   #   class SendWelcomeMessage < TheHelp::Service
   #     input :user
-  #     input :success, default: ->() { }
+  #     input :success, default: ->(message) { }
   #
   #     main do
-  #       # whatever
-  #       success.call
+  #       message = 'Hello, world!'
+  #       # do something with message...
+  #       run_callback(success, message)
   #     end
   #   end
   #
@@ -96,6 +97,7 @@ module TheHelp
   #   service_result
   #   #=> :the_service_result
   #
+  # @note See README section "Running Callbacks"
   class Service
     include ProvidesCallbacks
     include ServiceCaller
@@ -189,6 +191,7 @@ module TheHelp
       self.logger = logger
       self.not_authorized = not_authorized
       self.inputs = inputs
+      self.stop_caller = false
     end
 
     def call
@@ -199,6 +202,7 @@ module TheHelp
         main
         self.block_result = yield result if block_given?
       end
+      throw :stop if stop_caller
       return block_result if block_given?
       return result if result_set?
       self
@@ -206,7 +210,8 @@ module TheHelp
 
     private
 
-    attr_accessor :context, :logger, :not_authorized, :block_result
+    attr_accessor :context, :logger, :not_authorized, :block_result,
+                  :stop_caller
     attr_writer :result
     attr_reader :inputs
 
@@ -243,8 +248,8 @@ module TheHelp
       return if authorized?
       logger.warn("Unauthorized attempt to access #{self.class.name} " \
                   "as #{context.inspect}")
-      not_authorized.call(service: self.class, context: context)
-      throw :stop
+      run_callback(not_authorized, service: self.class, context: context)
+      stop!
     end
 
     def stop!
@@ -259,5 +264,14 @@ module TheHelp
     def result_set?
       defined?(@result)
     end
+
+    def run_callback(callback, *args)
+      continue = false
+      continue = catch(:stop) do
+        callback.call(*args)
+        true
+      end
+      self.stop_caller ||= !continue
+    end
   end
 end

data/lib/the_help/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TheHelp
-  VERSION = '1.4.2'
+  VERSION = '1.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: the_help
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.5.0
 platform: ruby
 authors:
 - John Wilger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-08-31 00:00:00.000000000 Z
+date: 2018-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake