activeinteractor 1.0.0.beta.7 → 1.0.0

data/lib/active_interactor/context/loader.rb

@@ -1,31 +1,36 @@
 # frozen_string_literal: true
 
-require 'active_support/core_ext/string/inflections'
-
 module ActiveInteractor
   module Context
+    # Find or create {Base context} classes for a given {ActiveInteractor::Base interactor}
+    #
     # @api private
-    # Load, find or create {Context::Base} classes for a given interactor.
-    # @author Aaron Allen <hello@aaronmallen.me>
+    # @author Aaron Allen <hello@aaronmallen>
     # @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
+      # ActiveInteractor base classes
+      # @return [Array<Const>]
+      BASE_CLASSES = [ActiveInteractor::Base, ActiveInteractor::Organizer::Base].freeze
+      # The {ActiveInteractor::Context::Base} class
+      # @return [Const]
       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
+      # Create a {Base context} class for a given {ActiveInteractor::Base interactor}
+      #
+      # @param context_class_name [Symbol, String] the class name of the
+      #   {Base context} class to create
+      # @param interactor_class [Const] an {ActiveInteractor::Base interactor} class
+      # @return [Const] a class that inherits from {Base}
       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
+      # Find or create a {Base context} class for a given {ActiveInteractor::Base interactor}. If a class exists
+      # following the pattern of `InteractorNameContext` or `InteractorName::Context` then that class will be returned
+      # otherwise a new class will be created with the pattern `InteractorName::Context`.
+      #
+      # @param interactor_class [Const] an {ActiveInteractor::Base interactor} class
+      # @return [Const] a class that inherits from {Base}
       def self.find_or_create(interactor_class)
         return BASE_CONTEXT if BASE_CLASSES.include?(interactor_class)
 

data/lib/active_interactor/context/status.rb

@@ -2,24 +2,26 @@
 
 module ActiveInteractor
   module Context
-    # Context status methods included by all {Context::Base}
+    # Context status methods. Because {Status} is a module classes should include {Status} rather than inherit from it.
+    #
     # @author Aaron Allen <hello@aaronmallen.me>
     # @since 1.0.0
     module Status
-      # @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
+      # Add an instance of {ActiveInteractor::Base interactor} to the list of {ActiveInteractor::Base interactors}
+      # called on the {Base context}. This list is used when {#rollback!} is called on a {Base context} instance.
+      #
+      # @since 0.1.0
+      #
+      # @param interactor [Class] an {ActiveInteractor::Base interactor} instance
+      # @return [Array<Class>] the list of called {ActiveInteractor::Base 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
+      # Fail the {Base context} instance. Failing an instance raises an error that may be rescued by the calling
+      # {ActiveInteractor::Base interactor}. The instance is also flagged as having failed.
+      #
+      # @since 0.1.0
       #
       # @example Fail an interactor context
       #   class MyInteractor < ActiveInteractor::Base
@@ -29,60 +31,42 @@ module ActiveInteractor
       #   end
       #
       #   MyInteractor.perform!
-      #   #=> ActiveInteractor::Error::ContextFailure: <#MyInteractor::Context>
-      # @param errors [ActiveModel::Errors|nil] errors to add to the context on failure
+      #   ActiveInteractor::Error::ContextFailure "<#MyInteractor::Context>"
+      #
+      # @param errors [ActiveModel::Errors, String] error messages for the 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
+        raise ActiveInteractor::Error::ContextFailure, self
       end
 
-      # Whether the context instance has failed. By default, a new
-      # context is successful and only changes when explicitly failed
+      # Whether the {Base context} instance has {#fail! failed}. By default, a new instance is successful and only
+      # changes when explicitly {#fail! failed}.
+      #
+      # @since 0.1.0
       # @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
       #
+      # @example Check if a context has failed
       #   result = MyInteractor.perform
-      #   #=> <#MyInteractor::Context>
-      #
       #   result.failure?
       #   #=> false
-      # @return [Boolean] `false` by default or `true` if failed
+      #
+      # @return [Boolean] `false` by default or `true` if {#fail! 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
+      # {#rollback! Rollback} an instance of {Base context}. Any {ActiveInteractor::Base interactors} the instance has
+      # been passed via the {#called!} method are asked to roll themselves back by invoking their
+      # {Interactor::Perform#rollback #rollback} methods. The instance is also flagged as rolled back.
       #
-      #     def rollback
-      #       context.user&.destroy
-      #     end
-      #   end
+      # @since 0.1.0
       #
-      #   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
+      # @return [Boolean] `true` if {#rollback! rolled back} successfully or `false` if already
+      #  {#rollback! rolled back}
       def rollback!
         return false if @_rolled_back
 
