interaktor 0.1.5 → 0.2.0

data/interaktor.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name = "interaktor"
-  spec.version = "0.1.5"
+  spec.version = "0.2.0"
 
   spec.author = "Taylor Thurlow"
   spec.email = "taylorthurlow@me.com"

data/lib/interaktor.rb

@@ -13,193 +13,11 @@ module Interaktor
     base.class_eval do
       extend ClassMethods
       include Hooks
+      include Callable
     end
   end
 
   module ClassMethods
-    # The list of attributes which are required to be passed in when calling
-    # the interaktor.
-    #
-    # @return [Array<Symbol>]
-    def required_attributes
-      @required_attributes ||= []
-    end
-
-    # The list of attributes which are NOT required to be passed in when
-    # calling the interaktor.
-    #
-    # @return [Array<Symbol>]
-    def optional_attributes
-      @optional_attributes ||= []
-    end
-
-    # A list of optional attributes and their default values.
-    #
-    # @return [Array<Symbol>]
-    def optional_defaults
-      @optional_defaults ||= {}
-    end
-
-    # The list of attributes which are required to be passed in when calling
-    # `#fail!` from within the interaktor.
-    #
-    # @return [Array<Symbol>]
-    def failure_attributes
-      @failure_attributes ||= []
-    end
-
-    # The list of attributes which are required to be passed in when calling
-    # `#fail!` from within the interaktor.
-    #
-    # @return [Array<Symbol>]
-    def success_attributes
-      @success_attributes ||= []
-    end
-
-    # A DSL method for documenting required interaktor attributes.
-    #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    # @param options [Hash]
-    #
-    # @return [void]
-    def required(*attributes, **options)
-      required_attributes.concat attributes
-
-      attributes.each do |attribute|
-        # Define getter
-        define_method(attribute) { @context.send(attribute) }
-
-        # Define setter
-        define_method("#{attribute}=".to_sym) do |value|
-          @context.send("#{attribute}=".to_sym, value)
-        end
-
-        raise "Unknown option(s): #{options.keys.join(", ")}" if options.any?
-      end
-    end
-
-    # A DSL method for documenting optional interaktor attributes.
-    #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    # @param options [Hash]
-    #
-    # @return [void]
-    def optional(*attributes, **options)
-      optional_attributes.concat attributes
-
-      attributes.each do |attribute|
-        # Define getter
-        define_method(attribute) { @context.send(attribute) }
-
-        # Define setter
-        define_method("#{attribute}=".to_sym) do |value|
-          unless @context.to_h.key?(attribute)
-            raise <<~ERROR
-                    You can't assign a value to an optional parameter if you
-                    didn't initialize the interaktor with it in the first
-                    place.
-                  ERROR
-          end
-
-          @context.send("#{attribute}=".to_sym, value)
-        end
-
-        # Handle options
-        optional_defaults[attribute] = options[:default] if options[:default]
-        options.delete(:default)
-
-        raise "Unknown option(s): #{options.keys.join(", ")}" if options.any?
-      end
-    end
-
-    # A DSL method for documenting required interaktor failure attributes.
-    #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    #
-    # @return [void]
-    def failure(*attributes)
-      failure_attributes.concat attributes
-    end
-
-    # A DSL method for documenting required interaktor success attributes.
-    #
-    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
-    #
-    # @return [void]
-    def success(*attributes)
-      success_attributes.concat attributes
-    end
-
-    # Invoke an Interaktor. This is the primary public API method to an
-    # interaktor.
-    #
-    # @param context [Hash, Interaktor::Context] the context object as a hash
-    # with attributes or an already-built context
-    #
-    # @return [Interaktor::Context] the context, following interaktor execution
-    def call(context = {})
-      apply_default_optional_attributes(context)
-      verify_attribute_presence(context)
-
-      new(context).tap(&:run).instance_variable_get(:@context)
-    end
-
-    # Invoke an Interaktor. This method behaves identically to `#call`, with
-    # one notable exception - if the context is failed during the invocation of
-    # the interaktor, `Interaktor::Failure` is raised.
-    #
-    # @param context [Hash, Interaktor::Context] the context object as a hash
-    # with attributes or an already-built context
-    #
-    # @raises [Interaktor::Failure]
-    #
-    # @return [Interaktor::Context] the context, following interaktor execution
-    def call!(context = {})
-      apply_default_optional_attributes(context)
-      verify_attribute_presence(context)
-
-      new(context).tap(&:run!).instance_variable_get(:@context)
-    end
-
-    private
-
-    # 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 <<~ERROR if missing_attrs.any?
-        Required attribute(s) were not provided when initializing #{name} interaktor:
-          #{missing_attrs.join("\n  ")}
-      ERROR
-
-      allowed_attrs = required_attributes + optional_attributes
-      extra_attrs = context.to_h.keys.reject { |attr| allowed_attrs.include?(attr) }
-
-      raise <<~ERROR if extra_attrs.any?
-        One or more provided attributes were not recognized when initializing #{name} interaktor:
-          #{extra_attrs.join("\n  ")}
-      ERROR
-    end
-
-    # 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
-      end
-    end
   end
 
   # @param context [Hash, Interaktor::Context] the context object as a hash
@@ -215,9 +33,10 @@ module Interaktor
   # @return [void]
   def fail!(failure_attributes = {})
     # Make sure we have all required attributes
-    missing_attrs = self.class.failure_attributes
+    missing_attrs = self.class
+                        .failure_attributes
                         .reject { |failure_attr| failure_attributes.key?(failure_attr) }
