interaktor 0.2.0 → 0.4.0

data/lib/interaktor/callable.rb

@@ -1,3 +1,7 @@
+require "dry-schema"
+
+Dry::Schema.load_extensions(:info)
+
 module Interaktor::Callable
   # When the module is included in a class, add the relevant class methods to
   # that class.
@@ -8,131 +12,277 @@ module Interaktor::Callable
   end
 
   module ClassMethods
+    ####################
+    # INPUT ATTRIBUTES #
+    ####################
+
     # The list of attributes which are required to be passed in when calling
     # the interaktor.
     #
     # @return [Array<Symbol>]
-    def required_attributes
-      @required_attributes ||= []
+    def required_input_attributes
+      @required_input_attributes ||= input_schema.info[:keys]
+                                                 .select { |_, info| info[:required] }
+                                                 .keys
     end
 
-    # The list of attributes which are NOT required to be passed in when
+    # The list of attributes which are not required to be passed in when
     # calling the interaktor.
     #
     # @return [Array<Symbol>]
-    def optional_attributes
-      @optional_attributes ||= []
+    def optional_input_attributes
+      # Adding an optional attribute with NO predicates with Dry::Schema is
+      # sort of a "nothing statement" - the schema can sort of ignore it. The
+      # problem is that the optional-with-no-predicate key is not included in
+      # the #info results, so we need to find an list of keys elsewhere, find
+      # the ones that are listed there but not in the #info results, and find
+      # the difference. The result are the keys that are omitted from the #info
+      # result because they are optional and have no predicates.
+      #
+      # See https://github.com/dry-rb/dry-schema/issues/347
+      @optional_input_attributes ||= begin
+          attributes_in_info = input_schema.info[:keys].keys
+          all_attributes = input_schema.key_map.keys.map(&:id)
+          optional_attributes_by_exclusion = all_attributes - attributes_in_info
+
+          explicitly_optional_attributes = input_schema.info[:keys].reject { |_, info| info[:required] }.keys
+
+          explicitly_optional_attributes + optional_attributes_by_exclusion
+        end
     end
 
-    # A list of optional attributes and their default values.
+    # The complete list of input attributes.
     #
     # @return [Array<Symbol>]
-    def optional_defaults
-      @optional_defaults ||= {}
+    def input_attributes
+      required_input_attributes + optional_input_attributes
     end
 
-    # A list of attributes which could be passed when calling the interaktor.
+    # Get the input attribute schema. Fall back to an empty schema with a
+    # configuration that will deny ALL provided attributes - not defining an
+    # input schema should mean the interaktor has no input attributes.
     #
-    # @return [Array<Symbol>]
-    def input_attributes
-      required_attributes + optional_attributes
+    # @return [Dry::Schema::Params]
+    def input_schema
+      @input_schema || Dry::Schema.Params
     end
 
-    # The list of attributes which are required to be passed in when calling
-    # `#fail!` from within the interaktor.
+    # @param context [Hash]
     #
-    # @return [Array<Symbol>]
-    def failure_attributes
-      @failure_attributes ||= []
+    # @return [void]
+    def validate_input_schema(context)
+      return unless input_schema
+
+      result = input_schema.call(context)
+
+      if result.errors.any?
+        raise Interaktor::Error::AttributeSchemaValidationError.new(
+          self,
+          result.errors.to_h,
+        )
+      end
     end
 
-    # The list of attributes which are required to be passed in when calling
-    # `#fail!` from within the interaktor.
+    # @param schema [Dry::Schema::Params, nil] a predefined schema object
+    # @yield a new Dry::Schema::Params definition block
+    def input(schema = nil, &block)
+      raise "No schema or schema definition block provided to interaktor input." if schema.nil? && !block
+
+      raise "Provided both a schema and a schema definition block for interaktor input." if schema && block
+
+      if schema
+        raise "Provided argument is not a Dry::Schema::Params object." unless schema.is_a?(Dry::Schema::Params)
+
+        @input_schema = schema
+      elsif block
+        @input_schema = Dry::Schema.Params { instance_eval(&block) }
+      end
+
+      # define the getters and setters for the input attributes
+      @input_schema.key_map.keys.each do |key| # rubocop:disable Style/HashEachMethods
+        attribute_name = key.id
+
+        # Define getter
+        define_method(attribute_name) { @context.send(attribute_name) }
+
+        # Define setter
+        define_method("#{attribute_name}=".to_sym) do |value|
+          @context.send("#{attribute_name}=".to_sym, value)
+        end
+      end
+    end
+
+    ######################
+    # FAILURE ATTRIBUTES #
+    ######################
+
+    # The list of attributes which are required to be provided when failing the
+    # interaktor.
     #
     # @return [Array<Symbol>]
-    def success_attributes
-      @success_attributes ||= []
+    def required_failure_attributes
+      @required_failure_attributes ||= failure_schema.info[:keys]
+        .select { |_, info| info[:required] }
+        .keys
     end
 
-    # A DSL method for documenting required interaktor attributes.
-    #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    # @param options [Hash]
+    # The list of attributes which are not required to be provided when failing
+    # the interaktor.
     #
-    # @return [void]
-    def required(*attributes, **options)
-      required_attributes.concat attributes
+    # @return [Array<Symbol>]
+    def optional_failure_attributes
+      # Adding an optional attribute with NO predicates with Dry::Schema is
+      # sort of a "nothing statement" - the schema can sort of ignore it. The
+      # problem is that the optional-with-no-predicate key is not included in
+      # the #info results, so we need to find an list of keys elsewhere, find
+      # the ones that are listed there but not in the #info results, and find
+      # the difference. The result are the keys that are omitted from the #info
+      # result because they are optional and have no predicates.
+      #
+      # See https://github.com/dry-rb/dry-schema/issues/347
+      @optional_failure_attributes ||= begin
+          attributes_in_info = failure_schema.info[:keys].keys
+          all_attributes = failure_schema.key_map.keys.map(&:id)
+          optional_attributes_by_exclusion = all_attributes - attributes_in_info
 
-      attributes.each do |attribute|
-        # Define getter
-        define_method(attribute) { @context.send(attribute) }
+          explicitly_optional_attributes = failure_schema.info[:keys].reject { |_, info| info[:required] }.keys
 
-        # Define setter
-        define_method("#{attribute}=".to_sym) do |value|
-          @context.send("#{attribute}=".to_sym, value)
+          explicitly_optional_attributes + optional_attributes_by_exclusion
         end
+    end
 
-        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
-      end
+    # The complete list of failure attributes.
+    #
+    # @return [Array<Symbol>]
+    def failure_attributes
+      required_failure_attributes + optional_failure_attributes
     end
 
-    # A DSL method for documenting optional interaktor attributes.
+    # Get the failure attribute schema. Fall back to an empty schema with a
+    # configuration that will deny ALL provided attributes - not defining an
+    # failure schema should mean the interaktor has no failure attributes.
     #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    # @param options [Hash]
+    # @return [Dry::Schema::Params]
+    def failure_schema
+      @failure_schema || Dry::Schema.Params
+    end
+
+    # @param context [Hash]
     #
     # @return [void]
-    def optional(*attributes, **options)
-      optional_attributes.concat attributes
+    def validate_failure_schema(context)
+      return unless failure_schema
 
-      attributes.each do |attribute|
-        # Define getter
-        define_method(attribute) { @context.send(attribute) }
+      result = failure_schema.call(context)
 
-        # Define setter
-        define_method("#{attribute}=".to_sym) do |value|
-          unless @context.to_h.key?(attribute)
-            raise Interaktor::Error::DisallowedAttributeAssignmentError.new(self.class.to_s, [attribute])
-          end
+      if result.errors.any?
+        raise Interaktor::Error::AttributeSchemaValidationError.new(
+          self,
+          result.errors.to_h,
+        )
+      end
+    end
 
-          @context.send("#{attribute}=".to_sym, value)
-        end
+    # @param schema [Dry::Schema::Params, nil] a predefined schema object
+    # @yield a new Dry::Schema::Params definition block
+    def failure(schema = nil, &block)
+      raise "No schema or schema definition block provided to interaktor failure method." if schema.nil? && !block
 
-        # Handle options
-        optional_defaults[attribute] = options[:default] if options[:default]
-        options.delete(:default)
+      raise "Provided both a schema and a schema definition block for interaktor failure method." if schema && block
 
-        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
+      if schema
+        raise "Provided argument is not a Dry::Schema::Params object." unless schema.is_a?(Dry::Schema::Params)
+
+        @failure_schema = schema
+      elsif block
+        @failure_schema = Dry::Schema.Params { instance_eval(&block) }
       end
     end
 
-    # A DSL method for documenting required interaktor failure attributes.
+    ######################
+    # SUCCESS ATTRIBUTES #
+    ######################
+
+    # The list of attributes which are required to be provided when the
+    # interaktor succeeds.
     #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    # @param options [Hash]
+    # @return [Array<Symbol>]
+    def required_success_attributes
+      @required_success_attributes ||= success_schema.info[:keys]
+                                                     .select { |_, info| info[:required] }
+                                                     .keys
+    end
+
+    # The list of attributes which are not required to be provided when failing
+    # the interaktor.
     #
-    # @return [void]
-    def failure(*attributes, **options)
-      failure_attributes.concat attributes
+    # @return [Array<Symbol>]
+    def optional_success_attributes
+      # Adding an optional attribute with NO predicates with Dry::Schema is
+      # sort of a "nothing statement" - the schema can sort of ignore it. The
+      # problem is that the optional-with-no-predicate key is not included in
+      # the #info results, so we need to find an list of keys elsewhere, find
+      # the ones that are listed there but not in the #info results, and find
+      # the difference. The result are the keys that are omitted from the #info
+      # result because they are optional and have no predicates.
+      #
+      # See https://github.com/dry-rb/dry-schema/issues/347
+      @optional_success_attributes ||= begin
+          attributes_in_info = success_schema.info[:keys].keys
+          all_attributes = success_schema.key_map.keys.map(&:id)
+          optional_attributes_by_exclusion = all_attributes - attributes_in_info
 
-      attributes.each do |attribute|
-        # Handle options
-        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
-      end
+          explicitly_optional_attributes = success_schema.info[:keys].reject { |_, info| info[:required] }.keys
+
+          explicitly_optional_attributes + optional_attributes_by_exclusion
+        end
     end
 
-    # A DSL method for documenting required interaktor success attributes.
+    # The complete list of success attributes.
     #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    # @param options [Hash]
+    # @return [Array<Symbol>]
+    def success_attributes
+      required_success_attributes + optional_success_attributes
+    end
+
+    # Get the success attribute schema. Fall back to an empty schema with a
+    # configuration that will deny ALL provided attributes - not defining an
+    # success schema should mean the interaktor has no success attributes.
+    #
+    # @return [Dry::Schema::Params]
+    def success_schema
+      @success_schema || Dry::Schema.Params
+    end
+
+    # @param context [Hash]
     #
     # @return [void]
-    def success(*attributes, **options)
-      success_attributes.concat attributes
+    def validate_success_schema(context)
+      return unless success_schema
+
+      result = success_schema.call(context)
 
-      attributes.each do |attribute|
-        # Handle options
-        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
+      if result.errors.any?
+        raise Interaktor::Error::AttributeSchemaValidationError.new(
+          self,
+          result.errors.to_h,
+        )
+      end
+    end
+
+    # @param schema [Dry::Schema::Params, nil] a predefined schema object
+    # @yield a new Dry::Schema::Params definition block
+    def success(schema = nil, &block)
+      raise "No schema or schema definition block provided to interaktor success method." if schema.nil? && !block
+
+      raise "Provided both a schema and a schema definition block for interaktor success method." if schema && block
+
+      if schema
+        raise "Provided argument is not a Dry::Schema::Params object." unless schema.is_a?(Dry::Schema::Params)
+
+        @success_schema = schema
+      elsif block
+        @success_schema = Dry::Schema.Params { instance_eval(&block) }
       end
     end
 
