activeinteractor 1.0.0.beta.7 → 1.0.0

data/lib/active_interactor/interactor/worker.rb

@@ -2,21 +2,24 @@
 
 module ActiveInteractor
   module Interactor
+    # A worker class to call {Base interactor} {Interactor::Perform#perform #perform} and
+    # {Interactor::Perform#rollback #rollback} methods in a thread safe manner.
+    #
     # @api private
-    # Thread safe execution of interactor {Interactor#perform #perform} and
-    #  {Interactor#rollback #rollback} methods.
     # @author Aaron Allen <hello@aaronmallen.me>
-    # @since 0.0.2
+    # @since 0.1.0
     class Worker
-      # @param interactor [Base] an instance of interactor
+      # Initialize a new instance of {Worker}
+      #
+      # @param interactor [Base] an {Base interactor} instance
       # @return [Worker] a new instance of {Worker}
       def initialize(interactor)
-        options = interactor.options.dup
-        @interactor = interactor.dup.with_options(options)
+        @interactor = interactor.deep_dup
       end
 
-      # Calls {#execute_perform!} and rescues {Error::ContextFailure}
-      # @return [Context::Base] an instance of {Context::Base}
+      # Run the {Base interactor} instance's {Interactor::Perform#perform #perform} with callbacks and validation.
+      #
+      # @return [Class] a {ActiveInteractor::Context::Base context} instance
       def execute_perform
         execute_perform!
       rescue Error::ContextFailure => e
@@ -24,18 +27,20 @@ module ActiveInteractor
         context
       end
 
-      # Calls {Interactor#perform} with callbacks and context validation
-      # @raise [Error::ContextFailure] if the context fails
-      # @return [Context::Base] an instance of {Context::Base}
+      # Run the {Base interactor} instance's {Interactor::Perform#perform #perform} with callbacks and validation
+      # without rescuing {Error::ContextFailure}.
+      #
+      # @raise [Error::ContextFailure] if the {Base interactor} fails it's {ActiveInteractor::Context::Base context}
+      # @return [Class] a {ActiveInteractor::Context::Base context} instance
       def execute_perform!
         execute_context!
       rescue StandardError => e
         handle_error(e)
       end
 
-      # Calls {Interactor#rollback} with callbacks
-      # @return [Boolean] `true` if rolled back successfully or `false` if already
-      #  rolled back
+      # Run the {Base interactor} instance's {Interactor::Perform#rollback #rollback} with callbacks
+      #
+      # @return [Boolean] `true` if context was successfully rolled back
       def execute_rollback
         return if interactor.options.skip_rollback
 

data/lib/active_interactor/models.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ActiveInteractor
+  # Helper methods for using classes that do not inherit from {Context::Base} as {Context::Base context} objects
+  # for {Base interactors}.  Classes should extend {Models}.
+  #
+  # @author Aaron Allen <hello@aaronmallen.me>
+  # @since 1.0.0
+  module Models
+    # Instance methods needed for a {Context::Base context} class to function properly.
+    #
+    # @private
+    # @author Aaron Allen <hello@aaronmallen.me>
+    # @since 1.0.0
+    module InstanceMethods
+      def initialize(attributes = nil)
+        copy_flags!(attributes) if attributes
+        copy_called!(attributes) if attributes
+        attributes_as_hash = context_attributes_as_hash(attributes)
+        super(attributes_as_hash)
+      end
+
+      # Merge an instance of model class into the calling model class instance
+      #
+      # @see Context::Attributes#merge!
+      #
+      # @param context [Class] a {Base context} instance to be merged
+      # @return [self] the {Base context} instance
+      def merge!(context)
+        copy_flags!(context)
+        context.each_pair do |key, value|
+          self[key] = value unless value.nil?
+        end
+        self
+      end
+
+      private
+
+      def context_attributes_as_hash(attributes)
+        return attributes.to_h if attributes&.respond_to?(:to_h)
+        return attributes.attributes.to_h if attributes.respond_to?(:attributes)
+      end
+    end
+
+    # Include methods needed for a {Context::Base context} class to function properly.
+    #
+    # @example
+    #   class User
+    #     extend ActiveInteractor::Models
+    #     acts_as_context
+    #   end
+    #
+    #   class MyInteractor < ActiveInteractor::Base
+    #     contextualize_with :user
+    #   end
+    def acts_as_context
+      class_eval do
+        include ActiveModel::Validations
+        include ActiveInteractor::Models::InstanceMethods
+        include ActiveInteractor::Context::Status
+        delegate :each_pair, to: :attributes
+      end
+    end
+  end
+end

