interactor_with_steroids 0.0.1

data/lib/interactor/context.rb

@@ -0,0 +1,139 @@
+require "active_support/core_ext/module/delegation"
+
+module Interactor
+  # Public: The object for tracking state of an Interactor's invocation. The
+  # context is used to initialize the interactor with the information required
+  # for invocation. The interactor manipulates the context to produce the result
+  # of invocation.
+  #
+  # The context is the mechanism by which success and failure are determined and
+  # the context is responsible for tracking individual interactor invocations
+  # for the purpose of rollback.
+  #
+  # The context may be manipulated using arbitrary getter and setter methods.
+  #
+  # Examples
+  #
+  #   context = Interactor::Context.new
+  #   # => #<Interactor::Context>
+  #   context.foo = "bar"
+  #   # => "bar"
+  #   context
+  #   # => #<Interactor::Context foo="bar">
+  #   context.hello = "world"
+  #   # => "world"
+  #   context
+  #   # => #<Interactor::Context foo="bar" hello="world">
+  #   context.foo = "baz"
+  #   # => "baz"
+  #   context
+  #   # => #<Interactor::Context foo="baz" hello="world">
+  class Context
+    # Internal: Initialize an Interactor::Context or preserve an existing one.
+    # If the argument given is an Interactor::Context, the argument is returned.
+    # Otherwise, a new Interactor::Context is initialized from the provided
+    # hash.
+    #
+    # The "build" method is used during interactor initialization.
+    #
+    # context - A Hash whose key/value pairs are used in initializing a new
+    #           Interactor::Context object. If an existing Interactor::Context
+    #           is given, it is simply returned. (default: {})
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.build(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #   context.object_id
+    #   # => 2170969340
+    #   context = Interactor::Context.build(context)
+    #   # => #<Interactor::Context foo="bar">
+    #   context.object_id
+    #   # => 2170969340
+    #
+    # Returns the Interactor::Context.
+    def self.build(context = {})
+      new(**context.to_h)
+    end
+
+    attr_accessor :error
+    delegate :to_s, to: :to_h
+
+    def initialize(*)
+    end
+
+    # Public: Whether the Interactor::Context is successful. By default, a new
+    # context is successful and only changes when explicitly failed.
+    #
+    # The "success?" method is the inverse of the "failure?" method.
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.new
+    #   # => #<Interactor::Context>
+    #   context.success?
+    #   # => true
+    #   context.fail!
+    #   # => Interactor::Failure: #<Interactor::Context>
+    #   context.success?
+    #   # => false
+    #
+    # Returns true by default or false if failed.
+    def success?
+      !failure?
+    end
+
+    # Public: Whether the Interactor::Context has failed. By default, a new
+    # context is successful and only changes when explicitly failed.
+    #
+    # The "failure?" method is the inverse of the "success?" method.
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.new
+    #   # => #<Interactor::Context>
+    #   context.failure?
+    #   # => false
+    #   context.fail!
+    #   # => Interactor::Failure: #<Interactor::Context>
+    #   context.failure?
+    #   # => true
+    #
+    # Returns false by default or true if failed.
+    def failure?
+      @failure || false
+    end
+
+    # Public: Fail the Interactor::Context. Failing a context raises an error
+    # that may be rescued by the calling interactor. The context is also flagged
+    # as having failed.
+    #
+    # Optionally the caller may provide a hash of key/value pairs to be merged
+    # into the context before failure.
+    #
+    # context - A Hash whose key/value pairs are merged into the existing
+    #           Interactor::Context instance. (default: {})
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.new
+    #   # => #<Interactor::Context>
+    #   context.fail!
+    #   # => Interactor::Failure: #<Interactor::Context>
+    #   context.fail! rescue false
+    #   # => false
+    #   context.fail!(foo: "baz")
+    #   # => Interactor::Failure: #<Interactor::Context foo="baz">
+    #
+    # Raises Interactor::Failure initialized with the Interactor::Context.
+    def fail!(error: nil)
+      self.error = error
+      @failure = true
+      raise Failure, self
+    end
+
+    def to_h
+      { error: error }
+    end
+  end
+end

data/lib/interactor/declaration.rb

@@ -0,0 +1,85 @@
+
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/class/attribute"
+require "active_support/concern"
+
+module Interactor
+  # Internal: Methods relating to declaring what we receive and what will be stored in the context.
+  module Declaration
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :context_class, instance_writer: false, default: Context
+    end
+
+    class_methods do
+      def receive(*required_arguments, **optional_arguments)
+        @required_arguments ||= []
+        new_required_arguments = required_arguments - @required_arguments
+        @required_arguments += new_required_arguments
+
+        delegate(*new_required_arguments, to: :context) unless new_required_arguments.empty?
+        delegate(*optional_arguments.keys, to: :context) unless optional_arguments.empty?
+
+        attributes = [*new_required_arguments, *optional_arguments.keys]
+
+        self.context_class = Class.new(context_class) do
+          attr_accessor *new_required_arguments
+          attr_writer *optional_arguments.keys
+
+          optional_arguments.each do |k, v|
+            define_method(k) do
+              ivar = "@#{k}"
+              return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+              instance_variable_set(ivar, v.is_a?(Proc) ? instance_eval(&v) : v)
+            end
+          end
+
+          class_eval %Q<
+            def initialize(
+              #{new_required_arguments.map { |a| "#{a}:" }.join(', ')}#{new_required_arguments.empty? ? '' : ', '}
+              **rest
+            )
+              super(**rest)
+
+              #{new_required_arguments.map { |a| "self.#{a} = #{a}" }.join(';')}
+
+              #{
+                optional_arguments.keys.map do |k|
+                  "instance_variable_set('@#{k}', rest[:#{k}]) if rest.key?(:#{k})"
+                end.join("\n")
+              }
+            end
+          >
+
+          class_eval %Q<
+            def to_h
+              super.merge(
+                #{attributes.map { |a| "#{a}: self.#{a}"}.join(', ')}
+              )
+            end
+          >
+        end
+      end
+
+      def hold(*held_fields)
+        @held_fields ||= []
+        @held_fields += held_fields
+
+        delegate(*@held_fields, to: :context)
+
+        self.context_class = Class.new(context_class) do
+          attr_accessor *held_fields
+
+          class_eval %Q<
+            def to_h
+              super.merge(#{held_fields.map { |f| "#{f}: self.#{f}"}.join(', ')})
+            end
+          >
+        end
+
+      end
+    end
+  end
+end

data/lib/interactor/error.rb

@@ -0,0 +1,31 @@
+module Interactor
+  # Internal: Error raised during Interactor::Context failure. The error stores
+  # a copy of the failed context for debugging purposes.
+  class Failure < StandardError
+    # Internal: Gets the Interactor::Context of the Interactor::Failure
+    # instance.
+    attr_reader :context
+
+    # Internal: Initialize an Interactor::Failure.
+    #
+    # context - An Interactor::Context to be stored within the
+    #           Interactor::Failure instance. (default: nil)
+    #
+    # Examples
+    #
+    #   Interactor::Failure.new
+    #   # => #<Interactor::Failure: Interactor::Failure>
+    #
+    #   context = Interactor::Context.new(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #   Interactor::Failure.new(context)
+    #   # => #<Interactor::Failure: #<Interactor::Context foo="bar">>
+    #
+    #   raise Interactor::Failure, context
+    #   # => Interactor::Failure: #<Interactor::Context foo="bar">
+    def initialize(context = nil)
+      @context = context
+      super
+    end
+  end
+end

data/lib/interactor/hooks.rb

@@ -0,0 +1,263 @@
+require "active_support/concern"
+
+module Interactor
+  # Internal: Methods relating to supporting hooks around Interactor invocation.
+  module Hooks
+    extend ActiveSupport::Concern
+
+    # Internal: Interactor::Hooks class methods.
+    class_methods do
+      # Public: Declare hooks to run around Interactor invocation. The around
+      # method may be called multiple times; subsequent calls append declared
+      # hooks to existing around hooks.
+      #
+      # hooks - Zero or more Symbol method names representing instance methods
+      #         to be called around interactor invocation. Each instance method
+      #         invocation receives an argument representing the next link in
+      #         the around hook chain.
+      # block - An optional block to be executed as a hook. If given, the block
+      #         is executed after methods corresponding to any given Symbols.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     around :time_execution
+      #
+      #     around do |interactor|
+      #       puts "started"
+      #       interactor.call
+      #       puts "finished"
+      #     end
+      #
+      #     def call
+      #       puts "called"
+      #     end
+      #
+      #     private
+      #
+      #     def time_execution(interactor)
+      #       context.start_time = Time.now
+      #       interactor.call
+      #       context.finish_time = Time.now
+      #     end
+      #   end
+      #
+      # Returns nothing.
+      def around(*hooks, &block)
+        hooks << block if block
+        hooks.each { |hook| around_hooks.push(hook) }
+      end
+
+      # Public: Declare hooks to run before Interactor invocation. The before
+      # method may be called multiple times; subsequent calls append declared
+      # hooks to existing before hooks.
+      #
+      # hooks - Zero or more Symbol method names representing instance methods
+      #         to be called before interactor invocation.
+      # block - An optional block to be executed as a hook. If given, the block
+      #         is executed after methods corresponding to any given Symbols.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     before :set_start_time
+      #
+      #     before do
+      #       puts "started"
+      #     end
+      #
+      #     def call
+      #       puts "called"
+      #     end
+      #
+      #     private
+      #
+      #     def set_start_time
+      #       context.start_time = Time.now
+      #     end
+      #   end
+      #
+      # Returns nothing.
+      def before(*hooks, &block)
+        hooks << block if block
+        hooks.each { |hook| before_hooks.push(hook) }
+      end
+
+      # Public: Declare hooks to run after Interactor invocation. The after
+      # method may be called multiple times; subsequent calls prepend declared
+      # hooks to existing after hooks.
+      #
+      # hooks - Zero or more Symbol method names representing instance methods
+      #         to be called after interactor invocation.
+      # block - An optional block to be executed as a hook. If given, the block
+      #         is executed before methods corresponding to any given Symbols.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     after :set_finish_time
+      #
+      #     after do
+      #       puts "finished"
+      #     end
+      #
+      #     def call
+      #       puts "called"
+      #     end
+      #
+      #     private
+      #
+      #     def set_finish_time
+      #       context.finish_time = Time.now
+      #     end
+      #   end
+      #
+      # Returns nothing.
+      def after(*hooks, &block)
+        hooks << block if block
+        hooks.each { |hook| after_hooks.unshift(hook) }
+      end
+
+      # Internal: An Array of declared hooks to run around Interactor
+      # invocation. The hooks appear in the order in which they will be run.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     around :time_execution, :use_transaction
+      #   end
+      #
+      #   MyInteractor.around_hooks
+      #   # => [:time_execution, :use_transaction]
+      #
+      # Returns an Array of Symbols and Procs.
+      def around_hooks
+        @around_hooks ||= []
+      end
+
+      # Internal: An Array of declared hooks to run before Interactor
+      # invocation. The hooks appear in the order in which they will be run.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     before :set_start_time, :say_hello
+      #   end
+      #
+      #   MyInteractor.before_hooks
+      #   # => [:set_start_time, :say_hello]
+      #
+      # Returns an Array of Symbols and Procs.
+      def before_hooks
+        @before_hooks ||= []
+      end
+
+      # Internal: An Array of declared hooks to run before Interactor
+      # invocation. The hooks appear in the order in which they will be run.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     after :set_finish_time, :say_goodbye
+      #   end
+      #
+      #   MyInteractor.after_hooks
+      #   # => [:say_goodbye, :set_finish_time]
+      #
+      # Returns an Array of Symbols and Procs.
+      def after_hooks
+        @after_hooks ||= []
+      end
+    end
+
+    private
+
+    # Internal: Run around, before and after hooks around yielded execution. The
+    # required block is surrounded with hooks and executed.
+    #
+    # Examples
+    #
+    #   class MyProcessor
+    #     include Interactor::Hooks
+    #
+    #     def process_with_hooks
+    #       with_hooks do
+    #         process
+    #       end
+    #     end
+    #
+    #     def process
+    #       puts "processed!"
+    #     end
+    #   end
+    #
+    # Returns nothing.
+    def with_hooks
+      run_around_hooks do
+        run_before_hooks
+        yield
+        run_after_hooks
+      end
+    end
+
+    # Internal: Run around hooks.
+    #
+    # Returns nothing.
+    def run_around_hooks(&block)
+      self.class.around_hooks.reverse.inject(block) { |chain, hook|
+        proc { run_hook(hook, chain) }
+      }.call
+    end
+
+    # Internal: Run before hooks.
+    #
+    # Returns nothing.
+    def run_before_hooks
+      run_hooks(self.class.before_hooks)
+    end
+
+    # Internal: Run after hooks.
+    #
+    # Returns nothing.
+    def run_after_hooks
+      run_hooks(self.class.after_hooks)
+    end
+
+    # Internal: Run a colection of hooks. The "run_hooks" method is the common
+    # interface by which collections of either before or after hooks are run.
+    #
+    # hooks - An Array of Symbol and Proc hooks.
+    #
+    # Returns nothing.
+    def run_hooks(hooks)
+      hooks.each { |hook| run_hook(hook) }
+    end
+
+    # Internal: Run an individual hook. The "run_hook" method is the common
+    # interface by which an individual hook is run. If the given hook is a
+    # symbol, the method is invoked whether public or private. If the hook is a
+    # proc, the proc is evaluated in the context of the current instance.
+    #
+    # hook - A Symbol or Proc hook.
+    # args - Zero or more arguments to be passed as block arguments into the
+    #        given block or as arguments into the method described by the given
+    #        Symbol method name.
+    #
+    # Returns nothing.
+    def run_hook(hook, *args)
+      hook.is_a?(Symbol) ? send(hook, *args) : instance_exec(*args, &hook)
+    end
+  end
+end

data/lib/interactor/organizer.rb

@@ -0,0 +1,69 @@
+module Interactor
+  # Public: Interactor::Organizer methods. Because Interactor::Organizer is a
+  # module, custom Interactor::Organizer classes should include
+  # Interactor::Organizer rather than inherit from it.
+  #
+  # Examples
+  #
+  #   class MyOrganizer
+  #     include Interactor::Organizer
+  #
+  #     organizer InteractorOne, InteractorTwo
+  #   end
+  module Organizer
+    extend ActiveSupport::Concern
+    include Interactor
+
+    # Internal: Interactor::Organizer class methods.
+    class_methods do
+      # Public: Declare Interactors to be invoked as part of the
+      # Interactor::Organizer's invocation. These interactors are invoked in
+      # the order in which they are declared.
+      #
+      # interactors - Zero or more (or an Array of) Interactor classes.
+      #
+      # Examples
+      #
+      #   class MyFirstOrganizer
+      #     include Interactor::Organizer
+      #
+      #     organize InteractorOne, InteractorTwo
+      #   end
+      #
+      #   class MySecondOrganizer
+      #     include Interactor::Organizer
+      #
+      #     organize [InteractorThree, InteractorFour]
+      #   end
+      #
+      # Returns nothing.
+      def organize(*interactors)
+        @organized = interactors.flatten
+      end
+
+      # Internal: An Array of declared Interactors to be invoked.
+      #
+      # Examples
+      #
+      #   class MyOrganizer
+      #     include Interactor::Organizer
+      #
+      #     organize InteractorOne, InteractorTwo
+      #   end
+      #
+      #   MyOrganizer.organized
+      #   # => [InteractorOne, InteractorTwo]
+      #
+      # Returns an Array of Interactor classes or an empty Array.
+      def organized
+        @organized ||= []
+      end
+    end
+
+    def call
+      self.class.organized.inject(context) do |ctx, interactor|
+        interactor.call!(ctx)
+      end
+    end
+  end
+end