service_actor 3.3.0 → 3.4.0

data/lib/service_actor/conditionable.rb

@@ -1,39 +1,74 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Add checks to your inputs, by calling lambdas with the name of you choice
-  # under the "must" key.
-  #
-  # Will raise an error if any check returns a truthy value.
-  #
-  # Example:
-  #
-  #   class Pay < Actor
-  #     input :provider,
-  #           must: {
-  #             exist: -> provider { PROVIDERS.include?(provider) },
-  #           }
-  #   end
-  module Conditionable
-    def self.included(base)
-      base.prepend(PrependedMethods)
+# Add checks to your inputs, by calling lambdas with the name of you choice
+# under the "must" key.
+#
+# Will raise an error if any check returns a truthy value.
+#
+# Example:
+#
+#   class Pay < Actor
+#     input :provider,
+#           must: {
+#             exist: -> provider { PROVIDERS.include?(provider) },
+#           }
+#   end
+#
+#   class Pay < Actor
+#     input :provider,
+#           must: {
+#             exist: {
+#               is: -> provider { PROVIDERS.include?(provider) },
+#               message: (lambda do |input_key:, check_name:, actor:, value:|
+#                 "The specified provider \"#{value}\" was not found."
+#               end)
+#             }
+#           }
+#   end
+module ServiceActor::Conditionable
+  def self.included(base)
+    base.prepend(PrependedMethods)
+  end
+
+  module PrependedMethods
+    DEFAULT_MESSAGE = lambda do |input_key:, check_name:, actor:, value:|
+      "The \"#{input_key}\" input on \"#{actor}\" must \"#{check_name}\" " \
+        "but was #{value.inspect}"
     end
 
-    module PrependedMethods
-      def _call
-        self.class.inputs.each do |key, options|
-          next unless options[:must]
+    private_constant :DEFAULT_MESSAGE
+
+    def _call # rubocop:disable Metrics/MethodLength
+      self.class.inputs.each do |key, options|
+        next unless options[:must]
+
+        options[:must].each do |check_name, check|
+          value = result[key]
+
+          check, message = define_check_from(check)
 
-          options[:must].each do |name, check|
-            value = result[key]
-            next if check.call(value)
+          next if check.call(value)
 
-            raise ArgumentError,
-                  "Input #{key} must #{name} but was #{value.inspect}"
-          end
+          raise_error_with(
+            message,
+            input_key: key,
+            check_name: check_name,
+            actor: self.class,
+            value: value,
+          )
         end
+      end
+
+      super
+    end
+
+    private
 
-        super
+    def define_check_from(check)
+      if check.is_a?(Hash)
+        check.values_at(:is, :message)
+      else
+        [check, DEFAULT_MESSAGE]
       end
     end
   end

data/lib/service_actor/core.rb

@@ -1,59 +1,66 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  module Core
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+module ServiceActor::Core
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
 
-    module ClassMethods
-      # Call an actor with a given result. Returns the result.
-      #
-      #   CreateUser.call(name: "Joe")
-      def call(result = nil, **arguments)
-        result = Result.to_result(result).merge!(arguments)
-        new(result)._call
-        result
-      end
-
-      # Call an actor with arguments. Returns the result and does not raise on
-      # failure.
-      #
-      #   CreateUser.result(name: "Joe")
-      def result(result = nil, **arguments)
-        call(result, **arguments)
-      rescue Failure => e
-        e.result
-      end
+  module ClassMethods
+    # Call an actor with a given result. Returns the result.
+    #
+    #   CreateUser.call(name: "Joe")
+    def call(result = nil, **arguments)
+      result = ServiceActor::Result.to_result(result).merge!(arguments)
+      new(result)._call
+      result
     end
 
-    # :nodoc:
-    def initialize(result)
-      @result = result
+    # Call an actor with arguments. Returns the result and does not raise on
+    # failure.
+    #
+    #   CreateUser.result(name: "Joe")
+    def result(result = nil, **arguments)
+      call(result, **arguments)
+    rescue failure_class => e
+      e.result
     end
+  end
 
-    # To implement in your actors.
-    def call; end
+  # :nodoc:
+  def initialize(result)
+    @result = result
+  end
 
-    # To implement in your actors.
-    def rollback; end
+  # To implement in your actors.
+  def call; end
 
-    # 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.
-    # :nodoc:
-    def _call
-      call
-    end
+  # To implement in your actors.
+  def rollback; end
+
+  # 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.
+  # :nodoc:
+  def _call
+    call
+  end
 
-    protected
+  protected
 
-    # Returns the current context from inside an actor.
-    attr_reader :result
+  # Returns the current context from inside an actor.
+  attr_reader :result
 