data/lib/active_interactor/organizer/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveInteractor
+  module Organizer
+    # The base {Base organizer} class all {Base organizers} should inherit from.
+    #
+    # @author Aaron Allen <hello@aaronmallen.me>
+    # @since 1.0.0
+    class Base < ActiveInteractor::Base
+      extend ActiveInteractor::Organizer::Callbacks::ClassMethods
+      extend ActiveInteractor::Organizer::Organize::ClassMethods
+      extend ActiveInteractor::Organizer::Perform::ClassMethods
+
+      include ActiveInteractor::Organizer::Callbacks
+      include ActiveInteractor::Organizer::Perform
+    end
+  end
+end

data/lib/active_interactor/organizer/callbacks.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module ActiveInteractor
+  module Organizer
+    # Organizer callback methods. Because {Callbacks} is a module classes should include {Callbacks} rather than
+    # inherit from it.
+    #
+    # @author Aaron Allen <hello@aaronmallen.me>
+    # @since 1.0.0
+    # @see https://github.com/aaronmallen/activeinteractor/wiki/Callbacks Callbacks
+    # @see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html ActiveSupport::Callbacks
+    module Callbacks
+      # Organizer callback class methods. Because {ClassMethods} is a module classes should extend {ClassMethods}
+      # rather than inherit from it.
+      #
+      # @author Aaron Allen
+      # @since 1.0.0
+      module ClassMethods
+        # Define a callback to call after each {Organizer::Organize::ClassMethods#organized organized}
+        # {ActiveInteractor::Base interactor's} {Interactor::Perform#perform #perform} method has been called.
+        #
+        # @since 0.1.3
+        #
+        # @example
+        #  class MyInteractor1 < ActiveInteractor::Base
+        #    def perform
+        #      puts 'MyInteractor1'
+        #    end
+        #  end
+        #
+        #  class MyInteractor2 < ActiveInteractor::Base
+        #    def perform
+        #      puts 'MyInteractor2'
+        #    end
+        #  end
+        #
+        #  class MyOrganizer < ActiveInteractor::Organizer
+        #    after_each_perform :print_done
+        #
+        #    organized MyInteractor1, MyInteractor2
+        #
+        #    private
+        #
+        #    def print_done
+        #      puts 'Done'
+        #    end
+        #  end
+        #
+        #  MyOrganizer.perform
+        #  "MyInteractor1"
+        #  "Done"
+        #  "MyInteractor2"
+        #  "Done"
+        #  #=> <MyOrganizer::Context>
+        def after_each_perform(*filters, &block)
+          set_callback(:each_perform, :after, *filters, &block)
+        end
+
+        # Define a callback to call around each {Organizer::Organize::ClassMethods#organized organized}
+        # {ActiveInteractor::Base interactor's} {Interactor::Perform#perform #perform} method call.
+        #
+        # @since 0.1.3
+        #
+        # @example
+        #  class MyInteractor1 < ActiveInteractor::Base
+        #    def perform
+        #      puts 'MyInteractor1'
+        #      sleep(1)
+        #    end
+        #  end
+        #
+        #  class MyInteractor2 < ActiveInteractor::Base
+        #    def perform
+        #      puts 'MyInteractor2'
+        #      sleep(1)
+        #    end
+        #  end
+        #
+        #  class MyOrganizer < ActiveInteractor::Organizer
+        #    around_each_perform :print_time
+        #
+        #    organized MyInteractor1, MyInteractor2
+        #
+        #    private
+        #
+        #    def print_time
+        #      puts Time.now.utc
+        #      yield
+        #      puts Time.now.utc
+        #    end
+        #  end
+        #
+        #  MyOrganizer.perform
+        #  "2019-04-01 00:00:00 UTC"
+        #  "MyInteractor1"
+        #  "2019-04-01 00:00:01 UTC"
+        #  "2019-04-01 00:00:01 UTC"
+        #  "MyInteractor2"
+        #  "2019-04-01 00:00:02 UTC"
+        #  #=> <MyOrganizer::Context>
+        def around_each_perform(*filters, &block)
+          set_callback(:each_perform, :around, *filters, &block)
+        end
+
+        # Define a callback to call before each {Organizer::Organize::ClassMethods#organized organized}
+        # {ActiveInteractor::Base interactor's} {Interactor::Perform#perform #perform} method has been called.
+        #
+        # @since 0.1.3
+        #
+        # @example
+        #  class MyInteractor1 < ActiveInteractor::Base
+        #    def perform
+        #      puts 'MyInteractor1'
+        #    end
+        #  end
+        #
+        #  class MyInteractor2 < ActiveInteractor::Base
+        #    def perform
+        #      puts 'MyInteractor2'
+        #    end
+        #  end
+        #
+        #  class MyOrganizer < ActiveInteractor::Organizer
+        #    before_each_perform :print_starting
+        #
+        #    organized MyInteractor1, MyInteractor2
+        #
+        #    private
+        #
+        #    def print_starting
+        #      puts 'Starting'
+        #    end
+        #  end
+        #
+        #  MyOrganizer.perform
+        #  "Starting"
+        #  "MyInteractor1"
+        #  "Starting"
+        #  "MyInteractor2"
+        #  #=> <MyOrganizer::Context>
+        def before_each_perform(*filters, &block)
+          set_callback(:each_perform, :before, *filters, &block)
+        end
+      end
+
+      def self.included(base)
+        base.class_eval do
+          define_callbacks :each_perform
+        end
+      end
+    end
+  end
+end

