the_help 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f11ddd3d1fc5d239938188bda0cba4c3e57d86433fc39f5214dc9ae6aee875af
-  data.tar.gz: e1a80305b54998dfb4c84e6ec8c1b0c49ccaedc0b21c969becfaca90a671ac60
+  metadata.gz: 58c4ca451c960bbd6f54ee05d9a786db32365e8630cd57d1730d21b1e23b4b28
+  data.tar.gz: d6b16972071beed84aebb226bf77be94e8e04bdc38ea8eb452170da903287e05
 SHA512:
-  metadata.gz: 0af2dbe4d5979ed8d525794f9797c0011a4535ebe7127afd3bddd2a5c11911c0b919c86b8527916a49ee0e29decf662a28c9317cdea935cd8366e1bf56d781e7
-  data.tar.gz: '019aaca0b3c14e5d96ac5e0f661f5fb9cb8c04ddcbff254ae27f9c380c19a44019037ae80026dbb24604c0a2d09e8b50331f9e94b325515083ab1c67cb083594'
+  metadata.gz: 31854f6f5c438280a532d0f9674f10409873164fa240b06716939972d72dd28de48244dc9ab0b160d5714d9c351d5f37da2323cbf33780bcf4c62d23aeadbf2b
+  data.tar.gz: 59f1e173753355dbbaec54c1d4411c49184ff769e3a84061c5f81413e634761a9b959b86d8ffe9ff86bc54c3b2b316671bd75f477ee3fe693e7fbf7883ba6671

data/Gemfile.lock

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

data/README.md

@@ -28,10 +28,101 @@ 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'
+```
+
 ### 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 +180,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 +215,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

@@ -200,6 +200,16 @@ module TheHelp
         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

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.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: the_help
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - John Wilger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-28 00:00:00.000000000 Z
+date: 2019-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug