interaktor 0.1.3

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+
+task default: [:spec, :rubocop]

data/interaktor.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |spec|
+  spec.name = "interaktor"
+  spec.version = "0.1.3"
+
+  spec.author = "Taylor Thurlow"
+  spec.email = "taylorthurlow@me.com"
+  spec.description = "A common interface for building service objects."
+  spec.summary = "Simple service object implementation"
+  spec.homepage = "https://github.com/taylorthurlow/interaktor"
+  spec.license = "MIT"
+  spec.files = `git ls-files`.split
+  spec.test_files = spec.files.grep(/^spec/)
+  spec.required_ruby_version = ">= 2.5"
+  spec.require_path = "lib"
+
+  spec.add_runtime_dependency "zeitwerk", "~> 2.3.1"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+end

data/lib/interaktor.rb

@@ -0,0 +1,209 @@
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.push_dir(File.expand_path("../lib", __dir__))
+loader.setup
+
+module Interaktor
+  # When the Interaktor module is included in a class, add the relevant class
+  # methods and hooks to that class.
+  #
+  # @param base [Class] the class which is including the Interaktor module
+  def self.included(base)
+    base.class_eval do
+      extend ClassMethods
+      include Hooks
+    end
+
+    # @return [Interaktor::Context] this should not be used publicly
+    attr_accessor :context
+  end
+
+  module ClassMethods
+    # The list of attributes which are required to be passed in when calling
+    # the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def required_attributes
+      @required_attributes ||= []
+    end
+
+    # The list of attributes which are NOT required to be passed in when
+    # calling the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def optional_attributes
+      @optional_attributes ||= []
+    end
+
+    # The list of attributes which are required to be passed in when calling
+    # `#fail!` from within the interaktor.
+    #
+    # @return [Array<Symbol>]
+    def failure_attributes
+      @failure_attributes ||= []
+    end
+
+    # A DSL method for documenting required interaktor attributes.
+    #
+    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
+    #
+    # @return [void]
+    def required(*attributes)
+      required_attributes.concat attributes
+
+      attributes.each do |attribute|
+        define_method(attribute) { context.send(attribute) }
+        define_method("#{attribute}=".to_sym) do |value|
+          context.send("#{attribute}=".to_sym, value)
+        end
+      end
+    end
+
+    # A DSL method for documenting optional interaktor attributes.
+    #
+    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
+    #
+    # @return [void]
+    def optional(*attributes)
+      optional_attributes.concat attributes
+
+      attributes.each do |attribute|
+        define_method(attribute) { context.send(attribute) }
+        define_method("#{attribute}=".to_sym) do |value|
+          unless context.to_h.key?(attribute)
+            raise <<~ERROR
+                    You can't assign a value to an optional parameter if you didn't
+                    initialize the interaktor with it in the first place.
+                  ERROR
+          end
+
+          context.send("#{attribute}=".to_sym, value)
+        end
+      end
+    end
+
+    # A DSL method for documenting required interaktor failure attributes.
+    #
+    # @param attributes [Symbol, Array<Symbol>] the list of attribute names
+    #
+    # @return [void]
+    def failure(*attributes)
+      failure_attributes.concat attributes
+    end
+
+    # Invoke an Interaktor. This is the primary public API method to an
+    # interaktor.
+    #
+    # @param context [Hash, Interaktor::Context] the context object as a hash
+    # with attributes or an already-built context
+    #
+    # @return [Interaktor::Context] the context, following interaktor execution
+    def call(context = {})
+      verify_attribute_presence(context)
+
+      new(context).tap(&:run).context
+    end
+
+    # Invoke an Interaktor. This method behaves identically to `#call`, with
+    # one notable exception - if the context is failed during the invocation of
+    # the interaktor, `Interaktor::Failure` is raised.
+    #
+    # @param context [Hash, Interaktor::Context] the context object as a hash
+    # with attributes or an already-built context
+    #
+    # @raises [Interaktor::Failure]
+    #
+    # @return [Interaktor::Context] the context, following interaktor execution
+    def call!(context = {})
+      verify_attribute_presence(context)
+
+      new(context).tap(&:run!).context
+    end
+
+    private
+
+    # Check the provided context against the attributes defined with the DSL
+    # methods, and determine if there are any attributes which are required and
+    # have not been provided.
+    #
+    # @param context [Interaktor::Context] the context to check
+    #
+    # @return [void]
+    def verify_attribute_presence(context)
+      # TODO: Add "allow_nil?" option to required attributes
+      missing_attrs = required_attributes.reject { |required_attr| context.to_h.key?(required_attr) }
+
+      raise <<~ERROR if missing_attrs.any?
+        Required attribute(s) were not provided when initializing #{name} interaktor:
+          #{missing_attrs.join("\n  ")}
+      ERROR
+    end
+  end
+
+  # @param context [Hash, Interaktor::Context] the context object as a hash
+  #   with attributes or an already-built context
+  def initialize(context = {})
+    @context = Interaktor::Context.build(context)
+  end
+
+  # Fail the current interaktor.
+  #
+  # @param failure_attributes [Hash{Symbol=>Object}] the context attributes
+  #
+  # @return [void]
+  def fail!(failure_attributes = {})
+    # Make sure we have all required attributes
+    missing_attrs = self.class.failure_attributes
+                        .reject { |failure_attr| failure_attributes.key?(failure_attr) }
+    raise "Missing failure attrs: #{missing_attrs.join(", ")}" if missing_attrs.any?
+
+    context.fail!(failure_attributes)
+  end
+
+  # Invoke an Interaktor instance without any hooks, tracking, or rollback. It
+  # is expected that the `#call` instance method is overwritten for each
+  # interaktor class.
+  #
+  # @return [void]
+  def call; end
+
+  # Reverse prior invocation of an Interaktor instance. Any interaktor class
+  # that requires undoing upon downstream failure is expected to overwrite the
+  # `#rollback` instance method.
+  #
+  # @return [void]
+  def rollback; end
+
+  # Invoke an interaktor instance along with all defined hooks. The `run`
+  # method is used internally by the `call` class method. After successful
+  # invocation of the interaktor, the instance is tracked within the context.
+  # If the context is failed or any error is raised, the context is rolled
+  # back.
+  #
+  # @return [void]
+  def run
+    run!
+  rescue Interaktor::Failure # rubocop:disable Lint/SuppressedException
+  end
+
+  # Invoke an Interaktor instance along with all defined hooks, typically used
+  # internally by `.call!`. After successful invocation of the interaktor, the
+  # instance is tracked within the context. If the context is failed or any
+  # error is raised, the context is rolled back. This method behaves
+  # identically to `#run` with one notable exception - if the context is failed
+  # during the invocation of the interaktor, `Interaktor::Failure` is raised.
+  #
+  # @raises [Interaktor::Failure]
+  #
+  # @return [void]
+  def run!
+    with_hooks do
+      call
+      context.called!(self)
+    end
+  rescue StandardError
+    context.rollback!
+    raise
+  end
+end

