treaty 0.14.0 → 0.16.0

data/lib/treaty/attribute/option/registry.rb

@@ -3,7 +3,7 @@
 module Treaty
   module Attribute
     module Option
-      # Central registry for all option processors (validators and modifiers).
+      # Central registry for all option processors (validators, modifiers, and conditionals).
       #
       # ## Purpose
       #
@@ -14,7 +14,7 @@ module Treaty
       #
       # 1. **Registration** - Stores option processor classes
       # 2. **Retrieval** - Provides access to registered processors
-      # 3. **Categorization** - Organizes processors by category (validator/modifier)
+      # 3. **Categorization** - Organizes processors by category (validator/modifier/conditional)
       # 4. **Validation** - Checks if options are registered
       #
       # ## Registered Options
@@ -23,15 +23,23 @@ module Treaty
       # - `:required` → RequiredValidator
       # - `:type` → TypeValidator
       # - `:inclusion` → InclusionValidator
+      # - `:format` → FormatValidator
       #
       # ### Modifiers
       # - `:as` → AsModifier
       # - `:default` → DefaultModifier
+      # - `:transform` → TransformModifier
+      # - `:cast` → CastModifier
+      #
+      # ### Conditionals
+      # - `:if` → IfConditional
+      # - `:unless` → UnlessConditional
       #
       # ## Usage
       #
       # Registration (done in RegistryInitializer):
       #   Registry.register(:required, RequiredValidator, category: :validator)
+      #   Registry.register(:if, IfConditional, category: :conditional)
       #
       # Retrieval (done in OptionOrchestrator):
       #   processor_class = Registry.processor_for(:required)
@@ -111,6 +119,14 @@ module Treaty
                     .transform_values { |info| info.fetch(:processor_class) }
           end
 
+          # Get all conditionals
+          #
+          # @return [Hash] Hash of option_name => processor_class for conditionals
+          def conditionals
+            registry.select { |_, info| info.fetch(:category) == :conditional }
+                    .transform_values { |info| info.fetch(:processor_class) }
+          end
+
           # Reset registry (mainly for testing)
           def reset!
             @registry = nil

data/lib/treaty/attribute/option/registry_initializer.rb

@@ -7,14 +7,15 @@ module Treaty
       #
       # ## Purpose
       #
-      # Centralized registration point for all option processors (validators and modifiers).
+      # Centralized registration point for all option processors (validators, modifiers, and conditionals).
       # Automatically registers all built-in options when loaded.
       #
       # ## Responsibilities
       #
       # 1. **Validator Registration** - Registers all built-in validators
       # 2. **Modifier Registration** - Registers all built-in modifiers
-      # 3. **Auto-Loading** - Executes automatically when file is loaded
+      # 3. **Conditional Registration** - Registers all built-in conditionals
+      # 4. **Auto-Loading** - Executes automatically when file is loaded
       #
       # ## Built-in Validators
       #
@@ -25,10 +26,16 @@ module Treaty
       #
       # ## Built-in Modifiers
       #
-      # - `:as` → AsModifier - Renames attributes
-      # - `:default` → DefaultModifier - Provides default values
+      # - `:computed` → ComputedModifier - Computes values from all raw data (executes first)
       # - `:transform` → TransformModifier - Transforms values using custom lambdas
       # - `:cast` → CastModifier - Converts values between types automatically
+      # - `:default` → DefaultModifier - Provides default values
+      # - `:as` → AsModifier - Renames attributes
+      #
+      # ## Built-in Conditionals
+      #
+      # - `:if` → IfConditional - Conditionally includes attributes based on runtime data
+      # - `:unless` → UnlessConditional - Conditionally excludes attributes based on runtime data
       #
       # ## Auto-Registration
       #
@@ -63,6 +70,7 @@ module Treaty
           def register_all!
             register_validators!
             register_modifiers!
+            register_conditionals!
           end
 
           private
@@ -78,13 +86,23 @@ module Treaty
           end
 
           # Registers all built-in modifiers
+          # Order matters: computed runs first, then transform, cast, default, as
           #
           # @return [void]
           def register_modifiers!
