treaty 0.17.0 → 0.19.0

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

@@ -1,283 +0,0 @@
-# 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 -> date: Treats as Unix timestamp, converts to date
-        # - integer -> time: Treats as Unix timestamp
-        # - integer -> datetime: Treats as Unix timestamp, converts to datetime
-        #
-        # ### From String
-        # - string -> integer: Parses integer from string
-        # - string -> boolean: Parses truthy/falsy strings (true/false, yes/no, 1/0, on/off)
-        # - string -> date: Parses date string
-        # - string -> time: Parses time string
-        # - string -> datetime: Parses datetime string (ISO8601, RFC3339, etc.)
-        #
-        # ### From Boolean
-        # - boolean -> string: Converts to "true" or "false"
-        # - boolean -> integer: true = 1, false = 0
-        #
-        # ### From Date
-        # - date -> string: Converts to ISO8601 format
-        # - date -> integer: Converts to Unix timestamp
-        # - date -> time: Converts to Time at midnight
-        # - date -> datetime: Converts to DateTime at midnight
-        #
-        # ### From Time
-        # - time -> string: Converts to ISO8601 format
-        # - time -> integer: Converts to Unix timestamp
-        # - time -> date: Converts to Date
-        # - time -> datetime: Converts to DateTime
-        #
-        # ### From DateTime
-        # - datetime -> string: Converts to ISO8601 format
-        # - datetime -> integer: Converts to Unix timestamp
-        # - datetime -> date: Converts to Date
-        # - datetime -> time: Converts to Time
-        #
-        # ## Important Notes
-        #
-        # - Cast option only works with scalar types (integer, string, boolean, date, time, 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 # rubocop:disable Metrics/ClassLength
-          # Types that support casting (scalar types only)
-          ALLOWED_CAST_TYPES = %i[integer string boolean date time 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
-          # @param _root_data [Hash] Unused root data parameter
-          # @return [Object] Converted value
-          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
-            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 },
-                date: ->(value:) { Time.at(value).to_date },
-                time: ->(value:) { Time.at(value) },
-                datetime: ->(value:) { Time.at(value).to_datetime }
-              },
-              string: {
-                string: ->(value:) { value }, # No-op for same type
-                integer: ->(value:) { Integer(value) },
-                boolean: ->(value:) { parse_boolean(value) },
-                date: ->(value:) { Date.parse(value) },
-                time: ->(value:) { Time.parse(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 }
-              },
-              date: {
-                date: ->(value:) { value }, # No-op for same type
-                string: ->(value:) { value.iso8601 },
-                integer: ->(value:) { value.to_time.to_i },
-                time: ->(value:) { value.to_time },
-                datetime: ->(value:) { value.to_datetime }
-              },
-              time: {
-                time: ->(value:) { value }, # No-op for same type
-                string: ->(value:) { value.iso8601 },
-                integer: ->(value:) { value.to_i },
-                date: ->(value:) { value.to_date },
-                datetime: ->(value:) { value.to_datetime }
-              },
-              datetime: {
-                datetime: ->(value:) { value }, # No-op for same type
-                string: ->(value:) { value.iso8601 },
-                integer: ->(value:) { value.to_i },
-                date: ->(value:) { value.to_date },
-                time: ->(value:) { value.to_time }
-              }
-            }
-          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/computed_modifier.rb

@@ -1,126 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Attribute
-    module Option
-      module Modifiers
-        # Sets default values for attributes when value is nil.
-        #
-        # ## Usage Examples
-        #
-        # Simple mode with static value:
-        #   integer :limit, default: 12
-        #   string :status, default: "pending"
-        #   boolean :active, default: false
-        #
-        # Simple mode with dynamic value (Proc):
-        #   datetime :created_at, default: -> { Time.current }
-        #   string :uuid, default: -> { SecureRandom.uuid }
-        #
-        # Advanced mode:
-        #   integer :limit, default: { is: 12, message: nil }
-        #
-        # ## Use Cases
-        #
-        # 1. **Response defaults** (most common):
-        #    ```ruby
-        #    response 200 do
-        #      object :meta do
-        #        integer :limit, default: 12
-        #        integer :page, default: 1
-        #      end
-        #    end
-        #    # Service returns: { meta: { page: 1 } }
-        #    # Output: { meta: { page: 1, limit: 12 } }
-        #    ```
-        #
-        # 2. **Request defaults**:
-        #    ```ruby
-        #    request do
-        #      string :format, default: "json"
-        #    end
-        #    # Input: {}
-        #    # Service receives: { format: "json" }
-        #    ```
-        #
-        # ## Important Notes
-        #
-        # - Default is applied ONLY when value is nil
-        # - Empty strings, empty arrays, false are NOT replaced
-        # - Proc defaults are called at transformation time
-        # - Procs receive no arguments
-        #
-        # ## Array and Object Types
-        #
-        # NOTE: DO NOT use `default: []` or `default: {}` for array/object types!
-        # Array and object types automatically represent empty collections.
-        #
-        # Incorrect:
-        #   array :tags, default: []      # Wrong! Redundant
-        #   object :meta, default: {}     # Wrong! Redundant
-        #
-        # Correct:
-        #   array :tags                   # Automatically handles empty array
-        #   object :meta                  # Automatically handles empty object
-        #
-        # ## Advanced Mode
-        #
-        # Schema format: `{ is: value_or_proc, message: nil }`
-        class DefaultModifier < Treaty::Attribute::Option::Base
-          # Validates schema (no validation needed)
-          # Default value can be any type
-          #
-          # @return [void]
-          def validate_schema!
-            # Schema structure is already normalized by OptionNormalizer.
-            # Default value can be any type, so nothing specific to validate here.
-          end
-
-          # Applies default value if current value is nil
-          # Empty strings, empty arrays, and false are NOT replaced
-          #
-          # @param value [Object] The current value
-          # @param _root_data [Hash] Unused root data parameter
-          # @return [Object] Default value if original is nil, otherwise original value
-          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?
-
-            default_value = option_value
-
-            # If default value is a Proc, call it to get the value
-            if default_value.is_a?(Proc)
-              default_value.call
-            else
-              default_value
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,112 +0,0 @@
-# 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
-          # @param _root_data [Hash] Unused root data parameter
-          # @return [Object] Transformed value
-          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
-
-            # 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