treaty 0.19.0 → 0.20.0

data/lib/treaty/action/inventory/inventory.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Inventory
+      # Individual inventory item with lazy evaluation.
+      #
+      # ## Purpose
+      #
+      # Represents a single piece of data that can be passed from controller
+      # to service. Stores the name and source, and can be evaluated against
+      # a controller context when needed.
+      #
+      # ## Usage
+      #
+      # Created by:
+      # - Inventory::Factory (when `provide` is called)
+      #
+      # Consumed by:
+      # - Inventory::Collection (for bulk evaluation)
+      # - Executor::Inventory (for lazy single-item evaluation)
+      #
+      # ## Source Types
+      #
+      # | Type | Example | Evaluation |
+      # |------|---------|------------|
+      # | Symbol | `:current_user` | Calls `context.send(:current_user)` |
+      # | Proc | `-> { Time.current }` | Calls `context.instance_exec(&proc)` |
+      # | Other | `10`, `"string"` | Returns value as-is |
+      #
+      # ## Lazy Evaluation
+      #
+      # The source is NOT evaluated at creation time. Evaluation happens
+      # only when `evaluate(context)` is called, typically during treaty
+      # execution when the service needs the value.
+      #
+      # ## Example
+      #
+      #   # Symbol source (method call)
+      #   item = Inventory.new(name: :current_user, source: :current_user)
+      #   item.evaluate(controller)  # => calls controller.current_user
+      #
+      #   # Proc source (block execution)
+      #   item = Inventory.new(name: :meta, source: -> { { time: Time.current } })
+      #   item.evaluate(controller)  # => executes block in controller context
+      #
+      #   # Direct value
+      #   item = Inventory.new(name: :limit, source: 10)
+      #   item.evaluate(controller)  # => 10
+      class Inventory
+        # @return [Symbol] Inventory item name
+        attr_reader :name
+
+        # @return [Symbol, Proc, Object] Source for evaluation
+        attr_reader :source
+
+        # Creates a new inventory item
+        #
+        # @param name [Symbol] Item name (must be non-empty Symbol)
+        # @param source [Symbol, Proc, Object] Evaluation source
+        # @raise [Treaty::Exceptions::Inventory] If name is invalid
+        # @raise [Treaty::Exceptions::Inventory] If source is nil
+        def initialize(name:, source:)
+          validate_name!(name)
+          validate_source!(source)
+
+          @name = name
+          @source = source
+        end
+
+        # Evaluates source against controller context
+        #
+        # Behavior depends on source type:
+        # - Symbol: calls method on context
+        # - Proc: executes in context scope
+        # - Other: returns value directly
+        #
+        # @param context [Object] Controller instance
+        # @return [Object] Evaluated value
+        # @raise [Treaty::Exceptions::Inventory] If evaluation fails
+        def evaluate(context) # rubocop:disable Metrics/MethodLength
+          case source
+          when Symbol
+            evaluate_symbol(context)
+          when Proc
+            evaluate_proc(context)
+          else
+            source
+          end
+        rescue StandardError => e
+          raise Treaty::Exceptions::Inventory,
+                I18n.t(
+                  "treaty.inventory.evaluation_error",
+                  name: @name,
+                  error: e.message
+                )
+        end
+
+        private
+
+        # Evaluates Symbol source by calling method on context
+        #
+        # @param context [Object] Controller instance
+        # @return [Object] Method return value
+        def evaluate_symbol(context)
+          context.send(source)
+        end
+
+        # Evaluates Proc source in context scope
+        #
+        # Uses instance_exec so proc has access to controller
+        # instance variables and private methods.
+        #
+        # @param context [Object] Controller instance
+        # @return [Object] Proc return value
+        def evaluate_proc(context)
+          context.instance_exec(&source)
+        end
+
+        # Validates that name is a non-empty Symbol
+        #
+        # @param name [Object] Name to validate
+        # @raise [Treaty::Exceptions::Inventory] If invalid
+        # @return [void]
+        def validate_name!(name)
+          return if name.is_a?(Symbol) && !name.to_s.empty?
+
+          raise Treaty::Exceptions::Inventory,
+                I18n.t("treaty.inventory.invalid_name", name: name.inspect)
+        end
+
+        # Validates that source is not nil
+        #
+        # @param source [Object] Source to validate
+        # @raise [Treaty::Exceptions::Inventory] If nil
+        # @return [void]
+        def validate_source!(source)
+          return unless source.nil?
+
+          raise Treaty::Exceptions::Inventory,
+                I18n.t("treaty.inventory.source_required")
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/request/attribute/attribute.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Request
+      module Attribute
+        # Request-specific attribute definition.
+        #
+        # ## Purpose
+        #
+        # Extends Entity::Attribute::Base with Request-specific behavior.
+        # Key difference: attributes are **required by default**.
+        #
+        # ## Default Behavior
+        #
+        # Unlike Response attributes (optional by default), Request attributes
+        # default to `required: true`. This enforces strict input validation.
+        #
+        # ## Usage
+        #
+        # Created internally by:
+        # - Request::Attribute::Builder (when defining nested attributes)
+        # - Request::Entity (when defining top-level attributes)
+        #
+        # ## Nesting
+        #
+        # Object and array types create nested builders:
+        #
+        #   request do
+        #     object :post do           # Creates Attribute with nested builder
+        #       string :title           # Nested attribute (required by default)
+        #       array :tags do          # Nested array
+        #         string :_self         # Array element definition
+        #       end
+        #     end
+        #   end
+        #
+        # ## Example
+        #
+        #   # These are equivalent:
+        #   string :title               # required by default
+        #   string :title, :required    # explicit required
+        #
+        #   # Must explicitly mark optional:
+        #   string :bio, :optional
+        class Attribute < Treaty::Entity::Attribute::Base
+          private
+
+          # Sets default required behavior for request attributes
+          #
+          # Request attributes are required by default (is: true).
+          # This can be overridden with `:optional` helper or `required: false`.
+          #
+          # @return [void]
+          def apply_defaults!
+            @options[:required] ||= { is: true, message: nil }
+          end
+
+          # Creates nested builder for object/array type processing
+          #
+          # When a block is given to object or array attributes,
+          # creates a Builder to process the nested attribute definitions.
+          #
+          # @param block [Proc] Block containing nested attribute definitions
+          # @return [void]
+          def process_nested_attributes(&block)
+            return unless object_or_array?
+
+            builder = Builder.new(collection_of_attributes, @nesting_level + 1)
+            builder.instance_eval(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/request/attribute/builder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Request
+      module Attribute
+        # DSL builder for defining request attributes.
+        #
+        # ## Purpose
+        #
+        # Provides Request-specific implementation of the attribute builder.
+        # Creates Request::Attribute::Attribute instances instead of generic ones.
+        #
+        # ## Inheritance
+        #
+        # Extends Treaty::Entity::Attribute::Builder::Base which provides:
+        # - DSL interface (string, integer, object, array, etc.)
+        # - method_missing magic for type-based method calls
+        # - Helper support (:required, :optional)
+        # - Entity reuse via use_entity
+        #
+        # ## Usage
+        #
+        # Used internally by:
+        # - Request::Attribute::Attribute (when processing nested object/array blocks)
+        #
+        # ## DSL Example
+        #
+        #   request do
+        #     object :post do
+        #       string :title, :required
+        #       string :content
+        #       array :tags do
+        #         string :_self
+        #       end
+        #     end
+        #   end
+        #
+        # ## Methods
+        #
+        # Implements abstract methods from base class:
+        # - `create_attribute` - Creates Request::Attribute::Attribute
+        # - `deep_copy_attribute` - Deep copies attribute for use_entity support
+        class Builder < Treaty::Entity::Attribute::Builder::Base
+          private
+
+          # Creates a new request attribute instance
+          #
+          # Called by base class when defining attributes via DSL.
+          #
+          # @param name [Symbol] Attribute name
+          # @param type [Symbol] Attribute type (:string, :integer, :object, etc.)
+          # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+          # @param nesting_level [Integer] Current nesting depth
+          # @param options [Hash] Attribute options (default:, format:, etc.)
+          # @param block [Proc] Block for nested attributes (object/array)
+          # @return [Treaty::Action::Request::Attribute::Attribute] Created attribute instance
+          def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+            Attribute.new(
+              name,
+              type,
+              *helpers,
+              nesting_level:,
+              **options,
+              &block
+            )
+          end
+
+          # Deep copies an attribute with adjusted nesting level
+          #
+          # Used when copying attributes from Entity classes via use_entity.
+          # Recursively copies nested attributes for object/array types.
+          #
+          # @param source_attribute [Treaty::Entity::Attribute::Base] Source attribute to copy
+          # @param new_nesting_level [Integer] Nesting level for copied attribute
+          # @return [Treaty::Action::Request::Attribute::Attribute] Deep copied attribute
+          def deep_copy_attribute(source_attribute, new_nesting_level) # rubocop:disable Metrics/MethodLength
+            copied = Attribute.new(
+              source_attribute.name,
+              source_attribute.type,
+              nesting_level: new_nesting_level,
+              **deep_copy_options(source_attribute.options)
+            )
+
+            return copied unless source_attribute.nested?
+
+            source_attribute.collection_of_attributes.each do |nested_source|
+              nested_copied = deep_copy_attribute(nested_source, new_nesting_level + 1)
+              copied.collection_of_attributes << nested_copied
+            end
+
+            copied
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/request/entity.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Request
+      # Internal entity class for request attribute definitions.
+      #
+      # ## Purpose
+      #
+      # Provides DSL interface for defining request attributes when using
+      # inline block syntax in treaty definitions. Serves as the anonymous
+      # class base when `request do ... end` is used.
+      #
+      # ## Usage
+      #
+      # Created internally by:
+      # - Request::Factory (when using inline DSL blocks)
+      #
+      # ## DSL Interface
+      #
+      # Includes Treaty::Entity::Attribute::DSL which provides:
+      # - Type methods: string, integer, boolean, date, time, datetime
+      # - Structure methods: object, array
+      # - Helper support: :required, :optional
+      #
+      # ## Difference from Treaty::Entity::Base
+      #
+      # While Treaty::Entity::Base creates standalone entity classes,
+      # Request::Entity creates Request-specific attributes with:
+      # - Required by default behavior
+      # - Request::Attribute::Attribute instances
+      #
+      # ## Example
+      #
+      #   # When you write:
+      #   version 1 do
+      #     request do
+      #       object :post do
+      #         string :title, :required
+      #       end
+      #     end
+      #   end
+      #
+      #   # Factory creates: Class.new(Request::Entity)
+      #   # and calls string, object etc. on it
+      class Entity
+        include Treaty::Entity::Attribute::DSL
+
+        class << self
+          private
+
+          # Creates request-specific attribute instances
+          #
+          # Called by DSL methods (string, integer, etc.) to create
+          # Request::Attribute::Attribute instead of generic attributes.
+          #
+          # @param name [Symbol] Attribute name
+          # @param type [Symbol] Attribute type
+          # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+          # @param nesting_level [Integer] Current nesting depth
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [Treaty::Action::Request::Attribute::Attribute] Created attribute
+          def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+            Attribute::Attribute.new(
+              name,
+              type,
+              *helpers,
+              nesting_level:,
+              **options,
+              &block
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/request/factory.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Request
+      # Factory for creating request attribute collections.
+      #
+      # ## Purpose
+      #
+      # Captures request attribute definitions from treaty DSL and provides
+      # access to the resulting attribute collection. Supports both inline
+      # block syntax and Entity class references.
+      #
+      # ## Usage
+      #
+      # Created internally by:
+      # - Versions::Factory (when `request do ... end` is called)
+      #
+      # Consumed by:
+      # - Request::Validator (to validate incoming params)
+      # - Info::Builder (to build request schema information)
+      #
+      # ## Definition Modes
+      #
+      # ### Inline Block Mode
+      #
+      #   request do
+      #     object :post do
+      #       string :title, :required
+      #     end
+      #   end
+      #
+      # ### Entity Class Mode
+      #
+      #   request Posts::Create::RequestEntity
+      #
+      # ## Implementation
+      #
+      # Uses method_missing to forward DSL calls to a dynamically created
+      # Entity class. The Entity class collects all attribute definitions.
+      #
+      # ## Example
+      #
+      #   factory = Request::Factory.new
+      #   factory.object :post do
+      #     factory.string :title, :required
+      #   end
+      #   factory.collection_of_attributes  # => Collection with post attribute
+      class Factory
+        # Registers an Entity class for request schema
+        #
+        # Use this to reference a pre-defined Entity class instead of
+        # inline attribute definitions.
+        #
+        # @param entity_class [Class] Must be Treaty::Entity::Base subclass
+        # @raise [Treaty::Exceptions::Validation] If entity_class is invalid
+        # @return [void]
+        def use_entity(entity_class)
+          validate_entity_class!(entity_class)
+          @entity_class = entity_class
+        end
+
+        # Returns the collection of defined attributes
+        #
+        # @return [Treaty::Entity::Attribute::Collection] Attribute collection
+        def collection_of_attributes
+          return Treaty::Entity::Attribute::Collection.new if @entity_class.nil?
+
+          @entity_class.collection_of_attributes
+        end
+
+        # Forwards DSL method calls to internal Entity class
+        #
+        # Creates an anonymous Entity class on first call, then forwards
+        # all DSL methods (string, integer, object, etc.) to it.
+        #
+        # @param type [Symbol] Attribute type (method name)
+        # @param helpers [Array] Helper symbols and arguments
+        # @param options [Hash] Attribute options
+        # @param block [Proc] Block for nested attributes
+        # @return [void]
+        def method_missing(type, *helpers, **options, &block)
+          @entity_class ||= Class.new(Entity)
+
+          @entity_class.public_send(type, *helpers, **options, &block)
+        end
+
+        # Checks if method should be handled by method_missing
+        #
+        # @param name [Symbol] Method name
+        # @return [Boolean]
+        def respond_to_missing?(name, *)
+          super
+        end
+
+        private
+
+        # Validates that entity_class is a Treaty::Entity::Base subclass
+        #
+        # @param entity_class [Class] Class to validate
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        # @return [void]
+        def validate_entity_class!(entity_class)
+          return if entity_class.is_a?(Class) && entity_class < Treaty::Entity::Base
+
+          raise Treaty::Exceptions::Validation,
+                I18n.t(
+                  "treaty.request.factory.invalid_entity_class",
+                  type: entity_class.class,
+                  value: entity_class
+                )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/request/validator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Request
+      # Validates incoming request parameters against schema.
+      #
+      # ## Purpose
+      #
+      # Validates incoming request params against the request schema defined
+      # in the treaty version. Runs all validators (required, type, inclusion,
+      # format) and transformations (default, cast, transform, as).
+      #
+      # ## Usage
+      #
+      # Called internally by:
+      # - Versions::Execution::Base (before delegating to service)
+      #
+      # ## Validation Flow
+      #
+      # 1. Convert ActionController::Parameters to hash if needed
+      # 2. Check if request schema is defined
+      # 3. Create dynamic Orchestrator with version's attributes
+      # 4. Run validation pipeline (validate + transform)
+      # 5. Return validated/transformed params or raise error
+      #
+      # ## Error Handling
+      #
+      # Raises Treaty::Exceptions::Validation with detailed messages
+      # including attribute path and specific validation failures.
+      #
+      # ## Example
+      #
+      #   # Typically called via class method:
+      #   validated = Request::Validator.validate!(
+      #     params: controller.params,
+      #     version_factory: version_factory
+      #   )
+      #
+      #   # validated contains transformed params ready for service
+      class Validator
+        class << self
+          # Validates request parameters
+          #
+          # @param params [Hash, ActionController::Parameters] Request params
+          # @param version_factory [Treaty::Action::Versions::Factory] Version with request schema
+          # @return [Hash] Validated and transformed parameters
+          # @raise [Treaty::Exceptions::Validation] If validation fails
+          def validate!(params:, version_factory:)
+            new(params:, version_factory:).validate!
+          end
+        end
+
+        # Creates new validator instance
+        #
+        # @param params [Hash, ActionController::Parameters] Request params
+        # @param version_factory [Treaty::Action::Versions::Factory] Version with request schema
+        def initialize(params:, version_factory:)
+          @params = params
+          @version_factory = version_factory
+        end
+
+        # Runs validation pipeline
+        #
+        # @return [Hash] Validated and transformed parameters
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        def validate!
+          validate_request_attributes!
+        end
+
+        private
+
+        # Converts params to plain hash
+        #
+        # Handles both ActionController::Parameters (with to_unsafe_h)
+        # and plain Hash objects.
+        #
+        # @return [Hash] Plain hash of request data
+        def request_data
+          @request_data ||= begin
+            @params.to_unsafe_h
+          rescue NoMethodError
+            @params
+          end
+        end
+
+        # Validates and transforms request data
+        #
+        # Creates dynamic Orchestrator class that uses version's request
+        # attributes for validation. Returns raw data if no schema defined.
+        #
+        # @return [Hash] Validated and transformed data
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        def validate_request_attributes!
+          return request_data unless request_attributes_exist?
+
+          orchestrator_class = Class.new(Treaty::Entity::Attribute::Validation::Orchestrator::Base) do
+            define_method(:collection_of_attributes) do
+              @version_factory.request_factory.collection_of_attributes
+            end
+          end
+
+          orchestrator_class.validate!(
+            version_factory: @version_factory,
+            data: request_data
+          )
+        end
+
+        # Checks if request schema is defined for this version
+        #
+        # @return [Boolean] True if request attributes exist
+        def request_attributes_exist?
+          return false if @version_factory.request_factory&.collection_of_attributes&.empty?
+
+          @version_factory.request_factory.collection_of_attributes.exists?
+        end
+      end
+    end
+  end
+end