-            Registry.register(:as, Modifiers::AsModifier, category: :modifier)
-            Registry.register(:default, Modifiers::DefaultModifier, category: :modifier)
+            Registry.register(:computed, Modifiers::ComputedModifier, category: :modifier)
             Registry.register(:transform, Modifiers::TransformModifier, category: :modifier)
             Registry.register(:cast, Modifiers::CastModifier, category: :modifier)
+            Registry.register(:default, Modifiers::DefaultModifier, category: :modifier)
+            Registry.register(:as, Modifiers::AsModifier, category: :modifier)
+          end
+
+          # Registers all built-in conditionals
+          #
+          # @return [void]
+          def register_conditionals!
+            Registry.register(:if, Conditionals::IfConditional, category: :conditional)
+            Registry.register(:unless, Conditionals::UnlessConditional, category: :conditional)
           end
         end
       end

data/lib/treaty/attribute/option_orchestrator.rb

@@ -103,10 +103,11 @@ module Treaty
       # Applies transformations like defaults, type coercion, etc.
       #
       # @param value [Object] The value to transform
+      # @param root_data [Hash] Full raw data from root level (used by computed modifier)
       # @return [Object] Transformed value
-      def transform_value(value)
+      def transform_value(value, root_data = {})
         @processors.values.reduce(value) do |current_value, processor|
-          processor.transform_value(current_value)
+          processor.transform_value(current_value, root_data)
         end
       end
 

data/lib/treaty/attribute/validation/attribute_validator.rb

@@ -68,9 +68,10 @@ module Treaty
         # Transforms attribute value through all modifiers
         #
         # @param value [Object] The value to transform
+        # @param root_data [Hash] Full raw data from root level (used by computed modifier)
         # @return [Object] Transformed value
-        def transform_value(value)
-          option_orchestrator.transform_value(value)
+        def transform_value(value, root_data = {})
+          option_orchestrator.transform_value(value, root_data)
         end
 
         # Checks if attribute name is transformed

data/lib/treaty/attribute/validation/nested_transformer.rb

@@ -22,15 +22,16 @@ module Treaty
         # Returns original value if nil or not nested
         #
         # @param value [Object] The value to transform
+        # @param root_data [Hash] Full raw data from root level (for computed modifier)
         # @return [Object] Transformed value
-        def transform(value)
+        def transform(value, root_data = {})
           return value if value.nil?
 
           case attribute.type
           when :object
-            transform_object(value)
+            transform_object(value, root_data)
           when :array
-            transform_array(value)
+            transform_array(value, root_data)
           else
             value
           end
@@ -41,23 +42,25 @@ module Treaty
         # Transforms object (hash) value
         #
         # @param value [Hash] The hash to transform
+        # @param root_data [Hash] Full raw data from root level (for computed modifier)
         # @return [Hash] Transformed hash
-        def transform_object(value)
+        def transform_object(value, root_data = {})
           return value unless attribute.nested?
 
           transformer = ObjectTransformer.new(attribute)
-          transformer.transform(value)
+          transformer.transform(value, root_data)
         end
 
         # Transforms array value
         #
         # @param value [Array] The array to transform
+        # @param root_data [Hash] Full raw data from root level (for computed modifier)
         # @return [Array] Transformed array
-        def transform_array(value)
+        def transform_array(value, root_data = {})
           return value unless attribute.nested?
 
           transformer = ArrayTransformer.new(attribute)
-          transformer.transform(value)
+          transformer.transform(value, root_data)
         end
 
         # Transforms object (hash) with nested attributes
@@ -74,12 +77,16 @@ module Treaty
           # Transforms hash by processing all nested attributes
           #
           # @param value [Hash] The source hash
+          # @param root_data [Hash] Full raw data from root level (for computed modifier)
           # @return [Hash] Transformed hash with processed attributes
-          def transform(value)
+          def transform(value, root_data = {})
             transformed = {}
 
             attribute.collection_of_attributes.each do |nested_attribute|
