interactor_with_steroids 0.0.1

data/lib/interactor.rb

@@ -0,0 +1,158 @@
+require "interactor/context"
+require "interactor/declaration"
+require "interactor/error"
+require "interactor/hooks"
+require "interactor/organizer"
+
+require "active_support/concern"
+
+# Public: Interactor methods. Because Interactor is a module, custom Interactor
+# classes should include Interactor rather than inherit from it.
+#
+# Examples
+#
+#   class MyInteractor
+#     include Interactor
+#
+#     def call
+#       puts context.foo
+#     end
+#   end
+module Interactor
+  extend ActiveSupport::Concern
+  include Hooks
+  include Declaration
+
+  included do
+    # Public: Gets the Interactor::Context of the Interactor instance.
+    attr_reader :context
+  end
+
+  # Internal: Interactor class methods.
+  class_methods do
+    # Public: Invoke an Interactor. This is the primary public API method to an
+    # interactor.
+    #
+    # context - A Hash whose key/value pairs are used in initializing a new
+    #           Interactor::Context object. An existing Interactor::Context may
+    #           also be given. (default: {})
+    #
+    # Examples
+    #
+    #   MyInteractor.call(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #
+    #   MyInteractor.call
+    #   # => #<Interactor::Context>
+    #
+    # Returns the resulting Interactor::Context after manipulation by the
+    #   interactor.
+    def call(context = {})
+      new(context).tap(&:run).context
+    end
+
+    # Public: Invoke an Interactor. The "call!" method behaves identically to
+    # the "call" method with one notable exception. If the context is failed
+    # during invocation of the interactor, the Interactor::Failure is raised.
+    #
+    # context - A Hash whose key/value pairs are used in initializing a new
+    #           Interactor::Context object. An existing Interactor::Context may
+    #           also be given. (default: {})
+    #
+    # Examples
+    #
+    #   MyInteractor.call!(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #
+    #   MyInteractor.call!
+    #   # => #<Interactor::Context>
+    #
+    #   MyInteractor.call!(foo: "baz")
+    #   # => Interactor::Failure: #<Interactor::Context foo="baz">
+    #
+    # Returns the resulting Interactor::Context after manipulation by the
+    #   interactor.
+    # Raises Interactor::Failure if the context is failed.
+    def call!(context = {})
+      new(context).tap(&:run!).context
+    end
+  end
+
+  # Internal: Initialize an Interactor.
+  #
+  # context - A Hash whose key/value pairs are used in initializing the
+  #           interactor's context. An existing Interactor::Context may also be
+  #           given. (default: {})
+  #
+  # Examples
+  #
+  #   MyInteractor.new(foo: "bar")
+  #   # => #<MyInteractor @context=#<Interactor::Context foo="bar">>
+  #
+  #   MyInteractor.new
+  #   # => #<MyInteractor @context=#<Interactor::Context>>
+  def initialize(context = {})
+    @context = self.context_class.build(context)
+  end
+
+  # Internal: Invoke an interactor instance along with all defined hooks. The
+  # "run" method is used internally by the "call" class method. The following
+  # are equivalent:
+  #
+  #   MyInteractor.call(foo: "bar")
+  #   # => #<Interactor::Context foo="bar">
+  #
+  #   interactor = MyInteractor.new(foo: "bar")
+  #   interactor.run
+  #   interactor.context
+  #   # => #<Interactor::Context foo="bar">
+  #
+  # After successful invocation of the interactor, the instance is tracked
+  # within the context. If the context is failed or any error is raised, the
+  # context is rolled back.
+  #
+  # Returns nothing.
+  def run
+    run!
+  rescue Failure
+  end
+
+  # Internal: Invoke an Interactor instance along with all defined hooks. The
+  # "run!" method is used internally by the "call!" class method. The following
+  # are equivalent:
+  #
+  #   MyInteractor.call!(foo: "bar")
+  #   # => #<Interactor::Context foo="bar">
+  #
+  #   interactor = MyInteractor.new(foo: "bar")
+  #   interactor.run!
+  #   interactor.context
+  #   # => #<Interactor::Context foo="bar">
+  #
+  # After successful invocation of the interactor, the instance is tracked
+  # within the context. If the context is failed or any error is raised, the
+  # context is rolled back.
+  #
+  # The "run!" method behaves identically to the "run" method with one notable
+  # exception. If the context is failed during invocation of the interactor,
+  # the Interactor::Failure is raised.
+  #
+  # Returns nothing.
+  # Raises Interactor::Failure if the context is failed.
+  def run!
+    with_hooks do
+      call
+    end
+  rescue Failure => e
+    # Make sure we fail the current context when a call! to another interactor fails
+    context.fail!(error: e.context&.error)
+  end
+
+  # Public: Invoke an Interactor instance without any hooks, tracking, or
+  # rollback. It is expected that the "call" instance method is overwritten for
+  # each interactor class.
+  #
+  # Returns nothing.
+  def call
+  end
+end

data/spec/interactor/context_spec.rb

