service_actor 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1cffe28ea4e94682af7f8ee771ad803134e80ce17a9230552d13b4c169b20c7
-  data.tar.gz: 179b2cbf950872b1dbf46d3bd3b24bafbbc3bbb8cd32574f4dbad6a361958abd
+  metadata.gz: ccd0af6d1704b2efc805ce3bfa5cdfd1e74797c9b0a015511daf351e692ab6e8
+  data.tar.gz: 6fa64250a89f505bfc0b9b2e300faf5c3ae222740317263fe4947a383e1b64c8
 SHA512:
-  metadata.gz: 1e2804c9d25b20b853300d59976075c5ab451670b7e0b05986507e3e07fe9295efa79d3de34ef2d96a59a2f64154bebd4a88a5726ee308dbaed17c5fac2aa3a5
-  data.tar.gz: 5fc857d43785fe5c6bf5c3723dd91253f4e914f6dccfffc0c258504e306bd4ebc3992ef72a6d37ccc70b4420fba0f86da51165e5fbf0d153b3d64ba9c5bfb18d
+  metadata.gz: a3041c28efd75c40e793e299432b743274803b7a237a22525a05de3b916b17f899c6de85a0eeeb98594de47f8d742d595c7582ecb505700a3ec9712f842d1c87
+  data.tar.gz: 2f6e0ece1cc4964311a25035dba7011844b1d3992d7ec14f9a36a497b6b62f361ba5826ee364e1871411dd3ce5fff144354a104c846f98f0bcfe971cd8b53030

data/README.md

