interactor_support 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b479b98d9029e0865ab4526efcc08ec47736ecba96547d2ab9be294f54d2880
-  data.tar.gz: 74f5d2a0024afb6b7c49ff153a339d6373d25072d37e546827407e65cfd0bc8d
+  metadata.gz: 4d6d8c9f46a3e48520652cdb83a9257d487a3411feef0b1efd69c1fc4a209c03
+  data.tar.gz: 31b939d573a1dc042b671304ec777bf4a8bf53ad61bd3b4d63fccc3fd4dd2806
 SHA512:
-  metadata.gz: e1d24d1b7fe20316f26d14f029387d90e1c88e2dc9654500dd40ae9546e030121efcb5de991d091b752308f0f976533a4dabaebc3cb2bebc269b7f5ca70ab7d3
-  data.tar.gz: 32c320144c9f90dc53769bd104a308d17ce663e8618cc0f55f8435d89835ed3aa2cb3049df023422de0d34068ced12795e12127e8eb976f18a3db8a56c0e759a
+  metadata.gz: 2cf4e789be122df812109df549d3d94a4cf685af0a85eb3fa3d47e811fc73d2231a4fd5af95a2e3c397505102c363bb831df716f16fe701fa0e2fd33e586e757
+  data.tar.gz: 8d6e5ee59b6c0523d0d7a9931d6b0ee4f1f98c7aa7d87aabfd45f8dcad8b9f7831444030803abc98bf0594b87a9e084cc9285e8f7382dd378f0d68f4fdc79823

data/CHANGELOG.md

@@ -17,3 +17,7 @@
 - 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
+
+## [1.0.4] - 2025-04-05
+
+- Added the organizable concern

data/README.md

