interactor_support 1.0.2 → 1.0.4

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,344 +348,307 @@ 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.
+
+## InteractorSupport::Organizable
+
+The Organizable concern provides utility methods to simplify working with interactors and request objects. It gives you a clean and consistent pattern for extracting, transforming, and preparing parameters for use in service objects or interactors.
+
+Features
+
+- organize: Call interactors with request objects, optionally namespaced under a context_key.
+- request_params: Extract, shape, filter, rename, flatten, and merge incoming params in a clear and declarative way.
+- Built for controllers or service entry points.
+- Rails-native feel — works seamlessly with strong params.
+
+#### API Reference
+
+**#organize(interactor, params:, request_object:, context_key: nil)**
+Calls the given interactor with a request object built from the provided params.
+
+| Argument       | Type          | Description                                                                 |
+| -------------- | ------------- | --------------------------------------------------------------------------- |
+| interactor     | Class         | The interactor to call (.call must be defined).                             |
+| params         | Hash          | Parameters passed to the request object.                                    |
+| request_object | Class         | A request object class that accepts params in its initializer.              |
+| context_key    | Symbol or nil | Optional key to namespace the request object inside the interactor context. |
+
+Examples
+
+```rb
+organize(MyInteractor, params: request_params, request_object: MyRequest)
+
+# => MyInteractor.call(MyRequest.new(params))
+
+organize(MyInteractor, params: request_params, request_object: MyRequest, context_key: :request)
+
+# => MyInteractor.call({ request: MyRequest.new(params) })
+```
+
+#### #request_params(\*top_level_keys, merge: {}, except: [], rewrite: [])
+
+Returns a shaped parameter hash derived from params.permit!. You can extract specific top-level keys, rename them, flatten values, apply defaults, and remove unwanted fields.
+
+| Argument          | Type                             | Description                                                               |
+| ----------------- | -------------------------------- | ------------------------------------------------------------------------- |
+| `*top_level_keys` | `Symbol...`                      | Optional list of top-level keys to include. If omitted, includes all.     |
+| `merge:`          | `Hash`                           | Extra values to merge into the result.                                    |
+| `except:`         | `Array<Symbol or Array<Symbol>>` | Keys or nested key paths to exclude.                                      |
+| `rewrite:`        | `Array<Hash>`                    | Rules for renaming, flattening, filtering, merging, or defaulting values. |
+
+Rewrite Options
+
+Each rewrite entry is a hash in the form { key => options }, where options may include:
+| Option | Type | Description |
+|-----------|---------------------------|-------------------------------------------------------------------|
+| `as` | `Symbol` | Rename the key to a new top-level key. |
+| `only` | `Array<Symbol>` | Include only these subkeys in the result. |
+| `except` | `Array<Symbol>` | Remove these subkeys from the result. |
+| `flatten` | `true` or `Array<Symbol>` | Flatten all subkeys into top-level (or just the specified ones). |
+| `default` | `Hash` | Use this value if the original key is missing or nil. |
+| `merge` | `Hash` | Merge this hash into the result (after filtering and flattening). |
+
+Example: full usage
+
+```rb
+# Incoming params:
+params = {
+  order: {
+    product_id: 1,
+    quantity: 2,
+    internal: "should be removed"
+  },
+  metadata: {
+    source: "mobile",
+    internal: "hidden",
+    location: { ip: "1.2.3.4" }
+  },
+  flags: {
+    foo: true
+  },
+  internal: "global_internal",
+  session: nil
+}
+
+# Incantation:
+request_params(:order, :metadata, :flags, :session,
+  merge: { user: current_user }, # <- Add the user
+  except: [[:order, :internal], :internal], # <- remove `order.internal`, and the top level key `internal`
+  rewrite: [
+    { order: { flatten: true } }, # <- moves all the values from order to top level keys
+    { metadata: { as: :meta, only: [:source, :location], flatten: [:location] } }, # <- Rename metadata to meta, pluck source and location, move location's values to meta
+    { flags: { merge: { debug: true } } }, # <- add flags.debug = true
+    { session: { default: { id: nil } } } # <- create a default value for session
+  ]
+)
+
+# Result
+{
+  product_id: 1,
+  quantity: 2,
+  meta: {
+    source: "mobile",
+    ip: "1.2.3.4"
+  },
+  flags: {
+    foo: true,
+    debug: true
+  },
+  session: {
+    id: nil
+  },
+  user: current_user
+}
+```
+
+⚠️ Array flattening is not supported
+
+Flattening arrays of hashes (e.g., { events: [{ id: 1 }] }) is intentionally not supported to avoid accidental key collisions. If needed, transform such structures manually before passing to request_params.
+
+**Usage**
+
+Include in a controller or service base class
+
+```rb
+class ApplicationController < ActionController::Base
+  include InteractorSupport::Concerns::Organizable
 end
 ```