activeinteractor 0.1.0

data/lib/active_interactor.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+require 'active_interactor/version'
+
+# Copyright (c) 2019 Aaron Allen
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# @author Aaron Allen <hello@aaronmallen.me>
+# @since 0.0.1
+# @version 0.1
+module ActiveInteractor
+  extend ActiveSupport::Autoload
+
+  autoload :Base
+  autoload :Configuration
+  autoload :Context
+  autoload :Interactor
+
+  class << self
+    # The ActiveInteractor configuration
+    # @return [ActiveInteractor::Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configures the ActiveInteractor gem
+    #
+    # @example Configure ActiveInteractor
+    #  ActiveInteractor.configure do |config|
+    #    config.logger = Rails.logger
+    #  end
+    #
+    # @yield [ActiveInteractor#configuration]
+    def configure
+      yield(configuration)
+    end
+
+    # The ActiveInteractor logger object
+    # @return [Logger] the configured logger instance
+    def logger
+      configuration.logger
+    end
+  end
+end

data/lib/active_interactor/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveInteractor
+  # The Base Interactor class inherited by all interactors
+  #
+  # @author Aaron Allen <hello@aaronmallen.me>
+  # @since 0.0.1
+  # @version 0.1
+  class Base
+    include Interactor
+    # A new instance of {Base}
+    # @param context [Hash, nil] the properties of the context
+    # @return [ActiveInteractor::Base] a new instance of {Base}
+    def initialize(context = {})
+      @context = self.class.context_class.new(self, context)
+    end
+  end
+end

data/lib/active_interactor/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveInteractor
+  # The Configuration object for the ActiveInteractor gem
+  #
+  # @author Aaron Allen <hello@aaronmallen.me>
+  # @since 0.0.1
+  # @version 0.1
+  #
+  # @!attribute [rw] logger
+  #  @return [Logger] an instance of Logger
+  class Configuration
+    # The default configuration options for {Configuration}
+    # @return [Hash{Symbol => *}]
+    DEFAULTS = {
+      logger: Logger.new(STDOUT)
+    }.freeze
+
+    attr_accessor :logger
+
+    # A new instance of {Configuration}
+    # @param options [Hash{Symbol => *}] the options to initialize the
+    #  configuration with.
+    # @option options [Logger] :logger the logger ActiveInteractor should
+    #  use for logging
+    # @return [ActiveInteractor::Configuration] a new instance of {Configuration}
+    def initialize(options = {})
+      options = DEFAULTS.merge(options.dup || {}).slice(*DEFAULTS.keys)
+      options.each_key do |attribute|
+        instance_variable_set("@#{attribute}", options[attribute])
+      end
+    end
+  end
+end

