interactor_support 1.0.2 → 1.0.4

data/lib/interactor_support/actions.rb

@@ -1,6 +1,39 @@
+# lib/interactor_support/version.rb
 module InteractorSupport
+  ##
+  # A bundle of DSL-style concerns that enhance interactors with expressive,
+  # composable behavior.
+  #
+  # This module is intended to be included into an `Interactor` or `Organizer`,
+  # providing access to a suite of declarative action helpers:
+  #
+  # - {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
+  #     include Interactor
+  #     include InteractorSupport::Actions
+  #
+  #     find_by :user
+  #
+  #     transform :email, with: [:strip, :downcase]
+  #
+  #     update :user, attributes: { email: :email }
+  #   end
+  #
+  #
+  # @see InteractorSupport::Concerns::Skippable
+  # @see InteractorSupport::Concerns::Transactionable
+  # @see InteractorSupport::Concerns::Updatable
+  # @see InteractorSupport::Concerns::Findable
+  # @see InteractorSupport::Concerns::Transformable
   module Actions
     extend ActiveSupport::Concern
+
     included do
       include InteractorSupport::Concerns::Skippable
       include InteractorSupport::Concerns::Transactionable

data/lib/interactor_support/concerns/findable.rb

@@ -1,18 +1,50 @@
 module InteractorSupport
   module Concerns
+    ##
+    # Adds dynamic model-finding helpers (`find_by`, `find_where`) to an interactor.
+    #
+    # This concern wraps ActiveRecord `.find_by` and `.where` queries into
+    # declarative DSL methods that load records into the interactor context.
+    #
+    # These methods support symbols (for context keys) and lambdas (for dynamic runtime evaluation).
+    #
+    # @example Find a post by ID from the context
+    #   find_by :post
+    #
+    # @example Find by query using context value
+    #   find_by :post, query: { slug: :slug }, required: true
+    #
+    # @example Find using a dynamic lambda
+    #   find_by :post, query: { created_at: -> { 1.week.ago..Time.current } }
+    #
+    # @example Find all posts for a user with a scope
+    #   find_where :post, where: { user_id: :user_id }, scope: :published
+    #
+    # @see InteractorSupport::Actions
     module Findable
       extend ActiveSupport::Concern
       include InteractorSupport::Core
-      
+
       included do
         class << self
-          # This method finds a single record using query parameters.
-          # Supports symbols (context keys) and lambdas for dynamic values.
+          # Adds a `before` callback to find a single record and assign it to 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).
+          #
+          # @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)
+          # @param context_key [Symbol, nil] the key under which to store the result in context (defaults to the model name)
+          # @param required [Boolean] if true, fails the context if no record is found
           #
-          # Examples:
-          # find_by :post, query: { slug: :slug }, context_key: :current_post
-          # find_by :post, query: { id: :post_id, published: true }
-          # find_by :post, query: { created_at: -> { 1.week.ago..Time.current } }
+          # @example Basic ID-based lookup
+          #   find_by :post
+          #
+          # @example Query with context value
+          #   find_by :post, query: { slug: :slug }
+          #
+          # @example Query with a lambda
+          #   find_by :post, query: { created_at: -> { 1.week.ago..Time.current } }
           def find_by(model, query: {}, context_key: nil, required: false)
             context_key ||= model
             before do
@@ -24,9 +56,9 @@ module InteractorSupport
                   model.to_s.classify.constantize.find_by(
                     query.transform_values do |v|
                       case v
-                      when Symbol then context[v] # Lookup symbol in context
-                      when Proc then instance_exec(&v) # Evaluate lambda dynamically
-                      else v # Use raw value
+                      when Symbol then context[v]
+                      when Proc then instance_exec(&v)
+                      else v
                       end
                     end,
                   )
@@ -37,14 +69,26 @@ module InteractorSupport
             end
           end
 
-          # This method finds multiple records using where conditions.
-          # Supports symbols (context keys) and lambdas for dynamic values.
+          # Adds a `before` callback to find multiple records 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).
           #
-          # Examples:
-          # find_where :post, where: { user_id: :user_id }
-          # find_where :post, where: { created_at: -> { 5.days.ago..Time.current } }
-          # find_where :post, where: { user_id: :user_id }, where_not: { active: false }
-          # find_where :post, where: { user_id: :user_id }, scope: :active
+          # @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)
+          # @param where_not [Hash{Symbol=>Object,Proc}] conditions for `.where.not`
+          # @param scope [Symbol, nil] optional named scope to call on the model
+          # @param context_key [Symbol, nil] the key under which to store the result in context (defaults to pluralized model name)
+          # @param required [Boolean] if true, fails the context if no records are found
+          #
+          # @example Where query with symbol context values
+          #   find_where :post, where: { user_id: :user_id }
+          #
+          # @example Where with a lambda and scope
+          #   find_where :post, where: { created_at: -> { 5.days.ago..Time.current } }, scope: :published
+          #
+          # @example Where with exclusions
+          #   find_where :post, where: { user_id: :user_id }, where_not: { active: false }
           def find_where(model, where: {}, where_not: {}, scope: nil, context_key: nil, required: false)
             context_key ||= model.to_s.pluralize.to_sym
             before do
