interactor_support 1.0.2 → 1.0.3

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/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

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