treaty 0.17.0 → 0.19.0

data/lib/treaty/entity/attribute/option/conditionals/unless_conditional.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Conditionals
+          # Conditionally excludes attributes based on runtime data evaluation.
+          #
+          # ## Usage Examples
+          #
+          # Basic usage with keyword arguments splat:
+          #   array :tags, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #   integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # Named argument pattern:
+          #   array :draft_notes, unless: ->(post:) { post[:published_at].present? }
+          #   integer :edit_count, unless: ->(post:) { post[:published_at].present? }
+          #
+          # Complex conditions:
+          #   string :internal_note, unless: (lambda do |**attributes|
+          #     attributes.dig(:user, :role) == "admin" && attributes.dig(:post, :flagged)
+          #   end)
+          #
+          # ## Use Cases
+          #
+          # 1. **Hide fields when published**:
+          #    ```ruby
+          #    response 200 do
+          #      object :post do
+          #        string :id
+          #        string :title
+          #        datetime :published_at, :optional
+          #        integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #      end
+          #    end
+          #    # If published_at is nil → draft_views is included in response
+          #    # If published_at exists → draft_views is excluded
+          #    ```
+          #
+          # 2. **Role-based field exclusion**:
+          #    ```ruby
+          #    response 200 do
+          #      object :user do
+          #        string :name
+          #        string :internal_id, unless: ->(user:) { user[:role] == "public" }
+          #      end
+          #    end
+          #    ```
+          #
+          # 3. **Nested attribute conditionals**:
+          #    ```ruby
+          #    object :post do
+          #      string :title
+          #      array :draft_notes, unless: ->(post:) { post[:published_at].present? } do
+          #        string :_self
+          #      end
+          #    end
+          #    ```
+          #
+          # ## Important Notes
+          #
+          # - Lambda receives raw data as named arguments
+          # - Lambda MUST return truthy/falsy value
+          # - If condition is true → attribute is completely omitted (OPPOSITE of `if`)
+          # - If condition is false → attribute is validated and transformed normally
+          # - All exceptions in lambda are caught and wrapped in Treaty::Exceptions::Validation
+          # - Does NOT support simple mode (unless: true) or advanced mode (unless: { is: ..., message: ... })
+          #
+          # ## Difference from `if` Option
+          #
+          # `unless` is the logical opposite of `if`:
+          # - `if` includes attribute when condition is TRUE
+          # - `unless` includes attribute when condition is FALSE
+          #
+          # ```ruby
+          # # These are equivalent:
+          # integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          # integer :rating, unless: ->(**attributes) { attributes.dig(:post, :published_at).blank? }
+          #
+          # # These are also equivalent:
+          # integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          # integer :draft_views, if: ->(**attributes) { attributes.dig(:post, :published_at).blank? }
+          # ```
+          #
+          # ## Error Handling
+          #
+          # If the lambda raises any exception, it's caught and converted to a
+          # Treaty::Exceptions::Validation with detailed error message including:
+          # - Attribute name
+          # - Original exception message
+          #
+          # ## Data Access Pattern
+          #
+          # The lambda receives the same data structure that the orchestrator processes.
+          # For nested attributes, you can access parent data using dig:
+          #
+          # ```ruby
+          # # For response with { post: { title: "...", published_at: "..." } }
+          # integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # # Alternative: named argument pattern
+          # integer :draft_views, unless: ->(post:) { post[:published_at].present? }
+          # ```
+          class UnlessConditional < Treaty::Entity::Attribute::Option::Conditionals::Base
+            # Validates that unless option is a callable (Proc/Lambda)
+            #
+            # @raise [Treaty::Exceptions::Validation] If unless is not a Proc/lambda
+            # @return [void]
+            def validate_schema!
+              conditional_lambda = @option_schema
+
+              return if conditional_lambda.respond_to?(:call)
+
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.unless.invalid_type",
+                      attribute: @attribute_name,
+                      type: conditional_lambda.class
+                    )
+            end
+
+            # Evaluates the conditional lambda with runtime data
+            # Returns boolean indicating if attribute should be processed
+            #
+            # @param data [Hash] Raw data from request/response/entity
+            # @raise [Treaty::Exceptions::Validation] If lambda execution fails
+            # @return [Boolean] True if attribute should be processed (when condition is FALSE), false to skip it
+            def evaluate_condition(data)
+              conditional_lambda = @option_schema
+
+              # Call lambda with raw data as named arguments
+              # The lambda can use **attributes or specific named args like post:
+              result = conditional_lambda.call(**data)
+
+              # Convert result to boolean and NEGATE it (opposite of if)
+              # unless includes attribute when condition is FALSE
+              !result
+            rescue StandardError => e
+              # Catch all exceptions from lambda execution
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.unless.evaluation_error",
+                      attribute: @attribute_name,
+                      error: e.message
+                    )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Modifiers
+          # Transforms attribute names during data processing.
+          #
+          # ## Usage Examples
+          #
+          # Simple mode:
+          #   # Request: expects "handle", outputs as "value"
+          #   string :handle, as: :value
+          #
+          # Advanced mode:
+          #   string :handle, as: { is: :value, message: nil }
+          #
+          # ## Use Cases
+          #
+          # 1. **Request to Service mapping**:
+          #    ```ruby
+          #    request do
+          #      string :user_id, as: :id
+          #    end
+          #    # Input: { user_id: "123" }
+          #    # Service receives: { id: "123" }
+          #    ```
+          #
+          # 2. **Service to Response mapping**:
+          #    ```ruby
+          #    response 200 do
+          #      string :id, as: :user_id
+          #    end
+          #    # Service returns: { id: "123" }
+          #    # Output: { user_id: "123" }
+          #    ```
+          #
+          # ## How It Works
+          #
+          # AsModifier doesn't transform values - it transforms attribute names.
+          # The orchestrator uses `target_name` to map source name to target name.
+          #
+          # ## Advanced Mode
+          #
+          # Schema format: `{ is: :symbol, message: nil }`
+          class AsModifier < Treaty::Entity::Attribute::Option::Base
+            # Validates that target name is a Symbol
+            #
+            # @raise [Treaty::Exceptions::Validation] If target is not a Symbol
+            # @return [void]
+            def validate_schema!
+              target = option_value
+
+              return if target.is_a?(Symbol)
+
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.modifiers.as.invalid_type",
+                      attribute: @attribute_name,
+                      type: target.class
+                    )
+            end
+
+            # Indicates that AsModifier transforms attribute names
+            #
+            # @return [Boolean] Always returns true
+            def transforms_name?
+              true
+            end
+
+            # Returns the target name for the attribute
+            #
+            # @return [Symbol] The target attribute name
+            def target_name
+              option_value
+            end
+
+            # AsModifier doesn't modify the value itself, only the name
+            # 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, _root_data = {})
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

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