-    # Can be called from inside an actor to stop execution and mark as failed.
-    def fail!(**arguments)
-      result.fail!(**arguments)
-    end
+  # Can be called from inside an actor to stop execution and mark as failed.
+  def fail!(**arguments)
+    result.fail!(self.class.failure_class, **arguments)
+  end
+
+  private
+
+  # Raises an error depending on the mode
+  def raise_error_with(message, **arguments)
+    message = message.call(**arguments) if message.is_a?(Proc)
+
+    raise self.class.argument_error_class, message
   end
 end

data/lib/service_actor/defaultable.rb

@@ -1,37 +1,76 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Adds the `default:` option to inputs. Accepts regular values and lambdas.
-  # If no default is set and the value has not been given, raises an error.
-  #
-  # Example:
-  #
-  #   class MultiplyThing < Actor
-  #     input :counter, default: 1
-  #     input :multiplier, default: -> { rand(1..10) }
-  #   end
-  module Defaultable
-    def self.included(base)
-      base.prepend(PrependedMethods)
-    end
+# Adds the `default:` option to inputs. Accepts regular values and lambdas.
+# If no default is set and the value has not been given, raises an error.
+#
+# Example:
+#
+#   class MultiplyThing < Actor
+#     input :counter, default: 1
+#     input :multiplier, default: -> { rand(1..10) }
+#   end
+#
+#   class MultiplyThing < Actor
+#     input :counter,
+#           default: {
+#             is: 1,
+#             message: "Counter is required"
+#           }
+#
+#     input :multiplier,
+#           default: {
+#             is: -> { rand(1..10) },
+#             message: (lambda do |input_key:, actor:|
+#               "Input \"#{input_key}\" is required"
+#             end)
+#           }
+#   end
+module ServiceActor::Defaultable
+  def self.included(base)
+    base.prepend(PrependedMethods)
+  end
 
-    module PrependedMethods
-      def _call
-        self.class.inputs.each do |name, input|
-          next if result.key?(name)
+  module PrependedMethods
+    def _call # rubocop:disable Metrics/MethodLength
+      self.class.inputs.each do |key, input|
+        next if result.key?(key)
+
+        unless input.key?(:default)
+          raise_error_with(
+            "The \"#{key}\" input on \"#{self.class}\" is missing",
+          )
+        end
 
-          if input.key?(:default)
-            default = input[:default]
-            default = default.call if default.is_a?(Proc)
-            result[name] = default
-            next
-          end
+        default = input[:default]
 
-          raise(ArgumentError, "Input #{name} on #{self.class} is missing")
+        if default.is_a?(Hash)
+          default_for_advanced_mode_with(result, key, default)
+        else
+          default_for_normal_mode_with(result, key, default)
         end
+      end
+
+      super
+    end
 
-        super
+    private
+
+    def default_for_normal_mode_with(result, key, default)
+      default = default.call if default.is_a?(Proc)
+      result[key] = default
+    end
+
+    def default_for_advanced_mode_with(result, key, content)
+      default, message = content.values_at(:is, :message)
+
+      unless default
+        raise_error_with(message, input_key: key, actor: self.class)
       end
+
+      default = default.call if default.is_a?(Proc)
+      result[key] = default
+
+      message.call(key, self.class)
     end
   end
 end

data/lib/service_actor/error.rb

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Standard exception from which others inherit.
-  class Error < StandardError; end
-end
+# Standard exception from which others inherit.
+class ServiceActor::Error < StandardError; end

data/lib/service_actor/failable.rb

@@ -1,40 +1,38 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Adds the `fail_on` DSL to actors. This allows you to call `.result` and get
-  # back a failed actor instead of raising an exception.
-  #
-  #   class ApplicationActor < Actor
-  #     fail_on ServiceActor::ArgumentError
-  #   end
-  module Failable
-    def self.included(base)
-      base.extend(ClassMethods)
-      base.prepend(PrependedMethods)
-    end
+# Adds the `fail_on` DSL to actors. This allows you to call `.result` and get
+# back a failed actor instead of raising an exception.
+#
+#   class ApplicationActor < Actor
+#     fail_on ServiceActor::ArgumentError
+#   end
+module ServiceActor::Failable
+  def self.included(base)
+    base.extend(ClassMethods)
+    base.prepend(PrependedMethods)
+  end
 
-    module ClassMethods
-      def inherited(child)
-        super
+  module ClassMethods
+    def inherited(child)
+      super
 
-        child.fail_ons.push(*fail_ons)
-      end
+      child.fail_ons.push(*fail_ons)
+    end
 