@@ -174,45 +324,22 @@ module Interaktor::Callable
     #
     # @return [Interaktor::Context] the context, following interaktor execution
     def execute(context, raise_exception)
-      unless context.is_a?(Hash) || context.is_a?(Interaktor::Context)
-        raise ArgumentError, "Expected a hash argument when calling the interaktor, got a #{context.class} instead."
-      end
-
-      apply_default_optional_attributes(context)
-      verify_attribute_presence(context)
-
       run_method = raise_exception ? :run! : :run
 
-      new(context).tap(&run_method).instance_variable_get(:@context)
-    end
-
-    # Check the provided context against the attributes defined with the DSL
-    # methods, and determine if there are any attributes which are required and
-    # have not been provided, or if there are any attributes which have been
-    # provided but are not listed as either required or optional.
-    #
-    # @param context [Interaktor::Context] the context to check
-    #
-    # @return [void]
-    def verify_attribute_presence(context)
-      # TODO: Add "allow_nil?" option to required attributes
-      missing_attrs = required_attributes.reject { |required_attr| context.to_h.key?(required_attr) }
-      raise Interaktor::Error::MissingAttributeError.new(self, missing_attrs) if missing_attrs.any?
+      case context
+      when Hash
+        # Silently remove any attributes that are not included in the schema
+        allowed_keys = input_schema.key_map.keys.map { |k| k.name.to_sym }
+        context.select! { |k, _| allowed_keys.include?(k.to_sym) }
 
-      allowed_attrs = required_attributes + optional_attributes
-      extra_attrs = context.to_h.keys.reject { |attr| allowed_attrs.include?(attr) }
-      raise Interaktor::Error::UnknownAttributeError.new(self, extra_attrs) if extra_attrs.any?
-    end
+        validate_input_schema(context)
 
-    # Given the list of optional default attribute values defined by the class,
-    # assign those default values to the context if they were omitted.
-    #
-    # @param context [Interaktor::Context]
-    #
-    # @return [void]
-    def apply_default_optional_attributes(context)
-      optional_defaults.each do |attribute, default|
-        context[attribute] ||= default
+        new(context).tap(&run_method).instance_variable_get(:@context)
+      when Interaktor::Context
+        new(context).tap(&run_method).instance_variable_get(:@context)
+      else
+        raise ArgumentError,
+              "Expected a hash argument when calling the interaktor, got a #{context.class} instead."
       end
     end
   end

data/lib/interaktor/error/attribute_error.rb

@@ -10,7 +10,9 @@ class Interaktor::Error::AttributeError < Interaktor::Error::Base
     @attributes = attributes
   end
 
+  # @return [String]
+  # @abstract
   def message
-    raise NotImplementedError
+    raise NoMethodError
   end
 end

data/lib/interaktor/error/attribute_schema_validation_error.rb

@@ -0,0 +1,54 @@
+class Interaktor::Error::AttributeSchemaValidationError < Interaktor::Error::Base
+  # @return [Hash{Symbol=>Array<String>}]
+  attr_reader :validation_errors
+
+  # @param interaktor [Class]
+  # @param validation_errors [Hash{Symbol=>Array<String>}]
+  def initialize(interaktor, validation_errors)
+    super(interaktor)
+
+    @validation_errors = validation_errors
+  end
+
+  # @return [String]
+  # @abstract
+  def message
+    "Interaktor attribute schema failed validation:\n  #{error_list}"
+  end
+
+  private
+
+  # @return [String]
+  def error_list
+    result = ""
+
+    validation_errors.each do |attribute, errors|
+      result << error_entry(attribute, errors)
+    end
+
+    result
+  end
+
+  def error_entry(key, value, depth = 0)
+    result = " " * depth * 2
+
+    case value
+    when Hash
+      result << "#{key}:\n"
+      value.each do |sub_key, sub_value|
+        result << "  "
+        result << error_entry(sub_key, sub_value, depth + 1)
+      end
+    when Array
+      result << "#{key}:\n"
+      value.each do |error_message|
+        result << "  "
+        result << error_entry(nil, error_message, depth + 1)
+      end
+    else
+      result << "- #{value}\n"
+    end
+
+    result
+  end
+end

data/lib/interaktor/error/missing_explicit_success_error.rb

@@ -0,0 +1,5 @@
+class Interaktor::Error::MissingExplicitSuccessError < Interaktor::Error::AttributeError
+  def message
+    "#{interaktor} interaktor execution finished successfully but requires one or more success parameters to have been provided: #{attributes.join(", ")}"
+  end
+end

data/lib/interaktor/error/organizer_missing_passed_attribute_error.rb

@@ -0,0 +1,21 @@
+class Interaktor::Error::OrganizerMissingPassedAttributeError < Interaktor::Error::AttributeError
+  # @return [Symbol]
+  attr_reader :attribute
+
+  # @param next_interaktor [Class]
+  # @param attribute [Symbol]
+  def initialize(interaktor, attribute)
+    super(interaktor, [attribute])
+
+    @attribute = attribute
+  end
+
+  def message
+    <<~MESSAGE.strip.tr("\n", "")
+      An organized #{interaktor} interaktor requires a '#{attribute}' input
+      attribute, but none of the interaktors that come before it in the
+      organizer list it as a success attribute, and the organizer does not list
+      it as a required attribute.
+    MESSAGE
+  end
+end

data/lib/interaktor/error/organizer_success_attribute_missing_error.rb

@@ -0,0 +1,20 @@
+class Interaktor::Error::OrganizerSuccessAttributeMissingError < Interaktor::Error::AttributeError
+  # @return [Symbol]
+  attr_reader :attribute
+
+  # @param interaktor [Class]
+  # @param attribute [Symbol]
+  def initialize(interaktor, attribute)
+    super(interaktor, [attribute])
+
+    @attribute = attribute
+  end
+
+  def message
+    <<~MESSAGE.strip.tr("\n", "")
+      A #{interaktor} organizer requires a '#{attribute}' success attribute,
+      but none of the success attributes provided by any of the organized
+      interaktors list it.
+    MESSAGE
+  end
+end

data/lib/interaktor/hooks.rb

@@ -126,6 +126,11 @@ module Interaktor::Hooks
       hooks.each { |hook| after_hooks.unshift(hook) }
     end
 
+    def ensure_hook(*hooks, &block)
+      hooks << block if block
+      hooks.each { |hook| ensure_hooks.push(hook) }
+    end
+
     # Internal: An Array of declared hooks to run around Interaktor
     # invocation. The hooks appear in the order in which they will be run.
     #
@@ -182,6 +187,10 @@ module Interaktor::Hooks
     def after_hooks
       @after_hooks ||= []
     end
+
+    def ensure_hooks
+      @ensure_hooks ||= []
+    end
   end
 
   private
@@ -212,6 +221,8 @@ module Interaktor::Hooks
       yield
       run_after_hooks
     end
+  ensure
+    run_ensure_hooks
   end
 
   # Internal: Run around hooks.
@@ -237,6 +248,11 @@ module Interaktor::Hooks
     run_hooks(self.class.after_hooks)
   end
 
+
+  def run_ensure_hooks
+    run_hooks(self.class.ensure_hooks)
+  end
+
   # Internal: Run a colection of hooks. The "run_hooks" method is the common
   # interface by which collections of either before or after hooks are run.
   #

data/lib/interaktor/organizer.rb

@@ -39,16 +39,42 @@ module Interaktor::Organizer
     #
     # @return [void]
     def call
-      self.class.organized.each do |interaktor|
-        # Take the context that is being passed to each interaktor and remove
-        # any attributes from it that are not required by the interactor.
-        @context.to_h
-                .keys
-                .reject { |attr| interaktor.input_attributes.include?(attr) }
-                .each { |attr| @context.delete_field(attr) }
+      check_attribute_flow_valid
 
+      self.class.organized.each do |interaktor|
         catch(:early_return) { interaktor.call!(@context) }
       end
     end
+
+    private
+
+    # @return [void]
+    def check_attribute_flow_valid
+      interaktors = self.class.organized
+
+      # @type [Array<Symbol>]
+      success_attributes_so_far = []
+
+      success_attributes_so_far += self.class.required_input_attributes
+
+      # @param interaktor [Class]
+      interaktors.each do |interaktor|
+        interaktor.required_input_attributes.each do |required_attr|
+          unless success_attributes_so_far.include?(required_attr)
+            raise Interaktor::Error::OrganizerMissingPassedAttributeError.new(interaktor, required_attr)
+          end
+        end
+
+        success_attributes_so_far += interaktor.success_attributes
+
+        next unless interaktor == interaktors.last
+
+        self.class.success_attributes.each do |success_attr|
+          unless success_attributes_so_far.include?(success_attr)
+            raise Interaktor::Error::OrganizerSuccessAttributeMissingError.new(interaktor, success_attr)
+          end
+        end
+      end
+    end
   end
 end

data/lib/interaktor.rb

@@ -32,11 +32,11 @@ module Interaktor
   #
   # @return [void]
   def fail!(failure_attributes = {})
-    # Make sure we have all required attributes
-    missing_attrs = self.class
-                        .failure_attributes
-                        .reject { |failure_attr| failure_attributes.key?(failure_attr) }
-    raise Interaktor::Error::MissingAttributeError.new(self.class.to_s, missing_attrs) if missing_attrs.any?
+    # Silently remove any attributes that are not included in the schema
+    allowed_keys = self.class.failure_schema.key_map.keys.map { |k| k.name.to_sym }
+    failure_attributes.select! { |k, _| allowed_keys.include?(k.to_sym) }
+
+    self.class.validate_failure_schema(failure_attributes)
 
     @context.fail!(failure_attributes)
   end
@@ -48,16 +48,11 @@ module Interaktor
   #
   # @return [void]
   def success!(success_attributes = {})
-    # Make sure we have all required attributes
-    missing_attrs = self.class
-                        .success_attributes
-                        .reject { |success_attr| success_attributes.key?(success_attr) }
-    raise Interaktor::Error::MissingAttributeError.new(self.class.to_s, missing_attrs) if missing_attrs.any?
+    # Silently remove any attributes that are not included in the schema
+    allowed_keys = self.class.success_schema.key_map.keys.map { |k| k.name.to_sym }
+    success_attributes.select! { |k, _| allowed_keys.include?(k.to_sym) }
 
-    # Make sure we haven't provided any unknown attributes
-    unknown_attrs = success_attributes.keys
-                                      .reject { |success_attr| self.class.success_attributes.include?(success_attr) }
-    raise Interaktor::Error::UnknownAttributeError.new(self.class.to_s, unknown_attrs) if unknown_attrs.any?
+    self.class.validate_success_schema(success_attributes)
 
     @context.success!(success_attributes)
   end
@@ -104,8 +99,8 @@ module Interaktor
         call
       end
 
-      if !@context.early_return? && self.class.success_attributes.any?
-        raise Interaktor::Error::MissingAttributeError.new(self, self.class.success_attributes)
+      if !@context.early_return? && self.class.required_success_attributes.any?
+        raise Interaktor::Error::MissingExplicitSuccessError.new(self, self.class.required_success_attributes)
       end
 
       @context.called!(self)