treaty 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c10e0241b816115758a4383e524fc0f9cfb6738e95f4fddff5a1b32eb114c719
-  data.tar.gz: 4a5bfe17af7e6efb87975770aed1a3a67fb817aeee13cdbd05c88c187407efe0
+  metadata.gz: 600a422c9ddcdff83b3ec4cde1c8124adb8ae52e1c1d88744d8474bc4afa8c68
+  data.tar.gz: dd425b19d451b34f46b07747586f35ba7df4dcac9c554a481ac5dd27e1fe2141
 SHA512:
-  metadata.gz: 12b23780c22b9987d317323e723c81d5be07ff2099e74a6cf90c4eab5bb4d0d74a6f0c8b05f11f7800daf16c02d5dd7c317c2d7df770ad99c1638933e94b6297
-  data.tar.gz: 4074fa86260a0f9e79adeaf6b41a61f70f5e568e7cbd6592b4eb8c19c270c954753db941be3490ce40944d1edc8cf9445caf75ef1de0b18e65e7939ad6ffd191
+  metadata.gz: 1739edd5d1c38fe70fc6ab892b06ec15df3a665724df68c95f351675dae4e8c6a00368d65489bbfde0900a67841b9aad1e7eb57f81b948248ae902755f485519
+  data.tar.gz: 627d321a706c846e3249afb9e97f4ceb48573af52fcf962459e38316ed76ed7d979c4fd0fcffa8146cff5e7cfeab36b4cf391f9bfb3d7c82ca8de3cd6c5ea439

data/config/locales/en.yml

@@ -49,6 +49,17 @@ en:
         as:
           invalid_type: "Option 'as' for attribute '%{attribute}' must be a Symbol. Got: %{type}"
 