@@ -527,6 +527,131 @@ 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
+```
+
 ## 🤝 **Contributing**
 
 Pull requests are welcome on [GitHub](https://github.com/charliemitchell/interactor_support).

data/lib/interactor_support/actions.rb

@@ -7,11 +7,11 @@ module InteractorSupport
   # 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
+  # - {InteractorSupport::Concerns::Skippable} — Conditionally skip execution
+  # - {InteractorSupport::Concerns::Transactionable} — Wrap logic in an ActiveRecord transaction
+  # - {InteractorSupport::Concerns::Updatable} — Update records using context-driven attributes
+  # - {InteractorSupport::Concerns::Findable} — Find one or many records into context
+  # - {InteractorSupport::Concerns::Transformable} — Normalize or modify context values before execution
   #
   # @example Use in an interactor
   #   class UpdateUser
@@ -25,6 +25,7 @@ module InteractorSupport
   #     update :user, attributes: { email: :email }
   #   end
   #
+  #
   # @see InteractorSupport::Concerns::Skippable
   # @see InteractorSupport::Concerns::Transactionable
   # @see InteractorSupport::Concerns::Updatable
@@ -32,6 +33,7 @@ module InteractorSupport
   # @see InteractorSupport::Concerns::Transformable
   module Actions
     extend ActiveSupport::Concern
+
     included do
       include InteractorSupport::Concerns::Skippable
       include InteractorSupport::Concerns::Transactionable

data/lib/interactor_support/concerns/organizable.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module InteractorSupport
+  module Concerns
+    ##
+    # The `Organizable` module provides utility methods for organizing interactors
+    # and shaping request parameters in a structured way.
+    #
+    # It is intended to be included into a controller or a base service class that
+    # delegates to interactors using request objects.
+    #
+    # @example Include in a controller
+    #   class ApplicationController < ActionController::Base
+    #     include InteractorSupport::Organizable
+    #   end
+    #
+    # @see InteractorSupport::Organizable#organize
+    # @see InteractorSupport::Organizable#request_params
+    module Organizable
+      include ActiveSupport::Concern
+
+      # Calls the given interactor with a request object.
+      # Optionally wraps the request object under a key in the interactor context.
+      #
+      # @param interactor [Class] The interactor class to call.
+      # @param params [Hash] Parameters to initialize the request object.
+      # @param request_object [Class] A request object class that responds to `#new(params)`.
+      # @param context_key [Symbol, nil] Optional key to assign the request object under in the context.
+      #
+      # @return [void]
+      #
+      # @example
+      #  organize(MyInteractor, params: request_params, request_object: MyRequest)
+      #  # => Calls MyInteractor with an instance of MyRequest initialized with request_params.
+      #
+      # @example
+      #   organize(MyInteractor, params: request_params, request_object: MyRequest, context_key: :request)
+      #   # => Calls MyInteractor with an instance of MyRequest initialized with request_params at :context_key.
+      #   #   # => The context will contain { request: MyRequest.new(request_params) }
+      def organize(interactor, params:, request_object:, context_key: nil)
+        @context = interactor.call(
+          context_key ? { context_key => request_object.new(params) } : request_object.new(params),
+        )
+      end
+
+      # Builds a structured and optionally transformed parameter hash from Rails' `params`.
+      #
+      # This method supports extracting specific top-level keys, applying optional rewrite
+      # transformations, merging in additional values, and excluding unwanted keys.
+      #
+      # @param top_level_keys [Array<Symbol>] Top-level keys to extract from `params`. If empty, all keys are included.
+      # @param merge [Hash] Additional values to merge into the final result.
+      # @param except [Array<Symbol, Array<Symbol>>] Keys or nested key paths to exclude from the result.
+      # @param rewrite [Array<Hash>] A set of transformation rules applied to the top-level keys.
+      #
+      # @return [Hash] The final, shaped parameters hash.
+      #
+      # @example Extracting a specific top-level key
+      #   # Given: params = { order: { product_id: 1, quantity: 2 } }
+      #   request_params(:order)
+      #   # => { order: { product_id: 1, quantity: 2 } }
+      #
+      # @example Without top-level keys (includes all)
+      #   # Given: params = { order: { product_id: 1 }, app_id: 123 }
+      #   request_params()
+      #   # => { order: { product_id: 1 }, app_id: 123 }
+      #
+      # @example Merging and excluding
+      #   # Given: params = { order: { product_id: 1, quantity: 2 }, internal: "yes" }
+      #   request_params(:order, merge: { user_id: 123 }, except: [[:order, :quantity], :internal])
+      #   # => { order: { product_id: 1 }, user_id: 123 }
+      #
+      # @example Flattening a nested hash into the top-level
+      #   # Given: params = { order: { product_id: 1, quantity: 2 }, app_id: 123 }
+      #   request_params(:order, rewrite: [{ order: { flatten: true } }])
+      #   # => { product_id: 1, quantity: 2 }
+      #
+      # @example Rename a top-level key and filter nested keys
+      #   # Given: params = { metadata: { source: "mobile", internal: "x" } }
+      #   request_params(:metadata, rewrite: [
+      #     { metadata: { as: :meta, only: [:source] } }
+      #   ])
+      #   # => { meta: { source: "mobile" } }
+      #
+      # @example Provide a default value if a key is missing
+      #   # Given: params = {}
+      #   request_params(:session, rewrite: [
+      #     { session: { default: { id: nil } } }
+      #   ])
+      #   # => { session: { id: nil } }
+      #
+      # @example Merge values into a nested structure
+      #   # Given: params = { flags: { foo: true } }
+      #   request_params(:flags, rewrite: [
+      #     { flags: { merge: { debug: true } } }
+      #   ])
+      #   # => { flags: { foo: true, debug: true } }
+      #
+      # @example Combine multiple rewrite rules
+      #   # Given:
+      #   # params = {
+      #   #   order: { product_id: 1, quantity: 2 },
+      #   #   metadata: { source: "mobile", location: { ip: "1.2.3.4" } },
+      #   #   tracking: { click_id: "abc", session_id: "def" }
+      #   # }
+      #   request_params(:order, :metadata, :tracking, rewrite: [
+      #     { order: { flatten: true } },
+      #     { metadata: { as: :meta, only: [:source, :location], flatten: [:location] } }
+      #   ])
+      #   # => {
+      #   #   product_id: 1,
+      #   #   quantity: 2,
+      #   #   meta: { source: "mobile", ip: "1.2.3.4" },
+      #   #   tracking: { click_id: "abc", session_id: "def" }
+      #   # }
+      def request_params(*top_level_keys, merge: {}, except: [], rewrite: [])
+        permitted = params.permit!.to_h.deep_symbolize_keys
+        data = top_level_keys.any? ? permitted.slice(*top_level_keys) : permitted
+
+        apply_rewrites!(data, rewrite)
+
+        data
+          .deep_merge(merge)
+          .then { |result| except.any? ? deep_except(result, except) : result }
+      end
+
+      private
+
+      def apply_rewrites!(data, rewrites)
+        rewrites.each do |rule|
+          key, config = rule.first
+          config = { flatten: true } if config == :flatten
+
+          original = data.key?(key) ? data.delete(key) : nil
+          transformed = original.deep_dup if original.is_a?(Hash)
+          transformed ||= original
+
+          # Filtering
+          transformed.slice!(*config[:only]) if config[:only] && transformed.respond_to?(:slice!)
+          transformed.except!(*config[:except]) if config[:except] && transformed.respond_to?(:except!)
+
+          # Flatten specific nested keys
+          if config[:flatten].is_a?(Array) && transformed.is_a?(Hash)
+            config[:flatten].each do |subkey|
+              nested = transformed.delete(subkey)
+              if nested.is_a?(Hash)
+                transformed.merge!(nested)
+              elsif nested.is_a?(Array)
+                raise ArgumentError,
+                  "Cannot flatten array for the key `#{subkey}`. Flattening arrays of hashes is not supported."
+              end
+            end
+          end
+
+          # Apply default if nil or missing
+          transformed ||= config[:default]
+
+          # Merge additional keys
+          if config[:merge]
+            transformed = transformed.is_a?(Hash) ? transformed.merge(config[:merge]) : config[:merge]
+          end
+
+          # Fully flatten to top level
+          if config[:flatten] == true && transformed.is_a?(Hash)
+            data.merge!(transformed)
+          else
+            target_key = config[:as] || key
+            data[target_key] = transformed
+          end
+        end
+      end
+
+      def deep_except(hash, paths)
+        paths.reduce(hash) { |acc, path| remove_nested_key(acc, Array(path)) }
+      end
+
+      def remove_nested_key(hash, path)
+        return hash unless path.is_a?(Array) && path.any?
+
+        key, *rest = path
+        return hash unless hash.key?(key)
+
+        duped = hash.dup
+        if rest.empty?
+          duped.delete(key)
+        elsif duped[key].is_a?(Hash)
+          duped[key] = remove_nested_key(duped[key], rest)
+        end
+
+        duped
+      end
+    end
+  end
+end

data/lib/interactor_support/request_object.rb

@@ -82,6 +82,7 @@ module InteractorSupport
             value
           end
         end
+
         return Struct.new(*attrs.keys).new(*attrs.values) if key_type == :struct
 
         attrs

data/lib/interactor_support/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InteractorSupport
-  VERSION = '1.0.3'
+  VERSION = '1.0.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interactor_support
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - Charlie Mitchell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-04 00:00:00.000000000 Z
+date: 2025-04-05 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -30,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