the_help 2.0.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f11ddd3d1fc5d239938188bda0cba4c3e57d86433fc39f5214dc9ae6aee875af
-  data.tar.gz: e1a80305b54998dfb4c84e6ec8c1b0c49ccaedc0b21c969becfaca90a671ac60
+  metadata.gz: a75d7a8941930a8c0364a9ab46feb9d84ed033854f6f00f7c94b2edd7835a37a
+  data.tar.gz: 7a1155356c2e5d7b41aa7abae90cbf75debd78cfb2213cd1a73bf8e68250dc3d
 SHA512:
-  metadata.gz: 0af2dbe4d5979ed8d525794f9797c0011a4535ebe7127afd3bddd2a5c11911c0b919c86b8527916a49ee0e29decf662a28c9317cdea935cd8366e1bf56d781e7
-  data.tar.gz: '019aaca0b3c14e5d96ac5e0f661f5fb9cb8c04ddcbff254ae27f9c380c19a44019037ae80026dbb24604c0a2d09e8b50331f9e94b325515083ab1c67cb083594'
+  metadata.gz: 8b41c62f81ccca29c73cbdce4973c1fc7cbb9fd51c55e6b387cd7015c0280e5db1d38fd34d6b288ecca318782e53144364c0486df73ea15cebf66269a2b1c2dd
+  data.tar.gz: 339df6294d38b60184704eabdc219e8f5c960a3fd898d461aa4d7f885e0e13de0a2db1be9098a87510e9f2ce4e2c84f741f3d316ce5281c18c875bdf13fdcd46

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# TheHelp Changelog #
+
+## 3.3.0 ##
+
+* Calling `#stop!` with no arguments in a service definition will now check that a result was set
+  with either `#result.success` or `#result.error` and raise `TheHelp::NoResultError` if no result
+  was set.
+
+* You can now call `#stop!` with both a `type:` and `value:` argument. `type:` can be either
+  `:error` (the default) or `:success`, and `value:` can be any object. Calling in this manner
+  will set the service result to the specified type and value.

data/Gemfile.lock

@@ -1,50 +1,55 @@
 PATH
   remote: .
   specs:
-    the_help (2.0.0)
+    the_help (3.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.0)
-    byebug (11.0.1)
-    diff-lcs (1.3)
-    jaro_winkler (1.5.3)
-    parallel (1.18.0)
-    parser (2.6.5.0)
-      ast (~> 2.4.0)
+    ast (2.4.1)
+    byebug (11.1.3)
+    diff-lcs (1.4.4)
+    parallel (1.19.2)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
     rainbow (3.0.0)
-    rake (10.5.0)
+    rake (13.0.1)
+    regexp_parser (1.8.2)
+    rexml (3.2.4)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
       rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.0)
-      rspec-support (~> 3.9.0)
-    rspec-expectations (3.9.0)
+    rspec-core (3.9.3)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.0)
+    rspec-mocks (3.9.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
-    rspec-support (3.9.0)
-    rubocop (0.75.1)
-      jaro_winkler (~> 1.5.1)
+    rspec-support (3.9.4)
+    rubocop (0.93.1)
       parallel (~> 1.10)
-      parser (>= 2.6)
+      parser (>= 2.7.1.5)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8)
+      rexml
+      rubocop-ast (>= 0.6.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.1.0)
+      parser (>= 2.7.1.5)
     ruby-progressbar (1.10.1)
-    unicode-display_width (1.6.0)
-    yard (0.9.20)
+    unicode-display_width (1.7.0)
+    yard (0.9.25)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   byebug
-  rake (~> 10.0)
+  rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 0.50)
   the_help!

data/README.md

@@ -28,10 +28,128 @@ them.
 Make it easier to call a service by including
 [`TheHelp::ServiceCaller`](lib/the_help/service_caller.rb).
 