@@ -90,20 +74,18 @@ module ActiveInteractor
         @_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
+      # Whether the {Base context} instance is successful. By default, a new instance is successful and only changes
+      # when explicitly {#fail! failed}.
       #
-      #   result = MyInteractor.perform
-      #   #=> <#MyInteractor::Context>
+      # @since 0.1.0
+      # @note The {#success?} method is the inverse of the {#failure?} method
       #
+      # @example Check if a context has failed
+      #   result = MyInteractor.perform
       #   result.success?
       #   #=> true
-      # @return [Boolean] `true` by default or `false` if failed
+      #
+      # @return [Boolean] `true` by default or `false` if {#fail! failed}
       def success?
         !failure?
       end

data/lib/active_interactor/error.rb

@@ -2,17 +2,23 @@
 
 module ActiveInteractor
   # ActiveInteractor errors
+  #
   # @author Aaron Allen <hello@aaronmallen.me>
   # @since 0.1.5
   module Error
-    # Raised when an interactor context fails.
+    # Raised when an {Base interactor} {Context::Base context} {Context::Status#fail! fails}.
+    #
     # @!attribute [r] context
+    #  An instance of {Context::Base context} used for debugging.
+    #
     #  @return [Context::Base] an instance of {Context::Base}
     class ContextFailure < StandardError
       attr_reader :context
 
-      # @param context [Context::Base] the failed context instance.
-      # @return [ContextFailure] a new instance of {ContextFailure}.
+      # Initialize a new instance of {ContextFailure}
+      #
+      # @param context [Class, nil] an instance of {Context::Base context}
+      # @return [ContextFailure] a new instance of {ContextFailure}
       def initialize(context = nil)
         @context = context
         context_class_name = context&.class&.name || 'Context'
@@ -20,15 +26,17 @@ module ActiveInteractor
       end
     end
 
-    # Raised when an invalid context class is assigned to an interactor.
+    # Raised when an invalid {Context::Base context} class is assigned to an {Base interactor}.
+    #
     # @since 1.0.0
+    #
     # @!attribute [r] class_name
-    #  @return [String|nil] the class name of the context
+    #  The class name of the {Context::Base context} used for debugging.
+    #
+    #  @return [String|nil] the class name of the {Context::Base 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}")

data/lib/active_interactor/interactor/callbacks.rb

@@ -1,245 +1,250 @@
 # 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
-    # Interactor callback methods included by all {Base}
+    # Interactor callback methods. Because {Callbacks} is a module classes should include {Callbacks} rather than
+    # inherit from it.
+    #
     # @author Aaron Allen <hello@aaronmallen.me>
-    # @since 0.0.1
+    # @since 0.1.0
+    # @see https://github.com/aaronmallen/activeinteractor/wiki/Callbacks Callbacks
+    # @see https://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html ActiveSupport::Callbacks
     module Callbacks
-      def self.included(base)
-        base.class_eval do
-          extend ClassMethods
-          include ActiveSupport::Callbacks
-
-          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}
+      # Interactor callback class methods. Because {ClassMethods} is a module classes should extend {ClassMethods}
+      # rather than inherit from it.
+      #
+      # @author Aaron Allen
+      # @since 0.1.0
       module ClassMethods
-        # 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 :downcase_name
+        # Define a callback to call after validation has been run on an {Base interactor} instance's
+        # {ActiveInteractor::Context::Base context} instance.
         #
-        #    private
+        # @example
+        #   class MyInteractor < ActiveInteractor::Base
+        #     after_context_validation :ensure_name_is_aaron
+        #     context_validates :name, presence: true
         #
-        #    def downcase_name
-        #      context.name.downcase!
-        #    end
-        #  end
+        #     private
         #
-        #  result = MyInteractor.perform(name: 'Aaron')
-        #  #=> <MyInteractor::Context name='aaron'>
+        #     def ensure_name_is_aaron
+        #       context.name = 'Aaron'
+        #     end
+        #   end
         #
-        #  result.valid?
-        #  #=> true
+        #   result = MyInteractor.perform(name: 'Bob')
+        #   result.name
+        #   #=> 'Aaron'
         #
