activeinteractor 0.1.7 → 1.0.0.beta.1

data/lib/active_interactor/context/base.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require 'ostruct'
+
+require 'active_interactor/context/attributes'
+
+module ActiveInteractor
+  module Context
+    # The base context class.  All interactor contexts should inherit from
+    #  {Context::Base}.
+    # @author Aaron Allen <hello@aaronmallen.me>
+    # @since 0.0.1
+    class Base < OpenStruct
+      include ActiveModel::Validations
+      include Attributes
+
+      # @!method valid?(context = nil)
+      # @see
+      #   https://github.com/rails/rails/blob/master/activemodel/lib/active_model/validations.rb#L305
+      #   ActiveModel::Validations#valid?
+
+      # @api private
+      # Track that an Interactor has been called. The {#called!} method
+      #  is used by the interactor being invoked with this context. After an
+      #  interactor is successfully called, the interactor instance is tracked in
+      #  the context for the purpose of potential future rollback
+      # @param interactor [ActiveInteractor::Base] the called interactor
+      # @return [Array<ActiveInteractor::Base>] all called interactors
+      def called!(interactor)
+        _called << interactor
+      end
+
+      # Fail the context instance. Failing a context raises an error
+      #  that may be rescued by the calling interactor. The context is also flagged
+      #  as having failed
+      #
+      # @example Fail an interactor context
+      #   class MyInteractor < ActiveInteractor::Base
+      #     def perform
+      #       context.fail!
+      #     end
+      #   end
+      #
+      #   MyInteractor.perform!
+      #   #=> ActiveInteractor::Error::ContextFailure: <#MyInteractor::Context>
+      # @param errors [ActiveModel::Errors|nil] errors to add to the context on failure
+      # @see https://api.rubyonrails.org/classes/ActiveModel/Errors.html ActiveModel::Errors
+      # @raise [Error::ContextFailure]
+      def fail!(errors = nil)
+        merge_errors!(errors) if errors
+        @_failed = true
+        raise Error::ContextFailure, self
+      end
+
+      # Whether the context instance has failed. By default, a new
+      # context is successful and only changes when explicitly failed
+      # @note The {#failure?} method is the inverse of the {#success?} method
+      # @example Check if a context has failed
+      #   class MyInteractor < ActiveInteractor::Base
+      #     def perform; end
+      #   end
+      #
+      #   result = MyInteractor.perform
+      #   #=> <#MyInteractor::Context>
+      #
+      #   result.failure?
+      #   #=> false
+      # @return [Boolean] `false` by default or `true` if failed
+      def failure?
+        @_failed || false
+      end
+      alias fail? failure?
+
+      # Roll back an interactor context. Any interactors to which this
+      # context has been passed and which have been successfully called are asked
+      # to roll themselves back by invoking their
+      # {ActiveInteractor::Base#rollback} instance methods.
+      # @example Rollback an interactor's context
+      #   class MyInteractor < ActiveInteractor::Base
+      #     def perform
+      #       context.fail!
+      #     end
+      #
+      #     def rollback
+      #       context.user&.destroy
+      #     end
+      #   end
+      #
+      #   user = User.create
+      #   #=> <#User>
+      #
+      #   result = MyInteractor.perform(user: user)
+      #   #=> <#MyInteractor::Context user=<#User>>
+      #
+      #   result.user.destroyed?
+      #   #=> true
+      # @return [Boolean] `true` if rolled back successfully or `false` if already
+      #  rolled back
+      def rollback!
+        return false if @_rolled_back
+
+        _called.reverse_each(&:rollback)
+        @_rolled_back = true
+      end
+
+      # Whether the context instance is successful. By default, a new
+      # context is successful and only changes when explicitly failed
+      # @note the {#success?} method is the inverse of the {#failure?} method
+      # @example Check if a context is successful
+      #   class MyInteractor < ActiveInteractor::Base
+      #     def perform; end
+      #   end
+      #
+      #   result = MyInteractor.perform
+      #   #=> <#MyInteractor::Context>
+      #
+      #   result.success?
+      #   #=> true
+      # @return [Boolean] `true` by default or `false` if failed
+      def success?
+        !failure?
+      end
+      alias successful? success?
+
+      private
+
+      def _called
+        @_called ||= []
+      end
+
+      def merge_errors!(errors)
+        if errors.is_a? String
+          self.errors.add(:context, errors)
+        else
+          self.errors.merge!(errors)
+        end
+      end
+    end
+  end
+end

