interactor_support 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99b9bd6793db476faba16087e24a939982b13974853c2a022e865e011509b143
-  data.tar.gz: 6980cdf3351816cbd8209825c03b58b82c195ac21c337d0638223a97c68814f8
+  metadata.gz: 2b479b98d9029e0865ab4526efcc08ec47736ecba96547d2ab9be294f54d2880
+  data.tar.gz: 74f5d2a0024afb6b7c49ff153a339d6373d25072d37e546827407e65cfd0bc8d
 SHA512:
-  metadata.gz: ce6d5d43e59d7a70b8fa5e2183da93fc52644de5b12c796cf9b617e5a5eb5d78b32439e884cc40860e1bf2e7da6d1a926b58f9ed3257d2ced5ceb77a00c75715
-  data.tar.gz: 940bafa5fbf6d6178b0c8f5f603ff37995c178511aab9cb50d12acc15492a9ace497dbd1e66b76c12fbc3e6943d41d97a9ec557d5451bd3bb6e741e590316194
+  metadata.gz: e1d24d1b7fe20316f26d14f029387d90e1c88e2dc9654500dd40ae9546e030121efcb5de991d091b752308f0f976533a4dabaebc3cb2bebc269b7f5ca70ab7d3
+  data.tar.gz: 32c320144c9f90dc53769bd104a308d17ce663e8618cc0f55f8435d89835ed3aa2cb3049df023422de0d34068ced12795e12127e8eb976f18a3db8a56c0e759a

data/.prettierignore

@@ -0,0 +1 @@
+.yardopts

data/.yardopts

@@ -0,0 +1,19 @@
+lib/interactor_support.rb
+lib/interactor_support/**/*.rb
+
+--title
+InteractorSupport Documentation
+
+--markup
+markdown
+
+--no-private
+--no-yardopts
+
+--exclude
+bin/
+spec/
+test/
+config/
+db/
+vendor/

data/CHANGELOG.md

@@ -7,3 +7,13 @@
 ## [1.0.1] - 2025-03-26
 
 - Removed runtime requirements for rails and interactor.
+
+## [1.0.2] - 2025-03-28
+
+- Added support for mixing symbols and procs in the transformable concern
+
+## [1.0.3] - 2025-04-02
+
+- Added support for rewriting attribute names in a request object
+- Better support for type coersion, using Active model + Array, Hash, and Symbol
+- Better support for `AnyClass` type validations

data/README.md

@@ -28,7 +28,7 @@ Make your **Rails interactors** clean, powerful, and less error-prone!
 Add to your Gemfile:
 
 ```sh
-bundle add interactor_support
+gem 'interactor_support', '~> 1.0', '>= 1.0.1'
 ```
 
 Or install manually:
@@ -84,7 +84,7 @@ class UpdateTodoTitle
   include Interactor
   include InteractorSupport
 
-  requires :todo_id, :title
+  required :todo_id, :title
   transform :title, with: :strip
   find_by :todo, query: { id: :todo_id }, required: true
   update :todo, attributes: { title: :title }
@@ -110,7 +110,7 @@ class CompleteTodo
   include InteractorSupport
 
   transaction
-  requires :todo_id
+  required :todo_id
   find_by :todo, query: { id: :todo_id }, required: true
 
   update :todo, attributes: {
@@ -133,7 +133,7 @@ class CompleteTodo
   include InteractorSupport
 
   transaction
-  requires :todo
+  required :todo
   skip if: -> { todo.completed? }
   update :todo, attributes: { completed: true, completed_at: -> { Time.current } }
 end
@@ -235,10 +235,53 @@ find_where :post, where: { user_id: :user_id }, context_key: :user_posts
 
 Provides `transform` to **sanitize and normalize inputs**.
 
+```rb
+# any method that the attribute responds to will work
+transform :title, with: :strip
+
+# You can chain transformers on an attribute
+# show_the_thing == "1" => "1".to_i.positive? => true
+transform :show_the_thing, with: [:to_i, :positive?]
+
+# transforming a string to a boolean using a lambda, eg: "true" => true
+transform :my_param, with: -> (val) { ActiveModel::Type::Boolean.new.cast(val) }
+
+# added in 1.0.2
+# mixing symbols and keys. eg: " True     " => true
+transform :my_param, with: [
+  :strip,
+  :downcase,
+  -> (val) { ActiveModel::Type::Boolean.new.cast(val) }
+]
+
+```
+
 #### 🔹 **`InteractorSupport::Concerns::Skippable`**
 
 Allows an interactor to **skip execution** if a condition is met.
 
+```rb
+# skips execution
+skip if: true
+# skips execution when a lambda is passed
+skip if: -> { true }
+# using a method
+skip if: :some_method?
+# using a context variable
+skip if: :condition
+
+# Using `unless`
+
+# skips execution
+skip unless: false
+# skips execution when a lambda is passed
+skip unless: -> { false }
+# using a method
+skip unless: :some_method?
+# using a context variable
+skip unless: :condition
+```
+
 #### 🔹 **`InteractorSupport::Validations`**
 
 Provides **automatic input validation** before execution. This includes `ActiveModel::Validations` and
@@ -272,7 +315,217 @@ If any validation fails, context.fail!(errors: errors.full_messages) will automa
 
 #### 🔹 **`InteractorSupport::RequestObject`**
 
-Provides structured, validated request objects based on **ActiveModel**.
+A flexible, form-like abstraction for service object inputs, built on top of ActiveModel. InteractorSupport::RequestObject extends ActiveModel::Model and ActiveModel::Validations to provide structured, validated, and transformed input objects. It adds first-class support for nested objects, type coercion, attribute transformation, and array handling. It's ideal for use with any architecture that benefits from strong input modeling.
+
+_RequestObject Enforces Input Integrity, and 🔐 allow-lists attributes by default_
+
+**Features**
+
+- Define attributes with types and transformation pipelines
+- Supports primitive and custom object types
+- Deeply nested input coercion and validation
+- Array support for any type
+- Auto-generated context hashes or structs
+- Key rewriting for internal/external mapping
+- Full ActiveModel validation support
+
+Rather than manually massaging and validating hashes or params in your services, define intent-driven objects that:
+
+- clean incoming values
+- validate data structure and content
+- expose clean interfaces for business logic
+
+🚀 Getting Started
+
+1. Define a Request Object
+
+```rb
+class GenreRequest
+  include InteractorSupport::RequestObject
+
+  attribute :title, transform: :strip
+  attribute :description, transform: :strip
+
+  validates :title, :description, presence: true
+end
+```
+
+2. Use it in your Interactor, Service, or Controller
+
+```rb
+class GenresController < ApplicationController
+  def create
+    context = SomeOrganizerForCreatingGenres.call(
+      GenreRequest.new(params.permit!) # 😉 request objects are a safe and powerful replacement for strong params
+    )
+
+    # render context.genre & handle success? vs failure?
+  end
+end
+```
+
+## Attribute Features
+
+#### Transformations:
+
+Apply one or more transformations when values are assigned.
+
+```rb
+attribute :email, transform: [:strip, :downcase]
+```
+
+- You can use any transform that the value can `respond_to?`
+- Define custom transforms as instance methods.
+
+Type Casting:
+Cast inputs to expected types automatically:
+
+```rb
+attribute :age, type: :integer
+attribute :tags, type: :string, array: true
+attribute :config, type: Hash
+attribute :published_at, type: :datetime
+attribute :user, type: User
+```
+
+If the value is already of the expected type, it will just pass through. Otherwise, it will try to cast it.
+If casting fails, or you specify an unsupported type, it will raise an `InteractorSupport::RequestObject::TypeError`
+
+Supported types are
+
+- Any ActiveModel::Type, provided as a symbol.
+- The following primitives, Array, Hash, Symbol
+- RequestObject subclasses (for nesting request objects)
+
+#### Nesting Request Objects
+
+```rb
+class AuthorRequest
+  include InteractorSupport::RequestObject
+
+  attribute :name
+  attribute :location, type: LocationRequest
+end
+
+class PostRequest
+  include InteractorSupport::RequestObject
+
+  attribute :authors, type: AuthorRequest, array: true
+end
+```
+
+Nested objects are instantiated recursively and validated automatically.
+
+## Rewrite Keys
+
+Rename external keys for internal use.
+
+```rb
+attribute :image, rewrite: :image_url, transform: :strip
+
+request = ImageUploadRequest.new(image: '  https://url.com  ')
+request.image_url # => "https://url.com"
+request.respond_to?(:image) # => false
+```
+
+## to_context Output
+
+Return a nested Hash, Struct, or self:
+
+```rb
+# Default
+PostRequest.new(authors: [{ name: "Ruby", location: { city: "Seattle" }}])
+# returns a hash with symbol keys => {:authors=>[{:name=>"Ruby", :location=>{:city=>"Seattle"}}]}
+
+# Configure globally
+InteractorSupport.configure do |config|
+  config.request_object_behavior = :returns_context # or :returns_self
+  config.request_object_key_type = :symbol # or :string, :struct
+end
+
+# request_object_behavior = :returns_context, request_object_key_type = :string
+PostRequest.new(authors: [{ name: "Ruby", location: { city: "Seattle" }}])
+# returns a hash with string keys => {"authors"=>[{"name"=>"Ruby", "location"=>{"city"=>"Seattle"}}]}
+
+# request_object_behavior = :returns_context, request_object_key_type = :struct
+PostRequest.new(authors: [{ name: "Ruby", location: { city: "Seattle" }}])
+# returns a Struct => #<struct  authors=[{:name=>"Ruby", :location=>{:city=>"Seattle"}}]>
+
+# request_object_behavior = :returns_self, request_object_key_type = :symbol
+request = PostRequest.new(authors: [{ name: "Ruby", location: { city: "Seattle" }}])
+# returns the request object => #<PostRequest  authors=[{:name=>"Ruby", :location=>{:city=>"Seattle"}}]>
+# request.authors.first.location.city => "Seattle"
+# request.to_context => {:authors=>[{:name=>"Ruby", :location=>{:city=>"Seattle"}}]}
+```
+
+🛡 Replacing Strong Parameters Safely
+
+InteractorSupport::RequestObject is a safe, testable, and expressive alternative to Rails’ strong_parameters. While strong_params are great for sanitizing controller input, they tend to:
+
+- Leak into your business logic
+- Lack structure and type safety
+- Require repetitive permit/require declarations
+- Get clumsy with nesting and arrays
+
+Instead, RequestObject defines the expected shape and behavior of input once, and gives you:
+
+- Input sanitization via transform:
+- Validation via ActiveModel
+- Type coercion (including arrays and nesting)
+- Reusable, composable input classes
+
+StrongParams Example
+
+```rb
+def user_params
+  params.require(:user).permit(:name, :email, :age)
+end
+
+def create
+  user = User.new(user_params)
+  ...
+end
+```
+
+Even with this, you still have to:
+• Validate formats (like email)
+• Coerce types (:age is still a string!)
+• Repeat this logic elsewhere
+
+**Request Object Equivelent**
+
+```rb
+class UserRequest
+  include InteractorSupport::RequestObject
+
+  attribute :name, transform: :strip
+  attribute :email, transform: [:strip, :downcase]
+  attribute :age, type: :integer # or transform: [:to_i]
+
+  validates :name, presence: true
+  validates_format_of :email, with: URI::MailTo::EMAIL_REGEXP
+end
+```
+
+**Why replace Strong Params?**
+| Feature | Strong Params | Request Object |
+|----------------------------------|---------------------|----------------------|
+| Requires manual permit/require | ✅ Yes | ❌ Not needed |
+| Validates types/formats | ❌ No | ✅ Yes |
+| Handles nested objects | 😬 With effort | ✅ First-class support |
+| Works outside controllers | ❌ Not cleanly | ✅ Perfect for services/interactors |
+| Self-documenting input shape | ❌ No | ✅ Defined via attribute DSL |
+| Testable as a unit | ❌ Not directly | ✅ Easily tested like a form object |
+
+💡 Tip
+
+You can still use params.require(...).permit(...) in the controller if you want to restrict top-level keys, then pass that sanitized hash to your RequestObject:
+
+```rb
+UserRequest.new(params.require(:user).permit(:name, :email, :age))
+```
+
+But with RequestObject, that’s often unnecessary because you’re already defining a schema.
 
 ## 🤝 **Contributing**
 

data/lib/interactor_support/actions.rb

@@ -1,4 +1,35 @@
+# 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:
+  #
+  # - {Skippable} — Conditionally skip execution
+  # - {Transactionable} — Wrap logic in an ActiveRecord transaction
+  # - {Updatable} — Update records using context-driven attributes
+  # - {Findable} — Find one or many records into context
+  # - {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

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