@@ -0,0 +1,141 @@
+module Interactor
+
+  describe Context do
+    def build_interactor(&block)
+      Class.new.send(:include, Interactor).tap do |interactor|
+        interactor.class_eval(&block) if block
+      end
+    end
+
+    let(:interactor) {
+      build_interactor do
+        receive :foo
+      end
+    }
+
+    describe ".build" do
+      it "converts the given hash to a context" do
+        context = interactor.context_class.build(foo: "bar")
+
+        expect(context).to be_a(Context)
+        expect(context.foo).to eq("bar")
+      end
+
+      it "raises if a required argument is not provided" do
+        expect { interactor.context_class.build }.to raise_error(ArgumentError)
+      end
+
+      it "doesn't affect the original hash" do
+        hash = { foo: "bar" }
+        context = interactor.context_class.build(hash)
+
+        expect(context).to be_a(interactor.context_class)
+        expect {
+          context.foo = "baz"
+        }.not_to change {
+          hash[:foo]
+        }
+      end
+    end
+
+    describe "#success?" do
+      let(:context) { Context.build }
+
+      it "is true by default" do
+        expect(context.success?).to eq(true)
+      end
+    end
+
+    describe "#failure?" do
+      let(:context) { Context.build }
+
+      it "is false by default" do
+        expect(context.failure?).to eq(false)
+      end
+    end
+
+    describe "#fail!" do
+      let(:context) { interactor.context_class.build(foo: "bar") }
+
+      it "sets success to false" do
+        expect {
+          begin
+            context.fail!
+          rescue
+            nil
+          end
+        }.to change {
+          context.success?
+        }.from(true).to(false)
+      end
+
+      it "sets failure to true" do
+        expect {
+          begin
+            context.fail!
+          rescue
+            nil
+          end
+        }.to change {
+          context.failure?
+        }.from(false).to(true)
+      end
+
+      it "preserves failure" do
+        begin
+          context.fail!
+        rescue
+          nil
+        end
+
+        expect {
+          begin
+            context.fail!
+          rescue
+            nil
+          end
+        }.not_to change {
+          context.failure?
+        }
+      end
+
+      it "preserves the context" do
+        expect {
+          begin
+            context.fail!
+          rescue
+            nil
+          end
+        }.not_to change {
+          context.foo
+        }
+      end
+
+      it "updates the context" do
+        expect {
+          begin
+            context.fail!(error: "baz")
+          rescue
+            nil
+          end
+        }.to change {
+          context.error
+        }.to("baz")
+      end
+
+      it "raises failure" do
+        expect {
+          context.fail!
+        }.to raise_error(Failure)
+      end
+
+      it "makes the context available from the failure" do
+        begin
+          context.fail!
+        rescue Failure => error
+          expect(error.context).to eq(context)
+        end
+      end
+    end
+  end
+end

data/spec/interactor/declaration_spec.rb

@@ -0,0 +1,116 @@
+module Interactor
+  describe Declaration do
+    def build_declared(&block)
+      Class.new.send(:include, Declaration).tap do |declared|
+        declared.class_eval(&block)
+
+        declared.class_eval do
+          def context
+            self
+          end
+        end
+      end
+    end
+
+    subject { declared.context_class }
+
+    describe "#receive" do
+      context "with a required argument" do
+        let(:declared) {
+          build_declared do
+            receive :foo
+          end
+        }
+
+        it "cannot be initialized without foo" do
+          expect { subject.new }.to raise_error(ArgumentError)
+        end
+
+        it "can be initialized with foo" do
+          expect(subject.new(foo: 'bar').foo).to eq('bar')
+        end
+
+        context 'when duplicated in a submodule' do
+          let(:submodule) do
+            Module.new do
+              extend ActiveSupport::Concern
+
+              included do
+                receive :foo
+              end
+            end
+          end
+
+          let(:declared) {
+            build_declared do
+              include Submodule
+
+              receive :foo
+            end
+          }
+
+          before { stub_const("Submodule", submodule) }
+
+          it "can be initialized with foo" do
+            expect(subject.new(foo: 'bar').foo).to eq('bar')
+          end
+        end
+
+      end
+
+      context "with an optional argument" do
+        context "with a constant default value" do
+          let(:declared) {
+            build_declared do
+              receive foo: 'bar'
+            end
+          }
+
+          it "can be initialized without foo" do
+            expect(subject.new.foo).to eq('bar')
+          end
+
+          it "can be initialized with foo" do
+            expect(subject.new(foo: 'baz').foo).to eq('baz')
+          end
+
+          it "can be initialized with nil" do
+            expect(subject.new(foo: nil).foo).to be nil
+          end
+        end
+
+        context "with a nil default value" do
+          let(:declared) {
+            build_declared do
+              receive foo: nil
+            end
+          }
+
+          it "can be initialized without foo" do
+            expect(subject.new.foo).to be nil
+          end
+
+          it "can be initialized with foo" do
+            expect(subject.new(foo: 'baz').foo).to eq('baz')
+          end
+        end
+
+        context "with a Proc default value" do
+          let(:declared) {
+            build_declared do
+              receive :bar, foo: ->(context) { context.bar }
+            end
+          }
+
+          it "can be initialized without foo" do
+            expect(subject.new(bar: 'bar').foo).to eq('bar')
+          end
+
+          it "can be initialized with foo" do
+            expect(subject.new(bar: 'bar', foo: 'baz').foo).to eq('baz')
+          end
+        end
+      end
+    end
+  end
+end