interactor_support 1.0.1 → 1.0.3

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?
@@ -42,11 +96,20 @@ module InteractorSupport
                     context.fail!(errors: ["#{key} failed to transform: #{e.message}"])
                   end
                 elsif with.is_a?(Array)
-                  context.fail!(errors: ["#{key} does not respond to all transforms"]) unless with.all? do |t|
-                    t.is_a?(Symbol) && context[key].respond_to?(t)
-                  end
-                  context[key] = with.inject(context[key]) do |value, method|
-                    value.send(method)
+                  with.each do |method|
+                    if method.is_a?(Proc)
+                      begin
+                        context[key] = context.instance_exec(&method)
+                      rescue => e
+                        context.fail!(errors: ["#{key} failed to transform: #{e.message}"])
+                      end
+                    else
+                      context.fail!(
+                        errors: ["#{key} does not respond to all transforms"],
+                      ) unless context[key].respond_to?(method)
+
+                      context[key] = context[key].send(method)
+                    end
                   end
                 elsif with.is_a?(Symbol) && context[key].respond_to?(with)
                   context[key] = context[key].send(with)

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

data/lib/interactor_support/core.rb

@@ -1,8 +1,26 @@
 module InteractorSupport
+  ##
+  # Core behavior that ensures the `Interactor` module is included
+  # when any InteractorSupport concern is mixed in.
+  #
+  # This module is automatically included by all `InteractorSupport::Concerns`,
+  # so you generally do not need to include it manually.
+  #
+  # @example Included implicitly
+  #   class MyInteractor
+  #     include InteractorSupport::Concerns::Findable
+  #     # => Interactor is automatically included
+  #   end
   module Core
     class << self
+      ##
+      # Ensures the `Interactor` module is included in the base class.
+      #
+      # This hook runs when `Core` is included by a concern and conditionally
+      # includes `Interactor` if not already present.
+      #
+      # @param base [Class] the class or module including this concern
       def included(base)
-        # Only include Interactor if it isn’t already present.
         base.include(Interactor) unless base.included_modules.include?(Interactor)
       end
     end

data/lib/interactor_support/request_object.rb

@@ -1,18 +1,75 @@
-# app/concerns/interactor_support/request_object.rb
 module InteractorSupport
+  ##
+  # A base module for building validated, transformable, and optionally 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.
+  #
+  # @example Basic usage
+  #   class CreateUserRequest
+  #     include InteractorSupport::RequestObject
+  #
+  #     attribute :name, transform: [:strip, :downcase]
+  #     attribute :email
+  #     attribute :metadata, default: {}
+  #   end
+  #
+  #   CreateUserRequest.new(name: " JOHN ", email: "hi@example.com")
+  #   # => { name: "john", email: "hi@example.com", metadata: {} }
+  #
+  # @example Key rewriting
+  #   class UploadRequest
+  #     include InteractorSupport::RequestObject
+  #
+  #     attribute :image, rewrite: :image_url
+  #   end
+  #
+  #   UploadRequest.new(image: "url").image_url # => "url"
+  #
+  # @see InteractorSupport::Configuration
   module RequestObject
     extend ActiveSupport::Concern
+    SUPPORTED_ACTIVEMODEL_TYPES = ActiveModel::Type.registry.send(:registrations).keys.map { |type| ":#{type}" }
+    SUPPORTED_PRIMITIVES = ['AnyClass', 'Symbol', 'Hash', 'Array']
+    SUPPORTED_TYPES = SUPPORTED_PRIMITIVES + SUPPORTED_ACTIVEMODEL_TYPES
+
+    class TypeError < StandardError
+    end
 
     included do
       include ActiveModel::Model
       include ActiveModel::Attributes
       include ActiveModel::Validations::Callbacks
 
+      ##
+      # Initializes the request object and raises if invalid.
+      #
+      # Rewritten keys are converted before passing to ActiveModel.
+      #
+      # @param attributes [Hash] the input attributes
+      # @raise [ActiveModel::ValidationError] if the object is invalid
       def initialize(attributes = {})
+        attributes = attributes.dup
+        self.class.rewritten_attributes.each do |external, internal|
+          if attributes.key?(external)
+            attributes[internal] = attributes.delete(external)
+          end
+        end
+
         super(attributes)
         raise ActiveModel::ValidationError, self unless valid?
       end
 
+      ##
+      # Converts the request object into a format suitable for interactor context.
+      #
+      # - If `key_type` is `:symbol` or `:string`, returns a Hash.
+      # - If `key_type` is `:struct`, returns a Struct instance.
+      #
+      # Nested request objects will also be converted recursively.
+      #
+      # @return [Hash, Struct]
       def to_context
         key_type = InteractorSupport.configuration.request_object_key_type
         attrs = attributes.each_with_object({}) do |(name, value), hash|