+        transform:
+          invalid_type: "Option 'transform' for attribute '%{attribute}' must be a Proc or Lambda. Got: %{type}"
+          execution_error: "Transform 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}"
+          target_not_supported: "Option 'cast' for attribute '%{attribute}' cannot cast to '%{target_type}'. Supported target types: %{allowed}"
+          conversion_not_supported: "Option 'cast' for attribute '%{attribute}' does not support conversion from '%{from}' to '%{to}'"
+          conversion_error: "Cast failed for attribute '%{attribute}' from '%{from}' to '%{to}'. Value: '%{value}'. Error: %{error}"
+
       # Attribute builder DSL
       builder:
         not_implemented: "%{class} must implement #create_attribute"

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

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Modifiers
+        # Converts attribute values between different types automatically.
+        #
+        # ## Usage Examples
+        #
+        # Simple mode:
+        #   string :created_at, cast: :datetime
+        #   datetime :timestamp, cast: :string
+        #   integer :active, cast: :boolean
+        #
+        # Advanced mode with custom error message:
+        #   string :created_at, cast: {
+        #     to: :datetime,
+        #     message: "Invalid date format"
+        #   }
+        #
+        # ## Use Cases
+        #
+        # 1. **Request type conversion**:
+        #    ```ruby
+        #    request do
+        #      string :created_at, cast: :datetime
+        #    end
+        #    # Input: { created_at: "2024-01-15T10:30:00Z" }
+        #    # Service receives: { created_at: DateTime object }
+        #    ```
+        #
+        # 2. **Response type conversion**:
+        #    ```ruby
+        #    response 200 do
+        #      datetime :created_at, cast: :string
+        #    end
+        #    # Service returns: { created_at: DateTime object }
+        #    # Output: { created_at: "2024-01-15T10:30:00Z" }
+        #    ```
+        #
+        # 3. **Unix timestamp conversion**:
+        #    ```ruby
+        #    integer :timestamp, cast: :datetime
+        #    datetime :created_at, cast: :integer
+        #    ```
+        #
+        # ## Supported Conversions
+        #
+        # ### From Integer
+        # - integer -> string: Converts to string representation
+        # - integer -> boolean: 0 = false, non-zero = true
+        # - integer -> datetime: Treats as Unix timestamp
+        #
+        # ### From String
+        # - string -> integer: Parses integer from string
+        # - string -> boolean: Parses truthy/falsy strings (true/false, yes/no, 1/0, on/off)
+        # - string -> datetime: Parses datetime string (ISO8601, RFC3339, etc.)
+        #
+        # ### From Boolean
+        # - boolean -> string: Converts to "true" or "false"
+        # - boolean -> integer: true = 1, false = 0
+        #
+        # ### From DateTime
+        # - datetime -> string: Converts to ISO8601 format
+        # - datetime -> integer: Converts to Unix timestamp
+        #
+        # ## Important Notes
+        #
+        # - Cast option only works with scalar types (integer, string, boolean, datetime)
+        # - Array and Object types are not supported for casting
+        # - Casting to the same type is allowed (no-op)
+        # - Nil values are not transformed (handled by RequiredValidator)
+        # - All conversion errors are caught and re-raised as Validation errors
+        #
+        # ## Error Handling
+        #
+        # If conversion fails (e.g., invalid date string, non-numeric string to integer),
+        # the error is caught and converted to a Treaty::Exceptions::Validation error.
+        #
+        # ## Advanced Mode
+        #
+        # Schema format: `{ to: :target_type, message: "Custom error" }`
+        # Note: Uses `:to` key instead of the default `:is` key.
+        class CastModifier < Treaty::Attribute::Option::Base
+          # Types that support casting (scalar types only)
+          ALLOWED_CAST_TYPES = %i[integer string boolean datetime].freeze
+
+          # Validates that cast option is correctly configured
+          #
+          # @raise [Treaty::Exceptions::Validation] If cast configuration is invalid
+          # @return [void]
+          def validate_schema! # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            # If option_schema is nil, cast is not used for this attribute
+            return if @option_schema.nil?
+
+            target_type = option_value
+
+            # Validate that target type is a Symbol
+            unless target_type.is_a?(Symbol)
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.modifiers.cast.invalid_type",
+                      attribute: @attribute_name,
+                      type: target_type.class
+                    )
+            end
+
+            # Validate that source type supports casting
+            unless ALLOWED_CAST_TYPES.include?(@attribute_type)
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.modifiers.cast.source_not_supported",
+                      attribute: @attribute_name,
+                      source_type: @attribute_type,
+                      allowed: ALLOWED_CAST_TYPES.join(", ")
+                    )
+            end
+
+            # Validate that target type is allowed
+            unless ALLOWED_CAST_TYPES.include?(target_type)
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.modifiers.cast.target_not_supported",
+                      attribute: @attribute_name,
+                      target_type:,
+                      allowed: ALLOWED_CAST_TYPES.join(", ")
+                    )
+            end
+
+            # Validate that conversion from source to target is supported
+            return if conversion_supported?(@attribute_type, target_type)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.modifiers.cast.conversion_not_supported",
+                    attribute: @attribute_name,
+                    from: @attribute_type,
+                    to: target_type
+                  )
+          end
+
+          # Applies type conversion to the value
+          # Skips conversion for nil values (handled by RequiredValidator)
+          #
+          # @param value [Object] The current value
+          # @return [Object] Converted value
+          def transform_value(value) # rubocop:disable Metrics/MethodLength
+            return value if value.nil? # Cast doesn't modify nil, required validator handles it.
+
+            target_type = option_value
+            conversion_lambda = conversion_matrix.dig(@attribute_type, target_type)
+
+            # Call conversion lambda
+            conversion_lambda.call(value:)
+          rescue StandardError => e
+            attributes = {
+              attribute: @attribute_name,
+              from: @attribute_type,
+              to: target_type,
+              value:,
+              error: e.message
+            }
+
+            # Catch all exceptions from conversion execution
+            error_message = resolve_custom_message(**attributes) || I18n.t(
+              "treaty.attributes.modifiers.cast.conversion_error",
+              **attributes
+            )
+
+            raise Treaty::Exceptions::Validation, error_message
+          end
+
+          protected
+
+          # Override value_key to use :to instead of :is
+          # This makes advanced mode syntax: cast: { to: :datetime }
+          #
+          # @return [Symbol] The key :to
+          def value_key
+            :to
+          end
+
+          private
+
+          # Checks if conversion from source type to target type is supported
+          #
+          # @param from_type [Symbol] Source type
+          # @param to_type [Symbol] Target type
+          # @return [Boolean] True if conversion is supported
+          def conversion_supported?(from_type, to_type)
+            conversion_matrix.dig(from_type, to_type).present?
+          end
+
+          # Matrix of all supported type conversions
+          # Maps from_type => to_type => conversion_lambda
+          #
+          # @return [Hash] Conversion matrix
+          def conversion_matrix # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            @conversion_matrix ||= {
+              integer: {
+                integer: ->(value:) { value }, # No-op for same type
+                string: ->(value:) { value.to_s },
+                boolean: ->(value:) { value != 0 },
+                datetime: ->(value:) { Time.at(value) }
+              },
+              string: {
+                string: ->(value:) { value }, # No-op for same type
+                integer: ->(value:) { Integer(value) },
+                boolean: ->(value:) { parse_boolean(value) },
+                datetime: ->(value:) { DateTime.parse(value) }
+              },
+              boolean: {
+                boolean: ->(value:) { value }, # No-op for same type
+                string: ->(value:) { value.to_s },
+                integer: ->(value:) { value ? 1 : 0 }
+              },
+              datetime: {
+                datetime: ->(value:) { value }, # No-op for same type
+                string: ->(value:) { value.iso8601 },
+                integer: ->(value:) { value.to_i }
+              }
+            }
+          end
+
+          # Parses a string value into a boolean
+          # Recognizes: true/false, yes/no, 1/0, on/off (case-insensitive)
+          #
+          # @param value [String] The string value to parse
+          # @return [Boolean] Parsed boolean value
+          # @raise [ArgumentError] If string is not a recognized boolean value
+          def parse_boolean(value)
+            normalized = value.to_s.downcase.strip
+
+            return true if %w[true 1 yes on].include?(normalized)
+            return false if %w[false 0 no off].include?(normalized)
+
+            raise ArgumentError, "Cannot convert '#{value}' to boolean"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Modifiers
+        # Transforms attribute values using custom lambda functions.
+        #
+        # ## Usage Examples
+        #
+        # Simple mode:
+        #   integer :amount, transform: ->(value:) { value * 100 }
+        #   string :title, transform: ->(value:) { value.strip.upcase }
+        #
+        # Advanced mode with custom error message:
+        #   integer :amount, transform: {
+        #     is: ->(value:) { value * 100 },
+        #     message: "Failed to transform amount"
+        #   }
+        #
+        # ## Use Cases
+        #
+        # 1. **Request transformation**:
+        #    ```ruby
+        #    request do
+        #      integer :amount_cents, transform: ->(value:) { value * 100 }
+        #    end
+        #    # Input: { amount_cents: 10 }
+        #    # Service receives: { amount_cents: 1000 }
+        #    ```
+        #
+        # 2. **Response transformation**:
+        #    ```ruby
+        #    response 200 do
+        #      string :title, transform: ->(value:) { value.titleize }
+        #    end
+        #    # Service returns: { title: "hello world" }
+        #    # Output: { title: "Hello World" }
+        #    ```
+        #
+        # 3. **Complex transformations**:
+        #    ```ruby
+        #    string :email, transform: ->(value:) { value.downcase.strip }
+        #    datetime :timestamp, transform: ->(value:) { value.iso8601 }
+        #    ```
+        #
+        # ## Important Notes
+        #
+        # - Lambda must accept named argument `value:`
+        # - All exceptions raised in lambda are caught and re-raised as Validation errors
+        # - Transformation is applied during Phase 3 (after validation)
+        # - Can be combined with other options (required, default, as, etc.)
+        #
+        # ## Error Handling
+        #
+        # If the lambda raises any exception, it's caught and converted to a
+        # Treaty::Exceptions::Validation with appropriate error message.
+        #
+        # ## Advanced Mode
+        #
+        # Schema format: `{ is: lambda, message: nil }`
+        class TransformModifier < Treaty::Attribute::Option::Base
+          # Validates that transform value is a lambda
+          #
+          # @raise [Treaty::Exceptions::Validation] If transform is not a Proc/lambda
+          # @return [void]
+          def validate_schema!
+            transform_lambda = option_value
+
+            return if transform_lambda.respond_to?(:call)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.modifiers.transform.invalid_type",
+                    attribute: @attribute_name,
+                    type: transform_lambda.class
+                  )
+          end
+
+          # Applies transformation to the value using the provided lambda
+          # Catches all exceptions and re-raises as Validation errors
+          # Skips transformation for nil values (handled by RequiredValidator)
+          #
+          # @param value [Object] The current value
+          # @return [Object] Transformed value
+          def transform_value(value) # rubocop:disable Metrics/MethodLength
+            return value if value.nil? # Transform doesn't modify nil, required validator handles it.
+
+            transform_lambda = option_value
+
+            # Call lambda with named argument
+            transform_lambda.call(value:)
+          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.transform.execution_error",
+              **attributes
+            )
+
+            raise Treaty::Exceptions::Validation, error_message
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -27,6 +27,8 @@ module Treaty
       #
       # - `:as` → AsModifier - Renames attributes
       # - `:default` → DefaultModifier - Provides default values
+      # - `:transform` → TransformModifier - Transforms values using custom lambdas
+      # - `:cast` → CastModifier - Converts values between types automatically
       #
       # ## Auto-Registration
       #
@@ -81,6 +83,8 @@ module Treaty
           def register_modifiers!
             Registry.register(:as, Modifiers::AsModifier, category: :modifier)
             Registry.register(:default, Modifiers::DefaultModifier, category: :modifier)
+            Registry.register(:transform, Modifiers::TransformModifier, category: :modifier)
+            Registry.register(:cast, Modifiers::CastModifier, category: :modifier)
           end
         end
       end

data/lib/treaty/attribute/option_normalizer.rb

@@ -70,7 +70,8 @@ module Treaty
       OPTION_KEY_MAPPING = {
         in: { advanced_key: :inclusion, value_key: :in },
         as: { advanced_key: :as, value_key: :is },
-        default: { advanced_key: :default, value_key: :is }
+        default: { advanced_key: :default, value_key: :is },
+        cast: { advanced_key: :cast, value_key: :to }
       }.freeze
       private_constant :OPTION_KEY_MAPPING
 

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

@@ -138,8 +138,7 @@ module Treaty
           def transform(value)
             value.each_with_index.map do |item, index|
               if simple_array?
-                validate_simple_element(item, index)
-                item
+                transform_simple_element(item, index)
               else
                 transform_array_item(item, index)
               end
