treaty 0.18.0 → 0.20.0

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

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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::Entity::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
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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: (lambda do |**attributes|
+          #     "#{attributes.dig(:user, :first_name)} #{attributes.dig(:user, :last_name)}"
+          #   end)
+          #
+          # Advanced mode with custom error message:
+          #   string :full_name, computed: {
+          #     is: ->(**attributes) { "#{attributes.dig(:user, :first_name)} #{attributes.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: (lambda do |**attributes|
+          #          "#{attributes.dig(:user, :first_name)} #{attributes.dig(:user, :last_name)}"
+          #        end)
+          #      end
+          #    end
+          #    ```
+          #
+          # 2. **Calculated values (word count)**:
+          #    ```ruby
+          #    response 200 do
+          #      object :post do
+          #        string :content
+          #        integer :word_count, computed: (lambda do |**attributes|
+          #          attributes.dig(:post, :content).to_s.split.size
+          #        end)
+          #      end
+          #    end
+          #    ```
+          #
+          # 3. **Cross-object computations**:
+          #    ```ruby
+          #    response 200 do
+          #      object :order do
+          #        integer :quantity
+          #        integer :unit_price
+          #        integer :total, computed: (lambda do |**attributes|
+          #          attributes.dig(:order, :quantity).to_i * attributes.dig(:order, :unit_price).to_i
+          #        end)
+          #      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::Entity::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
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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::Entity::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
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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::Entity::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
+end