-              process_attribute(nested_attribute, value, transformed)
+              # Check if conditional (if/unless option) - skip attribute if condition evaluates to skip
+              next unless should_process_attribute?(nested_attribute, value)
+
+              process_attribute(nested_attribute, value, transformed, root_data)
             end
 
             transformed
@@ -87,14 +94,96 @@ module Treaty
 
           private
 
+          # Returns the conditional option name if present (:if or :unless)
+          # Raises error if both are present (mutual exclusivity)
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @raise [Treaty::Exceptions::Validation] If both :if and :unless are present
+          # @return [Symbol, nil] :if, :unless, or nil
+          def conditional_option_for(nested_attribute) # rubocop:disable Metrics/MethodLength
+            has_if = nested_attribute.options.key?(:if)
+            has_unless = nested_attribute.options.key?(:unless)
+
+            if has_if && has_unless
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.mutual_exclusivity_error",
+                      attribute: nested_attribute.name
+                    )
+            end
+
+            return :if if has_if
+            return :unless if has_unless
+
+            nil
+          end
+
+          # Gets cached conditional processors for attributes or builds them
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def conditionals_for_attributes
+            @conditionals_for_attributes ||= build_conditionals_for_attributes
+          end
+
+          # Builds conditional processors for attributes with :if or :unless option
+          # Validates schema at definition time for performance
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def build_conditionals_for_attributes # rubocop:disable Metrics/MethodLength
+            attribute.collection_of_attributes.each_with_object({}) do |nested_attribute, cache|
+              # Get conditional option name (:if or :unless)
+              conditional_type = conditional_option_for(nested_attribute)
+              next if conditional_type.nil?
+
+              processor_class = Option::Registry.processor_for(conditional_type)
+              next if processor_class.nil?
+
+              # Create processor instance
+              conditional = processor_class.new(
+                attribute_name: nested_attribute.name,
+                attribute_type: nested_attribute.type,
+                option_schema: nested_attribute.options.fetch(conditional_type)
+              )
+
+              # Validate schema at definition time (not runtime)
+              conditional.validate_schema!
+
+              cache[nested_attribute] = conditional
+            end
+          end
+
+          # Checks if an attribute should be processed based on its conditional (if/unless option)
+          # Returns true if no conditional is defined or if conditional evaluates appropriately
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @param source_hash [Hash] Source data to pass to conditional
+          # @return [Boolean] True if attribute should be processed, false to skip it
+          def should_process_attribute?(nested_attribute, source_hash)
+            # Check if attribute has a conditional option
+            conditional_type = conditional_option_for(nested_attribute)
+            return true if conditional_type.nil?
+
+            # Get cached conditional processor
+            conditional = conditionals_for_attributes[nested_attribute]
+            return true if conditional.nil?
+
+            # Evaluate condition with source hash data wrapped with parent object name
+            wrapped_data = { attribute.name => source_hash }
+            conditional.evaluate_condition(wrapped_data)
+          rescue StandardError
+            # If conditional evaluation fails, skip the attribute
+            false
+          end
+
           # Processes a single nested attribute
           # Validates, transforms, and adds to target hash
           #
           # @param nested_attribute [Attribute::Base] Attribute to process
           # @param source_hash [Hash] Source data
           # @param target_hash [Hash] Target hash to populate
+          # @param root_data [Hash] Full raw data from root level (for computed modifier)
           # @return [void]
-          def process_attribute(nested_attribute, source_hash, target_hash) # rubocop:disable Metrics/MethodLength
+          def process_attribute(nested_attribute, source_hash, target_hash, root_data = {}) # rubocop:disable Metrics/MethodLength
             source_name = nested_attribute.name
             nested_value = source_hash.fetch(source_name, nil)
 
@@ -105,10 +194,10 @@ module Treaty
                                   nested_transformer = NestedTransformer.new(nested_attribute)
                                   validator.validate_type!(nested_value) unless nested_value.nil?
                                   validator.validate_required!(nested_value)
-                                  nested_transformer.transform(nested_value)
+                                  nested_transformer.transform(nested_value, root_data)
                                 else
                                   validator.validate_value!(nested_value)