-    raise "Missing failure attrs: #{missing_attrs.join(", ")}" if missing_attrs.any?
+    raise Interaktor::Error::MissingAttributeError.new(self.class.to_s, missing_attrs) if missing_attrs.any?
 
     @context.fail!(failure_attributes)
   end
@@ -230,14 +49,15 @@ module Interaktor
   # @return [void]
   def success!(success_attributes = {})
     # Make sure we have all required attributes
-    missing_attrs = self.class.success_attributes
+    missing_attrs = self.class
+                        .success_attributes
                         .reject { |success_attr| success_attributes.key?(success_attr) }
-    raise "Missing success attrs: #{missing_attrs.join(", ")}" if missing_attrs.any?
+    raise Interaktor::Error::MissingAttributeError.new(self.class.to_s, missing_attrs) if missing_attrs.any?
 
     # 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 "Unknown success attrs: #{unknown_attrs.join(", ")}" if unknown_attrs.any?
+    raise Interaktor::Error::UnknownAttributeError.new(self.class.to_s, unknown_attrs) if unknown_attrs.any?
 
     @context.success!(success_attributes)
   end
@@ -284,6 +104,10 @@ module Interaktor
         call
       end
 
+      if !@context.early_return? && self.class.success_attributes.any?
+        raise Interaktor::Error::MissingAttributeError.new(self, self.class.success_attributes)
+      end
+
       @context.called!(self)
     end
   rescue StandardError

data/lib/interaktor/callable.rb

@@ -0,0 +1,219 @@
+module Interaktor::Callable
+  # When the module is included in a class, add the relevant class methods to
+  # that class.
+  #
+  # @param base [Class] the class which is including the module
+  def self.included(base)
+    base.class_eval { extend ClassMethods }
+  end
+
+  module ClassMethods
+    # The list of attributes which are required to be passed in when calling
+    # the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def required_attributes
+      @required_attributes ||= []
+    end
+
+    # The list of attributes which are NOT required to be passed in when
+    # calling the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def optional_attributes
+      @optional_attributes ||= []
+    end
+
+    # A list of optional attributes and their default values.
+    #
+    # @return [Array<Symbol>]
+    def optional_defaults
+      @optional_defaults ||= {}
+    end
+
+    # A list of attributes which could be passed when calling the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def input_attributes
+      required_attributes + optional_attributes
+    end
+
+    # The list of attributes which are required to be passed in when calling
+    # `#fail!` from within the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def failure_attributes
+      @failure_attributes ||= []
+    end
+
+    # The list of attributes which are required to be passed in when calling
+    # `#fail!` from within the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def success_attributes
+      @success_attributes ||= []
+    end
+
+    # A DSL method for documenting required interaktor attributes.
+    #
+    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
+    # @param options [Hash]
+    #
+    # @return [void]
+    def required(*attributes, **options)
+      required_attributes.concat attributes
+
+      attributes.each do |attribute|
+        # Define getter
+        define_method(attribute) { @context.send(attribute) }
+
+        # Define setter
+        define_method("#{attribute}=".to_sym) do |value|
+          @context.send("#{attribute}=".to_sym, value)
+        end
+
+        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
+      end
+    end
+
+    # A DSL method for documenting optional interaktor attributes.
+    #
+    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
+    # @param options [Hash]
+    #
+    # @return [void]
+    def optional(*attributes, **options)
+      optional_attributes.concat attributes
+
+      attributes.each do |attribute|
+        # Define getter
+        define_method(attribute) { @context.send(attribute) }
+
+        # 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
+
+          @context.send("#{attribute}=".to_sym, value)
+        end
+
+        # Handle options
+        optional_defaults[attribute] = options[:default] if options[:default]
+        options.delete(:default)
+
+        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
+      end
+    end
+
+    # A DSL method for documenting required interaktor failure attributes.
+    #
+    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
+    # @param options [Hash]
+    #
+    # @return [void]
+    def failure(*attributes, **options)
+      failure_attributes.concat attributes
+
+      attributes.each do |attribute|
+        # Handle options
+        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
+      end
+    end
+
+    # A DSL method for documenting required interaktor success attributes.
+    #
+    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
+    # @param options [Hash]
+    #
+    # @return [void]
+    def success(*attributes, **options)
+      success_attributes.concat attributes
+
+      attributes.each do |attribute|
+        # Handle options
+        raise Interaktor::Error::UnknownOptionError.new(self.class.to_s, options) if options.any?
+      end
+    end
+
+    # Invoke an Interaktor. This is the primary public API method to an
+    # interaktor. Interaktor failures will not raise an exception.
+    #
+    # @param context [Hash, Interaktor::Context] the context object as a hash
+    #   with attributes or an already-built context
+    #
+    # @return [Interaktor::Context] the context, following interaktor execution
+    def call(context = {})
+      execute(context, false)
+    end
+
+    # Invoke an Interaktor. This method behaves identically to `#call`, but if
+    # the interaktor is failed, `Interaktor::Failure` is raised.
+    #
+    # @param context [Hash, Interaktor::Context] the context object as a hash
+    #   with attributes or an already-built context
+    #
+    # @raises [Interaktor::Failure]
+    #
+    # @return [Interaktor::Context] the context, following interaktor execution
+    def call!(context = {})
+      execute(context, true)
+    end
+
+    private
+
+    # The main execution method triggered by the public `#call` or `#call!`
+    # methods.
+    #
+    # @param context [Hash, Interaktor::Context] the context object as a hash
+    #   with attributes or an already-built context
+    # @param raise_exception [Boolean] whether or not to raise exception on
+    #   failure
+    #
+    # @raises [Interaktor::Failure]
+    #
+    # @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?
+
+      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
+
+    # 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
+      end
+    end
+  end
+end