@@ -53,9 +97,9 @@ module InteractorSupport
               query = query.where(
                 where.transform_values do |v|
                   case v
-                  when Symbol then context[v] # Lookup symbol in context
-                  when Proc then instance_exec(&v) # Evaluate lambda dynamically
-                  else v # Use raw value
+                  when Symbol then context[v]
+                  when Proc then instance_exec(&v)
+                  else v
                   end
                 end,
               ) if where.present?

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/concerns/skippable.rb

@@ -1,11 +1,53 @@
+# frozen_string_literal: true
+
 module InteractorSupport
   module Concerns
+    ##
+    # Adds a DSL method to conditionally skip an interactor.
+    #
+    # 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.
+    #
+    # - Symbols will be looked up on the interactor or in the context.
+    # - Lambdas/Procs are evaluated using `instance_exec` with full access to context.
+    #
+    # @example Skip if the user is already authenticated (symbol in context)
+    #   skip if: :user_authenticated
+    #
+    # @example Skip unless a method returns true
+    #   skip unless: :should_run?
+    #
+    # @example Skip based on a lambda
+    #   skip if: -> { mode == "test" }
+    #
+    # @see InteractorSupport::Actions
     module Skippable
       extend ActiveSupport::Concern
       include InteractorSupport::Core
 
       included do
         class << self
+          ##
+          # 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.
+          #
+          # @param options [Hash]
+          # @option options [Proc, Symbol, Boolean] :if a condition that must be truthy to skip
+          # @option options [Proc, Symbol, Boolean] :unless a condition that must be falsy to skip
+          #
+          # @example Skip if a context value is truthy
+          #   skip if: :user_authenticated
+          #
+          # @example Skip unless a method returns true
+          #   skip unless: :should_run?
+          #
+          # @example Skip based on a lambda
+          #   skip if: -> { context[:mode] == "test" }
           def skip(**options)
             around do |interactor|
               unless options[:if].nil?

data/lib/interactor_support/concerns/transactionable.rb

@@ -1,11 +1,48 @@
 module InteractorSupport
   module Concerns
+    ##
+    # Adds transactional support to your interactor 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.
+    #
+    # @example Basic usage
+    #   class CreateUser
+    #     include Interactor
+    #     include InteractorSupport::Transactionable
+    #
+    #     transaction
+    #
+    #     def call
+    #       User.create!(context.user_params)
+    #       context.fail!(message: "Simulated failure") if something_wrong?
+    #     end
+    #   end
+    #
+    # @see InteractorSupport::Actions
     module Transactionable
       extend ActiveSupport::Concern
       include InteractorSupport::Core
 
       included do
         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.
+          #
+          # @param isolation [Symbol, nil] the transaction isolation level (e.g., `:read_committed`, `:serializable`)
+          # @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
+          #
+          # @example Wrap in a basic transaction
+          #   transaction
+          #
+          # @example With custom options
+          #   transaction requires_new: true, isolation: :serializable
           def transaction(isolation: nil, joinable: true, requires_new: false)
             around do |interactor|
               ActiveRecord::Base.transaction(isolation: isolation, joinable: joinable, requires_new: requires_new) do

data/lib/interactor_support/concerns/transformable.rb

@@ -1,15 +1,41 @@
 module InteractorSupport
   module Concerns
+    ##
+    # Adds helpers for assigning and transforming values in interactor context.
+    #
+    # 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.
+    #
+    # @example Assign context variables before the interactor runs
+    #   context_variable user: -> { User.find(user_id) }, numbers: [1, 2, 3]
+    #
+    # @example Normalize email and name before using them
+    #   transform :email, :name, with: [:strip, :downcase]
+    #
+    # @example Apply a lambda to clean up input
+    #   transform :name, with: ->(value) { value.gsub(/\s+/, ' ').strip }
+    #
+    # @example Mixing symbols and lambdas
+    #   transform :email, with: [:strip, :downcase, -> { email.gsub(/\s+/, '') }]
+    #
+    # @see InteractorSupport::Actions
     module Transformable
       extend ActiveSupport::Concern
       include InteractorSupport::Core
 
       included do
         class << self
-          # context_variable first_post: Post.first
-          # context_variable user: -> { User.find(user_id) }
-          # context_variable items: Item.all
-          # context_variable numbers: [1, 2, 3]
+          # 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.
+          #
+          # @param key_values [Hash{Symbol => Object, Proc}] a mapping of context keys to values or Procs
+          #
+          # @example Static and dynamic values
+          #   context_variable first_post: Post.first
+          #   context_variable user: -> { User.find(user_id) }
+          #   context_variable numbers: [1, 2, 3]
           def context_variable(key_values)
             before do
               key_values.each do |key, value|
@@ -22,12 +48,40 @@ module InteractorSupport
             end
           end
 