-                                  validator.transform_value(nested_value)
+                                  validator.transform_value(nested_value, root_data)
                                 end
 
             target_name = validator.target_name
@@ -117,7 +206,7 @@ module Treaty
         end
 
         # Transforms array with nested attributes
-        class ArrayTransformer
+        class ArrayTransformer # rubocop:disable Metrics/ClassLength
           SELF_OBJECT = :_self
           private_constant :SELF_OBJECT
 
@@ -134,19 +223,101 @@ module Treaty
           # Handles both simple arrays (:_self) and complex arrays (objects)
           #
           # @param value [Array] The source array
+          # @param root_data [Hash] Full raw data from root level (for computed modifier)
           # @return [Array] Transformed array
-          def transform(value)
+          def transform(value, root_data = {})
             value.each_with_index.map do |item, index|
               if simple_array?
-                transform_simple_element(item, index)
+                transform_simple_element(item, index, root_data)
               else
-                transform_array_item(item, index)
+                transform_array_item(item, index, root_data)
               end
             end
           end
 
           private
 
+          # Returns the conditional option name if present (:if or :unless)
+          # Raises error if both are present (mutual exclusivity)
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @raise [Treaty::Exceptions::Validation] If both :if and :unless are present
+          # @return [Symbol, nil] :if, :unless, or nil
+          def conditional_option_for(nested_attribute) # rubocop:disable Metrics/MethodLength
+            has_if = nested_attribute.options.key?(:if)
+            has_unless = nested_attribute.options.key?(:unless)
+
+            if has_if && has_unless
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.mutual_exclusivity_error",
+                      attribute: nested_attribute.name
+                    )
+            end
+
+            return :if if has_if
+            return :unless if has_unless
+
+            nil
+          end
+
+          # Gets cached conditional processors for attributes or builds them
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def conditionals_for_attributes
+            @conditionals_for_attributes ||= build_conditionals_for_attributes
+          end
+
+          # Builds conditional processors for attributes with :if or :unless option
+          # Validates schema at definition time for performance
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def build_conditionals_for_attributes # rubocop:disable Metrics/MethodLength
+            attribute.collection_of_attributes.each_with_object({}) do |nested_attribute, cache|
+              # Get conditional option name (:if or :unless)
+              conditional_type = conditional_option_for(nested_attribute)
+              next if conditional_type.nil?
+
+              processor_class = Option::Registry.processor_for(conditional_type)
+              next if processor_class.nil?
+
+              # Create processor instance
+              conditional = processor_class.new(
+                attribute_name: nested_attribute.name,
+                attribute_type: nested_attribute.type,
+                option_schema: nested_attribute.options.fetch(conditional_type)
+              )
+
+              # Validate schema at definition time (not runtime)
+              conditional.validate_schema!
+
+              cache[nested_attribute] = conditional
+            end
+          end
+
+          # Checks if an attribute should be processed based on its conditional (if/unless option)
+          # Returns true if no conditional is defined or if conditional evaluates appropriately
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @param source_hash [Hash] Source data to pass to conditional
+          # @return [Boolean] True if attribute should be processed, false to skip it
+          def should_process_attribute?(nested_attribute, source_hash)
+            # Check if attribute has a conditional option
+            conditional_type = conditional_option_for(nested_attribute)
+            return true if conditional_type.nil?
+
+            # Get cached conditional processor
+            conditional = conditionals_for_attributes[nested_attribute]
+            return true if conditional.nil?
+
+            # Evaluate condition with source hash data wrapped with parent array attribute name
+            wrapped_data = { attribute.name => source_hash }
+            conditional.evaluate_condition(wrapped_data)
+          rescue StandardError
+            # If conditional evaluation fails, skip the attribute
+            false
+          end
+
           # Checks if this is a simple array (primitive values)
           #
           # @return [Boolean] True if array contains primitive values with :_self attribute
@@ -160,16 +331,17 @@ module Treaty
           #
           # @param item [Object] Array element to transform
           # @param index [Integer] Element index for error messages
+          # @param root_data [Hash] Full raw data from root level (for computed modifier)
           # @raise [Treaty::Exceptions::Validation] If validation fails
           # @return [Object] Transformed element value
-          def transform_simple_element(item, index) # rubocop:disable Metrics/MethodLength
-            self_attr = attribute.collection_of_attributes.first
-            validator = AttributeValidator.new(self_attr)
+          def transform_simple_element(item, index, root_data = {}) # rubocop:disable Metrics/MethodLength
+            self_attribute = attribute.collection_of_attributes.first
+            validator = AttributeValidator.new(self_attribute)
             validator.validate_schema!
 
             begin
               validator.validate_value!(item)
-              validator.transform_value(item)
+              validator.transform_value(item, root_data)
             rescue Treaty::Exceptions::Validation => e
               raise Treaty::Exceptions::Validation,
                     I18n.t(
@@ -185,9 +357,10 @@ module Treaty
           #
           # @param item [Hash] Array element to transform
           # @param index [Integer] Element index for error messages
+          # @param root_data [Hash] Full raw data from root level (for computed modifier)
           # @raise [Treaty::Exceptions::Validation] If item is not a Hash
           # @return [Hash] Transformed hash
-          def transform_array_item(item, index) # rubocop:disable Metrics/MethodLength
+          def transform_array_item(item, index, root_data = {}) # rubocop:disable Metrics/MethodLength
             unless item.is_a?(Hash)
               raise Treaty::Exceptions::Validation,
                     I18n.t(
@@ -201,7 +374,10 @@ module Treaty
             transformed = {}
 
             attribute.collection_of_attributes.each do |nested_attribute|
-              process_attribute(nested_attribute, item, transformed, index)
+              # Check if conditional (if/unless option) - skip attribute if condition evaluates to skip
+              next unless should_process_attribute?(nested_attribute, item)
+
+              process_attribute(nested_attribute, item, transformed, index, root_data)
             end
 
             transformed
@@ -214,9 +390,10 @@ module Treaty
           # @param source_hash [Hash] Source data
           # @param target_hash [Hash] Target hash to populate
           # @param index [Integer] Array index for error messages
+          # @param root_data [Hash] Full raw data from root level (for computed modifier)
           # @raise [Treaty::Exceptions::Validation] If validation fails
           # @return [void]
-          def process_attribute(nested_attribute, source_hash, target_hash, index) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          def process_attribute(nested_attribute, source_hash, target_hash, index, root_data = {}) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             source_name = nested_attribute.name
             nested_value = source_hash.fetch(source_name, nil)
 
@@ -228,10 +405,10 @@ module Treaty
                                     nested_transformer = NestedTransformer.new(nested_attribute)
                                     validator.validate_type!(nested_value) unless nested_value.nil?
                                     validator.validate_required!(nested_value)
-                                    nested_transformer.transform(nested_value)
+                                    nested_transformer.transform(nested_value, root_data)
                                   else
                                     validator.validate_value!(nested_value)
-                                    validator.transform_value(nested_value)
+                                    validator.transform_value(nested_value, root_data)
                                   end
             rescue Treaty::Exceptions::Validation => e
               raise Treaty::Exceptions::Validation,

data/lib/treaty/attribute/validation/orchestrator/base.rb

@@ -70,12 +70,16 @@ module Treaty
 
           # Validates and transforms all attributes
           # Iterates through attributes, processes them, handles :_self objects
+          # Skips attributes with false conditional (if/unless option)
           #
           # @return [Hash] Transformed data with all attributes processed
-          def validate!
+          def validate! # rubocop:disable Metrics/MethodLength
             transformed_data = {}
 
             collection_of_attributes.each do |attribute|
+              # Check if conditional (if/unless option) - skip attribute if condition evaluates to skip
+              next unless should_process_attribute?(attribute)
+
               transformed_value = validate_and_transform_attribute!(attribute)
 
               if attribute.name == SELF_OBJECT && attribute.type == :object
@@ -91,6 +95,49 @@ module Treaty
 
           private
 
+          # Returns the conditional option name if present (:if or :unless)
+          # Raises error if both are present (mutual exclusivity)
+          #
+          # @param attribute [Attribute::Base] The attribute to check
+          # @raise [Treaty::Exceptions::Validation] If both :if and :unless are present
+          # @return [Symbol, nil] :if, :unless, or nil
+          def conditional_option_for(attribute) # rubocop:disable Metrics/MethodLength
+            has_if = attribute.options.key?(:if)
+            has_unless = attribute.options.key?(:unless)
+
+            if has_if && has_unless
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.mutual_exclusivity_error",
+                      attribute: attribute.name
+                    )
+            end
+
+            return :if if has_if
+            return :unless if has_unless
+
+            nil
+          end
+
+          # Checks if an attribute should be processed based on its conditional (if/unless option)
+          # Returns true if no conditional is defined or if conditional evaluates appropriately
+          #
+          # @param attribute [Attribute::Base] The attribute to check
+          # @return [Boolean] True if attribute should be processed, false to skip it
+          def should_process_attribute?(attribute)
+            # Check if attribute has a conditional option
+            conditional_type = conditional_option_for(attribute)
+            return true if conditional_type.nil?
+
+            # Get cached conditional processor
+            conditional = conditionals_for_attributes[attribute]
+            return true if conditional.nil?
+
+            # Evaluate condition with raw data
+            # The processor's evaluate_condition already handles if/unless logic
+            conditional.evaluate_condition(data)
+          end
+
           # Returns collection of attributes for this context
           # Must be implemented in subclasses
           #
@@ -119,6 +166,40 @@ module Treaty
             end
           end
 
+          # Gets cached conditional processors for attributes or builds them
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def conditionals_for_attributes
+            @conditionals_for_attributes ||= build_conditionals_for_attributes
+          end
+
+          # Builds conditional processors for attributes with :if or :unless option
+          # Validates schema at definition time for performance
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def build_conditionals_for_attributes # rubocop:disable Metrics/MethodLength
+            collection_of_attributes.each_with_object({}) do |attribute, cache|
+              # Get conditional option name (:if or :unless)
+              conditional_type = conditional_option_for(attribute)
+              next if conditional_type.nil?
+
+              processor_class = Option::Registry.processor_for(conditional_type)
+              next if processor_class.nil?
+
+              # Create processor instance
+              conditional = processor_class.new(
+                attribute_name: attribute.name,
+                attribute_type: attribute.type,
+                option_schema: attribute.options.fetch(conditional_type)
+              )
+
+              # Validate schema at definition time (not runtime)
+              conditional.validate_schema!
+
+              cache[attribute] = conditional
+            end
+          end
+
           # Validates and transforms a single attribute
           # Handles both nested and regular attributes
           #
@@ -138,7 +219,7 @@ module Treaty
               validate_and_transform_nested(attribute, value, validator)
             else
               validator.validate_value!(value)
-              validator.transform_value(value)
+              validator.transform_value(value, data)
             end
           end
 
@@ -168,8 +249,9 @@ module Treaty
 
             # Step 4: Transform non-nil value
             # At this point, value is guaranteed to be non-nil
+            # Pass full root data as context for computed modifiers
             transformer = NestedTransformer.new(attribute)
-            transformer.transform(value)
+            transformer.transform(value, data)
           end
         end
       end

data/lib/treaty/result.rb

@@ -2,11 +2,12 @@
 
 module Treaty
   class Result
-    attr_reader :data, :status
+    attr_reader :data, :status, :version
 
-    def initialize(data:, status:)
+    def initialize(data:, status:, version:)
       @data = data
       @status = status
+      @version = version
     end
 
     def inspect
@@ -16,7 +17,7 @@ module Treaty
     private
 
     def draw_result
-      "@data=#{@data.inspect}, @status=#{@status.inspect}"
+      "@data=#{@data.inspect}, @status=#{@status.inspect}, @version=#{@version.inspect}"
     end
   end
 end

data/lib/treaty/version.rb

@@ -3,7 +3,7 @@
 module Treaty
   module VERSION
     MAJOR = 0
-    MINOR = 14
+    MINOR = 16
     PATCH = 0
     PRE = nil