interactor_support 1.0.2 → 1.0.4

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|
@@ -25,32 +82,49 @@ module InteractorSupport
             value
           end
         end
+
         return Struct.new(*attrs.keys).new(*attrs.values) if key_type == :struct
 
         attrs
       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 +136,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.2'
+  VERSION = '1.0.4'
 end

data/lib/interactor_support.rb

@@ -12,15 +12,59 @@ require_relative 'interactor_support/configuration'
 
 Dir[File.join(__dir__, 'interactor_support/concerns/*.rb')].sort.each { |file| require file }
 
+##
+# InteractorSupport is a modular DSL for building expressive, validated, and
+# transactional service objects using the [Interactor](https://github.com/collectiveidea/interactor) gem.
+#
+# It enhances interactors with powerful helpers like:
+# - `Actions` for data loading, transformation, and persistence
+# - `Validations` for context-aware presence/type/inclusion checks
+# - `RequestObject` for clean, validated, form-like parameter objects
+#
+# It also provides configuration options to control request object behavior.
+#
+# @example Basic usage
+#   class CreateUser
+#     include Interactor
+#     include InteractorSupport
+#
+#     required :email, :name
+#
+#     transform :email, with: [:strip, :downcase]
+#
+#     find_by :account
+#
+#     update :user, attributes: { email: :email, name: :name }
+#   end
+#
+# @example Configuration
+#   InteractorSupport.configure do |config|
+#     config.request_object_behavior = :returns_self
+#     config.request_object_key_type = :symbol
+#   end
+#
+# @see InteractorSupport::Actions
+# @see InteractorSupport::Validations
+# @see InteractorSupport::RequestObject
+# @see InteractorSupport::Configuration
 module InteractorSupport
   extend ActiveSupport::Concern
 
   class << self
+    ##
+    # Allows external configuration of InteractorSupport.
+    #
+    # @yieldparam config [InteractorSupport::Configuration] the global configuration object
+    # @return [void]
     def configure
       self.configuration ||= Configuration.new
       yield(configuration) if block_given?
     end
 
+    ##
+    # Returns the global InteractorSupport configuration object.
+    #
+    # @return [InteractorSupport::Configuration]
     def configuration
       @configuration ||= Configuration.new
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interactor_support
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.4
 platform: ruby
 authors:
 - Charlie Mitchell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-28 00:00:00.000000000 Z
+date: 2025-04-05 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -17,8 +17,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".prettierignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -28,6 +30,7 @@ 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