service_actor 3.8.1 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca3921af29250e8b2b68925ede79f0ad223d87bfa1be362e8e50cc178999658f
-  data.tar.gz: 86f770c478e718d0c1c20f0809ade458d1687cabeac24b35cfa39d35430ea35d
+  metadata.gz: 240bbafeef337eec8bdb7f265b1c5ad1715ae4909967e65eb0fb313d3aaa74e8
+  data.tar.gz: 7b8a442ff7ffec97bc9cd1466f5c6a2074e10bfa7edf6319468138acb37ad0d0
 SHA512:
-  metadata.gz: 29cfec59fba54ea9ea8ddd4a250588513ad3132d5ecef79f6d6f43a58c5fa6aded756bc34cd6e698f233e4d584072f7f7e7342e8e3ee71cb1027463334450c7b
-  data.tar.gz: 73b264aa00a02f23513da5b3b61b5a4a2b9a5afc72bb627d929f0a27c44a5cebf01b561d7e62c17fdb5293886f1bf65a6af0b69d0bd68674c2cad19eaef92ab3
+  metadata.gz: b8491915f458d3dae52063f3d4f2131c246101dd50393a9de921d7e68e6189f0eddbc87910438bd8f9a9a68f36f72a5b50c121c4879f07053ad1f0e2ec61be16
+  data.tar.gz: 4be5e6db8633232e0af626c0c71cb978c78b05be9082058f7bad3aeb81fa485975ade749f8be830f26ac049dc543c78553e0d0182e7d066e1c6e535bb2760fc2

data/README.md

@@ -123,6 +123,22 @@ actor.greeting # => "Have a wonderful day!"
 actor.greeting? # => true
 ```
 
+If you only have one value you want from an actor, you can skip defining an
+output by making it the return value of `.call()` and calling your actor with
+`.value()`:
+
+```rb
+class BuildGreeting < Actor
+  input :name
+
+  def call
+    "Have a wonderful day, #{name}!"
+  end
+end
+
+BuildGreeting.value(name: "Fred") # => "Have a wonderful day, Fred!"
+```
+
 ### Fail
 
 To stop the execution and mark an actor as having failed, use `fail!`:
@@ -183,6 +199,9 @@ Calling this actor will now call every actor along the way. Inputs and outputs
 will go from one actor to the next, all sharing the same result set until it is
 finally returned.
 
+If you use `.value()` to call this actor, it will give the return value of
+the final actor in the play chain.
+
 ### Rollback
 
 When using `play`, if an actor calls `fail!`, the following actors will not be

data/lib/service_actor/base.rb

@@ -15,6 +15,7 @@ module ServiceActor::Base
       base.include(ServiceActor::Checkable)
       base.include(ServiceActor::Defaultable)
       base.include(ServiceActor::Failable)
+      base.include(ServiceActor::Valuable)
     end
   end
 end

data/lib/service_actor/checkable.rb

@@ -20,8 +20,9 @@ module ServiceActor::Checkable
       self.service_actor_argument_errors = []
 
       service_actor_checks_for(:input)
-      super
+      return_val = super
       service_actor_checks_for(:output)
+      return_val
     end
 
     private

data/lib/service_actor/core.rb

@@ -45,6 +45,8 @@ module ServiceActor::Core
   # This method is used internally to override behavior on call. Overriding
   # `call` instead would mean that end-users have to call `super` in their
   # actors.
+  # When overriding and calling `super`, make sure the final value is the return
+  # value of `super` (see e.g. ServiceActor::Checkable).
   # :nodoc:
   def _call
     call

data/lib/service_actor/playable.rb

@@ -54,11 +54,17 @@ module ServiceActor::Playable
 
   module PrependedMethods
     def call
+      default_output = nil
+
       self.class.play_actors.each do |options|
         next unless callable_actor?(options)
 
-        options[:actors].each { |actor| play_actor(actor) }
+        options[:actors].each do |actor|
+          default_output = play_actor(actor)
+        end
       end
+
+      default_output
     rescue self.class.failure_class
       rollback
       raise
@@ -95,17 +101,18 @@ module ServiceActor::Playable
       return unless actor.ancestors.include?(ServiceActor::Core)
 
       actor = actor.new(result)
-      actor._call
+      call_output = actor._call
 
       (@played_actors ||= []).unshift(actor)
+
+      call_output
     end
 
     def play_method(actor)
       return unless actor.is_a?(Symbol)
 
-      send(actor)
-
-      true
+      # return truthy method value, or true as fallback
+      send(actor) || true
     end
 
     def play_interactor(actor)

data/lib/service_actor/result.rb

@@ -33,7 +33,7 @@ class ServiceActor::Result < BasicObject
   end
 
   def to_h
-    data
+    filter_default_output(data)
   end
 
   def inspect
@@ -59,7 +59,7 @@ class ServiceActor::Result < BasicObject
   end
 
   def failure?
-    data[:failure] || false
+    data[:failure] || data[:failure?] || false
   end
 
   def error
@@ -103,6 +103,14 @@ class ServiceActor::Result < BasicObject
 
   attr_reader :data
 
+  # Key `_default_output` is an internal datum used by actor class
+  # method `.valuable`. Don't expose it with the rest of the result.
+  def filter_default_output(h)
+    # using `filter` instead of `except` to maintain Ruby 2.7 compatibility
+    # update once support for 2.7 is dropped
+    h.filter { |k| k != :_default_output }
+  end
+
   def respond_to_missing?(method_name, _include_private = false)
     return true if method_name.end_with?("=")
     if method_name.end_with?("?") &&

data/lib/service_actor/valuable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Adds the `value` method to actors. This allows you to call `.value` and get
+# back the return value of that actor's `call` method.
+#
+# In the case of play actors, it will return the value of the final actor's
+# `call` method in the chain.
+#
+#   class MyActor < Actor
+#     def call
+#       "foo"
+#     end
+#   end
+#
+#   > MyActor.value
+#   => "foo"
+module ServiceActor::Valuable
+  class << self
+    def included(base)
+      base.extend(ClassMethods)
+      base.prepend(PrependedMethods)
+    end
+  end
+
+  module ClassMethods
+    def value(result = nil, **arguments)
+      call(result, **arguments)[:_default_output]
+    end
+  end
+
+  module PrependedMethods
+    def _call
+      result[:_default_output] = super
+    end
+  end
+end

data/lib/service_actor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ServiceActor
-  VERSION = "3.8.1"
+  VERSION = "3.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 3.8.1
+  version: 3.9.0
 platform: ruby
 authors:
 - Sunny Ripert
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-26 00:00:00.000000000 Z
+date: 2024-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -223,6 +223,7 @@ files:
 - lib/service_actor/playable.rb
 - lib/service_actor/result.rb
 - lib/service_actor/support/loader.rb
+- lib/service_actor/valuable.rb
 - lib/service_actor/version.rb
 homepage: https://github.com/sunny/actor
 licenses: