service_actor 3.6.1 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0597123f9fd025cb0fdd1d099c9a4c29865a086a107d67f7b336b3828e6743c5'
-  data.tar.gz: fa2e8c72f82970ff779f1c870fa4074630b7e4d2d947f10f57e8a0670a9bae07
+  metadata.gz: a852443e88e3b6957cbaf093330d08691ba8e862826ac3b745fa5510d1b0273c
+  data.tar.gz: 21a7648a3e3302600b1946285a76b0e80c70ba1550776dfd07057718397d5f66
 SHA512:
-  metadata.gz: 73dea56535940a843c9cf9bee977882293a0dd2ad4b6c0d3069fe28ea4b7d2569f3c3508cc68f8d378ebb526b00027b72a232373049bcf541e91861fe558d589
-  data.tar.gz: 282acf3196702a03f15e8faba840abdf68075abcc3e132dce6efcb090c5349b426f8261bd13fafc68f4e4fbac2a25a1401da8ad9b2638eb1d2a907cb548c8887
+  metadata.gz: 692cc4e5240be00b9a184daf7e7ec921976649ec98c991e14b538e6be37e61462d06dadaa72704010f59c2f3c61ce5921a64871e5050e5fc0efb9a8a118c94d8
+  data.tar.gz: bc2a009e14baaa36d81179fd38f77ed22a972cc9486b0f5d511f4c49bef865d4e940fc990745a07922687340be4999f956f50bd4faae78c1567cb17d7902fd05

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.match?(/^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
@@ -341,7 +475,7 @@ end
             is: [TrueClass, FalseClass],
             message: (lambda do |input_key:, expected_type:, given_type:, **|
               "Wrong type \"#{given_type}\" for \"#{input_key}\". " \
-              "Expected: \"#{expected_type}\""
+                "Expected: \"#{expected_type}\""
             end)
           }
   end
@@ -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/arguments_validator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ServiceActor::ArgumentsValidator
+  module_function
+
+  def validate_origin_name(name, origin:)
+    return unless ServiceActor::Result.instance_methods.include?(name.to_sym)
+
+    raise ArgumentError,
+          "#{origin} `#{name}` overrides `ServiceActor::Result` instance method"
+  end
+
+  def validate_error_class(value)
+    return if value.is_a?(Class) && value <= Exception
+
+    raise ArgumentError, "Expected #{value} to be a subclass of Exception"
+  end
+end

data/lib/service_actor/attributable.rb

@@ -7,8 +7,10 @@
 #     output :name
 #   end
 module ServiceActor::Attributable
-  def self.included(base)
-    base.extend(ClassMethods)
+  class << self
+    def included(base)
+      base.extend(ClassMethods)
+    end
   end
 
   module ClassMethods
@@ -20,14 +22,18 @@ module ServiceActor::Attributable
     end
 
     def input(name, **arguments)
+      ServiceActor::ArgumentsValidator.validate_origin_name(
+        name, origin: :input
+      )
+
       inputs[name] = arguments
 
       define_method(name) do
         result[name]
       end
 
-      # For avoid method redefined warning messages.
-      alias_method name, name if method_defined?(name)
+      # To avoid method redefined warning messages.
+      alias_method(name, name) if method_defined?(name)
 
       protected name
     end
@@ -37,17 +43,21 @@ module ServiceActor::Attributable
     end
 
     def output(name, **arguments)
+      ServiceActor::ArgumentsValidator.validate_origin_name(
+        name, origin: :output
+      )
+
       outputs[name] = arguments
 
       define_method(name) do
         result[name]
       end
+      protected name
 
-      define_method("#{name}=") do |value|
+      define_method(:"#{name}=") do |value|
         result[name] = value
       end
-
-      protected name, "#{name}="
+      protected :"#{name}="
     end
 
     def outputs

data/lib/service_actor/base.rb

@@ -3,16 +3,18 @@
 require "service_actor/support/loader"
 
 module ServiceActor::Base
-  def self.included(base)
-    # Essential mechanics
-    base.include(ServiceActor::Core)
-    base.include(ServiceActor::Configurable)
-    base.include(ServiceActor::Attributable)
-    base.include(ServiceActor::Playable)
+  class << self
+    def included(base)
+      # Essential mechanics
+      base.include(ServiceActor::Core)
+      base.include(ServiceActor::Configurable)
+      base.include(ServiceActor::Attributable)
+      base.include(ServiceActor::Playable)
 
-    # Extra concerns
-    base.include(ServiceActor::Checkable)
-    base.include(ServiceActor::Defaultable)
-    base.include(ServiceActor::Failable)
+      # Extra concerns
+      base.include(ServiceActor::Checkable)
+      base.include(ServiceActor::Defaultable)
+      base.include(ServiceActor::Failable)
+    end
   end
 end

data/lib/service_actor/checkable.rb

@@ -1,11 +1,21 @@
 # frozen_string_literal: true
 
 module ServiceActor::Checkable
-  def self.included(base)
-    base.prepend(PrependedMethods)
+  class << self
+    def included(base)
+      base.prepend(PrependedMethods)
+    end
   end
 
   module PrependedMethods
+    CHECK_CLASSES = [
+      ServiceActor::Checks::TypeCheck,
+      ServiceActor::Checks::MustCheck,
+      ServiceActor::Checks::InclusionCheck,
+      ServiceActor::Checks::NilCheck,
+    ].freeze
+    private_constant :CHECK_CLASSES
+
     def _call
       self.service_actor_argument_errors = []
 
@@ -20,7 +30,8 @@ module ServiceActor::Checkable
 
     # rubocop:disable Metrics/MethodLength
     def service_actor_checks_for(origin)
-      self.class.public_send("#{origin}s").each do |input_key, input_options|
+      check_classes = CHECK_CLASSES.select { _1.applicable_to_origin?(origin) }
+      self.class.public_send(:"#{origin}s").each do |input_key, input_options|
         input_options.each do |check_name, check_conditions|
           check_classes.each do |check_class|
             argument_errors = check_class.check(
@@ -48,15 +59,5 @@ module ServiceActor::Checkable
       raise self.class.argument_error_class,
             service_actor_argument_errors.first
     end
-
-    def check_classes
-      [
-        ServiceActor::Checks::TypeCheck,
-        ServiceActor::Checks::MustCheck,
-        ServiceActor::Checks::InclusionCheck,
-        ServiceActor::Checks::NilCheck,
-        ServiceActor::Checks::DefaultCheck
-      ]
-    end
   end
 end

data/lib/service_actor/checks/base.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 class ServiceActor::Checks::Base
+  class << self
+    def applicable_to_origin?(_origin)
+      true
+    end
+  end
+
   def initialize
     @argument_errors = []
   end

data/lib/service_actor/checks/inclusion_check.rb

@@ -22,21 +22,23 @@ class ServiceActor::Checks::InclusionCheck < ServiceActor::Checks::Base
   DEFAULT_MESSAGE = lambda do |input_key:, actor:, inclusion_in:, value:|
     "The \"#{input_key}\" input must be included " \
       "in #{inclusion_in.inspect} on \"#{actor}\" " \
-        "instead of #{value.inspect}"
+      "instead of #{value.inspect}"
   end
 
   private_constant :DEFAULT_MESSAGE
 
-  def self.check(check_name:, input_key:, actor:, conditions:, result:, **) # rubocop:disable Metrics/ParameterLists
-    # DEPRECATED: `in` is deprecated in favor of `inclusion`.
-    return unless %i[inclusion in].include?(check_name)
+  class << self
+    def check(check_name:, input_key:, actor:, conditions:, result:, **)
+      # DEPRECATED: `in` is deprecated in favor of `inclusion`.
+      return unless %i[inclusion in].include?(check_name)
 
-    new(
-      input_key: input_key,
-      actor: actor,
-      inclusion: conditions,
-      value: result[input_key],
-    ).check
+      new(
+        input_key: input_key,
+        actor: actor,
+        inclusion: conditions,
+        value: result[input_key],
+      ).check
+    end
   end
 
   def initialize(input_key:, actor:, inclusion:, value:)
@@ -67,6 +69,7 @@ class ServiceActor::Checks::InclusionCheck < ServiceActor::Checks::Base
 
   def define_inclusion_and_message
     if @inclusion.is_a?(Hash)
+      @inclusion[:message] ||= DEFAULT_MESSAGE
       @inclusion.values_at(:in, :message)
     else
       [@inclusion, DEFAULT_MESSAGE]

data/lib/service_actor/checks/must_check.rb

@@ -33,15 +33,17 @@ class ServiceActor::Checks::MustCheck < ServiceActor::Checks::Base
 
   private_constant :DEFAULT_MESSAGE
 
-  def self.check(check_name:, input_key:, actor:, conditions:, result:, **) # rubocop:disable Metrics/ParameterLists
-    return unless check_name == :must
+  class << self
+    def check(check_name:, input_key:, actor:, conditions:, result:, **)
+      return unless check_name == :must
 
-    new(
-      input_key: input_key,
-      actor: actor,
-      nested_checks: conditions,
-      value: result[input_key],
-    ).check
+      new(
+        input_key: input_key,
+        actor: actor,
+        nested_checks: conditions,
+        value: result[input_key],
+      ).check
+    end
   end
 
   def initialize(input_key:, actor:, nested_checks:, value:)
@@ -86,6 +88,7 @@ class ServiceActor::Checks::MustCheck < ServiceActor::Checks::Base
 
   def define_check_and_message_from(nested_check_conditions)
     if nested_check_conditions.is_a?(Hash)
+      nested_check_conditions[:message] ||= DEFAULT_MESSAGE
       nested_check_conditions.values_at(:is, :message)
     else
       [nested_check_conditions, DEFAULT_MESSAGE]