-        #  result.name
-        #  #=> 'aaron'
+        #   result = MyInteractor.perform({ name: 'Bob' }, { validate: false })
+        #   result.name
+        #   #=> 'Bob'
         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 {Interactor#perform #perform} has been invoked
+        # Define a callback to call after {Interactor::Perform#perform #perform} has been called on an
+        # {Base interactor} instance.
+        #
         # @example
-        #  class MyInteractor < ActiveInteractor::Base
-        #    after_perform :print_done
+        #   class MyInteractor < ActiveInteractor::Base
+        #     after_perform :print_done
         #
-        #    def perform
-        #      puts 'Performing'
-        #    end
+        #     def perform
+        #       puts 'Performing'
+        #     end
         #
-        #    private
+        #     private
         #
-        #    def print_done
-        #      puts 'Done'
-        #    end
-        #  end
+        #     def print_done
+        #       puts 'Done'
+        #     end
+        #   end
         #
-        #  MyInteractor.perform(name: 'Aaron')
-        #  "Performing"
-        #  "Done"
-        #  #=> <MyInteractor::Context name='Aaron'>
+        #   MyInteractor.perform
+        #   "Performing"
+        #   "Done"
+        #   #=> <#MyInteractor::Context>
         def after_perform(*filters, &block)
           set_callback(:perform, :after, *filters, &block)
         end
 
-        # Define a callback to call after {Interactor#rollback #rollback} has been invoked
-        # @example
-        #  class MyInteractor < ActiveInteractor::Base
-        #    after_rollback :print_done
+        # Define a callback to call after {Interactor::Perform#rollback #rollback} has been called on an
+        # {Base interactor} instance.
         #
-        #    def perform
-        #      context.fail!
-        #    end
+        # @example
+        #   class MyInteractor < ActiveInteractor::Base
+        #     after_rollback :print_done
         #
-        #    def rollback
-        #      puts 'Rolling back'
-        #    end
+        #     def perform
+        #       context.fail!
+        #     end
         #
-        #    private
+        #     def rollback
+        #       puts 'Rolling Back'
+        #     end
         #
-        #    def print_done
-        #      puts 'Done'
-        #    end
-        #  end
+        #     private
         #
-        #  context = MyInteractor.perform(name: 'Aaron')
-        #  #=> <MyInteractor::Context name='Aaron'>
+        #     def print_done
+        #       puts 'Done'
+        #     end
+        #   end
         #
-        #  context.rollback!
-        #  "Rolling back"
-        #  "Done"
+        #   MyInteractor.perform
+        #   "Rolling Back"
+        #   "Done"
+        #   #=> <MyInteractor::Context>
         def after_rollback(*filters, &block)
           set_callback(:rollback, :after, *filters, &block)
         end
 
-        # Define a callback to call around {Interactor#perform #perform} invokation
-        # @example
-        #  class MyInteractor < ActiveInteractor::Base
-        #    around_perform :track_time
+        # Define a callback to call around {Interactor::Perform#perform #perform} invokation on an {Base interactor}
+        # instance.
         #
-        #    def perform
-        #      sleep(1)
-        #    end
+        # @example
+        #   class MyInteractor < ActiveInteractor::Base
+        #     around_perform :track_time
         #
-        #    private
+        #     def perform
+        #       sleep(1)
+        #     end
         #
-        #    def track_time
-        #      context.start_time = Time.now.utc
-        #      yield
-        #      context.end_time = Time.now.utc
-        #    end
-        #  end
+        #     private
         #
-        #  result = MyInteractor.perform(name: 'Aaron')
-        #  #=> <MyInteractor::Context name='Aaron'>
+        #     def track_time
+        #       context.start_time = Time.now.utc
+        #       yield
+        #       context.end_time = Time.now.utc
+        #     end
+        #   end
         #
-        #  result.start_time
-        #  #=> 2019-01-01 00:00:00 UTC
+        #   result = MyInteractor.perform
+        #   result.start_time
+        #   #=> 2019-01-01 00:00:00 UTC
         #
-        #  result.end_time
-        #  #=> 2019-01-01 00:00:01 UTC
+        #   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 {Interactor#rollback #rollback} invokation
-        # @example
-        #  class MyInteractor < ActiveInteractor::Base
-        #    around_rollback :track_time
+        # Define a callback to call around {Interactor::Perform#rollback #rollback} invokation on an {Base interactor}
+        # instance.
         #
-        #    def rollback
-        #      sleep(1)
-        #    end
+        # @example
+        #   class MyInteractor < ActiveInteractor::Base
+        #     around_rollback :track_time
         #
-        #    private
+        #     def perform
+        #       context.fail!
+        #     end
         #
-        #    def track_time
-        #      context.start_time = Time.now.utc
-        #      yield
-        #      context.end_time = Time.now.utc
-        #    end
-        #  end
+        #     def rollback
+        #       sleep(1)
+        #     end
         #
-        #  result = MyInteractor.perform(name: 'Aaron')
-        #  #=> <MyInteractor::Context name='Aaron'>
+        #     private
         #
-        #  result.rollback!
-        #  #=> true
+        #     def track_time
+        #       context.start_time = Time.now.utc
+        #       yield
+        #       context.end_time = Time.now.utc
+        #     end
+        #   end
         #
-        #  result.start_time
-        #  #=> 2019-01-01 00:00:00 UTC
+        #   result = MyInteractor.perform
+        #   result.start_time
+        #   #=> 2019-01-01 00:00:00 UTC
         #
-        #  result.end_time
-        #  #=> 2019-01-01 00:00:01 UTC
+        #   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 {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 :downcase_name
+        # Define a callback to call before validation has been run on an {Base interactor} instance's
+        # {ActiveInteractor::Context::Base context} instance.
+        #
+        # @example
+        #   class MyInteractor < ActiveInteractor::Base
+        #     before_context_validation :ensure_name_is_aaron
+        #     context_validates :name, inclusion: { in: %w[Aaron] }
         #
-        #    private
+        #     private
         #
-        #    def downcase_name
-        #      context.name.downcase!
-        #    end
-        #  end
+        #     def ensure_name_is_aaron
+        #       context.name = 'Aaron'
+        #     end
+        #   end
         #
-        #  result = MyInteractor.perform(name: 'Aaron')
-        #  #=> <MyInteractor::Context name='aaron'>
+        #   result = MyInteractor.perform(name: 'Bob')
+        #   result.successful?
+        #   #=> true
         #
-        #  result.valid?
-        #  #=> true
+        #   result.name
+        #   #=> 'Aaron'
         #
-        #  result.name
-        #  #=> 'aaron'
+        #   result = MyInteractor.perform({ name: 'Bob' }, { validate: false })
+        #   result.name
+        #   #=> 'Bob'
         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 {Interactor#perform #perform} has been invoked
+        # Define a callback to call before {Interactor::Perform#perform #perform} has been called on an
+        # {Base interactor} instance
+        #
         # @example
-        #  class MyInteractor < ActiveInteractor::Base
-        #    before_perform :print_start
+        #   class MyInteractor < ActiveInteractor::Base
+        #     before_perform :print_starting
         #
-        #    def perform
-        #      puts 'Performing'
-        #    end
+        #     def perform
+        #       puts 'Performing'
+        #     end
         #
-        #    private
+        #     private
         #
-        #    def print_start
-        #      puts 'Start'
-        #    end
-        #  end
+        #     def print_starting
+        #       puts 'Starting'
+        #     end
+        #   end
         #
-        #  MyInteractor.perform(name: 'Aaron')
-        #  "Start"
-        #  "Performing"
-        #  #=> <MyInteractor::Context name='Aaron'>
+        #   MyInteractor.perform
+        #   "Starting"
+        #   "Performing"
+        #   #=> <#MyInteractor::Context>
         def before_perform(*filters, &block)
           set_callback(:perform, :before, *filters, &block)
         end
 
-        # Define a callback to call before {Interactor#rollback #rollback} has been invoked
+        # Define a callback to call before {Interactor::Perform#rollback #rollback} has been called on an
+        # {Base interactor} instance.
+        #
         # @example
-        #  class MyInteractor < ActiveInteractor::Base
-        #    before_rollback :print_start
+        #   class MyInteractor < ActiveInteractor::Base
+        #     before_rollback :print_starting
         #
-        #    def rollback
-        #      puts 'Rolling Back'
-        #    end
+        #     def perform
+        #       context.fail!
+        #     end
         #
-        #    private
+        #     def rollback
+        #       puts 'Rolling Back'
+        #     end
         #
-        #    def print_start
-        #      puts 'Start'
-        #    end
-        #  end
+        #     private
         #
-        #  context = MyInteractor.perform(name: 'Aaron')
-        #  #=> <MyInteractor::Context name='Aaron'>
+        #     def print_starting
+        #       puts 'Starting'
+        #     end
+        #   end
         #
-        #  context.rollback!
-        #  "Start"
-        #  "Rolling Back"
-        #  #=> true
+        #   MyInteractor.perform
+        #   "Starting"
+        #   "Rolling Back"
+        #   #=> <#MyInteractor::Context>
         def before_rollback(*filters, &block)
           set_callback(:rollback, :before, *filters, &block)
         end
@@ -256,6 +261,15 @@ module ActiveInteractor
           options
         end
       end
+
+      def self.included(base)
+        base.class_eval do
+          define_callbacks :validation,
+                           skip_after_callbacks_if_terminated: true,
+                           scope: %i[kind name]
+          define_callbacks :perform, :rollback
+        end
+      end
     end
   end
 end