data/lib/active_interactor/context/loader.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string/inflections'
+
+module ActiveInteractor
+  module Context
+    # @api private
+    # Load, find or create {Context::Base} classes for a given interactor.
+    # @author Aaron Allen <hello@aaronmallen.me>
+    # @since 1.0.0
+    module Loader
+      # @return [Array<Class>] ActiveInteractor base classes
+      BASE_CLASSES = [ActiveInteractor::Base, ActiveInteractor::Organizer].freeze
+      # @return [Class] the base context class
+      BASE_CONTEXT = ActiveInteractor::Context::Base
+
+      # Create a new context class on an interactor
+      # @param context_class_name [String] the name of the class to create
+      # @param interactor_class [Class] the interactor class to create the context for
+      # @return [Class] the created context class
+      def self.create(context_class_name, interactor_class)
+        interactor_class.const_set(context_class_name.to_s.classify, Class.new(BASE_CONTEXT))
+      end
+
+      # Find or create a new context class for an interactor
+      # @note the loader will attempt to find an existing context given the naming conventions:
+      #   `MyInteractor::Context` or `MyInteractorContext`
+      # @param interactor_class [Class] the interactor class to find or create the context for
+      def self.find_or_create(interactor_class)
+        return BASE_CONTEXT if BASE_CLASSES.include?(interactor_class)
+
+        klass = possible_classes(interactor_class).first
+        klass || create('Context', interactor_class)
+      end
+
+      def self.possible_classes(interactor_class)
+        ["#{interactor_class.name}::Context", "#{interactor_class.name}Context"]
+          .map(&:safe_constantize)
+          .compact
+          .reject { |klass| klass&.name&.include?('ActiveInteractor') }
+      end
+      private_class_method :possible_classes
+    end
+  end
+end

data/lib/active_interactor/error.rb

@@ -1,30 +1,37 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
-  # ActiveInteractor::Error module
-  #
+  # ActiveInteractor errors
   # @author Aaron Allen <hello@aaronmallen.me>
   # @since 0.1.5
-  # @version 0.1
   module Error
-    # Raised when an interactor context fails
-    #
-    # @author Aaron Allen <hello@aaronmallen.me>
-    # @since 0.1.5
-    # @version 0.1
-    #
+    # Raised when an interactor context fails.
     # @!attribute [r] context
-    #  @return [Base] an instance of {Base}
+    #  @return [Context::Base] an instance of {Context::Base}
     class ContextFailure < StandardError
       attr_reader :context
 
-      # A new instance of {ContextFailure}
-      # @param context [ActiveInteractor::Context::Base] an
-      #  instance of {ActiveInteractor::Context::Base}
-      # @return [ContextFailure] a new instance of {ContextFailure}
+      # @param context [Context::Base] the failed context instance.
+      # @return [ContextFailure] a new instance of {ContextFailure}.
       def initialize(context = nil)
         @context = context
-        super
+        context_class_name = context&.class&.name || 'Context'
+        super("#{context_class_name} failed!")
+      end
+    end
+
+    # Raised when an invalid context class is assigned to an interactor.
+    # @since 1.0.0
+    # @!attribute [r] class_name
+    #  @return [String|nil] the class name of the context
+    class InvalidContextClass < StandardError
+      attr_reader :class_name
+
+      # @param class_name [String] the context class name
+      # @return [InvalidContextClass] a new instance of {InvalidContextClass}
+      def initialize(class_name = nil)
+        @class_name = class_name
+        super("invalid context class #{class_name}")
       end
     end
   end

data/lib/active_interactor/interactor.rb

@@ -1,65 +1,48 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
-  # Provides interactor methods to included classes
-  #
+  # Interactor methods. {Base} includes {Interactor} all interactors
+  #  should inherit from {Base}.
   # @author Aaron Allen <hello@aaronmallen.me>
   # @since 0.0.1
-  # @version 0.1
   module Interactor
-    extend ActiveSupport::Concern
-
-    included do
-      extend ClassMethods
-      include Callbacks
-      include Context
-      include Execution
-
-      private
-
-      attr_accessor :context
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        include Callbacks
+        include Context
+        delegate :execute_perform, :execute_perform!, :execute_rollback, to: :worker
+      end
     end
-
+    # Interactor class methods.
     module ClassMethods
-      # Invoke an interactor. This is the primary public API method to an
-      #  interactor.
-      #
+      # Run an interactor context.  This it the primary API method for
+      # interacting with interactors.
       # @example Run an interactor
       #  MyInteractor.perform(name: 'Aaron')
       #  #=> <#MyInteractor::Context name='Aaron'>
-      #
-      # @param context [Hash] properties to assign to the interactor context
-      # @return [ActiveInteractor::Context::Base] an instance of context
+      # @param context [Hash|Context::Base] properties to assign to
+      #  an interactor's context.
+      # @return [Context::Base] an instance of context.
       def perform(context = {})
         new(context).execute_perform
       end
 
-      # Invoke an Interactor. The {.perform!} method behaves identically to
+      # Run an interactor context. The {.perform!} method behaves identically to
       #  the {.perform} method with one notable exception. If the context is failed
-      #  during invocation of the interactor, the {ActiveInteractor::Error::ContextFailure}
+      #  during invocation of the interactor, the {Error::ContextFailure}
       #  is raised.
-      #
       # @example Run an interactor
       #  MyInteractor.perform!(name: 'Aaron')
       #  #=> <#MyInteractor::Context name='Aaron'>
-      #
-      # @param context [Hash] properties to assign to the interactor context
-      # @return [ActiveInteractor::Context::Base] an instance of context
+      # @param context [Hash|Context::Base] properties to assign to the interactor context.
+      # @raise [Error::ContextFailure] if the context fails.
+      # @return [Context::Base] an instance of context.
       def perform!(context = {})
         new(context).execute_perform!
       end
     end
 
-    # Whether or not the context should fail when invalid
-    #  this will return false if
-    #  {Interactor::Callbacks::ClassMethods#allow_context_to_be_invalid}
-    #  has been invoked on the class.
-    # @return [Boolean] `true` if the context should fail
-    #  `false` if it should not.
-    def fail_on_invalid_context?
-      self.class.__fail_on_invalid_context
-    end
-
     # Invoke an Interactor instance without any hooks, tracking, or rollback
     # @abstract It is expected that the {#perform} method is overwritten
     #  for each interactor class.
@@ -70,28 +53,12 @@ module ActiveInteractor
     #  failure is expected to overwrite the {#rollback} method.
     def rollback; end
 
-    # Whether or not the context should be cleaned after {#perform}
-    #  if {#skip_clean_context!} has not been invoked on the instance
-    #  and {Interactor::Callbacks::ClassMethods#clean_context_on_completion}
-    #  is invoked on the class this will return `true`.
-    #
-    # @return [Boolean] `true` if the context should be cleaned
-    #  `false` if it should not be cleaned.
-    def should_clean_context?
-      @should_clean_context.nil? && self.class.__clean_after_perform
-    end
+    private
 
-    # Skip {ActiveInteractor::Context::Attributes#clean! #clean! on an interactor
-    #  context that calls the {Callbacks.clean_context_on_completion} class method.
-    #  This method is meant to be invoked by organizer interactors
-    #  to ensure contexts are approriately passed between interactors.
-    #
-    # @return [Boolean] `true` if the context should be cleaned
-    #  `false` if it should not.
-    def skip_clean_context!
-      @should_clean_context = false
+    def worker
+      Worker.new(self)
     end
   end
 end
 
-Dir[File.expand_path('interactor/*.rb', __dir__)].each { |file| require file }
+Dir[File.expand_path('interactor/*.rb', __dir__)].sort.each { |file| require file }

data/lib/active_interactor/interactor/callbacks.rb

@@ -1,62 +1,56 @@
 # frozen_string_literal: true
 
+require 'active_support/callbacks'
 require 'active_support/core_ext/array/extract_options'
 require 'active_support/core_ext/class/attribute'
 
 module ActiveInteractor
   module Interactor
-    # Provides context attribute assignment methods to included classes
-    #
+    # Interactor callback methods included by all {Base}
     # @author Aaron Allen <hello@aaronmallen.me>
     # @since 0.0.1
-    # @version 0.1
     module Callbacks
-      extend ActiveSupport::Concern
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+          include ActiveSupport::Callbacks
 
-      included do
-        extend ClassMethods
-        include ActiveSupport::Callbacks
-
-        class_attribute :__clean_after_perform, instance_writer: false, default: false
-        class_attribute :__fail_on_invalid_context, instance_writer: false, default: true
-        define_callbacks :validation,
-                         skip_after_callbacks_if_terminated: true,
-                         scope: %i[kind name]
-        define_callbacks :perform, :rollback
+          define_callbacks :validation,
+                           skip_after_callbacks_if_terminated: true,
+                           scope: %i[kind name]
+          define_callbacks :perform, :rollback
+        end
       end
 
+      # Interactor callback class methods extended by all {Base}
       module ClassMethods
-        # Define a callback to call after `#valid?` has been invoked on an
+        # Define a callback to call after {ActiveInteractor::Context::Base#valid? #valid?} has been invoked on an
         #  interactor's context
-        #
         # @example Implement an after_context_validation callback
         #  class MyInteractor < ActiveInteractor::Base
-        #    after_context_validation :ensure_name_is_aaron
-        #    context_validates :name, inclusion: { in: %w[Aaron] }
+        #    after_context_validation :downcase_name
+        #
+        #    private
         #
-        #    def ensure_name_is_aaron
-        #      context.name = 'Aaron'
+        #    def downcase_name
+        #      context.name.downcase!
         #    end
         #  end
         #
-        #  context = MyInteractor.perform(name: 'Bob')
-        #  #=> <MyInteractor::Context name='Bob'>
+        #  result = MyInteractor.perform(name: 'Aaron')
+        #  #=> <MyInteractor::Context name='aaron'>
         #
-        #  context.valid?
-        #  #=> false
-        #
-        #  context.name
-        #  #=> 'Aaron'
-        #
-        #  context.valid?
+        #  result.valid?
         #  #=> true
+        #
+        #  result.name
+        #  #=> 'aaron'
         def after_context_validation(*args, &block)
           options = normalize_options(args.extract_options!.dup.merge(prepend: true))
           set_callback(:validation, :after, *args, options, &block)
         end
 
-        # Define a callback to call after {ActiveInteractor::Base.perform} has been invoked
-        #
+        # Define a callback to call after {Interactor#perform #perform} has been invoked
         # @example
         #  class MyInteractor < ActiveInteractor::Base
         #    after_perform :print_done
@@ -65,6 +59,8 @@ module ActiveInteractor
         #      puts 'Performing'
         #    end
         #
+        #    private
+        #
         #    def print_done
         #      puts 'Done'
         #    end
@@ -78,16 +74,21 @@ module ActiveInteractor
           set_callback(:perform, :after, *filters, &block)
         end
 
-        # Define a callback to call after {ActiveInteractor::Base#rollback} has been invoked
-        #
+        # Define a callback to call after {Interactor#rollback #rollback} has been invoked
         # @example
         #  class MyInteractor < ActiveInteractor::Base
         #    after_rollback :print_done
         #
+        #    def perform
+        #      context.fail!
+        #    end
+        #
         #    def rollback
         #      puts 'Rolling back'
         #    end
         #
+        #    private
+        #
         #    def print_done
         #      puts 'Done'
         #    end
@@ -103,17 +104,7 @@ module ActiveInteractor
           set_callback(:rollback, :after, *filters, &block)
         end
 
-        # By default an interactor context will fail if it is deemed
-        #  invalid before or after the {ActiveInteractor::Base.perform} method
-        #  is invoked.  Calling this method on an interactor class
-        #  will not invoke {ActiveInteractor::Context::Base#fail!} if the
-        #  context is invalid.
-        def allow_context_to_be_invalid
-          self.__fail_on_invalid_context = false
-        end
-
-        # Define a callback to call around {ActiveInteractor::Base.perform} invokation
-        #
+        # Define a callback to call around {Interactor#perform #perform} invokation
         # @example
         #  class MyInteractor < ActiveInteractor::Base
         #    around_perform :track_time
@@ -122,6 +113,8 @@ module ActiveInteractor
         #      sleep(1)
         #    end
         #
+        #    private
+        #
         #    def track_time
         #      context.start_time = Time.now.utc
         #      yield
@@ -129,20 +122,19 @@ module ActiveInteractor
         #    end
         #  end
         #
-        #  context = MyInteractor.perform(name: 'Aaron')
+        #  result = MyInteractor.perform(name: 'Aaron')
         #  #=> <MyInteractor::Context name='Aaron'>
         #
-        #  context.start_time
+        #  result.start_time
         #  #=> 2019-01-01 00:00:00 UTC
         #
-        #  context.end_time
+        #  result.end_time
         #  #=> 2019-01-01 00:00:01 UTC
         def around_perform(*filters, &block)
           set_callback(:perform, :around, *filters, &block)
         end
 
-        # Define a callback to call around {ActiveInteractor::Base#rollback} invokation
-        #
+        # Define a callback to call around {Interactor#rollback #rollback} invokation
         # @example
         #  class MyInteractor < ActiveInteractor::Base
         #    around_rollback :track_time
@@ -151,6 +143,8 @@ module ActiveInteractor
         #      sleep(1)
         #    end
         #
+        #    private
+        #
         #    def track_time
         #      context.start_time = Time.now.utc
         #      yield
@@ -158,49 +152,48 @@ module ActiveInteractor
         #    end
         #  end
         #
-        #  context = MyInteractor.perform(name: 'Aaron')
+        #  result = MyInteractor.perform(name: 'Aaron')
         #  #=> <MyInteractor::Context name='Aaron'>
         #
-        #  context.rollback!
+        #  result.rollback!
         #  #=> true
         #
-        #  context.start_time
+        #  result.start_time
         #  #=> 2019-01-01 00:00:00 UTC
         #
-        #  context.end_time
+        #  result.end_time
         #  #=> 2019-01-01 00:00:01 UTC
         def around_rollback(*filters, &block)
           set_callback(:rollback, :around, *filters, &block)
         end
 
-        # Define a callback to call before `#valid?` has been invoked on an
+        # Define a callback to call before {ActiveInteractor::Context::Base#valid? #valid?} has been invoked on an
         #  interactor's context
-        #
         # @example Implement an after_context_validation callback
         #  class MyInteractor < ActiveInteractor::Base
-        #    before_context_validation :set_name_aaron
-        #    context_validates :name, inclusion: { in: %w[Aaron] }
+        #    before_context_validation :downcase_name
         #
-        #    def set_name_aaron
-        #      context.name = 'Aaron'
+        #    private
+        #
+        #    def downcase_name
+        #      context.name.downcase!
         #    end
         #  end
         #
-        #  context = MyInteractor.perform(name: 'Bob')
-        #  #=> <MyInteractor::Context name='Bob'>
+        #  result = MyInteractor.perform(name: 'Aaron')
+        #  #=> <MyInteractor::Context name='aaron'>
         #
-        #  context.valid?
+        #  result.valid?
         #  #=> true
         #
-        #  context.name
-        #  #=> 'Aaron'
+        #  result.name
+        #  #=> 'aaron'
         def before_context_validation(*args, &block)
           options = normalize_options(args.extract_options!.dup)
           set_callback(:validation, :before, *args, options, &block)
         end
 
-        # Define a callback to call before {ActiveInteractor::Base.perform} has been invoked
-        #
+        # Define a callback to call before {Interactor#perform #perform} has been invoked
         # @example
         #  class MyInteractor < ActiveInteractor::Base
         #    before_perform :print_start
@@ -209,6 +202,8 @@ module ActiveInteractor
         #      puts 'Performing'
         #    end
         #
+        #    private
+        #
         #    def print_start
         #      puts 'Start'
         #    end
@@ -222,8 +217,7 @@ module ActiveInteractor
           set_callback(:perform, :before, *filters, &block)
         end
 
-        # Define a callback to call before {ActiveInteractor::Base#rollback} has been invoked
-        #
+        # Define a callback to call before {Interactor#rollback #rollback} has been invoked
         # @example
         #  class MyInteractor < ActiveInteractor::Base
         #    before_rollback :print_start
@@ -232,6 +226,8 @@ module ActiveInteractor
         #      puts 'Rolling Back'
         #    end
         #
+        #    private
+        #
         #    def print_start
         #      puts 'Start'
         #    end
@@ -248,14 +244,6 @@ module ActiveInteractor
           set_callback(:rollback, :before, *filters, &block)
         end
 
-        # Calling this method on an interactor class will invoke
-        #  {ActiveInteractor::Context::Base#clean!} on the interactor's
-        #  context instance after {ActiveInteractor::Base.perform}
-        #  is invoked.
-        def clean_context_on_completion
-          self.__clean_after_perform = true
-        end
-
         private
 
         def normalize_options(options)