@@ -31,26 +88,42 @@ module InteractorSupport
       end
 
       class << self
+        ##
+        # Custom constructor that optionally returns the context instead of the object itself.
+        #
+        # Behavior is configured via `InteractorSupport.configuration.request_object_behavior`.
+        #
+        # @param args [Array] positional args
+        # @param kwargs [Hash] keyword args
+        # @return [RequestObject, Hash, Struct]
         def new(*args, **kwargs)
           return super(*args, **kwargs) if InteractorSupport.configuration.request_object_behavior == :returns_self
 
           super(*args, **kwargs).to_context
         end
 
-        # Accepts one or more attribute names along with options.
+        ##
+        # Defines one or more attributes with optional coercion, default values, transformation,
+        # and an optional `rewrite:` key to rename the underlying attribute.
+        #
+        # @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
         #
-        # Options:
-        #   - type: a class to cast the value (often another RequestObject)
-        #   - array: when true, expects an array; each element is cast.
-        #   - default: default value for the attribute.
-        #   - transform: a symbol or an array of symbols that will be applied (if the value responds to them).
-        def attribute(*names, type: nil, array: false, default: nil, transform: nil)
+        # @raise [ArgumentError] if a transform method is not found
+        def attribute(*names, type: nil, array: false, default: nil, transform: nil, rewrite: nil)
           names.each do |name|
-            transform_options[name.to_sym] = transform if transform.present?
-            super(name, default: default)
-            original_writer = instance_method("#{name}=")
-            define_method("#{name}=") do |value|
-              # Apply transforms immediately if provided.
+            attr_name = rewrite || name
+            rewritten_attributes[name.to_sym] = attr_name if rewrite
+            transform_options[attr_name.to_sym] = transform if transform.present?
+
+            super(attr_name, default: default)
+            original_writer = instance_method("#{attr_name}=")
+
+            define_method("#{attr_name}=") do |value|
               if transform
                 Array(transform).each do |method|
                   if value.respond_to?(method)
@@ -62,25 +135,64 @@ module InteractorSupport
                   end
                 end
               end
-              # Type: only wrap if not already an instance.
+
+              # If a `type` is specified, we attempt to cast the `value` to that type
               if type
-                value = if array
-                  Array(value).map { |v| v.is_a?(type) ? v : type.new(v) }
-                else
-                  value.is_a?(type) ? value : type.new(value)
-                end
+                value = array ? Array(value).map { |v| cast_value(v, type) } : cast_value(value, type)
               end
+
               original_writer.bind(self).call(value)
             end
           end
         end
 
+        ##
+        # Internal map of external attribute names to internal rewritten names.
+        #
+        # @return [Hash{Symbol => Symbol}]
+        def rewritten_attributes
+          @_rewritten_attributes ||= {}
+        end
+
         private
 
+        ##
+        # Internal storage for transform options per attribute.
+        #
+        # @return [Hash{Symbol => Symbol, Array<Symbol>}]
         def transform_options
           @_transform_options ||= {}
         end
       end
+
+      private
+
+      def cast_value(value, type)
+        return typecast(value, type) if type.is_a?(Symbol)
+        return value if value.is_a?(type)
+        return type.new(value) if type <= InteractorSupport::RequestObject
+
+        typecast(value, type)
+      end
+
+      def typecast(value, type)
+        if type.is_a?(Symbol)
+          ActiveModel::Type.lookup(type).cast(value)
+        elsif type == Symbol
+          value.to_sym
+        elsif type == Array
+          value.to_a
+        elsif type == Hash
+          value.to_h
+        else
+          raise TypeError
+        end
+      rescue ArgumentError
+        message = ":#{type} is not a supported type. Supported types are: #{SUPPORTED_TYPES.join(", ")}"
+        raise TypeError, message
+      rescue
+        raise TypeError, "Cannot cast #{value.inspect} to #{type.name}"
+      end
     end
   end
 end

data/lib/interactor_support/validations.rb

@@ -1,6 +1,29 @@
 require 'active_model'
 
 module InteractorSupport
+  ##
+  # Provides context-aware validation DSL for interactors.
+  #
+  # 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.
+  #
+  # @example Required attributes with ActiveModel rules
+  #   required :email, :name
+  #   required age: { numericality: { greater_than: 18 } }
+  #
+  # @example Optional attributes with presence/format validations
+  #   optional bio: { length: { maximum: 500 } }
+  #
+  # @example Type and inclusion validation before execution
+  #   validates_before :role, type: String, inclusion: { in: %w[admin user guest] }
+  #
+  # @example Persistence validation after execution
+  #   validates_after :user, persisted: true
+  #
+  # @see ActiveModel::Validations
   module Validations
     extend ActiveSupport::Concern
     include InteractorSupport::Core