data/lib/active_interactor/organizer/interactor_interface.rb

@@ -1,49 +1,61 @@
 # frozen_string_literal: true
 
-require 'active_support/core_ext/string/inflections'
-
 module ActiveInteractor
-  class Organizer < ActiveInteractor::Base
+  module Organizer
+    # An interface object to facilitate conditionally calling {Interactor::Perform::ClassMethods#perform .perform} on
+    # an {ActiveInteractor::Base interactor}
+    #
     # @api private
-    # An interface for an interactor's to allow conditional invokation of an
-    #  interactor's {Interactor#perform #perform} method.
     # @author Aaron Allen <hello@aaronmallen.me>
     # @since 1.0.0
+    #
     # @!attribute [r] filters
-    #  @return [Hash{Symbol=>*}] conditional filters for an interactor's
-    #    {Interactor#perform #perform} invocation.
+    #  Conditional options for the {ActiveInteractor::Base interactor} class
+    #
+    #  @return [Hash{Symbol=>Proc, Symbol}] conditional options for the {ActiveInteractor::Base interactor} class
+    #
     # @!attribute [r] interactor_class
-    #  @return [Class] an interactor class
+    #  An {ActiveInteractor::Base interactor} class
+    #
+    #  @return [Const] an {ActiveInteractor::Base interactor} class
+    #
     # @!attribute [r] perform_options
