interactor_support 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b479b98d9029e0865ab4526efcc08ec47736ecba96547d2ab9be294f54d2880
-  data.tar.gz: 74f5d2a0024afb6b7c49ff153a339d6373d25072d37e546827407e65cfd0bc8d
+  metadata.gz: 315dd265352ed997c5b69934609478e6e5f8b61bbe74bba065acf495f7dac41c
+  data.tar.gz: 6a942d0ccb3f3323d156d85f302987b4af7809cdcce852dca56fb9b1ae8419bc
 SHA512:
-  metadata.gz: e1d24d1b7fe20316f26d14f029387d90e1c88e2dc9654500dd40ae9546e030121efcb5de991d091b752308f0f976533a4dabaebc3cb2bebc269b7f5ca70ab7d3
-  data.tar.gz: 32c320144c9f90dc53769bd104a308d17ce663e8618cc0f55f8435d89835ed3aa2cb3049df023422de0d34068ced12795e12127e8eb976f18a3db8a56c0e759a
+  metadata.gz: 2fb25732876e4702b12da283cf4d205504c597ecb904cc9406af3a9825814e8ba518e84bcc615c1c8aadc31ed81cfb9008e2addf759273c2688e029d5b07628e
+  data.tar.gz: 5615bf986b8ab272cff775eebbd874c336be93f4e17333d37fd6e87a04b9d74d110b2fcab2a48fb1e0ff86956785b4a7825d03f4201701700566825c2335c633

data/CHANGELOG.md

@@ -17,3 +17,15 @@
 - Added support for rewriting attribute names in a request object
 - Better support for type coersion, using Active model + Array, Hash, and Symbol
 - Better support for `AnyClass` type validations
+
+## [1.0.4] - 2025-04-05
+
+- Added the organizable concern
+
+## [1.0.5] - 2025-06-30
+
+- Add support for ignoring unknown attributes in RequestObjects via `ignore_unknown_attributes` class method
+- Introduce `InteractorSupport.configuration.log_unknown_request_object_attributes` to optionally log ignored attributes
+- 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

data/README.md

@@ -148,6 +148,7 @@ Instead of raw hashes, **Request Objects** provide **validation, transformation,
 - Works just like an **ActiveRecord model**
 - Supports **validations** out of the box
 - Automatically **transforms & sanitizes** data
+- Gracefully ignores unknown attributes if configured, with optional logging
 
 ```ruby
 class TodoRequest
@@ -162,6 +163,31 @@ class TodoRequest
 end
 ```
 
+### 🔍 Ignoring Unknown Attributes
+
+To prevent `RequestObject` from raising an error on unexpected keys, declare `ignore_unknown_attributes` in your class.
+
+```ruby
+class CalendarRequest
+  include InteractorSupport::RequestObject
+
+  ignore_unknown_attributes
+
+  attribute :start_date, type: :date
+  attribute :end_date, type: :date
+  attribute :timezone, transform: :strip
+
+  validates :start_date, :end_date, presence: true
+end
+```
+
+Now, if you initialize the request with an unexpected attribute, it will be logged (if logging is enabled) and ignored:
+
+```ruby
+CalendarRequest.new(start_date: "2025-07-01", end_date: "2025-07-02", foo: "bar")
+# => No exception raised; 'foo' is ignored.
+```
+
 ---
 
 ## 📖 **Documentation**
@@ -527,6 +553,159 @@ UserRequest.new(params.require(:user).permit(:name, :email, :age))
 
 But with RequestObject, that’s often unnecessary because you’re already defining a schema.
 
