treaty 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3fcf5acc02ad345e7ff61ba70124596a89be46af035b6ee5d4114de8509f883
-  data.tar.gz: bc5d32074c9cab57438851555fb6849014b52da7f0732517a54db2f48563a198
+  metadata.gz: cc42fa86dd5dc35d49f0a07a189d9ddc59f619e2341905c1ed62193e0d3069b7
+  data.tar.gz: ffc66f03e0ced6e666bb12db50f405117831b48c26475ab034ab4a16f4c431b1
 SHA512:
-  metadata.gz: 3ebb477674d48c4e4e0aafa30eeb9ca3ad20dd96c65f19d38d31b55f6256b7e816768b149720662c9de239242a9aeab78ed038685dd0d82754b005c9e31380c8
-  data.tar.gz: b04b8248df32a42c41b833920cada319fcfb73344a7fa9520867b59fbba60655716f8152342f9a34765c06aa05d99160b7ff9812b826ff7bebca2ccd6a1cda94
+  metadata.gz: 0b31ad204ddb19df8a296007f334d29e2e220fbb771f9c5a3851309e0a9ec1909dae0dbef3608633f6a5203da0b827fb90c75132e83f5ebb3fcc28f36fd33cc9
+  data.tar.gz: 0c6ec71d1be9155da662498264667a63072c5ce513d1ae0987a54091d76aa35a9fd21b3c722db38a8f4154919a2894f442736c44e23ff88961c9a1aadc841c49

data/README.md

@@ -13,7 +13,7 @@
 </div>
 
 > [!WARNING]
-> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.15.0"`) until the 1.0 release.
+> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.16.0"`) until the 1.0 release.
 
 ## 📚 Documentation
 

data/config/locales/en.yml

@@ -56,6 +56,10 @@ en:
           invalid_type: "Option 'transform' for attribute '%{attribute}' must be a Proc or Lambda. Got: %{type}"
           execution_error: "Transform failed for attribute '%{attribute}': %{error}"
 
+        computed:
+          invalid_type: "Option 'computed' for attribute '%{attribute}' must be a Proc or Lambda. Got: %{type}"
+          execution_error: "Computed failed for attribute '%{attribute}': %{error}"
+
         cast:
           invalid_type: "Option 'cast' for attribute '%{attribute}' must be a Symbol. Got: %{type}"
           source_not_supported: "Option 'cast' for attribute '%{attribute}' cannot be used with type '%{source_type}'. Casting is only supported for: %{allowed}"

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

@@ -76,8 +76,9 @@ module Treaty
         # Override in subclasses if transformation is needed
         #
         # @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 = {})
           value
         end
 

data/lib/treaty/attribute/option/modifiers/as_modifier.rb

@@ -79,8 +79,9 @@ module Treaty
           # The renaming is handled by the orchestrator using target_name
           #
           # @param value [Object] The value to transform
+          # @param _root_data [Hash] Unused root data parameter
           # @return [Object] Unchanged value
-          def transform_value(value)
+          def transform_value(value, _root_data = {})
             value
           end
         end

data/lib/treaty/attribute/option/modifiers/cast_modifier.rb

@@ -162,8 +162,9 @@ module Treaty
           # Skips conversion for nil values (handled by RequiredValidator)
           #
           # @param value [Object] The current value
+          # @param _root_data [Hash] Unused root data parameter
           # @return [Object] Converted value
-          def transform_value(value) # rubocop:disable Metrics/MethodLength
+          def transform_value(value, _root_data = {}) # rubocop:disable Metrics/MethodLength
             return value if value.nil? # Cast doesn't modify nil, required validator handles it.
 
             target_type = option_value

data/lib/treaty/attribute/option/modifiers/computed_modifier.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Modifiers
+        # Computes attribute values from all available raw data.
+        #
+        # ## Key Difference from Transform
+        #
+        # - `transform:` receives only `value:` (the current attribute's value)
+        # - `computed:` receives `**attributes` (ALL raw data from root level)
+        #
+        # ## Usage Examples
+        #
+        # Simple mode:
+        #   string :full_name, computed: ->(**attrs) {
+        #     "#{attrs.dig(:user, :first_name)} #{attrs.dig(:user, :last_name)}"
+        #   }
+        #
+        # Advanced mode with custom error message:
+        #   string :full_name, computed: {
+        #     is: ->(**attrs) { "#{attrs.dig(:user, :first_name)} #{attrs.dig(:user, :last_name)}" },
+        #     message: "Failed to compute full name"
+        #   }
+        #
+        # ## Use Cases
+        #
+        # 1. **Derived fields (full name from parts)**:
+        #    ```ruby
+        #    response 200 do
+        #      object :user do
+        #        string :first_name
+        #        string :last_name
+        #        string :full_name, computed: ->(**attrs) {
+        #          "#{attrs.dig(:user, :first_name)} #{attrs.dig(:user, :last_name)}"
+        #        }
+        #      end
+        #    end
+        #    ```
+        #
+        # 2. **Calculated values (word count)**:
+        #    ```ruby
+        #    response 200 do
+        #      object :post do
+        #        string :content
+        #        integer :word_count, computed: ->(**attrs) {
+        #          attrs.dig(:post, :content).to_s.split.size
+        #        }
+        #      end
+        #    end
+        #    ```
+        #
+        # 3. **Cross-object computations**:
+        #    ```ruby
+        #    response 200 do
+        #      object :order do
+        #        integer :quantity
+        #        integer :unit_price
+        #        integer :total, computed: ->(**attrs) {
+        #          attrs.dig(:order, :quantity).to_i * attrs.dig(:order, :unit_price).to_i
+        #        }
+        #      end
+        #    end
+        #    ```
+        #
+        # ## Important Notes
+        #
+        # - Lambda must accept `**attributes` (named argument splat)
+        # - Receives full raw data from root level (not just current object)
+        # - **Always computes** - ignores any existing value, result replaces everything
+        # - All exceptions raised in lambda are caught and re-raised as Validation errors
+        # - Computation is applied during Phase 3 (transformation phase)
+        # - Executes FIRST in modifier chain: computed -> transform -> cast -> default -> as
+        #
+        # ## Advanced Mode
+        #
+        # Schema format: `{ is: lambda, message: nil }`
+        class ComputedModifier < Treaty::Attribute::Option::Base
+          # Validates that computed value is a lambda
+          #
+          # @raise [Treaty::Exceptions::Validation] If computed is not a Proc/lambda
+          # @return [void]
+          def validate_schema!
+            computed_lambda = option_value
+
+            return if computed_lambda.respond_to?(:call)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.modifiers.computed.invalid_type",
+                    attribute: @attribute_name,
+                    type: computed_lambda.class
+                  )
+          end
+
+          # Computes value using the provided lambda and full root data
+          # Always executes - ignores any existing value
+          #
+          # @param _value [Object] The current value (ignored - always computes)
+          # @param root_data [Hash] Full raw data from root level
+          # @return [Object] Computed value
+          def transform_value(_value, root_data = {}) # rubocop:disable Metrics/MethodLength
+            computed_lambda = option_value
+
+            # Call lambda with full root data as named arguments
+            computed_lambda.call(**root_data)
+          rescue StandardError => e
+            attributes = {
+              attribute: @attribute_name,
+              error: e.message
+            }
+
+            # Catch all exceptions from lambda execution
+            error_message = resolve_custom_message(**attributes) || I18n.t(
+              "treaty.attributes.modifiers.computed.execution_error",
+              **attributes
+            )
+
+            raise Treaty::Exceptions::Validation, error_message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option/modifiers/default_modifier.rb

@@ -80,9 +80,9 @@ module Treaty
           # Empty strings, empty arrays, and false are NOT replaced
           #
           # @param value [Object] The current value
-          # @param _context [Hash] Unused context parameter
+          # @param _root_data [Hash] Unused root data parameter
           # @return [Object] Default value if original is nil, otherwise original value
-          def transform_value(value, _context = {})
+          def transform_value(value, _root_data = {})
             # Only apply default if value is nil
             # Empty strings, empty arrays, false are NOT replaced
             return value unless value.nil?

data/lib/treaty/attribute/option/modifiers/transform_modifier.rb

@@ -82,8 +82,9 @@ module Treaty
           # Skips transformation for nil values (handled by RequiredValidator)
           #
           # @param value [Object] The current value
+          # @param _root_data [Hash] Unused root data parameter
           # @return [Object] Transformed value
-          def transform_value(value) # rubocop:disable Metrics/MethodLength
+          def transform_value(value, _root_data = {}) # rubocop:disable Metrics/MethodLength
             return value if value.nil? # Transform doesn't modify nil, required validator handles it.
 
             transform_lambda = option_value

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

@@ -26,10 +26,11 @@ 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
       #
@@ -85,13 +86,15 @@ 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

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,15 +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|
               # 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)
+              process_attribute(nested_attribute, value, transformed, root_data)
             end
 
             transformed
@@ -177,8 +181,9 @@ module Treaty
           # @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)
 
@@ -189,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
@@ -218,13 +223,14 @@ 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
@@ -325,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
+          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(
@@ -350,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(
@@ -369,7 +377,7 @@ module Treaty
               # 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)
+              process_attribute(nested_attribute, item, transformed, index, root_data)
             end
 
             transformed
@@ -382,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)
 
@@ -396,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

@@ -219,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
 
@@ -249,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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -160,6 +160,7 @@ files:
 - lib/treaty/attribute/option/conditionals/unless_conditional.rb
 - lib/treaty/attribute/option/modifiers/as_modifier.rb
 - lib/treaty/attribute/option/modifiers/cast_modifier.rb
+- lib/treaty/attribute/option/modifiers/computed_modifier.rb
 - lib/treaty/attribute/option/modifiers/default_modifier.rb
 - lib/treaty/attribute/option/modifiers/transform_modifier.rb
 - lib/treaty/attribute/option/registry.rb