data/lib/interaktor/context.rb

@@ -0,0 +1,91 @@
+require "ostruct"
+
+# The object for tracking state of an Interaktor's invocation. The context is
+# used to initialize the interaktor with the information required for
+# invocation. The interaktor 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 interaktor
+# invocations for the purpose of rollback. It may be manipulated using
+# arbitrary getter and setter methods.
+class Interaktor::Context < OpenStruct
+  # Initialize an Interaktor::Context or preserve an existing one. If the
+  # argument given is an Interaktor::Context, the argument is returned.
+  # Otherwise, a new Interaktor::Context is initialized from the provided hash.
+  # Used during interaktor initialization.
+  #
+  # @param context [Hash, Interaktor::Context] the context object as a hash
+  # with attributes or an already-built context
+  #
+  # @return [Interaktor::Context]
+  def self.build(context = {})
+    context.is_a?(Interaktor::Context) ? context : new(context)
+  end
+
+  # Whether the Interaktor::Context is successful. By default, a new context is
+  # successful and only changes when explicitly failed. This method is the
+  # inverse of the `#failure?` method.
+  #
+  # @return [Boolean] true by default, or false if failed
+  def success?
+    !failure?
+  end
+
+  # Whether the Interaktor::Context has failed. By default, a new context is
+  # successful and only changes when explicitly failed. This method is the
+  # inverse of the `#success?` method.
+  #
+  # @return [Boolean] false by default, or true if failed
+  def failure?
+    @failure || false
+  end
+
+  # Fail the Interaktor::Context. Failing a context raises an error that may be
+  # rescued by the calling interaktor. 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.
+  #
+  # @param context [Hash] data to be merged into the existing context
+  #
+  # @raises [Interaktor::Failure]
+  #
+  # @return [void]
+  def fail!(context = {})
+    context.each { |key, value| self[key.to_sym] = value }
+    @failure = true
+    raise Interaktor::Failure, self
+  end
+
+  # Roll back the Interaktor::Context. Any interaktors to which this context
+  # has been passed and which have been successfully called are asked to roll
+  # themselves back by invoking their `#rollback` methods.
+  #
+  # @return [Boolean] true if rolled back successfully, false if already
+  #   rolled back
+  def rollback!
+    return false if @rolled_back
+
+    _called.reverse_each(&:rollback)
+    @rolled_back = true
+  end
+
+  # Track that an Interaktor has been called. The `#called!` method is used by
+  # the interaktor being invoked with this context. After an interaktor is
+  # successfully called, the interaktor instance is tracked in the context for
+  # the purpose of potential future rollback.
+  #
+  # @param interaktor [Interaktor] an interaktor that has been successfully
+  #   called
+  #
+  # @return [void]
+  def called!(interaktor)
+    _called << interaktor
+  end
+
+  # An array of successfully called Interaktor instances invoked against this
+  # Interaktor::Context instance.
+  #
+  # @return [Array<Interaktor>]
+  def _called
+    @called ||= []
+  end
+end