+### Service Results
+
+Every service call will return an instance of `TheHelp::Service::Result`. Your service
+implementation MUST set a result using either the `#success` or the `#error` methods, for example:
+
+```ruby
+class MyService < TheHelp::Service
+  authorization_policy allow_all: true
+
+  input :foo
+
+  main do
+    if foo
+      result.success 'bar'
+    else
+      result.error 'sorry, that did not work'
+    end
+  end
+end
+
+result = MyService.call(context: {}, logger: logger, foo: false)
+result.success?
+#=> false
+result.error?
+#=> true
+result.value
+#=> 'sorry, that did not work'
+result.value!
+# raises the exception TheHelp::Service::ResultError with the message 'sorry, that did not work'
+
+result = MyService.call(context: {}, logger: logger, foo: true)
+result.success?
+#=> true
+result.error?
+#=> false
+result.value
+#=> 'bar'
+result.value!
+#=> 'bar'
+
+MyService.call(context: {}, logger: logger, foo: true) { |result|
+  break 'oops' if result.error?
+
+  result.value + ' baz'
+}
+#=> 'bar baz'
+```
+
+When using the ServiceCaller interface, unless a block is provided, the `#call_service` will call
+the `TheHelp::Service::Result#value!` method internally, and will either return the succesful
+result value or raise an exception as appropriate.
+
+```ruby
+call_service(MyService, foo: true)
+#=> 'bar'
+
+call_service(MyService, foo: false)
+# raises the exception TheHelp::Service::ResultError with the message 'sorry, that did not work'
+
+call_service(MyService, foo: true) { |result|
+  break 'oops' if result.error?
+
+  result.value + ' baz'
+}
+#=> 'bar baz'
+```
+
+Finally, you can change the type of the exception that is raised when
+`TheHelp::Service::Result#value!` is called on an error result by providing the exception itself
+as the result value:
+
+```ruby
+class MyService < TheHelp::Service
+  authorization_policy allow_all: true
+
+  input :foo
+
+  main do
+    if foo
+      result.success 'bar'
+    else
+      result.error ArgumentError.new('foo must be true')
+    end
+  end
+end
+
+call_service(MyService, foo: false)
+# raises the exception ArgumentError with the message 'foo must be true'
+```
+
+If you want to make sure the exception's backtrace points to the correct line of code, raise the
+exception in a block provided to the `#error` method:
+
+```ruby
+class MyService < TheHelp::Service
+  authorization_policy allow_all: true
+
+  input :foo
+
+  main do
+    if foo
+      result.success 'bar'
+    else
+      result.error { raise ArgumentError.new('foo must be true') }
+    end
+  end
+end
+
+call_service(MyService, foo: false)
+# raises the exception ArgumentError with the message 'foo must be true'
+```
+
+With the block form, the backtrace will point to the line where the exception was first raised
+rather than to the `#value!` method, however all other code execution will continue until the
+point where the `#value!` method is called (as long as the exception is a subtype of
+`StandardError`.)
+
 ### 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:
+In some cases a simple success or error result is not sufficient to describe the various results
+about which a service may need to be able to inform its callers. In these cases, a callback style
+of programming can be useful:
 
 ```ruby
 class Foo < TheHelp::Service
@@ -89,8 +207,10 @@ class GetSomeWidgets < TheHelp::Service
       invalid_customer.call
       no_widgets_found.call
       do_some_important_cleanup_for_invalid_customers
+      result.error 'invalid customer'
     else
       #...
+      result.success some_widgets
     end
   end
 
@@ -122,8 +242,10 @@ class GetSomeWidgets < TheHelp::Service
       run_callback(invalid_customer)
       run_callback(no_widgets_found)
       do_some_important_cleanup_for_invalid_customers
+      result.error 'invalid customer'
     else
       #...
+      result.success some_widgets
     end
   end
 

data/lib/the_help/errors.rb

@@ -6,5 +6,6 @@ module TheHelp
     class ServiceNotImplementedError < StandardError; end
     class NotAuthorizedError < RuntimeError; end
     class NoResultError < StandardError; end
+    class ResultError < StandardError; end
   end
 end

data/lib/the_help/service.rb

@@ -150,18 +150,42 @@ module TheHelp
         self
       end
 
-      def input(name, **options)
-        attr_accessor name, make_private: true
-        if options.key?(:default)
-          required_inputs.delete(name)
-          define_method(name) do
-            instance_variable_get("@#{name}") || options[:default]
-          end
+      # Defines a service input
+      #
+      # The specified input becomes a named parameter for the service's `#call` method.
+      #
+      # @param name [Symbol] This becomes the name of the input parameter
+      #
+      # @param block [Proc] If a block is provided, the contents of the block will be executed in
+      #                     the scope of the service instance in order to provide the default
+      #                     value of the input. This is different than providing a Proc to the
+      #                     `:default` option, which would simply return the Proc itself as the
+      #                     default value rather than calling it.
+      #
+      # @option options [Object] :default If specified (and no block is given), this becomes the
+      #                                   literal default value for the input.
+      def input(name, **options, &block)
+        if options.key?(:default) || block
+          make_optional_input(name, options[:default], &block)
         else