-      def fail_on(*exceptions)
-        fail_ons.push(*exceptions)
-      end
+    def fail_on(*exceptions)
+      fail_ons.push(*exceptions)
+    end
 
-      def fail_ons
-        @fail_ons ||= []
-      end
+    def fail_ons
+      @fail_ons ||= []
     end
+  end
 
-    module PrependedMethods
-      def _call
-        super
-      rescue *self.class.fail_ons => e
-        fail!(error: e.message)
-      end
+  module PrependedMethods
+    def _call
+      super
+    rescue *self.class.fail_ons => e
+      fail!(error: e.message)
     end
   end
 end

data/lib/service_actor/failure.rb

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Error raised when using `fail!` inside an actor.
-  class Failure < Error
-    def initialize(result)
-      @result = result
+# Error raised when using `fail!` inside an actor.
+class ServiceActor::Failure < ServiceActor::Error
+  def initialize(result)
+    @result = result
 
-      error = result.respond_to?(:error) ? result.error : nil
+    error = result.respond_to?(:error) ? result.error : nil
 
-      super(error)
-    end
-
-    attr_reader :result
+    super(error)
   end
+
+  attr_reader :result
 end

data/lib/service_actor/nil_checkable.rb

@@ -1,46 +1,88 @@
 # frozen_string_literal: true
 
-module ServiceActor
-  # Ensure your inputs and outputs are not nil by adding `allow_nil: false`.
-  #
-  # Example:
-  #
-  #   class CreateUser < Actor
-  #     input :name, allow_nil: false
-  #     output :user, allow_nil: false
-  #   end
-  module NilCheckable
-    def self.included(base)
-      base.prepend(PrependedMethods)
+# Ensure your inputs and outputs are not nil by adding `allow_nil: false`.
+#
+# Example:
+#
+#   class CreateUser < Actor
+#     input :name, allow_nil: false
+#     output :user, allow_nil: false
+#   end
+#
+#   class CreateUser < Actor
+#     input :name,
+#           allow_nil: {
+#             is: false,
+#             message: (lambda do |origin:, input_key:, actor:|
+#               "The value \"#{input_key}\" cannot be empty"
+#             end)
+#           }
+#
+#     input :phone, allow_nil: { is: false, message: "Phone must be present" }
+#
+#     output :user,
+#             allow_nil: {
+#               is: false,
+#               message: (lambda do |origin:, input_key:, actor:|
+#                 "The value \"#{input_key}\" cannot be empty"
+#               end)
+#             }
+#   end
+module ServiceActor::NilCheckable
+  def self.included(base)
+    base.prepend(PrependedMethods)
+  end
+
+  module PrependedMethods
+    DEFAULT_MESSAGE = lambda do |origin:, input_key:, actor:|
+      "The \"#{input_key}\" #{origin} on \"#{actor}\" does not allow " \
+      "nil values"
     end
 
-    module PrependedMethods
-      def _call
-        check_context_for_nil(self.class.inputs, origin: "input")
+    private_constant :DEFAULT_MESSAGE
 
-        super
+    def _call
+      check_context_for_nil(self.class.inputs, origin: "input")
 
-        check_context_for_nil(self.class.outputs, origin: "output")
-      end
+      super
 
-      private
+      check_context_for_nil(self.class.outputs, origin: "output")
+    end
 
-      def check_context_for_nil(definitions, origin:)
-        definitions.each do |name, options|
-          next if !result[name].nil? || allow_nil?(options)
+    private
 
-          raise ArgumentError,
-                "The #{origin} \"#{name}\" on #{self.class} does not allow " \
-                "nil values"
-        end
-      end
+    def check_context_for_nil(definitions, origin:)
+      definitions.each do |key, options|
+        value = result[key]
+
+        next unless value.nil?
+
+        allow_nil, message = define_allow_nil_from(options[:allow_nil])
 
-      def allow_nil?(options)
-        return options[:allow_nil] if options.key?(:allow_nil)
-        return true if options.key?(:default) && options[:default].nil?
+        next if allow_nil?(allow_nil, options)
 
-        !options[:type]
+        raise_error_with(
+          message,
+          origin: origin,
+          input_key: key,
+          actor: self.class,
+        )
       end
     end
+
+    def define_allow_nil_from(allow_nil)
+      if allow_nil.is_a?(Hash)
+        allow_nil.values_at(:is, :message)
+      else
+        [allow_nil, DEFAULT_MESSAGE]
+      end
+    end
+
+    def allow_nil?(allow_nil, options)
+      return allow_nil unless allow_nil.nil?
+      return true if options.key?(:default) && options[:default].nil?
+
+      !options[:type]
+    end
   end
 end