-          # transform :email, :name, with: [:downcase, :strip]
-          # transform :url, with: :downcase
-          # transform :items, with: :compact
-          # transform :items, with: ->(value) { value.compact }
-          # transform :email, :url, with: ->(value) { value.downcase.strip }
-          # transform :items, with: :compact
+          # Transforms one or more context values using a method, a proc, or a sequence of methods.
+          #
+          # This allows simple transformations like `:strip` or `:downcase`, or more complex lambdas.
+          # You can also chain transformations by passing an array of method names.
+          #
+          # If a transformation fails, the context fails with an error message.
+          #
+          # @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
+          #
+          # @raise [ArgumentError] if no keys are given, or if an invalid `with:` value is passed
+          #
+          # @example Single method
+          #   transform :email, with: :strip
+          #
+          # @example Method chain
+          #   transform :email, with: [:strip, :downcase]
+          #
+          # @example Lambda
+          #   transform :url, with: ->(value) { value.downcase.strip }
+          #
+          # @example Multiple keys
+          #   transform :email, :name, with: [:downcase, :strip]
+          #
+          # @example Normalize user input
+          #   transform :email, :name, with: [
+          #     :strip,
+          #     :downcase,
+          #     ->(value) { value.gsub(/\s+/, ' ') }, # collapse duplicate spaces
+          #   ]
+          #
+          #   # Result:
+          #   # context[:email] = "someone@example.com"
+          #   # context[:name]  = "john doe"
           def transform(*keys, with: [])
             before do
               if keys.empty?

data/lib/interactor_support/concerns/updatable.rb

@@ -1,11 +1,54 @@
 module InteractorSupport
   module Concerns
+    ##
+    # Adds an `update` DSL method for updating a context-loaded model with attributes.
+    #
+    # 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.
+    #
+    # This is useful for updating records cleanly and consistently in declarative steps.
+    #
+    # @example Update a user using context values
+    #   update :user, attributes: { name: :new_name, email: :new_email }
+    #
+    # @example Extract nested fields from a context object
+    #   update :user, attributes: { form_data: [:name, :email] }
+    #
+    # @example Use a lambda for computed value
+    #   update :post, attributes: { published_at: -> { Time.current } }
+    #
+    # @see InteractorSupport::Actions
     module Updatable
       extend ActiveSupport::Concern
       include InteractorSupport::Core
 
       included do
         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
+          #
+          # If the record or required data is missing, the context fails with an error.
+          #
+          # @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`)
+          #
+          # @example Basic attribute update using context keys
+          #   update :user, attributes: { name: :new_name, email: :new_email }
+          #
+          # @example Use a lambda for dynamic value
+          #   update :post, attributes: { published_at: -> { Time.current } }
+          #
+          # @example Nested context value lookup from a parent object
+          #   # Assuming context[:form_data] = OpenStruct.new(name: "Hi", email: "hi@example.com")
+          #   update :user, attributes: { form_data: [:name, :email] }
+          #
+          # @example Using a symbol to fetch all attributes from another context object
+          #   update :order, attributes: :order_attributes
           def update(model, attributes: {}, context_key: nil)
             context_key ||= model
 
@@ -46,7 +89,6 @@ module InteractorSupport
 
               record.update!(update_data)
 
-              # Assign the updated record to context
               context[context_key] = record
             end
           end

data/lib/interactor_support/configuration.rb

@@ -1,17 +1,40 @@
 module InteractorSupport
+  ##
+  # Global configuration for InteractorSupport.
+  #
+  # This allows customization of how request objects behave when used in interactors.
+  #
+  # @example Set custom behavior
+  #   InteractorSupport.configuration.request_object_behavior = :returns_self
+  #   InteractorSupport.configuration.request_object_key_type = :struct
+  #
+  # @see InteractorSupport.configuration
   class Configuration
-    attr_accessor :request_object_behavior, :request_object_key_type
+    ##
+    # Defines how request objects behave when called.
+    #
+    # - `:returns_context` — The request object returns an Interactor-style context.
+    # - `:returns_self` — The request object returns itself, allowing method chaining.
+    #
+    # @return [:returns_context, :returns_self]
+    attr_accessor :request_object_behavior
 
+    ##
+    # Defines the key type used in request object context when `:returns_context` is active.
+    #
+    # - `:string` — Keys are string-based (`"name"`)
+    # - `:symbol` — Keys are symbol-based (`:name`)
+    # - `:struct` — Keys are accessed via struct-style method calls (`name`)
+    #
+    # @return [:string, :symbol, :struct]
+    attr_accessor :request_object_key_type
+
+    ##
+    # Initializes the configuration with default values:
+    # - `request_object_behavior` defaults to `:returns_context`
+    # - `request_object_key_type` defaults to `:symbol`
     def initialize
-      # Default configuration values.
-      # :returns_context - request objects return a context object.
-      # :returns_self - request objects return self.
       @request_object_behavior = :returns_context
-
-      # Default configuration values, only applies when request_object_behavior is :returns_context.
-      # :string - request object keys are strings.
-      # :symbol - request object keys are symbols.
-      # :struct - request object keys are struct objects.
       @request_object_key_type = :symbol
     end
   end