@@ -11,14 +34,35 @@ module InteractorSupport
     end
 
     class_methods do
+      ##
+      # 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`.
+      #
+      # @param keys [Array<Symbol, Hash>] attribute names or hash of attributes with validation options
       def required(*keys)
         apply_validations(keys, required: true)
       end
 
+      ##
+      # Declares one or more attributes as optional.
+      #
+      # Optional values can be nil, but still support validation rules.
+      #
+      # @param keys [Array<Symbol, Hash>] attribute names or hash of attributes with validation options
       def optional(*keys)
         apply_validations(keys, required: false)
       end
 
+      ##
+      # Runs additional validations *after* the interactor executes.
+      #
+      # Useful for checking persisted records, custom conditions, or results
+      # that depend on post-processing logic.
+      #
+      # @param keys [Array<Symbol>] context keys to validate
+      # @param validations [Hash] validation options (e.g., presence:, type:, inclusion:, persisted:)
       def validates_after(*keys, **validations)
         after do
           keys.each do |key|
@@ -27,6 +71,15 @@ module InteractorSupport
         end
       end
 
+      ##
+      # Runs validations *before* the interactor executes.
+      #
+      # Prevents invalid data from reaching business logic.
+      #
+      # NOTE: `persisted:` validation is only available in `validates_after`.
+      #
+      # @param keys [Array<Symbol>] context keys to validate
+      # @param validations [Hash] validation options (e.g., presence:, type:, inclusion:)
       def validates_before(*keys, **validations)
         before do
           if validations[:persisted]
@@ -41,6 +94,11 @@ module InteractorSupport
 
       private
 
+      ##
+      # Applies ActiveModel-based validations and wires up accessors to context.
+      #
+      # @param keys [Array<Symbol, Hash>] attributes to validate
+      # @param required [Boolean] whether presence is enforced
       def apply_validations(keys, required:)
         keys.each do |key|
           if key.is_a?(Hash)
@@ -61,18 +119,27 @@ module InteractorSupport
             validates(key, presence: true) if required
           end
         end
-        # Ensure validations run before execution
+
         before do
           context.fail!(errors: errors.full_messages) unless valid?
         end
       end
 
+      ##
+      # Defines methods to read/write from the interactor context.
+      #
+      # @param key [Symbol] the context key
       def define_context_methods(key)
         define_method(key) { context[key] }
         define_method("#{key}=") { |value| context[key] = value }
       end
     end
 
+    ##
+    # Applies custom inline validations to a context key.
+    #
+    # @param key [Symbol] the context key
+    # @param validations [Hash] options like presence:, type:, inclusion:, persisted:
     def apply_custom_validations(key, validations)
       validation_for_presence(key) if validations[:presence]
       validation_for_inclusion(key, validations[:inclusion]) if validations[:inclusion]
@@ -80,10 +147,20 @@ module InteractorSupport
       validation_for_type(key, validations[:type]) if validations[:type]
     end
 
+    ##
+    # Fails if context value is not of expected type.
+    #
+    # @param key [Symbol]
+    # @param type [Class]
     def validation_for_type(key, type)
       context.fail!(errors: ["#{key} was not of type #{type}"]) unless context[key].is_a?(type)
     end
 
+    ##
+    # Fails if value is not included in allowed values.
+    #
+    # @param key [Symbol]
+    # @param inclusion [Hash] with `:in` key
     def validation_for_inclusion(key, inclusion)
       unless inclusion.is_a?(Hash) && inclusion[:in].is_a?(Enumerable)
         raise ArgumentError, 'inclusion validation requires an :in key with an array or range'
@@ -94,23 +171,26 @@ module InteractorSupport
       context.fail!(errors: [e.message])
     end
 
+    ##
+    # Fails if value is nil or blank.
+    #
+    # @param key [Symbol]
     def validation_for_presence(key)
       context.fail!(errors: ["#{key} does not exist"]) unless context[key].present?
     end
 
+    ##
+    # Fails if value is not a persisted `ApplicationRecord`.
+    #
+    # @param key [Symbol]
     def validation_for_persistence(key)
       validation_for_presence(key)
+
       unless context[key].is_a?(ApplicationRecord)
-        context.fail!(
-          errors: [
-            "#{key} is not an ApplicationRecord, which is required for persisted validation",
-          ],
-        )
+        context.fail!(errors: ["#{key} is not an ApplicationRecord, which is required for persisted validation"])
       end
 
-      context.fail!(
-        errors: ["#{key} was not persisted"] + context[key].errors.full_messages,
-      ) unless context[key].persisted?
+      context.fail!(errors: ["#{key} was not persisted"] + context[key].errors.full_messages) unless context[key].persisted?
     end
   end
 end

data/lib/interactor_support/version.rb

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