@@ -156,19 +155,21 @@ module Treaty
               attribute.collection_of_attributes.first.name == SELF_OBJECT
           end
 
-          # Validates a simple array element (primitive value)
+          # Transforms a simple array element (primitive value)
+          # Validates and applies transformations to the element
           #
-          # @param item [Object] Array element to validate
+          # @param item [Object] Array element to transform
           # @param index [Integer] Element index for error messages
           # @raise [Treaty::Exceptions::Validation] If validation fails
-          # @return [void]
-          def validate_simple_element(item, index) # rubocop:disable Metrics/MethodLength
+          # @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)
             validator.validate_schema!
 
             begin
               validator.validate_value!(item)
+              validator.transform_value(item)
             rescue Treaty::Exceptions::Validation => e
               raise Treaty::Exceptions::Validation,
                     I18n.t(

data/lib/treaty/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -156,7 +156,9 @@ files:
 - lib/treaty/attribute/helper_mapper.rb
 - lib/treaty/attribute/option/base.rb
 - lib/treaty/attribute/option/modifiers/as_modifier.rb
+- lib/treaty/attribute/option/modifiers/cast_modifier.rb
 - lib/treaty/attribute/option/modifiers/default_modifier.rb
+- lib/treaty/attribute/option/modifiers/transform_modifier.rb
 - lib/treaty/attribute/option/registry.rb
 - lib/treaty/attribute/option/registry_initializer.rb
 - lib/treaty/attribute/option/validators/format_validator.rb