interactor_support 1.0.6 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf8cda13999c9971a1499398e23135ef6e870af7581ffe7e9f173b9d7c4231ea
-  data.tar.gz: 48c401b5b42e80ccea3db170ecb1e8476861522804b800ad28651eebfa674222
+  metadata.gz: 2a9492a85b640343b10a985ca038fb2a2bbcd98a5532ae61f0b98abdb41106e9
+  data.tar.gz: 29bfa393df505cb275b0deea347b39c012e3e3af2f6f01610f99c1b639c3e0f1
 SHA512:
-  metadata.gz: 2adf5f317e6432571a24358e9e1ba453397fcfd5f6b83758930fd45bef652dfb01ead87aa68fcfec385151bd60646127a087968e332baa0193e5bb9f7ac14ff6
-  data.tar.gz: a6a670cacb4abd50812a82232dcbeb1e582eea72d3526b2659f4dccd827226c6e07c6b12f6c39b282eb276db482d02911cd4d0e125094f8c1d114fba5459c899
+  metadata.gz: 14d5ce85f9e66aaaeb0df8f23fe1de9cb21b3dabfe9a8c4bd7b4a072a9a8ec4400d05ae4402b09a73a0304e20c33cfd00a50c3188c874d1f8b3399c39729089a
+  data.tar.gz: 32159eb9b275c2c4aac8125d00e608836670b8775faf8daab3caa3e78abf8b63d17bdaa7eb6018c8882fb7ab41ea02a4389c72f856ba16f69e5c342a2158239c

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [1.0.7] - 2025-09-24
+
+- Add `handle_interactor_failure` DSL and per-call overrides for centralized interactor failure handling
+- Raise an internal failure signal so handled responses automatically halt controller actions (with opt-out via `halt_on_handle: false`)
+- Provide `InteractorSupport.configuration.default_interactor_error_handler` for global handler registration
+- Expose richer failure payloads (context, error, request object, params) to handlers
+
+## [1.0.6] - 2025-09-24
+
+- Wrap request object validation failures from `Organizable#organize` in `InteractorSupport::Errors::InvalidRequestObject` for consistent controller handling
+- Honor `configuration.log_unknown_request_object_attributes` when logging ignored request object keys
+- Improve request object error messaging for failed casts and unknown attributes
+
 ## [1.0.0] - 2025-03-20
 
 - Initial release
@@ -29,9 +42,3 @@
 - Introduce `InteractorSupport.configuration.logger` and `log_level` for customizable logging
 - Override `assign_attributes` to integrate attribute ignoring and error-raising behavior
 - Improve test coverage for unknown attribute handling and logging
-
-## [1.0.6] - 2025-09-24
-
-- Wrap request object validation failures from `Organizable#organize` in `InteractorSupport::Errors::InvalidRequestObject` for consistent controller handling
-- Honor `configuration.log_unknown_request_object_attributes` when logging ignored request object keys
-- Improve request object error messaging for failed casts and unknown attributes

data/README.md

@@ -575,6 +575,8 @@ Calls the given interactor with a request object built from the provided params.
 | params         | Hash          | Parameters passed to the request object.                                    |
 | request_object | Class         | A request object class that accepts params in its initializer.              |
 | context_key    | Symbol or nil | Optional key to namespace the request object inside the interactor context. |
+| error_handler  | Symbol, Proc, Array, `false`, `nil` | Override the failure handlers for this call. Use `false` to skip handlers or include `:defaults` to inject registered ones. |
+| halt_on_handle | Boolean | Whether to halt the caller when a handler marks the failure handled (defaults to `true`). |
 
 Examples
 
@@ -588,18 +590,43 @@ organize(MyInteractor, params: request_params, request_object: MyRequest, contex
 # => MyInteractor.call({ request: MyRequest.new(params) })
 ```
 
-Validation failures inside the request object raise `InteractorSupport::Errors::InvalidRequestObject`. The exception exposes the request class and its validation messages, making it straightforward to surface errors back to the caller.
+If you opt out of failure handlers, validation errors still bubble as `InteractorSupport::Errors::InvalidRequestObject`. Registering a handler with `handle_interactor_failure` lets you centralise the response instead:
 
 ```rb
-def create
-  organize(CreateUserInteractor, params: request_params(:user), request_object: CreateUserRequest)
-  redirect_to dashboard_path
-rescue InteractorSupport::Errors::InvalidRequestObject => e
-  flash.now[:alert] = "Unable to continue: #{e.errors.to_sentence}"
-  render :new, status: :unprocessable_entity
+class UsersController < ApplicationController
+  include InteractorSupport::Concerns::Organizable
+
+  handle_interactor_failure :render_failure
+
+  def create
+    organize(CreateUserInteractor,
+             params: request_params(:user),
+             request_object: CreateUserRequest)
+
+    render json: @context.user, status: :created
+  end
+
+  private
+
+  def render_failure(failure)
+    flash.now[:alert] = failure.errors.to_sentence
+    render :new, status: :unprocessable_entity
+    failure.handled!
+  end
 end
 ```
 
+When the handler calls `failure.handled!` (or returns truthy), the concern raises an internal signal that is swallowed by Rails’ `rescue_from`, halting the action before the success response runs. Pass `halt_on_handle: false` to `organize` for cases where you still want the action to continue.
+
+You can override handlers per call with the `error_handler:` option. Symbols/Procs are accepted, and the special token `:defaults` injects any class-level or globally configured handlers.
+
+##### Failure handler options
+
+- `handle_interactor_failure :method, only: [:create], except: [:destroy]` — scope handlers to particular actions.
+- `organize(..., error_handler: false)` — skip all registered handlers for a single call.
+- `organize(..., error_handler: [:audit_failure, :defaults])` — prepend custom handlers while still running the defaults.
+- `organize(..., halt_on_handle: false)` — allow logic after `organize` to run even if a handler reported the failure handled.
+
 #### #request_params(\*top_level_keys, merge: {}, except: [], rewrite: [])
 
 Returns a shaped parameter hash derived from params.permit!. You can extract specific top-level keys, rename them, flatten values, apply defaults, and remove unwanted fields.
@@ -704,6 +731,7 @@ All global settings for InteractorSupport can be set via the `InteractorSupport.
 | `log_unknown_request_object_attributes` | `Boolean` | `true` | Whether to log unknown request attributes that are ignored. |
 | `request_object_behavior` | `Symbol` | `:returns_context` | Controls what `RequestObject.new(...)` returns (`:returns_self` or `:returns_context`). |
 | `request_object_key_type` | `Symbol` | `:symbol` | Controls the output format of keys in `#to_context` (`:symbol`, `:string`, `:struct`).  |
+| `default_interactor_error_handler` | `Symbol`, `Proc`, `Array` | `nil` | Global failure handler(s) invoked when `handle_interactor_failure` is not used or when `:defaults` is requested. |
 <!-- prettier-ignore-end -->
 
 To update these settings, use:
@@ -715,6 +743,7 @@ InteractorSupport.configure do |config|
   config.log_unknown_request_object_attributes = true
   config.request_object_behavior = :returns_self
   config.request_object_key_type = :struct
+  config.default_interactor_error_handler = :render_global_failure
 end
 ```
 

data/Rakefile

@@ -1,10 +1,10 @@
 # filepath: ./Rakefile
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rails"
-require "rspec/core/rake_task"
-require "rubocop/rake_task"
+require 'bundler/gem_tasks'
+require 'rails'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 require 'active_record'
 require 'rake'
 require 'yaml'
@@ -12,7 +12,7 @@ require 'yaml'
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: [:spec, :rubocop]
 
 # Load the Rails environment
 ENV['RAILS_ENV'] ||= 'test'
@@ -25,27 +25,27 @@ ActiveRecord::Tasks::DatabaseTasks.migrations_paths = [File.expand_path('spec/mi
 
 # Load the ActiveRecord tasks manually
 namespace :db do
-  desc "Migrate the database"
+  desc 'Migrate the database'
   task :migrate do
     ActiveRecord::Migrator.migrations_paths = ActiveRecord::Tasks::DatabaseTasks.migrations_paths
     ActiveRecord::MigrationContext.new(ActiveRecord::Migrator.migrations_paths).migrate
   end
 
-  desc "Create the database"
+  desc 'Create the database'
   task :create do
     ActiveRecord::Tasks::DatabaseTasks.create_current
   end
 
-  desc "Drop the database"
+  desc 'Drop the database'
   task :drop do
     ActiveRecord::Tasks::DatabaseTasks.drop_current
   end
 
-  desc "Reset the database"
-  task :reset => [:drop, :create, :migrate]
+  desc 'Reset the database'
+  task reset: [:drop, :create, :migrate]
 end
 
 # Load the Rake tasks
 Rake::Task.define_task(:environment) do
   ActiveRecord::Base.establish_connection(:test)
-end
+end

data/lib/interactor_support/actions.rb

@@ -1,11 +1,9 @@
 # lib/interactor_support/version.rb
 module InteractorSupport
   ##
-  # A bundle of DSL-style concerns that enhance interactors with expressive,
-  # composable behavior.
+  # Bundles the most common InteractorSupport concerns into a single include.
   #
-  # This module is intended to be included into an `Interactor` or `Organizer`,
-  # providing access to a suite of declarative action helpers:
+  # Mix this into an `Interactor` or `Interactor::Organizer` to gain access to:
   #
   # - {InteractorSupport::Concerns::Skippable} — Conditionally skip execution
   # - {InteractorSupport::Concerns::Transactionable} — Wrap logic in an ActiveRecord transaction

data/lib/interactor_support/concerns/findable.rb

@@ -1,12 +1,12 @@
 module InteractorSupport
   module Concerns
     ##
-    # Adds dynamic model-finding helpers (`find_by`, `find_where`) to an interactor.
+    # DSL helpers for loading records into context before an interactor runs.
     #
-    # This concern wraps ActiveRecord `.find_by` and `.where` queries into
-    # declarative DSL methods that load records into the interactor context.
+    # - `find_by` loads a single record via `.find_by`, using context values or lambdas for conditions.
+    # - `find_where` loads collections via `.where`, `.where.not`, and optional scopes.
     #
-    # These methods support symbols (for context keys) and lambdas (for dynamic runtime evaluation).
+    # Use `required: true` to fail the context automatically when nothing is found.
     #
     # @example Find a post by ID from the context
     #   find_by :post
@@ -27,10 +27,10 @@ module InteractorSupport
 
       included do
         class << self
-          # Adds a `before` callback to find a single record and assign it to context.
+          # Adds a `before` callback to find a single record and assign it to the context.
           #
-          # This method searches for a record based on the provided query parameters.
-          # It supports dynamic values using symbols (context keys) and lambdas (for runtime evaluation).
+          # Symbols pull values from the context, lambdas run via `instance_exec`, and literal values are
+          # passed directly to `find_by`. When `query` is omitted, the DSL defaults to `<model>_id`.
           #
           # @param model [Symbol, String] the name of the model to query (e.g., `:post`)
           # @param query [Hash{Symbol=>Object,Proc}] a hash of attributes to match (can use symbols for context lookup or lambdas)
@@ -69,10 +69,10 @@ module InteractorSupport
             end
           end
 
-          # Adds a `before` callback to find multiple records and assign them to context.
+          # Adds a `before` callback to find multiple records (or relations) and assign them to context.
           #
-          # This method performs a `.where` query with optional `.where.not` and `.scope`,
-          # allowing dynamic values using symbols (for context lookup) and lambdas (for runtime evaluation).
+          # Supports `.where`, `.where.not`, and optional scopes. Symbols pull from context, lambdas run via
+          # `instance_exec`, enabling flexible query composition.
           #
           # @param model [Symbol, String] the name of the model to query (e.g., `:post`)
           # @param where [Hash{Symbol=>Object,Proc}] conditions for `.where` (can use symbols or lambdas)

data/lib/interactor_support/concerns/organizable.rb

@@ -3,71 +3,220 @@
 module InteractorSupport
   module Concerns
     ##
-    # The `Organizable` module provides utility methods for organizing interactors
-    # and shaping request parameters in a structured way.
+    # Utilities for invoking interactors with request objects and shaping incoming params.
     #
-    # It is intended to be included into a controller or a base service class that
-    # delegates to interactors using request objects.
+    # Include this concern in controllers or service entry points to:
+    # - Allowlist and transform request parameters in a single place
+    # - Build request objects and pass them to interactors with one call
+    # - Receive consistent `InvalidRequestObject` errors when validation fails
+    # - Register reusable failure handlers with {#handle_interactor_failure}
     #
     # @example Include in a controller
     #   class ApplicationController < ActionController::Base
     #     include InteractorSupport::Organizable
     #   end
     #
-    # @see InteractorSupport::Organizable#organize
-    # @see InteractorSupport::Organizable#request_params
+    # @see InteractorSupport::Concerns::Organizable#organize
+    # @see InteractorSupport::Concerns::Organizable#request_params
+    # @see InteractorSupport::Concerns::Organizable.handle_interactor_failure
     module Organizable
       include ActiveSupport::Concern
 
-      # Calls the given interactor with a request object.
-      # Optionally wraps the request object under a key in the interactor context.
+      FailureHandledSignal = Class.new(StandardError) do
+        attr_reader :failure
+
+        def initialize(failure)
+          @failure = failure
+          super('Interactor failure handled')
+        end
+      end
+
+      FailurePayload = Struct.new(
+        :context,
+        :error,
+        :interactor,
+        :request_object,
+        :params,
+        :controller,
+        keyword_init: true,
+      ) do
+        def handled!
+          @handled = true
+        end
+
+        def handled?
+          !!@handled
+        end
+
+        def errors
+          if error.respond_to?(:errors) && error.errors.present?
+            error.errors
+          elsif context.respond_to?(:errors) && context.errors.present?
+            context.errors
+          elsif error.respond_to?(:message)
+            Array(error.message).compact
+          else
+            []
+          end
+        end
+
+        def status
+          if error.respond_to?(:status)
+            error.status
+          elsif context.respond_to?(:status)
+            context.status
+          end
+        end
+
+        def to_h
+          {
+            context: context,
+            error: error,
+            interactor: interactor,
+            request_object: request_object,
+            params: params,
+            handled: handled?,
+          }
+        end
+      end
+
+      ErrorHandlerDefinition = Struct.new(:callable, :only, :except, keyword_init: true) do
+        def applicable?(action_name)
+          action = action_name&.to_sym
+          return false if only.any? && action && !only.include?(action)
+          return false if except.any? && action && except.include?(action)
+
+          true
+        end
+      end
+
+      def self.included(base)
+        super
+
+        base.extend(ClassMethods)
+
+        if base.respond_to?(:rescue_from)
+          base.rescue_from(FailureHandledSignal) do |_signal|
+            # Handled responses are already rendered by the registered handler.
+          end
+        end
+      end
+
+      module ClassMethods
+        ##
+        # Registers a failure handler that runs when an interactor fails.
+        #
+        # Handlers execute in declaration order. Use `only:` and `except:` to scope execution
+        # to specific actions (mirroring Rails filters). A handler may be a method name,
+        # Proc, or any callable responding to `#call`.
+        #
+        # Returning a truthy value or calling `failure.handled!` marks the failure as handled.
+        #
+        # @param handler [Symbol, Proc, #call] the handler to invoke
+        # @param only [Array<Symbol>, Symbol, nil] optional list of actions to run on
+        # @param except [Array<Symbol>, Symbol, nil] optional list of actions to skip
+        # @return [void]
+        def handle_interactor_failure(handler, only: nil, except: nil)
+          definition = ErrorHandlerDefinition.new(
+            callable: handler,
+            only: Array(only).compact.map(&:to_sym),
+            except: Array(except).compact.map(&:to_sym),
+          )
+
+          definitions = interactor_failure_handler_definitions + [definition]
+          @_interactor_failure_handler_definitions = definitions.freeze
+        end
+
+        def interactor_failure_handler_definitions
+          @_interactor_failure_handler_definitions ||= []
+        end
+
+        def reset_interactor_failure_handlers!
+          @_interactor_failure_handler_definitions = [].freeze
+        end
+      end
+
+      # Calls the given interactor with a request object derived from `params`.
+      #
+      # - If `context_key` is provided, the request is namespaced under that key when invoking `call`.
+      # - Validation failures raise {InteractorSupport::Errors::InvalidRequestObject}, allowing the caller
+      #   to rescue and render validation messages without inspecting ActiveModel internals.
       #
-      # @param interactor [Class] The interactor class to call.
-      # @param params [Hash] Parameters to initialize the request object.
-      # @param request_object [Class] A request object class that responds to `#new(params)`.
+      # @param interactor [Class] The interactor class or organizer to call.
+      # @param params [Hash] Raw parameters to initialize the request object.
+      # @param request_object [Class] A request object class that responds to `.new`.
       # @param context_key [Symbol, nil] Optional key to assign the request object under in the context.
+      # @param error_handler [Symbol, Proc, Array<Symbol,Proc>, false, nil] Override the registered failure handlers.
+      #   Use `false` to skip handlers, or include `:defaults` inside the array to inject class/config handlers.
+      # @param halt_on_handle [Boolean] When true (default), a handled failure halts the caller via an internal signal.
       #
-      # @return [void]
+      # @return [Interactor::Context]
       #
-      # @example
-      #  organize(MyInteractor, params: request_params, request_object: MyRequest)
-      #  # => Calls MyInteractor with an instance of MyRequest initialized with request_params.
+      # @example Basic call
+      #   organize(Users::Create, params: request_params(:user), request_object: CreateUserRequest)
       #
-      # @example
-      #   organize(MyInteractor, params: request_params, request_object: MyRequest, context_key: :request)
-      #   # => Calls MyInteractor with an instance of MyRequest initialized with request_params at :context_key.
-      #   #   # => The context will contain { request: MyRequest.new(request_params) }
-      def organize(interactor, params:, request_object:, context_key: nil)
-        request_payload = request_object.new(params)
+      # @example Namespace the request in context
+      #   organize(Users::Create,
+      #            params: request_params(:user),
+      #            request_object: CreateUserRequest,
+      #            context_key: :request)
+      def organize(interactor, params:, request_object:, context_key: nil, error_handler: nil, halt_on_handle: true)
+        @_interactor_failure_handled = false
+        @context = nil
 
-        @context = interactor.call(
-          context_key ? { context_key => request_payload } : request_payload,
-        )
-      rescue ActiveModel::ValidationError => e
-        errors =
-          if e.model&.respond_to?(:errors)
-            e.model.errors.full_messages
-          else
-            []
-          end
+        handlers = resolve_error_handlers(error_handler)
 
-        raise InteractorSupport::Errors::InvalidRequestObject.new(
-          request_class: request_object,
-          errors: errors,
+        request_payload = build_request_payload(
+          interactor: interactor,
+          request_object: request_object,
+          params: params,
+          handlers: handlers,
+          halt_on_handle: halt_on_handle,
         )
+
+        return @context if interactor_failure_handled?
+
+        payload = context_key ? { context_key => request_payload } : request_payload
+
+        @context = invoke_interactor(interactor, payload, handlers, request_object, params, halt_on_handle)
+
+        if failure_context?(@context)
+          failure = dispatch_interactor_failure_handlers(
+            handlers: handlers,
+            context: @context,
+            error: extract_context_error(@context),
+            interactor: interactor,
+            request_object: request_object,
+            params: params,
+          )
+
+          emit_failure_signal_if_needed(failure, halt_on_handle)
+        end
+
+        @context
+      end
+
+      ##
+      # Indicates whether the most recent `organize` call routed a failure through a handler.
+      # Useful when you pass `halt_on_handle: false` and want to branch manually.
+      #
+      # @return [Boolean]
+      def interactor_failure_handled?
+        !!@_interactor_failure_handled
       end
 
-      # Builds a structured and optionally transformed parameter hash from Rails' `params`.
+      # Builds a structured parameter hash from Rails' `params`, with helpers for rewriting keys.
       #
-      # This method supports extracting specific top-level keys, applying optional rewrite
-      # transformations, merging in additional values, and excluding unwanted keys.
+      # Use this as the single entry point for shaping incoming parameters before they are given to
+      # request objects. It combines extraction, filtering, renaming, flattening, defaults, and merges
+      # in a single call.
       #
       # @param top_level_keys [Array<Symbol>] Top-level keys to extract from `params`. If empty, all keys are included.
       # @param merge [Hash] Additional values to merge into the final result.
       # @param except [Array<Symbol, Array<Symbol>>] Keys or nested key paths to exclude from the result.
       # @param rewrite [Array<Hash>] A set of transformation rules applied to the top-level keys.
       #
-      # @return [Hash] The final, shaped parameters hash.
+      # @return [Hash] The shaped parameters hash ready for request object initialization.
       #
       # @example Extracting a specific top-level key
       #   # Given: params = { order: { product_id: 1, quantity: 2 } }
@@ -203,6 +352,180 @@ module InteractorSupport
 
         duped
       end
+
+      def build_request_payload(interactor:, request_object:, params:, handlers:, halt_on_handle:)
+        request_object.new(params)
+      rescue ActiveModel::ValidationError => e
+        invalid_error = InteractorSupport::Errors::InvalidRequestObject.new(
+          request_class: request_object,
+          errors: extract_active_model_errors(e),
+        )
+
+        failure = dispatch_interactor_failure_handlers(
+          handlers: handlers,
+          context: nil,
+          error: invalid_error,
+          interactor: interactor,
+          request_object: request_object,
+          params: params,
+        )
+
+        emit_failure_signal_if_needed(failure, halt_on_handle)
+
+        raise invalid_error unless failure.handled?
+
+        @context
+      rescue FailureHandledSignal
+        raise
+      rescue StandardError => e
+        failure = dispatch_interactor_failure_handlers(
+          handlers: handlers,
+          context: nil,
+          error: e,
+          interactor: interactor,
+          request_object: request_object,
+          params: params,
+        )
+
+        emit_failure_signal_if_needed(failure, halt_on_handle)
+
+        raise e unless failure.handled?
+
+        @context
+      end
+
+      def invoke_interactor(interactor, payload, handlers, request_object, params, halt_on_handle)
+        context = interactor.call(payload)
+        @context = context
+        context
+      rescue FailureHandledSignal
+        raise
+      rescue StandardError => e
+        failure = dispatch_interactor_failure_handlers(
+          handlers: handlers,
+          context: nil,
+          error: e,
+          interactor: interactor,
+          request_object: request_object,
+          params: params,
+        )
+
+        emit_failure_signal_if_needed(failure, halt_on_handle)
+
+        raise e unless failure.handled?
+
+        @context
+      end
+
+      def extract_active_model_errors(exception)
+        if exception.model&.respond_to?(:errors)
+          exception.model.errors.full_messages
+        else
+          []
+        end
+      end
+
+      def extract_context_error(context)
+        if context.respond_to?(:error)
+          context.error
+        elsif context.respond_to?(:errors) && context.errors.respond_to?(:full_messages)
+          context.errors
+        end
+      end
+
+      def failure_context?(context)
+        context.respond_to?(:failure?) && context.failure?
+      end
+
+      def dispatch_interactor_failure_handlers(handlers:, context:, error:, interactor:, request_object:, params:)
+        failure = FailurePayload.new(
+          context: context,
+          error: error,
+          interactor: interactor,
+          request_object: request_object,
+          params: params,
+          controller: self,
+        )
+
+        return failure if handlers.empty?
+
+        action_scope = current_interactor_action
+
+        handlers.each do |definition|
+          next unless definition.applicable?(action_scope)
+
+          invoke_handler(definition.callable, failure)
+        end
+
+        failure
+      end
+
+      def invoke_handler(handler, failure)
+        result =
+          case handler
+          when Proc
+            handler.arity.zero? ? instance_exec(&handler) : instance_exec(failure, &handler)
+          when Symbol, String
+            callable_method = method(handler)
+            callable_method.arity.zero? ? callable_method.call : callable_method.call(failure)
+          else
+            if handler.respond_to?(:call)
+              call_arity = handler.respond_to?(:arity) ? handler.arity : nil
+              call_arity&.zero? ? handler.call : handler.call(failure)
+            else
+              raise ArgumentError, "Interactor failure handler #{handler.inspect} is not callable"
+            end
+          end
+
+        failure.handled! if result && !failure.handled?
+
+        failure.handled?
+      end
+
+      def emit_failure_signal_if_needed(failure, halt_on_handle)
+        return unless failure.handled?
+
+        @_interactor_failure_handled = true
+
+        return unless halt_on_handle
+
+        if respond_to?(:rescue_with_handler)
+          raise FailureHandledSignal.new(failure)
+        end
+      end
+
+      def resolve_error_handlers(custom)
+        case custom
+        when false
+          []
+        when nil
+          class_handler_definitions + configuration_handler_definitions
+        else
+          Array(custom).flat_map do |item|
+            if item == :defaults || item == :default
+              class_handler_definitions + configuration_handler_definitions
+            else
+              ErrorHandlerDefinition.new(callable: item, only: [], except: [])
+            end
+          end
+        end
+      end
+
+      def class_handler_definitions
+        Array(self.class.interactor_failure_handler_definitions).dup
+      end
+
+      def configuration_handler_definitions
+        Array(InteractorSupport.configuration.default_interactor_error_handler).compact.map do |handler|
+          ErrorHandlerDefinition.new(callable: handler, only: [], except: [])
+        end
+      end
+
+      def current_interactor_action
+        return action_name.to_sym if respond_to?(:action_name) && action_name
+
+        nil
+      end
     end
   end
 end

data/lib/interactor_support/concerns/skippable.rb

@@ -3,14 +3,13 @@
 module InteractorSupport
   module Concerns
     ##
-    # Adds a DSL method to conditionally skip an interactor.
+    # Adds a declarative `skip` helper for short-circuiting interactor execution.
     #
-    # This concern provides a `skip` method that wraps the interactor in an `around` block.
-    # You can pass an `:if` or `:unless` condition using a Proc, Symbol, or literal.
-    # The condition will be evaluated at runtime to determine whether to run the interactor.
+    # Conditions run inside an `around` callback, accepting symbols, booleans, or lambdas executed via
+    # `instance_exec`. Use this to prevent unnecessary work when preconditions fail.
     #
-    # - Symbols will be looked up on the interactor or in the context.
-    # - Lambdas/Procs are evaluated using `instance_exec` with full access to context.
+    # - Symbols first look for an interactor instance method, then fall back to context values.
+    # - Lambdas have full access to the interactor instance and context.
     #
     # @example Skip if the user is already authenticated (symbol in context)
     #   skip if: :user_authenticated
@@ -31,10 +30,7 @@ module InteractorSupport
           ##
           # Skips the interactor based on a condition provided via `:if` or `:unless`.
           #
-          # This wraps the interactor in an `around` hook, and conditionally skips
-          # execution based on truthy/falsy evaluation of the provided options.
-          #
-          # The condition can be a Proc (evaluated in context), a Symbol (used to call a method or context key), or a literal value.
+          # A truthy `:if` or falsy `:unless` prevents `call` from running; otherwise execution continues.
           #
           # @param options [Hash]
           # @option options [Proc, Symbol, Boolean] :if a condition that must be truthy to skip

data/lib/interactor_support/concerns/transactionable.rb

@@ -1,13 +1,11 @@
 module InteractorSupport
   module Concerns
     ##
-    # Adds transactional support to your interactor using ActiveRecord.
+    # Adds a declarative `transaction` wrapper around interactor execution using ActiveRecord.
     #
-    # The `transaction` method wraps the interactor execution in an `around` block
-    # that uses `ActiveRecord::Base.transaction`. If the context fails (via `context.fail!`),
-    # the transaction is rolled back automatically using `ActiveRecord::Rollback`.
-    #
-    # This is useful for ensuring your interactor behaves atomically.
+    # Enabling the wrapper ensures that:
+    # - The interactor runs inside `ActiveRecord::Base.transaction` with configurable options.
+    # - `context.fail!` triggers an `ActiveRecord::Rollback` so partial work is undone.
     #
     # @example Basic usage
     #   class CreateUser
@@ -31,12 +29,12 @@ module InteractorSupport
         class << self
           # Wraps the interactor in a database transaction.
           #
-          # If the context fails (`context.failure?`), a rollback is triggered automatically.
-          # You can customize the transaction behavior using standard ActiveRecord options.
+          # If the context fails (`context.failure?`), a rollback is triggered automatically. Supports
+          # the same keyword options as `ActiveRecord::Base.transaction`.
           #
-          # @param isolation [Symbol, nil] the transaction isolation level (e.g., `:read_committed`, `:serializable`)
+          # @param isolation [Symbol, nil] optional transaction isolation level (e.g., `:read_committed`)
           # @param joinable [Boolean] whether this transaction can join an existing one
-          # @param requires_new [Boolean] whether to force a new transaction, even if one already exists
+          # @param requires_new [Boolean] whether to force a new transaction even if one already exists
           #
           # @example Wrap in a basic transaction
           #   transaction

data/lib/interactor_support/concerns/transformable.rb

@@ -1,10 +1,10 @@
 module InteractorSupport
   module Concerns
     ##
-    # Adds helpers for assigning and transforming values in interactor context.
+    # Adds helpers for preparing context data before the interactor `call` executes.
     #
-    # The `context_variable` method sets static or dynamic values before the interactor runs.
-    # The `transform` method allows chaining transformations (methods or lambdas) on context values.
+    # - `context_variable` seeds the context with static values or lazily evaluated lambdas.
+    # - `transform` normalizes existing context values using symbols, lambdas, or chains of both.
     #
     # @example Assign context variables before the interactor runs
     #   context_variable user: -> { User.find(user_id) }, numbers: [1, 2, 3]
@@ -27,10 +27,10 @@ module InteractorSupport
         class << self
           # Assigns one or more values to the context before the interactor runs.
           #
-          # Values can be static or lazily evaluated with a lambda/proc using `instance_exec`,
-          # which provides access to the context and interactor instance.
+          # Values can be static or lazily evaluated with a proc using `instance_exec`, which has
+          # access to the interactor instance and context.
           #
-          # @param key_values [Hash{Symbol => Object, Proc}] a mapping of context keys to values or Procs
+          # @param key_values [Hash{Symbol => Object, Proc}] mapping of context keys to values or Procs
           #
           # @example Static and dynamic values
           #   context_variable first_post: Post.first
@@ -48,15 +48,17 @@ module InteractorSupport
             end
           end
 
-          # Transforms one or more context values using a method, a proc, or a sequence of methods.
+          # Transforms one or more context values using symbols, procs, or chains of both.
           #
-          # This allows simple transformations like `:strip` or `:downcase`, or more complex lambdas.
-          # You can also chain transformations by passing an array of method names.
+          # - Symbols call the method on the current value (e.g., `:strip`).
+          # - Procs run via `instance_exec`, so they can reach other context values.
+          # - Arrays allow combining multiple operations in order.
           #
-          # If a transformation fails, the context fails with an error message.
+          # Any transformation failure uses `context.fail!` with a helpful error message so the
+          # interactor halts gracefully.
           #
           # @param keys [Array<Symbol>] one or more context keys to transform
-          # @param with [Symbol, Array<Symbol>, Proc] a single method name, an array of method names, or a proc
+          # @param with [Symbol, Array<Symbol, Proc>, Proc] method name(s) or a proc used to transform values
           #
           # @raise [ArgumentError] if no keys are given, or if an invalid `with:` value is passed
           #

data/lib/interactor_support/concerns/updatable.rb

@@ -1,13 +1,16 @@
 module InteractorSupport
   module Concerns
     ##
-    # Adds an `update` DSL method for updating a context-loaded model with attributes.
+    # Adds an `update` DSL for synchronizing context data back into ActiveRecord models.
     #
-    # This concern allows flexible updates using data from the interactor's context.
-    # It supports direct mapping from context keys, nested attribute extraction from parent objects,
-    # lambdas for dynamic evaluation, or passing a symbol pointing to an entire context object.
+    # The DSL supports:
+    # - Direct mappings from context keys to model attributes
+    # - Plucking nested values from other context objects (hashes or structs)
+    # - Lambdas for dynamic evaluation, executed in the interactor context
+    # - Passing a symbol that points to a hash of attributes in the context (mass assignment)
     #
-    # This is useful for updating records cleanly and consistently in declarative steps.
+    # Each update runs before `#call` and uses `record.update!`, so failures raise immediately unless
+    # rescued by the interactor.
     #
     # @example Update a user using context values
     #   update :user, attributes: { name: :new_name, email: :new_email }
@@ -27,15 +30,18 @@ module InteractorSupport
         class << self
           # Updates a model using values from the context before the interactor runs.
           #
-          # Supports flexible ways of specifying attributes:
-          # - A hash mapping attribute names to context keys, nested keys, or lambdas
-          # - A symbol pointing to a hash in context
+          # - When `attributes` is a Hash, keys are written to the record. Values can be:
+          #   * Symbols (looked up on the context)
+          #   * Arrays (pluck multiple keys from another context object)
+          #   * Hashes (extract values from a parent context object)
+          #   * Procs (executed with `instance_exec` for custom logic)
+          # - When `attributes` is a Symbol, the corresponding context hash is used directly.
           #
-          # If the record or required data is missing, the context fails with an error.
+          # Missing data triggers `context.fail!` with a helpful message so the update halts cleanly.
           #
-          # @param model [Symbol] the key in the context holding the record to update
-          # @param attributes [Hash, Symbol] a hash mapping attributes to context keys/lambdas, or a symbol pointing to a context hash
-          # @param context_key [Symbol, nil] key to assign the updated record to in context (defaults to `model`)
+          # @param model [Symbol] context key for the record to update
+          # @param attributes [Hash, Symbol] mapping of target attributes or context hash to copy from
+          # @param context_key [Symbol, nil] context key to store the updated record (defaults to `model`)
           #
           # @example Basic attribute update using context keys
           #   update :user, attributes: { name: :new_name, email: :new_email }

data/lib/interactor_support/configuration.rb

@@ -1,8 +1,8 @@
 module InteractorSupport
   ##
-  # Global configuration for InteractorSupport.
+  # Global configuration entry point for InteractorSupport.
   #
-  # This allows customization of how request objects behave when used in interactors.
+  # Use this to tailor request object behavior, logging, and context conversion.
   #
   # @example Set custom behavior
   #   InteractorSupport.configuration.request_object_behavior = :returns_self
@@ -45,6 +45,11 @@ module InteractorSupport
     # @see InteractorSupport::RequestObject#ignore_unknown_attributes
     attr_accessor :log_unknown_request_object_attributes
 
+    ##
+    # Default interactor failure handler(s) applied when none are specified.
+    # Accepts a symbol, callable, or array of either.
+    attr_accessor :default_interactor_error_handler
+
     ##
     # Initializes the configuration with default values:
     # - `request_object_behavior` defaults to `:returns_context`
@@ -58,6 +63,7 @@ module InteractorSupport
       @logger = Logger.new($stdout)
       @log_level = Logger::INFO
       @log_unknown_request_object_attributes = true
+      @default_interactor_error_handler = nil
     end
   end
 end

data/lib/interactor_support/core.rb

@@ -1,10 +1,9 @@
 module InteractorSupport
   ##
-  # Core behavior that ensures the `Interactor` module is included
-  # when any InteractorSupport concern is mixed in.
+  # Core hook that ensures the `Interactor` module is present when using InteractorSupport concerns.
   #
-  # This module is automatically included by all `InteractorSupport::Concerns`,
-  # so you generally do not need to include it manually.
+  # This module is automatically included by all `InteractorSupport::Concerns` so, in practice, you do
+  # not need to include it yourself.
   #
   # @example Included implicitly
   #   class MyInteractor

data/lib/interactor_support/errors.rb

@@ -1,4 +1,6 @@
 module InteractorSupport
+  ##
+  # Custom error types surfaced by InteractorSupport helpers.
   module Errors
     class UnknownAttribute < StandardError
       attr_reader :attribute, :owner
@@ -47,7 +49,7 @@ module InteractorSupport
             request_class.to_s
           end
 
-        detail = @errors.any? ? ": #{@errors.join(', ')}" : ''
+        detail = @errors.any? ? ": #{@errors.join(", ")}" : ''
 
         super("Invalid #{request_name}#{detail}")
       end

data/lib/interactor_support/request_object.rb

@@ -1,10 +1,16 @@
 module InteractorSupport
   ##
-  # A base module for building validated, transformable, and optionally nested request objects.
+  # Provides a concise DSL for building validated, transformable, and nested request objects.
   #
-  # It builds on top of `ActiveModel::Model`, adds coercion, default values, attribute transforms,
-  # key rewriting, and automatic context conversion (via `#to_context`). It integrates tightly with
-  # `InteractorSupport::Configuration` to control return behavior and key formatting.
+  # Including this module gives you:
+  # - ActiveModel validations and callbacks
+  # - Attribute coercion (via ActiveModel types or custom classes/request objects)
+  # - Value transforms, defaults, and key rewriting
+  # - A `#to_context` helper that converts the object into hashes or structs for interactors
+  # - Predictable error handling (unknown attributes raise {Errors::UnknownAttribute},
+  #   invalid records raise {ActiveModel::ValidationError})
+  #
+  # Configure return semantics (hash vs. struct vs. self) through {InteractorSupport::Configuration}.
   #
   # @example Basic usage
   #   class CreateUserRequest
@@ -13,16 +19,19 @@ module InteractorSupport
   #     attribute :name, transform: [:strip, :downcase]
   #     attribute :email
   #     attribute :metadata, default: {}
+  #
+  #     validates :email, presence: true
   #   end
   #
   #   CreateUserRequest.new(name: " JOHN ", email: "hi@example.com")
   #   # => { name: "john", email: "hi@example.com", metadata: {} }
   #
-  # @example Key rewriting
+  # @example Key rewriting and nested objects
   #   class UploadRequest
   #     include InteractorSupport::RequestObject
   #
   #     attribute :image, rewrite: :image_url
+  #     attribute :metadata, type: ImageMetadataRequest
   #   end
   #
   #   UploadRequest.new(image: "url").image_url # => "url"
@@ -44,9 +53,11 @@ module InteractorSupport
       include ActiveModel::Validations::Callbacks
 
       ##
-      # Initializes the request object and raises if invalid.
+      # Initializes the request object, applying key rewrites and validations.
       #
-      # Rewritten keys are converted before passing to ActiveModel.
+      # Unknown keys trigger {Errors::UnknownAttribute} (unless `ignore_unknown_attributes` is enabled).
+      # Validation failures raise `ActiveModel::ValidationError`, which is wrapped by
+      # {InteractorSupport::Concerns::Organizable#organize organize} when used through organizers.
       #
       # @param attributes [Hash] the input attributes
       # @raise [ActiveModel::ValidationError] if the object is invalid
@@ -63,12 +74,12 @@ module InteractorSupport
       end
 
       ##
-      # Converts the request object into a format suitable for interactor context.
+      # Converts the request object into the structure expected by interactors.
       #
-      # - If `key_type` is `:symbol` or `:string`, returns a Hash.
-      # - If `key_type` is `:struct`, returns a Struct instance.
+      # - If `request_object_key_type` is `:symbol` or `:string`, returns a Hash keyed accordingly.
+      # - If `request_object_key_type` is `:struct`, returns a Struct with attribute readers.
       #
-      # Nested request objects will also be converted recursively.
+      # Nested request objects (including arrays of request objects) are converted recursively.
       #
       # @return [Hash, Struct]
       def to_context
@@ -90,14 +101,14 @@ module InteractorSupport
       end
 
       ##
-      # Assigns the given attributes to the request object.
+      # Assigns external attributes, respecting rewrite rules and the unknown-attribute policy.
       #
-      # - Known attributes are assigned normally via their setters.
-      # - If `ignore_unknown_attributes?` is defined and true, unknown keys are ignored and logged.
-      # - Otherwise, raises `Errors::UnknownAttribute`.
+      # - Known attributes are routed through generated setters so transforms and type coercion run.
+      # - If `ignore_unknown_attributes` was declared, unrecognized keys are ignored (and optionally logged).
+      # - Otherwise {Errors::UnknownAttribute} is raised with the offending key and request class.
       #
       # @param attrs [Hash] input attributes to assign
-      # @raise [Errors::UnknownAttribute] if unknown attribute is encountered and not ignored
+      # @raise [Errors::UnknownAttribute] if an unknown attribute is encountered and not ignored
       # @return [void]
       def assign_attributes(attrs)
         attrs.each do |k, v|
@@ -119,9 +130,11 @@ module InteractorSupport
 
       class << self
         ##
-        # Custom constructor that optionally returns the context instead of the object itself.
+        # Custom constructor with pluggable return behavior.
         #
-        # Behavior is configured via `InteractorSupport.configuration.request_object_behavior`.
+        # Controlled by `InteractorSupport.configuration.request_object_behavior`:
+        # - `:returns_self` returns the request object instance (good for explicit `#valid?` checks).
+        # - `:returns_context` (default) immediately calls {#to_context} for interactor-style hashes/structs.
         #
         # @param args [Array] positional args
         # @param kwargs [Hash] keyword args
@@ -133,8 +146,10 @@ module InteractorSupport
         end
 
         ##
-        # Defines whether to ignore unknown attributes during assignment.
-        # If true, unknown attributes are logged but not raised as errors.
+        # Declares that unknown attributes should be ignored instead of raising.
+        #
+        # Ignored keys can still be logged (controlled via
+        # `InteractorSupport.configuration.log_unknown_request_object_attributes`).
         # @example
         #   class MyRequest
         #     include InteractorSupport::RequestObject
@@ -146,17 +161,16 @@ module InteractorSupport
         end
 
         ##
-        # Defines one or more attributes with optional coercion, default values, transformation,
-        # and an optional `rewrite:` key to rename the underlying attribute.
+        # Declares one or more attributes with optional coercion, defaults, transforms, and key rewrites.
         #
-        # @param names [Array<Symbol>] the attribute names
-        # @param type [Class, nil] optional class to coerce the value to (often another request object)
-        # @param array [Boolean] whether to treat the input as an array of typed objects
-        # @param default [Object] default value if not provided
-        # @param transform [Symbol, Array<Symbol>] method(s) to apply to the value
-        # @param rewrite [Symbol, nil] optional internal name to rewrite this attribute to
+        # @param names [Array<Symbol>] the attribute names declared on the public API
+        # @param type [Class, Symbol, nil] optional coercion target (ActiveModel symbol or another request object)
+        # @param array [Boolean] treat input as an array of typed objects and coerce each element
+        # @param default [Object] default value if not provided by the caller
+        # @param transform [Symbol, Array<Symbol>, Proc] one or more transformations applied before coercion
+        # @param rewrite [Symbol, nil] internal name to assign stored value to (useful for renaming keys)
         #
-        # @raise [ArgumentError] if a transform method is not found
+        # @raise [ArgumentError] if a transform method cannot be resolved
         def attribute(*names, type: nil, array: false, default: nil, transform: nil, rewrite: nil)
           names.each do |name|
             attr_name = rewrite || name
@@ -179,7 +193,7 @@ module InteractorSupport
                 end
               end
 
-              # If a `type` is specified, we attempt to cast the `value` to that type
+              # If a `type` is specified, cast the value to the configured type before assignment.
               if type
                 value = array ? Array(value).map { |v| cast_value(v, type) } : cast_value(value, type)
               end

data/lib/interactor_support/validations.rb

@@ -2,13 +2,13 @@ require 'active_model'
 
 module InteractorSupport
   ##
-  # Provides context-aware validation DSL for interactors.
+  # Provides a validation DSL tailored to interactor context.
   #
-  # This module adds `ActiveModel::Validations` and wraps it with methods like
-  # `required`, `optional`, `validates_before`, and `validates_after`, allowing
-  # declarative validation of interactor context values.
-  #
-  # Validations are executed automatically before (or after) the interactor runs.
+  # Including this module:
+  # - Adds `ActiveModel::Validations`
+  # - Introduces `required`, `optional`, `validates_before`, and `validates_after` helpers
+  # - Automatically maps validated attributes to `context` accessors
+  # - Halts execution with `context.fail!` when validations fail
   #
   # @example Required attributes with ActiveModel rules
   #   required :email, :name
@@ -37,8 +37,8 @@ module InteractorSupport
       ##
       # Declares one or more attributes as required.
       #
-      # Values must be present in the context. You can also pass validation options
-      # as a hash, which will be forwarded to ActiveModel's `validates`.
+      # Presence is enforced automatically, and any provided options are forwarded to
+      # `ActiveModel::Validations#validates`.
       #
       # @param keys [Array<Symbol, Hash>] attribute names or hash of attributes with validation options
       def required(*keys)
@@ -48,7 +48,7 @@ module InteractorSupport
       ##
       # Declares one or more attributes as optional.
       #
-      # Optional values can be nil, but still support validation rules.
+      # Optional values may be `nil` yet still participate in the provided validations.
       #
       # @param keys [Array<Symbol, Hash>] attribute names or hash of attributes with validation options
       def optional(*keys)
@@ -58,8 +58,7 @@ module InteractorSupport
       ##
       # Runs additional validations *after* the interactor executes.
       #
-      # Useful for checking persisted records, custom conditions, or results
-      # that depend on post-processing logic.
+      # Use this for checks that depend on side-effects inside `call` (e.g., persistence, background jobs).
       #
       # @param keys [Array<Symbol>] context keys to validate
       # @param validations [Hash] validation options (e.g., presence:, type:, inclusion:, persisted:)
@@ -74,9 +73,8 @@ module InteractorSupport
       ##
       # Runs validations *before* the interactor executes.
       #
-      # Prevents invalid data from reaching business logic.
-      #
-      # NOTE: `persisted:` validation is only available in `validates_after`.
+      # Use this to guard business logic from invalid input. The `persisted:` check is only available in
+      # {#validates_after} because it depends on side-effects.
       #
       # @param keys [Array<Symbol>] context keys to validate
       # @param validations [Hash] validation options (e.g., presence:, type:, inclusion:)
@@ -95,7 +93,7 @@ module InteractorSupport
       private
 
       ##
-      # Applies ActiveModel-based validations and wires up accessors to context.
+      # Applies ActiveModel validations and wires up reader/writer methods to the context.
       #
       # @param keys [Array<Symbol, Hash>] attributes to validate
       # @param required [Boolean] whether presence is enforced

data/lib/interactor_support/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InteractorSupport
-  VERSION = '1.0.6'
+  VERSION = '1.0.7'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interactor_support
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.0.7
 platform: ruby
 authors:
 - Charlie Mitchell