+          attr_accessor name, make_private: true
           required_inputs << name
         end
         self
       end
+
+      private
+
+      def make_optional_input(name, default, &block)
+        attr_writer name
+        private "#{name}="
+        default_routine = block || -> { default }
+        define_method("_#{name}", &default_routine)
+        define_method(name) do
+          instance_variable_get("@#{name}") || send("_#{name}")
+        end
+        required_inputs.delete(name)
+      end
     end
 
     # Holds the result of running a service as well as the execution status
@@ -194,12 +218,30 @@ module TheHelp
         freeze
       end
 
-      def error(value)
-        self.value = value
+      def error(value = nil, &block)
+        self.value = if block_given?
+                       begin
+                        self.value = block.call
+                       rescue StandardError => e
+                         e
+                       end
+                     else
+                       value
+                     end
         self.status = :error
         freeze
       end
 
+      def value!
+        raise TheHelp::NoResultError if pending?
+
+        raise value if error? && value.is_a?(Exception)
+
+        raise TheHelp::ResultError.new(value) if error?
+
+        value
+      end
+
       private
 
       attr_writer :status, :value
@@ -221,16 +263,21 @@ module TheHelp
     # @return [TheHelp::Service::Result]
     def call
       validate_service_definition
+
       catch(:stop) do
         authorize
         log_service_call
         main
         check_result!
-        self.block_result = yield result if block_given?
       end
+
+      self.block_result = yield result if block_given?
+
       throw :stop if stop_caller
+
       return block_result if block_given?
-      return result
+
+      result
     end
 
     private
@@ -273,11 +320,18 @@ module TheHelp
       return if authorized?
       logger.warn("Unauthorized attempt to access #{self.class.name}/#{__id__} " \
                   "as #{context.inspect}")
-      run_callback(not_authorized, service: self.class, context: context)
+      result.error run_callback(not_authorized, service: self.class, context: context)
       stop!
     end
 
-    def stop!
+    def stop!(type: :error, value: nil)
+      if value.nil?
+        check_result!
+      elsif type == :success
+        result.success value
+      else
+        result.error value
+      end
       throw :stop
     end
 

data/lib/the_help/service_caller.rb

@@ -39,7 +39,9 @@ module TheHelp
       }.merge(args)
       service_logger.debug("#{self.class.name}/#{__id__} called service " \
                            "#{service.name}")
-      service.call(**service_args, &block)
+      return service.call(**service_args, &block) if block_given?
+
+      service.call(**service_args).value!
     end
   end
 end

data/lib/the_help/version.rb

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

data/the_help.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'byebug'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 0.50'
   spec.add_development_dependency 'yard'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: the_help
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.3.0
 platform: ruby
 authors:
 - John Wilger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-28 00:00:00.000000000 Z
+date: 2020-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +93,7 @@ files:
 - ".rubocop.yml"
 - ".tool-versions"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock