interactor_support 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9389f81b3832c245eac6c1f850a1b55c6baaebbc01be44eccd8d4f31c45bc731
-  data.tar.gz: c3ee7cd401d9d744e51208bc9763cb417e25410e4e2797bb51676aece17ffeec
+  metadata.gz: 2b479b98d9029e0865ab4526efcc08ec47736ecba96547d2ab9be294f54d2880
+  data.tar.gz: 74f5d2a0024afb6b7c49ff153a339d6373d25072d37e546827407e65cfd0bc8d
 SHA512:
-  metadata.gz: 67218c44b1b89e1173abba43d298742eaa2bf59d7a884c5e65017c855f80a4ace05a2423232325395085f8e70c9d7f981e6ef39d267368e9eaf7c2c32fb7e57e
-  data.tar.gz: 0c8ff1bac440c0cd7f07d4e3f9463109986ce92240aaa5725e5d405f21c62040d6ea7509e1de2b951184db39cef977c181f01c73ed69895e599b67dda093628c
+  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

@@ -11,3 +11,9 @@
 ## [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

@@ -315,9 +315,29 @@ 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.
 
-For now, here's the specs:
+_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
@@ -328,347 +348,185 @@ class GenreRequest
 
   validates :title, :description, presence: true
 end
+```
 
-class LocationRequest
-  include InteractorSupport::RequestObject
-
-  attribute :city, transform: [:downcase, :strip]
-  attribute :country_code, transform: [:strip, :upcase]
-  attribute :state_code, transform: [:strip, :upcase]
-  attribute :postal_code, transform: [:strip, :clean_postal_code]
-  attribute :address, transform: :strip
+2. Use it in your Interactor, Service, or Controller
 
-  validates :city, :postal_code, :address, presence: true
-  validates :country_code, :state_code, presence: true, length: { is: 2 }
+```rb
+class GenresController < ApplicationController
+  def create
+    context = SomeOrganizerForCreatingGenres.call(
+      GenreRequest.new(params.permit!) # 😉 request objects are a safe and powerful replacement for strong params
+    )
 
-  def clean_postal_code(value)
-    value.to_s.gsub(/\D/, '')
-    value.first(5)
+    # 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, transform: :strip
-  attribute :email, transform: [:strip, :downcase]
-  attribute :age, transform: :to_i
+  attribute :name
   attribute :location, type: LocationRequest
-  validates_format_of :email, with: URI::MailTo::EMAIL_REGEXP
 end
 
 class PostRequest
   include InteractorSupport::RequestObject
 
-  attribute :user_id
-  attribute :title, transform: :strip
-  attribute :content, transform: :strip
-  attribute :genre, type: GenreRequest
   attribute :authors, type: AuthorRequest, array: true
 end
+```
 
-RSpec.describe(InteractorSupport::RequestObject) do
-  describe 'attribute transformation' do
-    before do
-      InteractorSupport.configure do |config|
-        config.request_object_behavior = :returns_self
-      end
-    end
-    context 'when using a single transform' do
-      it 'strips the value for a symbol transform' do
-        genre = GenreRequest.new(title: '  Science Fiction  ', description: ' A genre of speculative fiction  ')
-        expect(genre.title).to(eq('Science Fiction'))
-        expect(genre.description).to(eq('A genre of speculative fiction'))
-      end
-    end
-
-    context 'when using an array of transforms' do
-      it 'applies all transform methods in order' do
-        buyer = LocationRequest.new(
-          city: '  New York  ',
-          country_code: '  us  ',
-          state_code: '  ny  ',
-          postal_code: '  10001-5432  ',
-          address: '  123 Main St.  ',
-        )
-        expect(buyer.city).to(eq('new york'))
-        expect(buyer.country_code).to(eq('US'))
-        expect(buyer.state_code).to(eq('NY'))
-        expect(buyer.postal_code).to(eq('10001'))
-        expect(buyer.address).to(eq('123 Main St.'))
-      end
-    end
-
-    context 'when the value does not respond to a transform method' do
-      it 'raises and argument error if the transform method is not defined' do
-        class DummyRequest
-          include InteractorSupport::RequestObject
-          attribute :number, transform: :strip
-          validates :number, presence: true
-        end
-
-        expect { DummyRequest.new(number: 1234) }.to(raise_error(ArgumentError))
-      end
-    end
-  end
+Nested objects are instantiated recursively and validated automatically.
 
-  describe 'nesting request objects and array support' do
-    before do
-      InteractorSupport.configure do |config|
-        config.request_object_behavior = :returns_self
-      end
-    end
-    context 'when using a type without array' do
-      it "wraps the given hash in the type's new instance" do
-        post = PostRequest.new(
-          user_id: 1,
-          title: '  My First Post  ',
-          content: '  This is the content of my first post  ',
-          genre: { title: '  Science Fiction  ', description: ' A genre of speculative fiction  ' },
-          authors: [
-            {
-              name: '  John Doe  ',
-              email: 'me@mail.com',
-              age: '  25  ',
-              location: {
-                city: '  New York  ',
-                country_code: '  us  ',
-                state_code: '  ny  ',
-                postal_code: '  10001-5432  ',
-                address: '  123 Main St.  ',
-              },
-            },
-            {
-              name: '  Jane Doe  ',
-              email: 'you@mail.com',
-              age: '  25  ',
-              location: {
-                city: '  Los Angeles  ',
-                country_code: '  us  ',
-                state_code: '  ca  ',
-                postal_code: '  90001  ',
-                address: '  456 Elm St.  ',
-              },
-            },
-          ],
-        )
-
-        expect(post).to(be_valid)
-        expect(post.user_id).to(eq(1))
-        expect(post.title).to(eq('My First Post'))
-        expect(post.content).to(eq('This is the content of my first post'))
-        expect(post.genre).to(be_a(GenreRequest))
-        expect(post.genre.title).to(eq('Science Fiction'))
-        expect(post.genre.description).to(eq('A genre of speculative fiction'))
-        expect(post.authors).to(be_an(Array))
-        expect(post.authors.size).to(eq(2))
-        post.authors.each do |author|
-          expect(author).to(be_a(AuthorRequest))
-          expect(author).to(be_valid)
-          expect(author.location).to(be_a(LocationRequest))
-          expect(author.location).to(be_valid)
-          expect(author.location.city).to(be_in(['new york', 'los angeles']))
-          expect(author.location.country_code).to(eq('US'))
-          expect(author.location.state_code).to(be_in(['NY', 'CA']))
-          expect(author.location.postal_code).to(be_in(['10001', '90001']))
-          expect(author.location.address).to(be_in(['123 Main St.', '456 Elm St.']))
-        end
-      end
-    end
-  end
+## Rewrite Keys
 
-  describe 'to_context' do
-    before do
-      InteractorSupport.configure do |config|
-        config.request_object_behavior = :returns_self
-      end
-    end
-    it 'returns a struct and includes nested attributes' do
-      context = PostRequest.new(
-        user_id: 1,
-        title: '  My First Post  ',
-        content: '  This is the content of my first post  ',
-        genre: { title: '  Science Fiction  ', description: ' A genre of speculative fiction  ' },
-        authors: [
-          {
-            name: '  John Doe  ',
-            email: 'a@b.com',
-            age: '  25  ',
-            location: {
-              city: '  New York  ',
-              country_code: '  us  ',
-              state_code: '  ny  ',
-              postal_code: '  10001-5432  ',
-              address: '  123 Main St.  ',
-            },
-          },
-        ],
-      ).to_context
-
-      expect(context).to(be_a(Hash))
-      expect(context[:user_id]).to(eq(1))
-      expect(context[:title]).to(eq('My First Post'))
-      expect(context[:content]).to(eq('This is the content of my first post'))
-      expect(context[:genre]).to(be_a(Hash))
-      expect(context.dig(:genre, :title)).to(eq('Science Fiction'))
-      expect(context.dig(:genre, :description)).to(eq('A genre of speculative fiction'))
-      expect(context[:authors]).to(be_an(Array))
-      expect(context[:authors].size).to(eq(1))
-      author = context[:authors].first
-      expect(author).to(be_a(Hash))
-      expect(author[:name]).to(eq('John Doe'))
-      expect(author[:email]).to(eq('a@b.com'))
-      expect(author[:age]).to(eq(25))
-      expect(author[:location]).to(be_a(Hash))
-      expect(author[:location][:city]).to(eq('new york'))
-      expect(author[:location][:country_code]).to(eq('US'))
-    end
-  end
+Rename external keys for internal use.
 
-  describe 'configured request object behavior' do
-    it 'returns a context hash with symbol keys when configured to do so' do
-      InteractorSupport.configure do |config|
-        config.request_object_behavior = :returns_context
-        config.request_object_key_type = :symbol
-      end
-
-      context = PostRequest.new(
-        user_id: 1,
-        title: '  My First Post  ',
-        content: '  This is the content of my first post  ',
-        genre: { title: '  Science Fiction  ', description: ' A genre of speculative fiction  ' },
-        authors: [
-          {
-            name: '  John Doe  ',
-            email: 'j@j.com',
-            age: '  25  ',
-            location: {
-              city: '  New York  ',
-              country_code: '  us  ',
-              state_code: '  ny  ',
-              postal_code: '  10001-5432  ',
-              address: '  123 Main St.  ',
-            },
-          },
-        ],
-      )
-
-      expect(context).to(be_a(Hash))
-      expect(context[:user_id]).to(eq(1))
-      expect(context[:title]).to(eq('My First Post'))
-      expect(context[:content]).to(eq('This is the content of my first post'))
-      expect(context[:genre]).to(be_a(Hash))
-      expect(context.dig(:genre, :title)).to(eq('Science Fiction'))
-      expect(context.dig(:genre, :description)).to(eq('A genre of speculative fiction'))
-      expect(context[:authors]).to(be_an(Array))
-      expect(context[:authors].size).to(eq(1))
-      author = context[:authors].first
-      expect(author).to(be_a(Hash))
-      expect(author[:name]).to(eq('John Doe'))
-      expect(author[:email]).to(eq('j@j.com'))
-      expect(author[:age]).to(eq(25))
-      expect(author[:location]).to(be_a(Hash))
-      expect(author[:location][:city]).to(eq('new york'))
-      expect(author[:location][:country_code]).to(eq('US'))
-    end
-
-    it 'returns a context hash with string keys when configured to do so' do
-      InteractorSupport.configure do |config|
-        config.request_object_behavior = :returns_context
-        config.request_object_key_type = :string
-      end
-
-      post = PostRequest.new(
-        user_id: 1,
-        title: '  My First Post  ',
-        content: '  This is the content of my first post  ',
-        genre: { title: '  Science Fiction  ', description: ' A genre of speculative fiction  ' },
-        authors: [
-          {
-            name: '  John Doe  ',
-            email: 'j@j.com',
-            age: '  25  ',
-            location: {
-              city: '  New York  ',
-              country_code: '  us  ',
-              state_code: '  ny  ',
-              postal_code: '  10001-5432  ',
-              address: '  123 Main St.  ',
-            },
-          },
-        ],
-      )
-
-      context = post
-      expect(context).to(be_a(Hash))
-      expect(context['user_id']).to(eq(1))
-      expect(context['title']).to(eq('My First Post'))
-      expect(context['content']).to(eq('This is the content of my first post'))
-      expect(context['genre']).to(be_a(Hash))
-      expect(context.dig('genre', 'title')).to(eq('Science Fiction'))
-      expect(context.dig('genre', 'description')).to(eq('A genre of speculative fiction'))
-      expect(context['authors']).to(be_an(Array))
-      expect(context['authors'].size).to(eq(1))
-      author = context['authors'].first
-      expect(author).to(be_a(Hash))
-      expect(author['name']).to(eq('John Doe'))
-      expect(author['email']).to(eq('j@j.com'))
-      expect(author['age']).to(eq(25))
-      expect(author['location']).to(be_a(Hash))
-      expect(author['location']['city']).to(eq('new york'))
-      expect(author['location']['country_code']).to(eq('US'))
-    end
-
-    it 'returns a context struct when configured to do so' do
-      InteractorSupport.configure do |config|
-        config.request_object_behavior = :returns_context
-        config.request_object_key_type = :struct
-      end
-
-      post = PostRequest.new(
-        user_id: 1,
-        title: '  My First Post  ',
-        content: '  This is the content of my first post  ',
-        genre: { title: '  Science Fiction  ', description: ' A genre of speculative fiction  ' },
-        authors: [
-          {
-            name: '  John Doe  ',
-            email: 'j@j.com',
-            age: '  25  ',
-            location: {
-              city: '  New York  ',
-              country_code: '  us  ',
-              state_code: '  ny  ',
-              postal_code: '  10001-5432  ',
-              address: '  123 Main St.  ',
-            },
-          },
-        ],
-      )
-
-      context = post
-      expect(context).to(be_a(Struct))
-      expect(context.user_id).to(eq(1))
-      expect(context.title).to(eq('My First Post'))
-      expect(context.content).to(eq('This is the content of my first post'))
-      expect(context.genre).to(be_a(Struct))
-      expect(context.genre.title).to(eq('Science Fiction'))
-      expect(context.genre.description).to(eq('A genre of speculative fiction'))
-      expect(context.authors).to(be_an(Array))
-      expect(context.authors.size).to(eq(1))
-      author = context.authors.first
-      expect(author).to(be_a(Struct))
-      expect(author.name).to(eq('John Doe'))
-      expect(author.email).to(eq('j@j.com'))
-      expect(author.age).to(eq(25))
-      expect(author.location).to(be_a(Struct))
-      expect(author.location.city).to(eq('new york'))
-      expect(author.location.country_code).to(eq('US'))
-    end
-  end
+```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**
 
 Pull requests are welcome on [GitHub](https://github.com/charliemitchell/interactor_support).

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