data/lib/interaktor/failure.rb

@@ -0,0 +1,13 @@
+# Error raised during Interaktor::Context failure. The error stores a copy of
+# the failed context for debugging purposes.
+class Interaktor::Failure < StandardError
+  # @return [Interaktor::Context] the context of this failure instance
+  attr_reader :context
+
+  # @param context [Interaktor::Context] the context in which the error was
+  #   raised
+  def initialize(context = nil)
+    @context = context
+    super
+  end
+end

data/lib/interaktor/hooks.rb

@@ -0,0 +1,264 @@
+# Internal: Methods relating to supporting hooks around Interaktor invocation.
+module Interaktor::Hooks
+  # Internal: Install Interaktor's behavior in the given class.
+  def self.included(base)
+    base.class_eval do
+      extend ClassMethods
+    end
+  end
+
+  # Internal: Interaktor::Hooks class methods.
+  module ClassMethods
+    # Public: Declare hooks to run around Interaktor 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 interaktor 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 MyInteraktor
+    #     include Interaktor
+    #
+    #     around :time_execution
+    #
+    #     around do |interaktor|
+    #       puts "started"
+    #       interaktor.call
+    #       puts "finished"
+    #     end
+    #
+    #     def call
+    #       puts "called"
+    #     end
+    #
+    #     private
+    #
+    #     def time_execution(interaktor)
+    #       context.start_time = Time.now
+    #       interaktor.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 Interaktor 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 interaktor 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 MyInteraktor
+    #     include Interaktor
+    #
+    #     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 Interaktor 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 interaktor 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 MyInteraktor
+    #     include Interaktor
+    #
+    #     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 Interaktor
+    # invocation. The hooks appear in the order in which they will be run.
+    #
+    # Examples
+    #
+    #   class MyInteraktor
+    #     include Interaktor
+    #
+    #     around :time_execution, :use_transaction
+    #   end
+    #
+    #   MyInteraktor.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 Interaktor
+    # invocation. The hooks appear in the order in which they will be run.
+    #
+    # Examples
+    #
+    #   class MyInteraktor
+    #     include Interaktor
+    #
+    #     before :set_start_time, :say_hello
+    #   end
+    #
+    #   MyInteraktor.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 Interaktor
+    # invocation. The hooks appear in the order in which they will be run.
+    #
+    # Examples
+    #
+    #   class MyInteraktor
+    #     include Interaktor
+    #
+    #     after :set_finish_time, :say_goodbye
+    #   end
+    #
+    #   MyInteraktor.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 Interaktor::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