@@ -15,17 +15,17 @@ and controllers thin.
   - [Inputs](#inputs)
   - [Outputs](#outputs)
   - [Defaults](#defaults)
-  - [Conditions](#conditions)
   - [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)
 - [Testing](#testing)
-- [Build your own actor](#build-your-own-actor)
-- [Influences](#influences)
+- [FAQ](#faq)
 - [Thanks](#thanks)
 - [Contributing](#contributing)
 - [License](#contributing)
@@ -120,22 +120,12 @@ The result you get from calling an actor will include the outputs you set:
 ```rb
 actor = BuildGreeting.call
 actor.greeting # => "Have a wonderful day!"
-```
-
-For every output there is also a boolean method ending with `?` to test its
-presence:
-
-```rb
-if actor.greeting?
-  puts "Greetings is truthy"
-else
-  puts "Greetings is falsey"
-end
+actor.greeting? # => true
 ```
 
 ### Defaults
 
-Inputs can be marked as optional by providing a default:
+Inputs can be optional by providing a default:
 
 ```rb
 class BuildGreeting < Actor
@@ -149,29 +139,30 @@ class BuildGreeting < Actor
     self.greeting = "Have a #{adjective} #{length_of_time} #{name}!"
   end
 end
-```
-
-This lets you call the actor without specifying those keys:
 
-```rb
 actor = BuildGreeting.call(name: "Jim")
 actor.greeting # => "Have a wonderful week Jim!"
 ```
 
-If an input does not have a default, it will raise a error:
+### Allow nil
+
+By default inputs accept `nil` values. To raise an error instead:
 
 ```rb
-BuildGreeting.call
-=> ServiceActor::ArgumentError: Input name on BuildGreeting is missing.
+class UpdateUser < Actor
+  input :user, allow_nil: false
+
+  # …
+end
 ```
 
 ### Conditions
 
-You can ensure an input is included in a collection by using `in`:
+You can ensure an input is included in a collection by using `inclusion`:
 
 ```rb
 class Pay < Actor
-  input :currency, in: %w[EUR USD]
+  input :currency, inclusion: %w[EUR USD]
 
   # …
 end
@@ -180,7 +171,7 @@ end
 This raises an argument error if the input does not match one of the given
 values.
 
-You can also add custom conditions with the name of your choice by using `must`:
+Declare custom conditions with the name of your choice by using `must`:
 
 ```rb
 class UpdateAdminUser < Actor
@@ -193,19 +184,8 @@ class UpdateAdminUser < Actor
 end
 ```
 
-This raises an argument error if the given lambda returns a falsey value.
-
-### Allow nil
-
-By default inputs accept `nil` values. To raise an error instead:
-
-```rb
-class UpdateUser < Actor
-  input :user, allow_nil: false
-
-  # …
-end
-```
+This will raise an argument error if any of the given lambdas returns a falsey
+value.
 
 ### Types
 
@@ -234,7 +214,7 @@ When using a type condition, `allow_nil` defaults to `false`.
 To stop the execution and mark an actor as having failed, use `fail!`:
 
 ```rb
-class UpdateUser
+class UpdateUser < Actor
   input :user
   input :attributes
 
@@ -248,7 +228,8 @@ class UpdateUser
 end
 ```
 
-This will raise an error in your app with the given data added to the result.
+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
@@ -270,8 +251,118 @@ class UsersController < ApplicationController
 end
 ```
 
-The keys you add to `fail!` will be added to the result, for example you could
-do: `fail!(error_type: "validation", error_code: "uv52", …)`.
+### Custom input errors
+
+Use a `Hash` with `is:` and `message:` keys to prepare custom
+error messages on inputs. For example:
+
+```rb
+class UpdateAdminUser < Actor
+  input :user,
+        must: {
+          be_an_admin: {
+            is: -> user { user.admin? },
+            message: "The user is not an administrator"
+          }
+        }
+
+  # ...
+end
+```
+
+You can also use incoming arguments when shaping your error text:
+
+```rb
+class UpdateUser < Actor
+  input :user,
+        allow_nil: {
+          is: false,
+          message: (lambda do |input_key:, **|
+            "The value \"#{input_key}\" cannot be empty"
+          end)
+        }
+
+  # ...
+end
+```
+
+<details>
+  <summary>See examples of custom messages on all input arguments</summary>
+
+  #### Inclusion
+
+  ```ruby
+  class Pay < Actor
+    input :provider,
+          inclusion: {
+            in: ["MANGOPAY", "PayPal", "Stripe"],
+            message: (lambda do |value:, **|
+              "Payment system \"#{value}\" is not supported"
+            end)
+          }
+  end
+  ```
+
+  #### Must
+
+  ```ruby
+  class Pay < Actor
+    input :provider,
+          must: {
+            exist: {
+              is: -> provider { PROVIDERS.include?(provider) },
+              message: (lambda do |value:, **|
+                "The specified provider \"#{value}\" was not found."
+              end)
+            }
+          }
+  end
+  ```
+
+  #### Default
+
+  ```ruby
+  class MultiplyThing < Actor
+    input :multiplier,
+          default: {
+            is: -> { rand(1..10) },
+            message: (lambda do |input_key:, **|
+              "Input \"#{input_key}\" is required"
+            end)
+          }
+  end
+  ```
+
+  #### Type
+
+  ```ruby
+  class ReduceOrderAmount < Actor
+    input :bonus_applied,
+          type: {
+            is: [TrueClass, FalseClass],
+            message: (lambda do |input_key:, expected_type:, given_type:, **|
+              "Wrong type \"#{given_type}\" for \"#{input_key}\". " \
+              "Expected: \"#{expected_type}\""
+            end)
+          }
+  end
+  ```
+
+  #### Allow nil
+
+  ```ruby
+  class CreateUser < Actor
+    input :name,
+          allow_nil: {
+            is: false,
+            message: (lambda do |input_key:, **|
+              "The value \"#{input_key}\" cannot be empty"
+            end)
+          }
+  end
+  ```
+
+</details>
 
 ## Play actors in a sequence
 
@@ -287,13 +378,13 @@ class PlaceOrder < Actor
 end
 ```
 
-This creates a `call` method that will 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.
+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`, when an actor calls `fail!`, the following actors will not be
+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
@@ -384,22 +475,6 @@ class PlaceOrder < Actor
 end
 ```
 
-### Fail on argument error
-
-By default, errors on inputs will raise an error, even when using `.result`
-instead of `.call`. If instead you want to mark the actor as failed, you can
-catch the exception to treat it as an actor failure:
-
-```rb
-class PlaceOrder < Actor
-  fail_on ServiceActor::ArgumentError
-
-  input :currency, in: ["EUR", "USD"]
-
-  # …
-end
-```
-
 ## Testing
 
 In your application, add automated testing to your actors as you would do to any
@@ -408,57 +483,22 @@ other part of your applications.
 You will find that cutting your business logic into single purpose actors will
 make it easier for you to test your application.
 
-## Build your own actor
-
-If you application already uses a class called “Actor”, you can build your own
-by changing the gem’s require statement:
-
-```rb
-gem "service_actor", require: "service_actor/base"
-```
-
-And building your own class to inherit from:
-
-```rb
-class ApplicationActor
-  include ServiceActor::Base
-end
-```
+## FAQ
 
-## Influences
-
-This gem is heavily influenced by
-[Interactor](https://github.com/collectiveidea/interactor) ♥.
-Some key differences make Actor unique:
-
-- Does not [hide errors when an actor fails inside another
-  actor](https://github.com/collectiveidea/interactor/issues/170).
-- Requires you to document arguments with `input` and `output`.
-- Defaults to raising errors on failures: actor uses `call` and `result`
-  instead of `call!` and `call`. This way, the _default_ is to raise an error
-  and failures are not hidden away because you forgot to use `!`.
-- Allows defaults, type checking, requirements and conditions on inputs.
-- Delegates methods on the context: `foo` vs `context.foo`, `self.foo =` vs
-  `context.foo = `, `fail!` vs `context.fail!`.
-- Shorter setup syntax: inherit from `< Actor` vs having to `include Interactor`
-  and `include Interactor::Organizer`.
-- Organizers allow lambdas, instance methods, being called multiple times,
-  and having conditions.
-- Allows early success with conditions inside organizers.
-- No `before`, `after` and `around` hooks, prefer using `play` with lambdas or
-  overriding `call`.
-
-Actor supports mixing actors & interactors when using `play` for a smooth
-migration.
+Howtos and frequently asked questions can be found on the
+[wiki](https://github.com/sunny/actor/wiki).
 
 ## Thanks
 
-Thank you to @nicoolas25, @AnneSottise & @williampollet for the early thoughts
-and feedback on this gem.
+This gem is influenced by (and compatible with)
+[Interactor](https://github.com/sunny/actor/wiki/Interactor).
 
 Thank you to the wonderful
 [contributors](https://github.com/sunny/actor/graphs/contributors).
 
+Thank you to @nicoolas25, @AnneSottise & @williampollet for the early thoughts
+and feedback on this gem.
+
 Photo by [Lloyd Dirks](https://unsplash.com/photos/4SLz_RCk6kQ).
 
 ## Contributing

data/lib/service_actor/argument_error.rb

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Raised when an input or output does not match the given conditions.
-  class ArgumentError < Error; end
-end
+# Raised when an input or output does not match the given conditions.
+class ServiceActor::ArgumentError < ServiceActor::Error; end

data/lib/service_actor/attributable.rb

@@ -1,59 +1,57 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # DSL to document the accepted attributes.
-  #
-  #   class CreateUser < Actor
-  #     input :name
-  #     output :name
-  #   end
-  module Attributable
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    module ClassMethods
-      def inherited(child)
-        super
-
-        child.inputs.merge!(inputs)
-        child.outputs.merge!(outputs)
-      end
+# DSL to document the accepted attributes.
+#
+#   class CreateUser < Actor
+#     input :name
+#     output :name
+#   end
+module ServiceActor::Attributable
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
 
-      def input(name, **arguments)
-        inputs[name] = arguments
+  module ClassMethods
+    def inherited(child)
+      super
 
-        define_method(name) do
-          result[name]
-        end
+      child.inputs.merge!(inputs)
+      child.outputs.merge!(outputs)
+    end
 
-        # For avoid method redefined warning messages.
-        alias_method name, name if method_defined?(name)
+    def input(name, **arguments)
+      inputs[name] = arguments
 
-        protected name
+      define_method(name) do
+        result[name]
       end
 
-      def inputs
-        @inputs ||= {}
-      end
+      # For avoid method redefined warning messages.
+      alias_method name, name if method_defined?(name)
 
-      def output(name, **arguments)
-        outputs[name] = arguments
+      protected name
+    end
 
-        define_method(name) do
-          result[name]
-        end
+    def inputs
+      @inputs ||= {}
+    end
 
-        define_method("#{name}=") do |value|
-          result[name] = value
-        end
+    def output(name, **arguments)
+      outputs[name] = arguments
 
-        protected name, "#{name}="
+      define_method(name) do
+        result[name]
       end
 
-      def outputs
-        @outputs ||= {}
+      define_method("#{name}=") do |value|
+        result[name] = value
       end
+
+      protected name, "#{name}="
+    end
+
+    def outputs
+      @outputs ||= {}
     end
   end
 end

data/lib/service_actor/base.rb

@@ -1,39 +1,21 @@
 # frozen_string_literal: true
 
-# Exceptions
-require "service_actor/error"
-require "service_actor/failure"
-require "service_actor/argument_error"
+require "service_actor/support/loader"
 
-# Core
-require "service_actor/core"
-require "service_actor/attributable"
-require "service_actor/playable"
-require "service_actor/result"
+module ServiceActor::Base
+  def self.included(base)
+    # Essential mechanics
+    base.include(ServiceActor::Core)
+    base.include(ServiceActor::Raisable)
+    base.include(ServiceActor::Attributable)
+    base.include(ServiceActor::Playable)
 
-# Concerns
-require "service_actor/type_checkable"
-require "service_actor/nil_checkable"
-require "service_actor/conditionable"
-require "service_actor/defaultable"
-require "service_actor/collectionable"
-require "service_actor/failable"
-
-module ServiceActor
-  module Base
-    def self.included(base)
-      # Core
-      base.include(Core)
-      base.include(Attributable)
-      base.include(Playable)
-
-      # Concerns
-      base.include(TypeCheckable)
-      base.include(NilCheckable)
-      base.include(Conditionable)
-      base.include(Collectionable)
-      base.include(Defaultable)
-      base.include(Failable)
-    end
+    # Extra concerns
+    base.include(ServiceActor::TypeCheckable)
+    base.include(ServiceActor::NilCheckable)
+    base.include(ServiceActor::Conditionable)
+    base.include(ServiceActor::Collectionable)
+    base.include(ServiceActor::Defaultable)
+    base.include(ServiceActor::Failable)
   end
 end

data/lib/service_actor/collectionable.rb

@@ -1,32 +1,68 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Add checks to your inputs, by specifying what values are authorized
-  # under the "in" key.
-  #
-  # Example:
-  #
-  #   class Pay < Actor
-  #     input :provider, in: ["MANGOPAY", "PayPal", "Stripe"]
-  #   end
-  module Collectionable
-    def self.included(base)
-      base.prepend(PrependedMethods)
+# Add checks to your inputs, by specifying what values are authorized under the
+# "in" key.
+#
+# Example:
+#
+#   class Pay < Actor
+#     input :provider, inclusion: ["MANGOPAY", "PayPal", "Stripe"]
+#   end
+#
+#   class Pay < Actor
+#     input :provider,
+#           inclusion: {
+#             in: ["MANGOPAY", "PayPal", "Stripe"],
+#             message: (lambda do |input_key:, actor:, inclusion_in:, value:|
+#               "Payment system \"#{value}\" is not supported"
+#             end)
+#           }
+#   end
+module ServiceActor::Collectionable
+  def self.included(base)
+    base.prepend(PrependedMethods)
+  end
+
+  module PrependedMethods
+    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}"
     end
 
-    module PrependedMethods
-      def _call
-        self.class.inputs.each do |key, options|
-          next unless options[:in]
+    private_constant :DEFAULT_MESSAGE
+
+    def _call # rubocop:disable Metrics/MethodLength
+      self.class.inputs.each do |key, options|
+        value = result[key]
+
+        # DEPRECATED: `in` is deprecated in favor of `inclusion`.
+        inclusion = options[:inclusion] || options[:in]
+
+        inclusion_in, message = define_inclusion_from(inclusion)
 
-          next if options[:in].include?(result[key])
+        next if inclusion_in.nil?
+        next if inclusion_in.include?(value)
+
+        raise_error_with(
+          message,
+          input_key: key,
+          actor: self.class,
+          inclusion_in: inclusion_in,
+          value: value,
+        )
+      end
+
+      super
+    end
 
-          raise ArgumentError,
-                "Input #{key} must be included in #{options[:in].inspect} " \
-                "but instead was #{result[key].inspect}"
-        end
+    private
 
-        super
+    def define_inclusion_from(inclusion)
+      if inclusion.is_a?(Hash)
+        inclusion.values_at(:in, :message)
+      else
+        [inclusion, DEFAULT_MESSAGE]
       end
     end
   end