+## InteractorSupport::Organizable
+
+The Organizable concern provides utility methods to simplify working with interactors and request objects. It gives you a clean and consistent pattern for extracting, transforming, and preparing parameters for use in service objects or interactors.
+
+Features
+
+- organize: Call interactors with request objects, optionally namespaced under a context_key.
+- request_params: Extract, shape, filter, rename, flatten, and merge incoming params in a clear and declarative way.
+- Built for controllers or service entry points.
+- Rails-native feel — works seamlessly with strong params.
+
+#### API Reference
+
+**#organize(interactor, params:, request_object:, context_key: nil)**
+Calls the given interactor with a request object built from the provided params.
+
+| Argument       | Type          | Description                                                                 |
+| -------------- | ------------- | --------------------------------------------------------------------------- |
+| interactor     | Class         | The interactor to call (.call must be defined).                             |
+| 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. |
+
+Examples
+
+```rb
+organize(MyInteractor, params: request_params, request_object: MyRequest)
+
+# => MyInteractor.call(MyRequest.new(params))
+
+organize(MyInteractor, params: request_params, request_object: MyRequest, context_key: :request)
+
+# => MyInteractor.call({ request: MyRequest.new(params) })
+```
+
+#### #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.
+
+| Argument          | Type                             | Description                                                               |
+| ----------------- | -------------------------------- | ------------------------------------------------------------------------- |
+| `*top_level_keys` | `Symbol...`                      | Optional list of top-level keys to include. If omitted, includes all.     |
+| `merge:`          | `Hash`                           | Extra values to merge into the result.                                    |
+| `except:`         | `Array<Symbol or Array<Symbol>>` | Keys or nested key paths to exclude.                                      |
+| `rewrite:`        | `Array<Hash>`                    | Rules for renaming, flattening, filtering, merging, or defaulting values. |
+
+Rewrite Options
+
+Each rewrite entry is a hash in the form { key => options }, where options may include:
+| Option | Type | Description |
+|-----------|---------------------------|-------------------------------------------------------------------|
+| `as` | `Symbol` | Rename the key to a new top-level key. |
+| `only` | `Array<Symbol>` | Include only these subkeys in the result. |
+| `except` | `Array<Symbol>` | Remove these subkeys from the result. |
+| `flatten` | `true` or `Array<Symbol>` | Flatten all subkeys into top-level (or just the specified ones). |
+| `default` | `Hash` | Use this value if the original key is missing or nil. |
+| `merge` | `Hash` | Merge this hash into the result (after filtering and flattening). |
+
+Example: full usage
+
+```rb
+# Incoming params:
+params = {
+  order: {
+    product_id: 1,
+    quantity: 2,
+    internal: "should be removed"
+  },
+  metadata: {
+    source: "mobile",
+    internal: "hidden",
+    location: { ip: "1.2.3.4" }
+  },
+  flags: {
+    foo: true
+  },
+  internal: "global_internal",
+  session: nil
+}
+
+# Incantation:
+request_params(:order, :metadata, :flags, :session,
+  merge: { user: current_user }, # <- Add the user
+  except: [[:order, :internal], :internal], # <- remove `order.internal`, and the top level key `internal`
+  rewrite: [
+    { order: { flatten: true } }, # <- moves all the values from order to top level keys
+    { metadata: { as: :meta, only: [:source, :location], flatten: [:location] } }, # <- Rename metadata to meta, pluck source and location, move location's values to meta
+    { flags: { merge: { debug: true } } }, # <- add flags.debug = true
+    { session: { default: { id: nil } } } # <- create a default value for session
+  ]
+)
+
+# Result
+{
+  product_id: 1,
+  quantity: 2,
+  meta: {
+    source: "mobile",
+    ip: "1.2.3.4"
+  },
+  flags: {
+    foo: true,
+    debug: true
+  },
+  session: {
+    id: nil
+  },
+  user: current_user
+}
+```
+
+⚠️ Array flattening is not supported
+
+Flattening arrays of hashes (e.g., { events: [{ id: 1 }] }) is intentionally not supported to avoid accidental key collisions. If needed, transform such structures manually before passing to request_params.
+
+**Usage**
+
+Include in a controller or service base class
+
+```rb
+class ApplicationController < ActionController::Base
+  include InteractorSupport::Concerns::Organizable
+end
+```
+
+---
+
+## 🛠 Configuration Reference
+
+All global settings for InteractorSupport can be set via the `InteractorSupport.configure` block. Here's a full list of configuration options:
+
+<!-- prettier-ignore-start -->
+| Key | Type | Default | Description |
+| --- | ---- | ------- | -----------|
+| `logger` | `Logger` | `Logger.new($stdout)` | Logger instance used for internal logging. |
+| `log_level` | `Integer` (Logger constant) | `Logger::INFO` | Logging level (e.g., `Logger::DEBUG`, `Logger::WARN`, etc.). |
+| `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`).  |
+<!-- prettier-ignore-end -->
+
+To update these settings, use:
+
+```ruby
+InteractorSupport.configure do |config|
+  config.logger = Rails.logger
+  config.log_level = Logger::WARN
+  config.log_unknown_request_object_attributes = true
+  config.request_object_behavior = :returns_self
+  config.request_object_key_type = :struct
+end
+```
+
 ## 🤝 **Contributing**
 
 Pull requests are welcome on [GitHub](https://github.com/charliemitchell/interactor_support).

data/lib/interactor_support/actions.rb

@@ -7,11 +7,11 @@ module InteractorSupport
   # This module is intended to be included into an `Interactor` or `Organizer`,
   # providing access to a suite of declarative action helpers:
   #
-  # - {Skippable} — Conditionally skip execution
-  # - {Transactionable} — Wrap logic in an ActiveRecord transaction
-  # - {Updatable} — Update records using context-driven attributes
-  # - {Findable} — Find one or many records into context
-  # - {Transformable} — Normalize or modify context values before execution
+  # - {InteractorSupport::Concerns::Skippable} — Conditionally skip execution
+  # - {InteractorSupport::Concerns::Transactionable} — Wrap logic in an ActiveRecord transaction
+  # - {InteractorSupport::Concerns::Updatable} — Update records using context-driven attributes
+  # - {InteractorSupport::Concerns::Findable} — Find one or many records into context
+  # - {InteractorSupport::Concerns::Transformable} — Normalize or modify context values before execution
   #
   # @example Use in an interactor
   #   class UpdateUser
@@ -25,6 +25,7 @@ module InteractorSupport
   #     update :user, attributes: { email: :email }
   #   end
   #
+  #
   # @see InteractorSupport::Concerns::Skippable
   # @see InteractorSupport::Concerns::Transactionable
   # @see InteractorSupport::Concerns::Updatable
@@ -32,6 +33,7 @@ module InteractorSupport
   # @see InteractorSupport::Concerns::Transformable
   module Actions
     extend ActiveSupport::Concern
+
     included do
       include InteractorSupport::Concerns::Skippable
       include InteractorSupport::Concerns::Transactionable

data/lib/interactor_support/concerns/organizable.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module InteractorSupport
+  module Concerns
+    ##
+    # The `Organizable` module provides utility methods for organizing interactors
+    # and shaping request parameters in a structured way.
+    #
+    # It is intended to be included into a controller or a base service class that
+    # delegates to interactors using request objects.
+    #
+    # @example Include in a controller
+    #   class ApplicationController < ActionController::Base
+    #     include InteractorSupport::Organizable
+    #   end
+    #
+    # @see InteractorSupport::Organizable#organize
+    # @see InteractorSupport::Organizable#request_params
+    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.
+      #
+      # @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 context_key [Symbol, nil] Optional key to assign the request object under in the context.
+      #
+      # @return [void]
+      #
+      # @example
+      #  organize(MyInteractor, params: request_params, request_object: MyRequest)
+      #  # => Calls MyInteractor with an instance of MyRequest initialized with request_params.
+      #
+      # @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)
+        @context = interactor.call(
+          context_key ? { context_key => request_object.new(params) } : request_object.new(params),
+        )
+      end
+
+      # Builds a structured and optionally transformed parameter hash from Rails' `params`.
+      #
+      # This method supports extracting specific top-level keys, applying optional rewrite
+      # transformations, merging in additional values, and excluding unwanted keys.
+      #
+      # @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.
+      #
+      # @example Extracting a specific top-level key
+      #   # Given: params = { order: { product_id: 1, quantity: 2 } }
+      #   request_params(:order)
+      #   # => { order: { product_id: 1, quantity: 2 } }
+      #
+      # @example Without top-level keys (includes all)
+      #   # Given: params = { order: { product_id: 1 }, app_id: 123 }
+      #   request_params()
+      #   # => { order: { product_id: 1 }, app_id: 123 }
+      #
+      # @example Merging and excluding
+      #   # Given: params = { order: { product_id: 1, quantity: 2 }, internal: "yes" }
+      #   request_params(:order, merge: { user_id: 123 }, except: [[:order, :quantity], :internal])
+      #   # => { order: { product_id: 1 }, user_id: 123 }
+      #
+      # @example Flattening a nested hash into the top-level
+      #   # Given: params = { order: { product_id: 1, quantity: 2 }, app_id: 123 }
+      #   request_params(:order, rewrite: [{ order: { flatten: true } }])
+      #   # => { product_id: 1, quantity: 2 }
+      #
+      # @example Rename a top-level key and filter nested keys
+      #   # Given: params = { metadata: { source: "mobile", internal: "x" } }
+      #   request_params(:metadata, rewrite: [
+      #     { metadata: { as: :meta, only: [:source] } }
+      #   ])
+      #   # => { meta: { source: "mobile" } }
+      #
+      # @example Provide a default value if a key is missing
+      #   # Given: params = {}
+      #   request_params(:session, rewrite: [
+      #     { session: { default: { id: nil } } }
+      #   ])
+      #   # => { session: { id: nil } }
+      #
+      # @example Merge values into a nested structure
+      #   # Given: params = { flags: { foo: true } }
+      #   request_params(:flags, rewrite: [
+      #     { flags: { merge: { debug: true } } }
+      #   ])
+      #   # => { flags: { foo: true, debug: true } }
+      #
+      # @example Combine multiple rewrite rules
+      #   # Given:
+      #   # params = {
+      #   #   order: { product_id: 1, quantity: 2 },
+      #   #   metadata: { source: "mobile", location: { ip: "1.2.3.4" } },
+      #   #   tracking: { click_id: "abc", session_id: "def" }
+      #   # }
+      #   request_params(:order, :metadata, :tracking, rewrite: [
+      #     { order: { flatten: true } },
+      #     { metadata: { as: :meta, only: [:source, :location], flatten: [:location] } }
+      #   ])
+      #   # => {
+      #   #   product_id: 1,
+      #   #   quantity: 2,
+      #   #   meta: { source: "mobile", ip: "1.2.3.4" },
+      #   #   tracking: { click_id: "abc", session_id: "def" }
+      #   # }
+      def request_params(*top_level_keys, merge: {}, except: [], rewrite: [])
+        permitted = params.permit!.to_h.deep_symbolize_keys
+        data = top_level_keys.any? ? permitted.slice(*top_level_keys) : permitted
+
+        apply_rewrites!(data, rewrite)
+
+        data
+          .deep_merge(merge)
+          .then { |result| except.any? ? deep_except(result, except) : result }
+      end
+
+      private
+
+      def apply_rewrites!(data, rewrites)
+        rewrites.each do |rule|
+          key, config = rule.first
+          config = { flatten: true } if config == :flatten
+
+          original = data.key?(key) ? data.delete(key) : nil
+          transformed = original.deep_dup if original.is_a?(Hash)
+          transformed ||= original
+
+          # Filtering
+          transformed.slice!(*config[:only]) if config[:only] && transformed.respond_to?(:slice!)
+          transformed.except!(*config[:except]) if config[:except] && transformed.respond_to?(:except!)
+
+          # Flatten specific nested keys
+          if config[:flatten].is_a?(Array) && transformed.is_a?(Hash)
+            config[:flatten].each do |subkey|
+              nested = transformed.delete(subkey)
+              if nested.is_a?(Hash)
+                transformed.merge!(nested)
+              elsif nested.is_a?(Array)
+                raise ArgumentError,
+                  "Cannot flatten array for the key `#{subkey}`. Flattening arrays of hashes is not supported."
+              end
+            end
+          end
+
+          # Apply default if nil or missing
+          transformed ||= config[:default]
+
+          # Merge additional keys
+          if config[:merge]
+            transformed = transformed.is_a?(Hash) ? transformed.merge(config[:merge]) : config[:merge]
+          end
+
+          # Fully flatten to top level
+          if config[:flatten] == true && transformed.is_a?(Hash)
+            data.merge!(transformed)
+          else
+            target_key = config[:as] || key
+            data[target_key] = transformed
+          end
+        end
+      end
+
+      def deep_except(hash, paths)
+        paths.reduce(hash) { |acc, path| remove_nested_key(acc, Array(path)) }
+      end
+
+      def remove_nested_key(hash, path)
+        return hash unless path.is_a?(Array) && path.any?
+
+        key, *rest = path
+        return hash unless hash.key?(key)
+
+        duped = hash.dup
+        if rest.empty?
+          duped.delete(key)
+        elsif duped[key].is_a?(Hash)
+          duped[key] = remove_nested_key(duped[key], rest)
+        end
+
+        duped
+      end
+    end
+  end
+end

data/lib/interactor_support/configuration.rb

@@ -29,13 +29,35 @@ module InteractorSupport
     # @return [:string, :symbol, :struct]
     attr_accessor :request_object_key_type
 
+    ##
+    # Logger for InteractorSupport, defaults to STDOUT.
+    # @return [Logger]
+    attr_accessor :logger
+
+    ##
+    # The log level for InteractorSupport logs.
+    # @return [Integer]
+    attr_accessor :log_level
+
+    ##
+    # Whether to log unknown request object attributes when they are ignored.
+    # If true, logs a warning when an unknown attribute is encountered.
+    # @see InteractorSupport::RequestObject#ignore_unknown_attributes
+    attr_accessor :log_unknown_request_object_attributes
+
     ##
     # Initializes the configuration with default values:
     # - `request_object_behavior` defaults to `:returns_context`
     # - `request_object_key_type` defaults to `:symbol`
+    # - `logger` defaults to a new Logger instance writing to STDOUT
+    # - `log_level` defaults to `Logger::INFO`
+    # - `log_unknown_request_object_attributes` defaults to `true`
     def initialize
       @request_object_behavior = :returns_context
       @request_object_key_type = :symbol
+      @logger = Logger.new($stdout)
+      @log_level = Logger::INFO
+      @log_unknown_request_object_attributes = true
     end
   end
 end

data/lib/interactor_support/errors.rb

@@ -0,0 +1,9 @@
+module InteractorSupport
+  module Errors
+    class UnknownAttribute < StandardError
+      def initialize(attribute)
+        super("Unknown attribute: #{attribute}")
+      end
+    end
+  end
+end

data/lib/interactor_support/request_object.rb

@@ -40,6 +40,7 @@ module InteractorSupport
     included do
       include ActiveModel::Model
       include ActiveModel::Attributes
+      include ActiveModel::AttributeAssignment
       include ActiveModel::Validations::Callbacks
 
       ##
@@ -82,11 +83,38 @@ module InteractorSupport
             value
           end
         end
+
         return Struct.new(*attrs.keys).new(*attrs.values) if key_type == :struct
 
         attrs
       end
 
+      ##
+      # Assigns the given attributes to the request object.
+      #
+      # - 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`.
+      #
+      # @param attrs [Hash] input attributes to assign
+      # @raise [Errors::UnknownAttribute] if unknown attribute is encountered and not ignored
+      # @return [void]
+      def assign_attributes(attrs)
+        attrs.each do |k, v|
+          setter = "#{k}="
+          if respond_to?(setter)
+            send(setter, v)
+          elsif respond_to?(:ignore_unknown_attributes?) && ignore_unknown_attributes?
+            InteractorSupport.configuration.logger.log(
+              InteractorSupport.configuration.log_level,
+              "InteractorSupport::RequestObject ignoring unknown attribute '#{k}' for #{self.class.name}.",
+            )
+          else
+            raise Errors::UnknownAttribute, "`#{k}` for #{self.class.name}."
+          end
+        end
+      end
+
       class << self
         ##
         # Custom constructor that optionally returns the context instead of the object itself.
@@ -102,6 +130,19 @@ module InteractorSupport
           super(*args, **kwargs).to_context
         end
 
+        ##
+        # Defines whether to ignore unknown attributes during assignment.
+        # If true, unknown attributes are logged but not raised as errors.
+        # @example
+        #   class MyRequest
+        #     include InteractorSupport::RequestObject
+        #     ignore_unknown_attributes
+        #   end
+        #   @return [void]
+        def ignore_unknown_attributes
+          define_method(:ignore_unknown_attributes?) { true }
+        end
+
         ##
         # Defines one or more attributes with optional coercion, default values, transformation,
         # and an optional `rewrite:` key to rename the underlying attribute.

data/lib/interactor_support/version.rb

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

data/lib/interactor_support.rb

@@ -3,6 +3,7 @@
 require 'interactor'
 require 'logger'
 require 'active_support/concern'
+require 'interactor_support/errors'
 require_relative 'interactor_support/core'
 require_relative 'interactor_support/version'
 require_relative 'interactor_support/actions'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interactor_support
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Charlie Mitchell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-04 00:00:00.000000000 Z
+date: 2025-07-01 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -30,13 +30,16 @@ files:
 - lib/interactor_support.rb
 - lib/interactor_support/actions.rb
 - lib/interactor_support/concerns/findable.rb
+- lib/interactor_support/concerns/organizable.rb
 - lib/interactor_support/concerns/skippable.rb
 - lib/interactor_support/concerns/transactionable.rb
 - lib/interactor_support/concerns/transformable.rb
 - lib/interactor_support/concerns/updatable.rb
 - lib/interactor_support/configuration.rb
 - lib/interactor_support/core.rb
+- lib/interactor_support/errors.rb
 - lib/interactor_support/request_object.rb
+- lib/interactor_support/response_object.rb
 - lib/interactor_support/rubocop.rb
 - lib/interactor_support/rubocop/cop/base_interactor_cop.rb
 - lib/interactor_support/rubocop/cop/require_required_for_interactor_support.rb