-    #  @return [Hash{Symbol=>*}] perform options to use for an interactor's
-    #    {Interactor#perform #perform} invocation.
+    #  {Interactor::Perform::Options} for the {ActiveInteractor::Base interactor} {Interactor::Perform#perform #perform}
+    #
+    #  @see Interactor::Perform::Options
+    #
+    #  @return [Hash{Symbol=>*}] {Interactor::Perform::Options} for the {ActiveInteractor::Base interactor}
+    #   {Interactor::Perform#perform #perform}
     class InteractorInterface
       attr_reader :filters, :interactor_class, :perform_options
 
-      # @return [Array<Symbol>] keywords that indicate an option is a
-      #  conditional.
+      # Keywords for conditional filters
+      # @return [Array<Symbol>]
       CONDITIONAL_FILTERS = %i[if unless].freeze
 
-      # @param interactor_class [Class|Symbol|String] the {.interactor_class}
-      # @param options [Hash{Symbol=>*}] the {.filters} and {.perform_options}
-      # @return [InteractorInterface|nil] a new instance of {InteractorInterface} if
-      #  the {#interactor_class} exists
+      # Initialize a new instance of {InteractorInterface}
+      #
+      # @param interactor_class [Const] an {ActiveInteractor::Base interactor} class
+      # @param options [Hash] options to use for the {ActiveInteractor::Base interactor's}
+      #  {Interactor::Perform::ClassMethods#perform .perform}. See {Interactor::Perform::Options}.
+      # @return [InteractorInterface] a new instance of {InteractorInterface}
       def initialize(interactor_class, options = {})
         @interactor_class = interactor_class.to_s.classify.safe_constantize
         @filters = options.select { |key, _value| CONDITIONAL_FILTERS.include?(key) }
         @perform_options = options.reject { |key, _value| CONDITIONAL_FILTERS.include?(key) }
       end
 
-      # Check conditional filters on an interactor and invoke it's {Interactor#perform #perform}
-      #  method if conditions are met.
-      # @param target [Class] an instance of {Organizer}
-      # @param context [Context::Base] the organizer's {Context::Base context} instance
-      # @param fail_on_error [Boolean] if `true` {Interactor::ClassMethods#perform! .perform!}
-      #  will be invoked on the interactor. If `false` {Interactor::ClassMethods#perform .perform}
-      #  will be invokded on the interactor.
-      # @param perform_options [Hash{Symbol=>*}] options for perform
-      # @return [Context::Base|nil] an instance of {Context::Base} if an interactor's
-      #   {Interactor#perform #perform} is invoked
+      # Call the {#interactor_class} {Interactor::Perform::ClassMethods#perform .perform} or
+      # {Interactor::Perform::ClassMethods#perform! .perform!} method if all conditions in {#filters} are properly met.
+      #
+      # @param target [Class] the calling {Base organizer} instance
+      # @param context [Class] an instance of {Context::Base context}
+      # @param fail_on_error [Boolean] if `true` {Interactor::Perform::ClassMethods#perform! .perform!} will be called
+      #  on the {#interactor_class} other wise {Interactor::Perform::ClassMethods#perform .perform} will be called.
+      # @param perform_options [Hash] additional {Interactor::Perform::Options} to merge with {#perform_options}
+      # @raise [Error::ContextFailure] if `fail_on_error` is `true` and the {#interactor_class}
+      #  {Context::Status#fail! fails} its {Context::Base context}.
+      # @return [Class] an instance of {Context::Base context}
       def perform(target, context, fail_on_error = false, perform_options = {})
         return if check_conditionals(target, filters[:if]) == false
         return if check_conditionals(target, filters[:unless]) == true

data/lib/active_interactor/organizer/interactor_interface_collection.rb

@@ -1,56 +1,59 @@
 # frozen_string_literal: true
 
-require 'active_interactor/organizer/interactor_interface'
-
 module ActiveInteractor
-  class Organizer < ActiveInteractor::Base
+  module Organizer
+    # A collection of {InteractorInterface}
+    #
     # @api private
