interaktor 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d187b41c956972596b434b05aa5e4b3f8558457953327e305c5d76165f7c195b
-  data.tar.gz: e123fbeb3e8c1db843cb41b54023ca71d077a6947f0a3a50e0ec5bd78dfd4ddb
+  metadata.gz: 6937b87e9844c597a62670ffe90e7d2abba7a7559bc42254d195973e685b109f
+  data.tar.gz: 2d6f4b42e049de1d271b42118118a1a847f7fb71f21ce03c87394549af710419
 SHA512:
-  metadata.gz: 5549218310ebd0e3d0505eac4d43302f83c9508a0bee463f3a8c0f2042de5bfd25954aec67beae050a140606b14e75ce1e7ff8f0866726e5a24a09dd8071b4e6
-  data.tar.gz: a7eabf0b930c9efd51ec3407e119234d6a1d29aa3d88494bacde287cc0e3d67ae9882707d8636ddba7289c6889f536bcdbad22eebc47a8344b659828a0718f4b
+  metadata.gz: 3c68b887ff7cd0888d165ef5468029225b20f046f339bbea9184cd072ee221d7a1bb7bf37dbfff8b24c06ffc17c11839333172000d277d17a07307d788ad2530
+  data.tar.gz: 3b6546acf884222f52472887ddd2af0439a891486aa542a7410ef787ed7b8ac2e662c728068d7f2852ee8cc3bf83610fa4c3f97410c19ac764d04a6a81457575

data/.github/workflows/tests.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: [2.5, 2.6, 2.7, 3.0, head, debug]
+        ruby: [3.0, 3.1, 3.2, 3.3, 3.4, head, debug]
     runs-on: ${{ matrix.os }}
     continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
     env:

data/.ruby-version

@@ -1 +1 @@
-3.1.3
+3.4.7

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 3.0

data/Gemfile

@@ -2,12 +2,9 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "debug"
 gem "guard-rspec", require: false
-gem "rubocop"
-gem "rubocop-performance"
-gem "rubocop-rspec"
-gem "rufo", "~> 0.12.0"
-gem "solargraph"
+gem "standardrb"
 
 group :test do
   gem "pry-byebug", platforms: [:mri]

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://img.shields.io/gem/v/interaktor.svg)](http://rubygems.org/gems/interaktor)
 [![Build Status](https://img.shields.io/travis/collectiveidea/interaktor/master.svg)](https://travis-ci.org/taylorthurlow/interaktor)
 
-**DISCLAIMER: Interaktor is under active development. Feel free to use it, but until 1.0 is released, any update could break compatibility with an older version.**
+**DISCLAIMER: Interaktor is considered to be stable, but has not yet reached version 1.0. Following semantic versioning, minor version updates can introduce breaking changes. Please review the changelog when updating.**
 
 **Interaktor** is a fork of [Interactor by collectiveidea](https://github.com/collectiveidea/interactor). While Interactor is still used by collectiveidea internally, communication and progress has been slow in adapting to pull requests and issues. This inactivity combined with my desire to dial back on the Interactor's inherent permissivity led me to fork it and create Interaktor.
 
@@ -66,7 +66,7 @@ CreateUser.call(name: "Foo Bar")
 
 Based on the outcome of the interaktor's work, we can require certain attributes. In the example below, we must succeed with a `user_id` attribute, and if we fail, we must provide an `error_messages` attribute.
 
-The use of `#success!` allows you to early-return from an interaktor's work. If no `success` attribute is provided, and the `call` method finishes execution normally, then the interaktor is considered to be in a successful state.
+The use of `#success!` allows you to early-return from an interaktor's work. If no `success` attribute is provided, and the `call` method finishes execution normally, then the interaktor is considered to to have completed successfully.
 
 ```ruby
 class CreateUser
@@ -108,7 +108,7 @@ end
 
 `#fail!` always throws an exception of type `Interaktor::Failure`.
 
-Normally, however, these exceptions are not seen. In the recommended usage, the caller invokes the interaktor using the class method `.call`, then checks the `#success?` method of the returned object. This works because the `call` class method swallows exceptions. When unit testing an interaktor, if calling custom business logic methods directly and bypassing `call`, be aware that `fail!` will generate such exceptions.
+Normally, however, these exceptions are not seen. In the recommended usage, the caller invokes the interaktor using the class method `.call`, then checks the `#success?` method of the returned object. This works because the `call` class method rescues the `Interaktor::Failure` exception. When unit testing an interaktor, if calling custom business logic methods directly and bypassing `call`, be aware that `fail!` will generate such exceptions.
 
 See _Interaktors in the controller_, below, for the recommended usage of `.call` and `#success?`.
 
@@ -144,6 +144,16 @@ after do
 end
 ```
 
+#### Ensure hooks
+
+Very similar to `after` hooks, but the hooks are run in an `ensure` block in the order they are defined.
+
+```ruby
+ensure_hook do
+  file.close
+end
+```
+
 #### Around hooks
 
 You can also define around hooks in the same way as before or after hooks, using either a block or a symbol method name. The difference is that an around block or method accepts a single argument. Invoking the `call` method on that argument will continue invocation of the interaktor. For example, with a block:
@@ -285,6 +295,10 @@ class PlaceOrder
     required(:order_params).filled(:hash)
   end
 
+  success do
+    required(:order)
+  end
+
   organize CreateOrder, ChargeCard, SendThankYou
 end
 ```
@@ -312,7 +326,14 @@ class OrdersController < ApplicationController
 end
 ```
 
-The organizer passes any of its own defined attributes into first interaktor that it organizes. That first interaktor is then called and executed using those attributes. For the following interaktors in the organize list, each interaktor receives its attributes from the previous interaktor (both input attributes and success attributes). Any attributes which are _not_ accepted by the next interaktor (listed as required or optional attributes) are dropped in the transition.
+The organizer passes its own input arguments (if present) into first interaktor that it organizes, which is called and executed using those arguments. For the following interaktors in the organize list, each interaktor receives its input arguments from the previous interaktor (both input arguments and success arguments, with success arguments taking priority in the case of a name collision).
+
+Any arguments which are _not_ accepted by the next interaktor (listed as required or optional input attributes) are dropped in the transition.
+
+If the organizer specifies any success attributes, the final interaktor in the
+organized list must also specify those success attributes. In general, it is
+recommended to avoid using success attributes on an organizer in the first
+place, to avoid coupling between the organizer and the interaktors it organizes.
 
 #### Rollback
 

data/bin/_guard-core

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application '_guard-core' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("guard", "_guard-core")

data/bin/guard

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("guard", "guard")

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/standardrb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'standardrb' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("standard", "standardrb")

data/interaktor.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name = "interaktor"
-  spec.version = "0.4.0"
+  spec.version = "0.5.0"
 
   spec.author = "Taylor Thurlow"
   spec.email = "thurlow@hey.com"
@@ -9,12 +9,11 @@ Gem::Specification.new do |spec|
   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.required_ruby_version = ">= 3.0"
   spec.require_path = "lib"
 
   spec.add_runtime_dependency "dry-schema", "~> 1.0"
-  spec.add_runtime_dependency "zeitwerk", "~> 2.0"
+  spec.add_runtime_dependency "zeitwerk", ">= 2"
 
   spec.add_development_dependency "rake", "~> 13.0"
 end

data/lib/interaktor/callable.rb

@@ -21,9 +21,10 @@ module Interaktor::Callable
     #
     # @return [Array<Symbol>]
     def required_input_attributes
-      @required_input_attributes ||= input_schema.info[:keys]
-                                                 .select { |_, info| info[:required] }
-                                                 .keys
+      @required_input_attributes ||= input_schema
+        .info[:keys]
+        .select { |_, info| info[:required] }
+        .keys
     end
 
     # The list of attributes which are not required to be passed in when
@@ -41,14 +42,14 @@ module Interaktor::Callable
       #
       # See https://github.com/dry-rb/dry-schema/issues/347
       @optional_input_attributes ||= begin
-          attributes_in_info = input_schema.info[:keys].keys
-          all_attributes = input_schema.key_map.keys.map(&:id)
-          optional_attributes_by_exclusion = all_attributes - attributes_in_info
+        attributes_in_info = input_schema.info[:keys].keys
+        all_attributes = input_schema.key_map.keys.map(&:id)
+        optional_attributes_by_exclusion = all_attributes - attributes_in_info
 
-          explicitly_optional_attributes = input_schema.info[:keys].reject { |_, info| info[:required] }.keys
+        explicitly_optional_attributes = input_schema.info[:keys].reject { |_, info| info[:required] }.keys
 
-          explicitly_optional_attributes + optional_attributes_by_exclusion
-        end
+        explicitly_optional_attributes + optional_attributes_by_exclusion
+      end
     end
 
     # The complete list of input attributes.
@@ -67,18 +68,14 @@ module Interaktor::Callable
       @input_schema || Dry::Schema.Params
     end
 
-    # @param context [Hash]
-    #
-    # @return [void]
-    def validate_input_schema(context)
-      return unless input_schema
-
-      result = input_schema.call(context)
+    # @param args [Hash]
+    def validate_input_schema(args)
+      return if !input_schema
 
-      if result.errors.any?
+      if (errors = input_schema.call(args).errors).any?
         raise Interaktor::Error::AttributeSchemaValidationError.new(
           self,
-          result.errors.to_h,
+          errors.to_h
         )
       end
     end
@@ -103,11 +100,11 @@ module Interaktor::Callable
         attribute_name = key.id
 
         # Define getter
-        define_method(attribute_name) { @context.send(attribute_name) }
+        define_method(attribute_name) { @interaction.send(attribute_name) }
 
         # Define setter
-        define_method("#{attribute_name}=".to_sym) do |value|
-          @context.send("#{attribute_name}=".to_sym, value)
+        define_method(:"#{attribute_name}=") do |value|
+          @interaction.send(:"#{attribute_name}=", value)
         end
       end
     end
@@ -141,14 +138,14 @@ module Interaktor::Callable
       #
       # See https://github.com/dry-rb/dry-schema/issues/347
       @optional_failure_attributes ||= begin
-          attributes_in_info = failure_schema.info[:keys].keys
-          all_attributes = failure_schema.key_map.keys.map(&:id)
-          optional_attributes_by_exclusion = all_attributes - attributes_in_info
+        attributes_in_info = failure_schema.info[:keys].keys
+        all_attributes = failure_schema.key_map.keys.map(&:id)
+        optional_attributes_by_exclusion = all_attributes - attributes_in_info
 
-          explicitly_optional_attributes = failure_schema.info[:keys].reject { |_, info| info[:required] }.keys
+        explicitly_optional_attributes = failure_schema.info[:keys].reject { |_, info| info[:required] }.keys
 
-          explicitly_optional_attributes + optional_attributes_by_exclusion
-        end
+        explicitly_optional_attributes + optional_attributes_by_exclusion
+      end
     end
 
     # The complete list of failure attributes.
@@ -167,18 +164,16 @@ module Interaktor::Callable
       @failure_schema || Dry::Schema.Params
     end
 
-    # @param context [Hash]
+    # @param args [Hash]
     #
     # @return [void]
-    def validate_failure_schema(context)
-      return unless failure_schema
-
-      result = failure_schema.call(context)
+    def validate_failure_schema(args)
+      return if !failure_schema
 
-      if result.errors.any?
+      if (errors = failure_schema.call(args).errors).any?
         raise Interaktor::Error::AttributeSchemaValidationError.new(
           self,
-          result.errors.to_h,
+          errors.to_h
         )
       end
     end
@@ -209,8 +204,8 @@ module Interaktor::Callable
     # @return [Array<Symbol>]
     def required_success_attributes
       @required_success_attributes ||= success_schema.info[:keys]
-                                                     .select { |_, info| info[:required] }
-                                                     .keys
+        .select { |_, info| info[:required] }
+        .keys
     end
 
     # The list of attributes which are not required to be provided when failing
@@ -228,14 +223,14 @@ module Interaktor::Callable
       #
       # See https://github.com/dry-rb/dry-schema/issues/347
       @optional_success_attributes ||= begin
-          attributes_in_info = success_schema.info[:keys].keys
-          all_attributes = success_schema.key_map.keys.map(&:id)
-          optional_attributes_by_exclusion = all_attributes - attributes_in_info
+        attributes_in_info = success_schema.info[:keys].keys
+        all_attributes = success_schema.key_map.keys.map(&:id)
+        optional_attributes_by_exclusion = all_attributes - attributes_in_info
 
-          explicitly_optional_attributes = success_schema.info[:keys].reject { |_, info| info[:required] }.keys
+        explicitly_optional_attributes = success_schema.info[:keys].reject { |_, info| info[:required] }.keys
 
-          explicitly_optional_attributes + optional_attributes_by_exclusion
-        end
+        explicitly_optional_attributes + optional_attributes_by_exclusion
+      end
     end
 
     # The complete list of success attributes.
@@ -254,18 +249,14 @@ module Interaktor::Callable
       @success_schema || Dry::Schema.Params
     end
 
-    # @param context [Hash]
-    #
-    # @return [void]
-    def validate_success_schema(context)
-      return unless success_schema
-
-      result = success_schema.call(context)
+    # @param args [Hash]
+    def validate_success_schema(args)
+      return if !success_schema
 
-      if result.errors.any?
+      if (errors = success_schema.call(args).errors).any?
         raise Interaktor::Error::AttributeSchemaValidationError.new(
           self,
-          result.errors.to_h,
+          errors.to_h
         )
       end
     end
@@ -289,25 +280,23 @@ module Interaktor::Callable
     # Invoke an Interaktor. This is the primary public API method to an
     # interaktor. Interaktor failures will not raise an exception.
     #
-    # @param context [Hash, Interaktor::Context] the context object as a hash
-    #   with attributes or an already-built context
+    # @param args [Hash, Interaktor::Interaction]
     #
-    # @return [Interaktor::Context] the context, following interaktor execution
-    def call(context = {})
-      execute(context, false)
+    # @return [Interaktor::Interaction]
+    def call(args = {})
+      execute(args, raise_exception: false)
     end
 
     # Invoke an Interaktor. This method behaves identically to `#call`, but if
-    # the interaktor is failed, `Interaktor::Failure` is raised.
+    # the interaktor fails, `Interaktor::Failure` is raised.
     #
-    # @param context [Hash, Interaktor::Context] the context object as a hash
-    #   with attributes or an already-built context
+    # @param args [Hash, Interaktor::Interaction]
     #
     # @raises [Interaktor::Failure]
     #
-    # @return [Interaktor::Context] the context, following interaktor execution
-    def call!(context = {})
-      execute(context, true)
+    # @return [Interaktor::Interaction]
+    def call!(args = {})
+      execute(args, raise_exception: true)
     end
 
     private
@@ -315,31 +304,29 @@ module Interaktor::Callable
     # The main execution method triggered by the public `#call` or `#call!`
     # methods.
     #
-    # @param context [Hash, Interaktor::Context] the context object as a hash
-    #   with attributes or an already-built context
+    # @param args [Hash, Interaktor::Interaction]
     # @param raise_exception [Boolean] whether or not to raise exception on
     #   failure
     #
     # @raises [Interaktor::Failure]
     #
-    # @return [Interaktor::Context] the context, following interaktor execution
-    def execute(context, raise_exception)
+    # @return [Interaktor::Interaction]
+    def execute(args, raise_exception:)
       run_method = raise_exception ? :run! : :run
 
-      case context
+      case args
       when Hash
-        # Silently remove any attributes that are not included in the schema
-        allowed_keys = input_schema.key_map.keys.map { |k| k.name.to_sym }
-        context.select! { |k, _| allowed_keys.include?(k.to_sym) }
-
-        validate_input_schema(context)
+        if (disallowed_key = args.keys.find { |k| !input_attributes.include?(k.to_sym) })
+          raise Interaktor::Error::UnknownAttributeError.new(self, disallowed_key)
+        end
 
-        new(context).tap(&run_method).instance_variable_get(:@context)
-      when Interaktor::Context
-        new(context).tap(&run_method).instance_variable_get(:@context)
+        validate_input_schema(args)
+        new(args).tap(&run_method).instance_variable_get(:@interaction)
+      when Interaktor::Interaction
+        new(args).tap(&run_method).instance_variable_get(:@interaction)
       else
         raise ArgumentError,
-              "Expected a hash argument when calling the interaktor, got a #{context.class} instead."
+          "Expected a hash argument when calling the interaktor, got a #{args.class} instead."
       end
     end
   end

data/lib/interaktor/error/invalid_method_for_state_error.rb

@@ -0,0 +1,10 @@
+class Interaktor::Error::InvalidMethodForStateError < Interaktor::Error::Base
+  attr_reader :message
+
+  # @param interaktor [Class]
+  # @param method [Symbol]
+  def initialize(interaktor, message)
+    super(interaktor)
+    @message = message
+  end
+end

data/lib/interaktor/error/organizer_missing_passed_attribute_error.rb

@@ -11,7 +11,7 @@ class Interaktor::Error::OrganizerMissingPassedAttributeError < Interaktor::Erro
   end
 
   def message
-    <<~MESSAGE.strip.tr("\n", "")
+    <<~MESSAGE.strip.tr("\n", " ")
       An organized #{interaktor} interaktor requires a '#{attribute}' input
       attribute, but none of the interaktors that come before it in the
       organizer list it as a success attribute, and the organizer does not list

data/lib/interaktor/error/organizer_success_attribute_missing_error.rb

@@ -11,7 +11,7 @@ class Interaktor::Error::OrganizerSuccessAttributeMissingError < Interaktor::Err
   end
 
   def message
-    <<~MESSAGE.strip.tr("\n", "")
+    <<~MESSAGE.strip.tr("\n", " ")
       A #{interaktor} organizer requires a '#{attribute}' success attribute,
       but none of the success attributes provided by any of the organized
       interaktors list it.

data/lib/interaktor/error/unknown_attribute_error.rb

@@ -0,0 +1,16 @@
+class Interaktor::Error::UnknownAttributeError < Interaktor::Error::AttributeError
+  # @return [Symbol]
+  attr_reader :attribute
+
+  # @param interaktor [Class]
+  # @param attribute [Symbol]
+  def initialize(interaktor, attribute)
+    super(interaktor, [attribute])
+
+    @attribute = attribute
+  end
+
+  def message
+    "Unknown attribute '#{attribute}'"
+  end
+end

data/lib/interaktor/failure.rb

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

data/lib/interaktor/hooks.rb

@@ -126,6 +126,38 @@ module Interaktor::Hooks
       hooks.each { |hook| after_hooks.unshift(hook) }
     end
 
+    # Public: Declare hooks to run after Interaktor invocation in an ensure block.
+    # The after method may be called multiple times; subsequent calls append
+    # declared hooks to existing ensure_hook 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
+    #
+    #     ensure_hook :close_file
+    #
+    #     ensure_hook do
+    #       puts "finished"
+    #     end
+    #
+    #     def call
+    #       puts "called"
+    #     end
+    #
+    #     private
+    #
+    #     def close_file
+    #       context.file.close
+    #     end
+    #   end
+    #
+    # Returns nothing.
     def ensure_hook(*hooks, &block)
       hooks << block if block
       hooks.each { |hook| ensure_hooks.push(hook) }
@@ -188,6 +220,22 @@ module Interaktor::Hooks
       @after_hooks ||= []
     end
 
+    # Internal: An Array of declared hooks to run afer Interaktor
+    # invocation in an ensure block. The hooks appear in the order
+    # in which they will be run.
+    #
+    # Examples
+    #
+    #   class MyInteraktor
+    #     include Interaktor
+    #
+    #     ensure_hook :set_finish_time, :say_goodbye
+    #   end
+    #
+    #   MyInteraktor.ensure_hooks
+    #   # => [:say_goodbye, :set_finish_time]
+    #
+    # Returns an Array of Symbols and Procs.
     def ensure_hooks
       @ensure_hooks ||= []
     end
@@ -195,8 +243,8 @@ module Interaktor::Hooks
 
   private
 
-  # Internal: Run around, before and after hooks around yielded execution. The
-  # required block is surrounded with hooks and executed.
+  # Internal: Run around, before, after and ensure hooks around yielded execution.
+  # The required block is surrounded with hooks and executed.
   #
   # Examples
   #
@@ -248,7 +296,9 @@ module Interaktor::Hooks
     run_hooks(self.class.after_hooks)
   end
 
-
+  # Internal: Run ensure hooks.
+  #
+  # Returns nothing.
   def run_ensure_hooks
     run_hooks(self.class.ensure_hooks)
   end