service_actor 3.6.1 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0597123f9fd025cb0fdd1d099c9a4c29865a086a107d67f7b336b3828e6743c5'
-  data.tar.gz: fa2e8c72f82970ff779f1c870fa4074630b7e4d2d947f10f57e8a0670a9bae07
+  metadata.gz: 5654d6b33f83eaccbc860a7072e0f3f3fcf694e4e9ba5fdb4224ab6bd180f860
+  data.tar.gz: 755220b315eccaf564f6eeb85c234a4da1deeb24ea3e71740f7bba3cb5029135
 SHA512:
-  metadata.gz: 73dea56535940a843c9cf9bee977882293a0dd2ad4b6c0d3069fe28ea4b7d2569f3c3508cc68f8d378ebb526b00027b72a232373049bcf541e91861fe558d589
-  data.tar.gz: 282acf3196702a03f15e8faba840abdf68075abcc3e132dce6efcb090c5349b426f8261bd13fafc68f4e4fbac2a25a1401da8ad9b2638eb1d2a907cb548c8887
+  metadata.gz: 753d97cc97069242febc4212ca78c3f1149083dd928578e581c52073f556d40a6f275d08d28a28b97e1fd04841c05e78e3be3b122c2005cbd2775b7257f93b91
+  data.tar.gz: 511d62768af23e9b84aa8ae6d268901f5227caf54956cd6261c1835d518823413c43dae16d278ecf63d45737df4373dbb755b5d1e779afd4c90d7bec78848bc4

data/README.md

@@ -1,6 +1,6 @@
 # ServiceActor
 
-This Ruby gem lets you move your application logic into into small composable
+This Ruby gem lets you move your application logic into small composable
 service objects. It is a lightweight framework that helps you keep your models
 and controllers thin.
 