-    # A collection of ordered interactors for an {Organizer}
     # @author Aaron Allen <hello@aaronmallen.me>
     # @since 1.0.0
+    #
     # @!attribute [r] collection
-    #  @return [Array<Hash{Symbol=>*}] the organized interactors and filters
+    #  An array of {InteractorInterface}
+    #
+    #  @return [Array<InteractorInterface>] the {InteractorInterface} collection
     class InteractorInterfaceCollection
       attr_reader :collection
-
-      # @!method each(&block)
-      # Calls the given block once for each element of {#collection}, passing that
-      #  element as a parameter
-      # @yield [.collection] the {#collection}
-      # @return [Array<InteractorInterface>] the {#collection}
-
       # @!method map(&block)
-      # Invokes the given block once fore each element of {#collection}.
-      # @yield [.collection] the {#collection}
-      # @return [Array] a new array containing the values returned by the block.
-      delegate :each, :map, to: :collection
+      #  Invokes the given block once for each element of {#collection}.
+      #  @return [Array] a new array containing the values returned by the block.
+      delegate :map, to: :collection
 
+      # Initialize a new instance of {InteractorInterfaceCollection}
       # @return [InteractorInterfaceCollection] a new instance of {InteractorInterfaceCollection}
       def initialize
         @collection = []
       end
 
       # Add an {InteractorInterface} to the {#collection}
-      # @param interactor [Class|Symbol|String] an interactor class name
-      # @param filters [Hash{Symbol=>*}] conditions and {Interactor::PerformOptions} for the interactor
-      # @option filters [Symbol|Proc] :if only invoke the interactor's perform method
-      #   if method or block returns `true`
-      # @option filters [Symbol|Proc] :unless only invoke the interactor's perform method
-      #   if method or block returns `false`
-      # @see Interactor::PerformOptions
-      # @return [InteractorInterface] the {InteractorInterface} instance
-      def add(interactor, filters = {})
-        interface = InteractorInterface.new(interactor, filters)
+      #
+      # @param interactor_class [Const, Symbol, String] an {ActiveInteractor::Base interactor} class
+      # @param filters [Hash{Symbol=> Proc, Symbol}] conditional options for the {ActiveInteractor::Base interactor}
+      #  class
+      # @option filters [Proc, Symbol] :if only call the {ActiveInteractor::Base interactor}
+      #  {Interactor::Perform::ClassMethods#perform .perform} if `Proc` or `method` returns `true`
+      # @option filters [Proc, Symbol] :unless only call the {ActiveInteractor::Base interactor}
+      #  {Interactor::Perform::ClassMethods#perform .perform} if `Proc` or `method` returns `false` or `nil`
+      # @return [self] the {InteractorInterfaceCollection} instance
+      def add(interactor_class, filters = {})
+        interface = ActiveInteractor::Organizer::InteractorInterface.new(interactor_class, filters)
         collection << interface if interface.interactor_class
         self
       end
 
-      # Concat multiple {InteractorInterface} to the {#collection}
-      # @param interactors [Array<Class>] the interactor classes to add
-      #  to the collection
-      # @return [InteractorInterface] the {InteractorInterface} instance
-      def concat(interactors)
-        interactors.flatten.each { |interactor| add(interactor) }
+      # Add multiple {InteractorInterface} to the {#collection}
+      #
+      # @param interactor_classes [Array<Const, Symbol, String>] the {ActiveInteractor::Base interactor} classes
+      # @return [self] the {InteractorInterfaceCollection} instance
+      def concat(interactor_classes)
+        interactor_classes.flatten.each { |interactor_class| add(interactor_class) }
+        self
+      end
+
+      # Calls the given block once for each element in {#collection}, passing that element as a parameter.
+      # @return [self] the {InteractorInterfaceCollection} instance
+      def each(&block)
+        collection.each(&block) if block
         self
       end
     end