data/lib/active_interactor/context.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/class/attribute'
+require 'ostruct'
+
+module ActiveInteractor
+  # ActiveInteractor::Context module
+  #
+  # @author Aaron Allen <hello@aaronmallen.me>
+  # @since 0.0.1
+  # @version 0.1
+  module Context
+    # Raised when an interactor context fails
+    #
+    # @author Aaron Allen <hello@aaronmallen.me>
+    # @since 0.0.1
+    # @version 0.1
+    #
+    # @!attribute [r] context
+    #  @return [Base] an instance of {Base}
+    class Failure < StandardError
+      attr_reader :context
+
+      # A new instance of {Failure}
+      # @param context [Hash] an instance of {Base}
+      # @return [Failure] a new instance of {Failure}
+      def initialize(context = {})
+        @context = context
+        super
+      end
+    end
+
+    # The base context class inherited by all {Interactor::Context} classes
+    #
+    # @author Aaron Allen <hello@aaronmallen.me>
+    # @since 0.0.1
+    # @version 0.1
+    class Base < OpenStruct
+      include ActiveModel::Validations
+
+      class_attribute :__default_attributes, instance_writer: false, default: []
+
+      # A new instance of {Base}
+      # @param interactor [ActiveInteractor::Base] an interactor instance
+      # @param attributes [Hash, nil] the attributes of the context
+      # @return [ActiveInteractor::Context::Base] a new instance of {Base}
+      def initialize(interactor, attributes = {})
+        copy_flags!(attributes)
+        @interactor = interactor
+        super(attributes)
+      end
+
+      class << self
+        # Attributes defined on the context class
+        #
+        # @example Get attributes defined on a context class
+        #  MyInteractor::Context.attributes
+        #  #=> [:first_name, :last_name]
+        #
+        # @return [Array<Symbol>] the defined attributes
+        def attributes
+          __default_attributes
+            .concat(_validate_callbacks.map(&:filter).map(&:attributes).flatten)
+            .flatten
+            .uniq
+        end
+
+        # Set attributes on a context class
+        # @param [Array<Symbol, String>] attributes
+        #
+        # @example Define attributes on a context class
+        #  MyInteractor::Context.attributes = :first_name, :last_name
+        #  #=> [:first_name, :last_name]
+        #
+        # @return [Array<Symbol>] the defined attributes
+        def attributes=(*attributes)
+          self.__default_attributes = self.attributes.concat(attributes.flatten.map(&:to_sym)).uniq
+        end
+      end
+
+      # Attributes defined on the instance
+      #
+      # @example Get attributes defined on an instance
+      #  MyInteractor::Context.attributes = :first_name, :last_name
+      #  #=> [:first_name, :last_name]
+      #
+      #  context = MyInteractor::Context.new(first_name: 'Aaron', last_name: 'Allen')
+      #  #=> <#MyInteractor::Context first_name='Aaron', last_name='Allen'>
+      #
+      #  context.attributes
+      #  #=> { first_name: 'Aaron', last_name: 'Allen' }
+      #
+      # @example Get attributes defined on an instance with unknown attribute
+      #  MyInteractor::Context.attributes = :first_name, :last_name
+      #  #=> [:first_name, :last_name]
+      #
+      #  context = MyInteractor::Context.new(first_name: 'Aaron', last_name: 'Allen', unknown: 'unknown')
+      #  #=> <#MyInteractor::Context first_name='Aaron', last_name='Allen', unknown='unknown'>
+      #
+      #  context.attributes
+      #  #=> { first_name: 'Aaron', last_name: 'Allen' }
+      #
+      #  context.unknown
+      #  #=> 'unknown'
+      #
+      # @return [Hash{Symbol => *}] the defined attributes and values
+      def attributes
+        self.class.attributes.each_with_object({}) do |attribute, hash|
+          hash[attribute] = self[attribute] if self[attribute]
+        end
+      end
+
+      # 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
+      #
+      # @return [Array<ActiveInteractor::Base>] all called interactors
+      def called!
+        _called << interactor
+      end
+
+      # Removes properties from the instance that are not
+      # explicitly defined in the context instance {#attributes}
+      #
+      # @example Clean an instance of Context with unknown attribute
+      #  MyInteractor::Context.attributes = :first_name, :last_name
+      #  #=> [:first_name, :last_name]
+      #
+      #  context = MyInteractor::Context.new(first_name: 'Aaron', last_name: 'Allen', unknown: 'unknown')
+      #  #=> <#MyInteractor::Context first_name='Aaron', last_name='Allen', unknown='unknown'>
+      #
+      #  context.unknown
+      #  #=> 'unknown'
+      #
+      #  context.clean!
+      #  #=> { unknown: 'unknown' }
+      #
+      #  context.unknown
+      #  #=> nil
+      #
+      # @return [Hash{Symbol => *}] the deleted attributes
+      def clean!
+        deleted = {}
+        return deleted if keys.empty?
+
+        keys.reject { |key| self.class.attributes.include?(key) }.each do |attribute|
+          deleted[attribute] = self[attribute] if self[attribute]
+          delete_field(key.to_s)
+        end
+        deleted
+      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
+      #  interactor = MyInteractor.new(name: 'Aaron')
+      #  #=> <#MyInteractor name='Aaron'>
+      #
+      #  interactor.context.fail!
+      #  #=> ActiveInteractor::Context::Failure: <#MyInteractor::Context name='Aaron'>
+      #
+      # @param errors [ActiveModel::Errors, Hash] errors to add to the context on failure
+      # @see https://api.rubyonrails.org/classes/ActiveModel/Errors.html ActiveModel::Errors
+      # @raise [Failure]
+      def fail!(errors = {})
+        self.errors.merge!(errors) unless errors.empty?
+        @_failed = true
+        raise Failure, 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
+      #  context = MyInteractor::Context.new
+      #  #=> <#MyInteractor::Context>
+      #
+      #  context.failure?
+      #  false
+      #
+      #  context.fail!
+      #  #=> ActiveInteractor::Context::Failure: <#MyInteractor::Context>
+      #
+      #  context.failure?
+      #  #=> true
+      #
+      # @return [Boolean] `false` by default or `true` if failed
+      def failure?
+        @_failed || false
+      end
+      alias fail? failure?
+
+      # All keys of properties currently defined on the instance
+      #
+      # @example An instance of Context with unknown attribute
+      #  MyInteractor::Context.attributes = :first_name, :last_name
+      #  #=> [:first_name, :last_name]
+      #
+      #  context = MyInteractor::Context.new(first_name: 'Aaron', last_name: 'Allen', unknown: 'unknown')
+      #  #=> <#MyInteractor::Context first_name='Aaron', last_name='Allen', unknown='unknown'>
+      #
+      #  context.keys
+      #  #=> [:first_name, :last_name, :unknown]
+      #
+      # @return [Array<Symbol>] keys defined on the instance
+      def keys
+        each_pair.map { |pair| pair[0].to_sym }
+      end
+
+      # Attempt to call the interactor for missing validation callback methods
+      # @raise [NameError] if the method is not a validation callback or method
+      #  does not exist on the interactor instance
+      def method_missing(name, *args, &block)
+        interactor.send(name, *args, &block) if validation_callback?(name)
+        super
+      end
+
+      # Attempt to call the interactor for missing validation callback methods
+      # @return [Boolean] `true` if method is a validation callback and exists
+      #  on the interactor instance
+      def respond_to_missing?(name, include_private)
+        return false unless validation_callback?(name)
+
+        interactor.respond_to?(name, include_private)
+      end
+
+      # 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::Interactor#rollback #rollback} instance methods.
+      #
+      # @example Rollback an interactor's context
+      #  context = MyInteractor.perform(name: 'Aaron')
+      #  #=> <#MyInteractor::Context name='Aaron'>
+      #
+      #  context.rollback!
+      #  #=> true
+      #
+      #  context
+      #  #=> <#MyInteractor::Context name='Aaron'>
+      #
+      # @return [Boolean] `true` if rolled back successfully or `false` if already
+      #  rolled back
+      def rollback!
+        return false if @_rolled_back
+
+        _called.reverse_each(&:execute_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 has failed
+      #  context = MyInteractor::Context.new
+      #  #=> <#MyInteractor::Context>
+      #
+      #  context.success?
+      #  true
+      #
+      #  context.fail!
+      #  #=> ActiveInteractor::Context::Failure: <#MyInteractor::Context>
+      #
+      #  context.success?
+      #  #=> false
+      #
+      # @return [Boolean] `true` by default or `false` if failed
+      def success?
+        !failure?
+      end
+      alias successful? success?
+
+      private
+
+      attr_reader :interactor
+
+      def copy_flags!(context)
+        @_called = context.send(:_called) if context.respond_to?(:_called, true)
+        @_failed = context.failure? if context.respond_to?(:failure?)
+      end
+
+      def _called
+        @_called ||= []
+      end
+
+      def validation_callback?(method_name)
+        _validate_callbacks.map(&:filter).include?(method_name)
+      end
+    end
+  end
+
+  Dir[File.expand_path('context/*.rb', __dir__)].each { |file| require file }
+end

data/lib/active_interactor/interactor.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ActiveInteractor
+  # Provides interactor methods to included classes
+  #
+  # @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
+    end
+
+    module ClassMethods
+      # Invoke an interactor. This is the primary public API method to an
+      #  interactor.
+      #
+      # @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
+      def perform(context = {})
+        new(context).execute_perform
+      end
+
+      # Invoke an Interactor. 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::Context::Failure}
+      #  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
+      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.
+    def perform; end
+
+    # Reverse prior invocation of an Interactor instance.
+    # @abstract Any interactor class that requires undoing upon downstream
+    #  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
+
+    # Skip {ActiveInteractor::Context::Base#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
+    end
+  end
+end
+
+Dir[File.expand_path('interactor/*.rb', __dir__)].each { |file| require file }