interactor_support 1.0.2 → 1.0.3

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.3'
 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.3
 platform: ruby
 authors:
 - Charlie Mitchell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-28 00:00:00.000000000 Z
+date: 2025-04-04 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