@@ -12,17 +12,18 @@ and controllers thin.
 - [Usage](#usage)
   - [Inputs](#inputs)
   - [Outputs](#outputs)
-  - [Defaults](#defaults)
-  - [Allow nil](#allow-nil)
-  - [Conditions](#conditions)
-  - [Types](#types)
   - [Fail](#fail)
-  - [Custom input errors](#custom-input-errors)
 - [Play actors in a sequence](#play-actors-in-a-sequence)
   - [Rollback](#rollback)
   - [Inline actors](#inline-actors)
   - [Play conditions](#play-conditions)
   - [Input aliases](#input-aliases)
+- [Input options](#input-options)
+  - [Defaults](#defaults)
+  - [Allow nil](#allow-nil)
+  - [Conditions](#conditions)
+  - [Types](#types)
+  - [Custom input errors](#custom-input-errors)
 - [Testing](#testing)
 - [FAQ](#faq)
 - [Thanks](#thanks)
@@ -77,7 +78,7 @@ SendNotification.call # => <ServiceActor::Result…>
 When called, an actor returns a result. Reading and writing to this result allows
 actors to accept and return multiple arguments. Let’s find out how to do that
 and then we’ll see how to
-[chain multiple actors togethor](#play-actors-in-a-sequence).
+[chain multiple actors together](#play-actors-in-a-sequence).
 
 ### Inputs
 
@@ -122,25 +123,200 @@ actor.greeting # => "Have a wonderful day!"
 actor.greeting? # => true
 ```
 
+### Fail
+
+To stop the execution and mark an actor as having failed, use `fail!`:
+
+```rb
+class UpdateUser < Actor
+  input :user
+  input :attributes
+
+  def call
+    user.attributes = attributes
+
+    fail!(error: "Invalid user") unless user.valid?
+
+    # …
+  end
+end
+```
+
+This will raise an error in your application with the given data added to the
+result.
+
+To test for the success of your actor instead of raising an exception, use
+`.result` instead of `.call`. You can then call `success?` or `failure?` on
+the result.
+
+For example in a Rails controller:
+
+```rb
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def create
+    actor = UpdateUser.result(user: user, attributes: user_attributes)
+    if actor.success?
+      redirect_to actor.user
+    else
+      render :new, notice: actor.error
+    end
+  end
+end
+```
+
+## Play actors in a sequence
+
+To help you create actors that are small, single-responsibility actions, an
+actor can use `play` to call other actors:
+
+```rb
+class PlaceOrder < Actor
+  play CreateOrder,
+       PayOrder,
+       SendOrderConfirmation,
+       NotifyAdmins
+end
+```
+
+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.
+
+### Rollback
+
+When using `play`, if an actor calls `fail!`, the following actors will not be
+called.
+
+Instead, all the actors that succeeded will have their `rollback` method called
+in reverse order. This allows actors a chance to cleanup, for example:
+
+```rb
+class CreateOrder < Actor
+  output :order
+
+  def call
+    self.order = Order.create!(…)
+  end
+
+  def rollback
+    order.destroy
+  end
+end
+```
+
+Rollback is only called on the _previous_ actors in `play` and is not called on
+the failing actor itself. Actors should be kept to a single purpose and not have
+anything to clean up if they call `fail!`.
+
+### Inline actors
+
+For small work or preparing the result set for the next actors, you can create
+inline actors by using lambdas. Each lambda has access to the shared result. For
+example:
+
+```rb
+class PayOrder < Actor
+  input :order
+
+  play -> actor { actor.order.currency ||= "EUR" },
+       CreatePayment,
+       UpdateOrderBalance,
+       -> actor { Logger.info("Order #{actor.order.id} paid") }
+end
+```
+
+You can also call instance methods. For example:
+
+```rb
+class PayOrder < Actor
+  input :order
+
+  play :assign_default_currency,
+       CreatePayment,
+       UpdateOrderBalance,
+       :log_payment
+
+  private
+
+  def assign_default_currency
+    order.currency ||= "EUR"
+  end
+
+  def log_payment
+    Logger.info("Order #{order.id} paid")
+  end
+end
+```
+
+If you want to do work around the whole actor, you can also override the `call`
+method. For example:
+
+```rb
+class PayOrder < Actor
+  # …
+
+  def call
+    Time.with_timezone("Paris") do
+      super
+    end
+  end
+end
+```
+
+### Play conditions
+
+Actors in a play can be called conditionally:
+
+```rb
+class PlaceOrder < Actor
+  play CreateOrder,
+       Pay
+  play NotifyAdmins, if: -> actor { actor.order.amount > 42 }
+  play CreatePayment, unless: -> actor { actor.order.currency == "USD" }
+end
+```
+
+### Input aliases
+
+You can use `alias_input` to transform the output of an actor into the input of
+the next actors.
+
+```rb
+class PlaceComment < Actor
+  play CreateComment,
+       NotifyCommentFollowers,
+       alias_input(commenter: :user),
+       UpdateUserStats
+end
+```
+
+## Input options
+
 ### Defaults
 
-Inputs can be optional by providing a default:
+Inputs can be optional by providing a `default` value or lambda.
 
 ```rb
 class BuildGreeting < Actor
   input :name
   input :adjective, default: "wonderful"
   input :length_of_time, default: -> { ["day", "week", "month"].sample }
+  input :article,
+        default: -> context { context.adjective =~ /^aeiou/ ? 'an' : 'a' }
 
   output :greeting
 
   def call
-    self.greeting = "Have a #{adjective} #{length_of_time} #{name}!"
+    self.greeting = "Have #{article} #{length_of_time}, #{name}!"
   end
 end
 
 actor = BuildGreeting.call(name: "Jim")
-actor.greeting # => "Have a wonderful week Jim!"
+actor.greeting # => "Have a wonderful week, Jim!"
+
+actor = BuildGreeting.call(name: "Siobhan", adjective: "elegant")
+actor.greeting # => "Have an elegant week, Siobhan!"
 ```
 
 ### Allow nil
@@ -208,48 +384,6 @@ You may also use strings instead of constants, such as `type: "User"`.
 
 When using a type condition, `allow_nil` defaults to `false`.
 
-### Fail
-
-To stop the execution and mark an actor as having failed, use `fail!`:
-
-```rb
-class UpdateUser < Actor
-  input :user
-  input :attributes
-
-  def call
-    user.attributes = attributes
-
-    fail!(error: "Invalid user") unless user.valid?
-
-    # …
-  end
-end
-```
-
-This will raise an error in your application with the given data added to the
-result.
-
-To test for the success of your actor instead of raising an exception, use
-`.result` instead of `.call`. You can then call `success?` or `failure?` on
-the result.
-
-For example in a Rails controller:
-
-```rb
-# app/controllers/users_controller.rb
-class UsersController < ApplicationController
-  def create
-    actor = UpdateUser.result(user: user, attributes: user_attributes)
-    if actor.success?
-      redirect_to actor.user
-    else
-      render :new, notice: actor.error
-    end
-  end
-end
-```
-
 ### Custom input errors
 
 Use a `Hash` with `is:` and `message:` keys to prepare custom
@@ -363,131 +497,6 @@ end
 
 </details>
 
-## Play actors in a sequence
-
-To help you create actors that are small, single-responsibility actions, an
-actor can use `play` to call other actors:
-
-```rb
-class PlaceOrder < Actor
-  play CreateOrder,
-       PayOrder,
-       SendOrderConfirmation,
-       NotifyAdmins
-end
-```
-
-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.
-
-### Rollback
-
-When using `play`, if an actor calls `fail!`, the following actors will not be
-called.
-
-Instead, all the actors that succeeded will have their `rollback` method called
-in reverse order. This allows actors a chance to cleanup, for example:
-
-```rb
-class CreateOrder < Actor
-  output :order
-
-  def call
-    self.order = Order.create!(…)
-  end
-
-  def rollback
-    order.destroy
-  end
-end
-```
-
-Rollback is only called on the _previous_ actors in `play` and is not called on
-the failing actor itself. Actors should be kept to a single purpose and not have
-anything to clean up if they call `fail!`.
-
-### Inline actors
-
-For small work or preparing the result set for the next actors, you can create
-inline actors by using lambdas. Each lambda has access to the shared result. For
-example:
-
-```rb
-class PayOrder < Actor
-  input :order
-
-  play -> actor { actor.order.currency ||= "EUR" },
-       CreatePayment,
-       UpdateOrderBalance,
-       -> actor { Logger.info("Order #{actor.order.id} paid") }
-end
-```
-
-You can also call instance methods. For example:
-
-```rb
-class PayOrder < Actor
-  input :order
-
-  play :assign_default_currency,
-       CreatePayment,
-       UpdateOrderBalance,
-       :log_payment
-
-  private
-
-  def assign_default_currency
-    order.currency ||= "EUR"
-  end
-
-  def log_payment
-    Logger.info("Order #{order.id} paid")
-  end
-end
-```
-
-If you want to do work around the whole actor, you can also override the `call`
-method. For example:
-
-```rb
-class PayOrder < Actor
-  # …
-
-  def call
-    Time.with_timezone("Paris") do
-      super
-    end
-  end
-end
-```
-
-### Play conditions
-
-Actors in a play can be called conditionally:
-
-```rb
-class PlaceOrder < Actor
-  play CreateOrder,
-       Pay
-  play NotifyAdmins, if: -> actor { actor.order.amount > 42 }
-end
-```
-
-### Input aliases
-
-You can use `alias_input` to transform the output of an actor into the input of
-the next actors.
-
-```rb
-class PlaceComment < Actor
-  play CreateComment,
-       NotifyCommentFollowers,
-       alias_input(commenter: :user),
-       UpdateUserStats
-end
-```
-
 ## Testing
 
 In your application, add automated testing to your actors as you would do to any

data/lib/service_actor/defaultable.rb

@@ -56,8 +56,7 @@ module ServiceActor::Defaultable
     private
 
     def default_for_normal_mode_with(result, key, default)
-      default = default.call if default.is_a?(Proc)
-      result[key] = default
+      result[key] = reify_default(result, default)
     end
 
     def default_for_advanced_mode_with(result, key, content)
@@ -67,8 +66,7 @@ module ServiceActor::Defaultable
         raise_error_with(message, input_key: key, actor: self.class)
       end
 
-      default = default.call if default.is_a?(Proc)
-      result[key] = default
+      result[key] = reify_default(result, default)
 
       message.call(key, self.class)
     end
@@ -79,5 +77,11 @@ module ServiceActor::Defaultable
 
       raise self.class.argument_error_class, message
     end
+
+    def reify_default(result, default)
+      return default unless default.is_a?(Proc)
+
+      default.arity.zero? ? default.call : default.call(result)
+    end
   end
 end

data/lib/service_actor/playable.rb

@@ -56,7 +56,7 @@ module ServiceActor::Playable
   module PrependedMethods
     def call
       self.class.play_actors.each do |options|
-        next if options[:if] && !options[:if].call(result)
+        next unless callable_actor?(options)
 
         options[:actors].each { |actor| play_actor(actor) }
       end
@@ -77,6 +77,13 @@ module ServiceActor::Playable
 
     private
 
+    def callable_actor?(options)
+      return false if options[:if] && !options[:if].call(result)
+      return false if options[:unless]&.call(result)
+
+      true
+    end
+
     def play_actor(actor)
       play_service_actor(actor) ||
         play_method(actor) ||

data/lib/service_actor/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.7.0
 platform: ruby
 authors:
 - Sunny Ripert
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-10 00:00:00.000000000 Z
+date: 2023-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk