treaty 0.18.0 → 0.19.0

data/lib/treaty/entity/attribute/dsl.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # DSL module for defining attributes in Entity-like classes.
+      #
+      # This module provides the class-level DSL for defining attributes.
+      # It can be included in any class that needs attribute definition capabilities.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # class MyEntity
+      #   include Treaty::Entity::Attribute::DSL
+      #
+      #   string :name
+      #   integer :age
+      # end
+      # ```
+      module DSL
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # Defines an attribute with explicit type
+          #
+          # @param name [Symbol] The attribute name
+          # @param type [Symbol] The attribute type
+          # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [void]
+          def attribute(name, type, *helpers, **options, &block)
+            collection_of_attributes << create_attribute(
+              name,
+              type,
+              *helpers,
+              nesting_level: 0,
+              **options,
+              &block
+            )
+          end
+
+          # Returns collection of attributes for this class
+          #
+          # @return [Collection] Collection of attributes
+          def collection_of_attributes
+            @collection_of_attributes ||= Treaty::Entity::Attribute::Collection.new
+          end
+
+          # Handles DSL methods like `string :name` where method name is the type
+          #
+          # @param type [Symbol] The attribute type (method name)
+          # @param name [Symbol] The attribute name (first argument)
+          # @param helpers [Array<Symbol>] Helper symbols
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [void]
+          def method_missing(type, *helpers, **options, &block)
+            name = helpers.shift
+
+            # If no attribute name provided, this is not an attribute definition
+            # Pass to super to handle it properly (e.g., for methods like 'info', 'call!', etc.)
+            return super if name.nil?
+
+            attribute(name, type, *helpers, **options, &block)
+          end
+
+          def respond_to_missing?(name, *)
+            super
+          end
+
+          private
+
+          # Creates an attribute instance (must be implemented by including class)
+          #
+          # @raise [Treaty::Exceptions::NotImplemented] If not implemented
+          # @return [Attribute::Base] Created attribute instance
+          def create_attribute(*)
+            raise Treaty::Exceptions::NotImplemented,
+                  I18n.t(
+                    "treaty.attributes.dsl.create_attribute_not_implemented",
+                    class: self
+                  )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/helper_mapper.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # Maps DSL helper symbols to their simple mode option equivalents.
+      #
+      # ## Purpose
+      #
+      # Helpers provide the most concise syntax for common options.
+      # They are syntactic sugar that gets converted to simple mode options.
+      #
+      # ## Available Helpers
+      #
+      # - `:required` → `required: true`
+      # - `:optional` → `required: false`
+      #
+      # ## Usage Examples
+      #
+      # Helper mode (most concise):
+      #   string :title, :required
+      #   string :bio, :optional
+      #
+      # Equivalent to simple mode:
+      #   string :title, required: true
+      #   string :bio, required: false
+      #
+      # ## Processing Flow
+      #
+      # 1. Helper mode: `string :title, :required`
+      # 2. HelperMapper: `:required` → `required: true`
+      # 3. OptionNormalizer: `required: true` → `{ is: true, message: nil }`
+      # 4. Final: Advanced mode used internally
+      #
+      # ## Adding New Helpers
+      #
+      # To add a new helper:
+      # ```ruby
+      # HELPER_MAPPINGS = {
+      #   required: { required: true },
+      #   optional: { required: false },
+      #   my_helper: { my_option: :smth }  # New helper example
+      # }.freeze
+      # ```
+      class HelperMapper
+        HELPER_MAPPINGS = {
+          required: { required: true },
+          optional: { required: false }
+        }.freeze
+
+        class << self
+          # Maps helper symbols to their simple mode equivalents
+          #
+          # @param helpers [Array<Symbol>] Array of helper symbols
+          # @return [Hash] Simple mode options hash
+          def map(helpers)
+            helpers.each_with_object({}) do |helper, result|
+              mapping = HELPER_MAPPINGS.fetch(helper)
+              result.merge!(mapping) if mapping.present?
+            end
+          end
+
+          # Checks if a symbol is a registered helper
+          #
+          # @param symbol [Symbol] Symbol to check
+          # @return [Boolean] True if symbol is a helper
+          def helper?(symbol)
+            HELPER_MAPPINGS.key?(symbol)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        # Base class for all option processors (validators and modifiers).
+        #
+        # ## Option Modes
+        #
+        # Treaty supports two modes for defining options:
+        #
+        # 1. **Simple Mode** - Concise syntax for common cases:
+        #    - `required: true`
+        #    - `as: :value`
+        #    - `default: 12`
+        #    - `in: %w[twitter linkedin]`
+        #
+        # 2. **Advanced Mode** - Extended syntax with custom messages:
+        #    - `required: { is: true, message: "Custom error" }`
+        #    - `as: { is: :value, message: nil }`
+        #    - `inclusion: { in: %w[...], message: "Must be one of..." }`
+        #
+        # ## Helpers
+        #
+        # Helpers are shortcuts in DSL that map to simple mode options:
+        # - `:required` → `required: true`
+        # - `:optional` → `required: false`
+        #
+        # ## Advanced Mode Keys
+        #
+        # Each option in advanced mode has a value key:
+        # - Default key: `:is` (used by most options)
+        # - Special key: `:in` (used by inclusion validator)
+        #
+        # The value key is defined by overriding `value_key` method in subclasses.
+        #
+        # ## Processing Phases
+        #
+        # Each option processor can participate in three phases:
+        # - Phase 1: Schema validation (validate DSL definition correctness)
+        # - Phase 2: Value validation (validate runtime data values)
+        # - Phase 3: Value transformation (transform values: defaults, renaming, etc.)
+        class Base
+          # Creates a new option processor instance
+          #
+          # @param attribute_name [Symbol] The name of the attribute
+          # @param attribute_type [Symbol] The type of the attribute
+          # @param option_schema [Object] The option schema (simple or advanced mode)
+          def initialize(attribute_name:, attribute_type:, option_schema:)
+            @attribute_name = attribute_name
+            @attribute_type = attribute_type
+            @option_schema = option_schema
+          end
+
+          # Phase 1: Validates schema (DSL definition)
+          # Override in subclasses if validation is needed
+          #
+          # @raise [Treaty::Exceptions::Validation] If schema is invalid
+          # @return [void]
+          def validate_schema!
+            # No-op by default
+          end
+
+          # Phase 2: Validates value (runtime data)
+          # Override in subclasses if validation is needed
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is invalid
+          # @return [void]
+          def validate_value!(value)
+            # No-op by default
+          end
+
+          # Phase 3: Transforms value
+          # Returns transformed value or original if no transformation needed
+          # Override in subclasses if transformation is needed
+          #
+          # @param value [Object] The value to transform
+          # @param _root_data [Hash] Full raw data from root level (used by computed modifier)
+          # @return [Object] Transformed value
+          def transform_value(value, _root_data = {})
+            value
+          end
+
+          # Indicates if this option processor transforms attribute names
+          # Override in subclasses if needed (e.g., AsModifier)
+          #
+          # @return [Boolean] True if this processor transforms names
+          def transforms_name?
+            false
+          end
+
+          # Returns the target name for the attribute if this processor transforms names
+          # Override in subclasses if needed (e.g., AsModifier)
+          #
+          # @return [Symbol] The target attribute name
+          def target_name
+            @attribute_name
+          end
+
+          protected
+
+          # Returns the value key for this option in advanced mode
+          # Default is :is, but can be overridden (e.g., :in for inclusion)
+          #
+          # @return [Symbol] The key used to store the value in advanced mode
+          def value_key
+            :is
+          end
+
+          # Checks if option is enabled
+          # Handles both simple mode (boolean) and advanced mode (hash with value key)
+          #
+          # @return [Boolean] Whether the option is enabled
+          def option_enabled?
+            return false if @option_schema.nil?
+            return @option_schema if @option_schema.is_a?(TrueClass) || @option_schema.is_a?(FalseClass)
+
+            @option_schema.fetch(value_key, false)
+          end
+
+          # Extracts the actual value from normalized schema
+          # Works with both simple mode and advanced mode
+          #
+          # In simple mode: returns the value directly
+          # In advanced mode: extracts value using the appropriate key (is/in)
+          #
+          # @return [Object] The actual value from the option schema
+          def option_value
+            return @option_schema unless @option_schema.is_a?(Hash)
+
+            @option_schema.fetch(value_key, nil)
+          end
+
+          # Gets custom error message from advanced mode schema
+          # Returns nil if no custom message, which triggers I18n default message
+          #
+          # @return [String, Proc, nil] Custom error message, lambda, or nil for default message
+          def custom_message
+            return nil unless @option_schema.is_a?(Hash)
+
+            @option_schema.fetch(:message, nil)
+          end
+
+          # Resolves custom message with lambda support
+          # If message is a lambda, calls it with provided named arguments
+          # Catches all exceptions from lambda execution and re-raises as Validation errors
+          #
+          # @param attributes [Hash] Named arguments to pass to lambda
+          # @return [String, nil] Resolved message string or nil
+          # @raise [Treaty::Exceptions::Validation] If custom message lambda raises an exception
+          def resolve_custom_message(**attributes) # rubocop:disable Metrics/MethodLength
+            message = custom_message
+            return nil if message.nil?
+
+            if message.respond_to?(:call)
+              message.call(**attributes)
+            else
+              message
+            end
+          rescue StandardError => e
+            # Catch all exceptions from custom message lambda execution
+            error_message = I18n.t(
+              "treaty.attributes.options.message_evaluation_error",
+              attribute: @attribute_name,
+              error: e.message
+            )
+
+            raise Treaty::Exceptions::Validation, error_message
+          end
+
+          # Checks if schema is in advanced mode
+          #
+          # @return [Boolean] True if schema is in advanced mode (hash with value key)
+          def advanced_mode?
+            @option_schema.is_a?(Hash) && @option_schema.key?(value_key)
+          end
+
+          # Checks if schema is in simple mode
+          #
+          # @return [Boolean] True if schema is in simple mode (not a hash or no value key)
+          def simple_mode?
+            !advanced_mode?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Conditionals
+          # Base class for conditional option processors.
+          #
+          # ## Purpose
+          #
+          # Conditionals control whether an attribute should be processed at all.
+          # Unlike validators (which check data) and modifiers (which transform data),
+          # conditionals determine attribute visibility based on runtime conditions.
+          #
+          # ## Key Difference from Validators/Modifiers
+          #
+          # - **Validators**: Check if data is valid
+          # - **Modifiers**: Transform data values
+          # - **Conditionals**: Decide if attribute exists in output
+          #
+          # ## Processing
+          #
+          # Conditionals are evaluated BEFORE validators and modifiers:
+          # 1. If condition evaluates to `false` → attribute is skipped entirely
+          # 2. If condition evaluates to `true` → attribute is processed normally
+          #
+          # ## Mode Support
+          #
+          # Conditionals do NOT support simple/advanced modes.
+          # They only accept lambda/proc directly:
+          #
+          # ```ruby
+          # # Correct
+          # integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          # array :tags, if: ->(post:) { post[:published_at].present? }
+          #
+          # # Incorrect - no simple/advanced mode
+          # integer :rating, if: true  # Not supported
+          # integer :rating, if: { is: ..., message: ... }  # Not supported
+          # ```
+          #
+          # ## Implementation
+          #
+          # Subclasses must implement:
+          # - `validate_schema!` - Validate the conditional schema at definition time
+          # - `evaluate_condition(data)` - Evaluate condition with runtime data
+          class Base < Treaty::Entity::Attribute::Option::Base
+            # Phase 1: Validates conditional schema
+            # Must be overridden in subclasses
+            #
+            # @raise [Treaty::Exceptions::Validation] If schema is invalid
+            # @return [void]
+            def validate_schema!
+              raise Treaty::Exceptions::NotImplemented,
+                    "#{self.class} must implement #validate_schema!"
+            end
+
+            # Evaluates the conditional with runtime data
+            # Must be overridden in subclasses
+            #
+            # @param _data [Hash] Raw data to evaluate condition against
+            # @raise [Treaty::Exceptions::Validation] If evaluation fails
+            # @return [Boolean] True if attribute should be processed, false otherwise
+            def evaluate_condition(_data)
+              raise Treaty::Exceptions::NotImplemented,
+                    "#{self.class} must implement #evaluate_condition"
+            end
+
+            # Conditionals do not validate values
+            # This is a no-op for conditionals
+            #
+            # @param _value [Object] The value (unused)
+            # @return [void]
+            def validate_value!(_value)
+              # No-op: conditionals don't validate values
+            end
+
+            # Conditionals do not transform values
+            # This is a no-op for conditionals
+            #
+            # @param value [Object] The value to pass through
+            # @return [Object] The unchanged value
+            def transform_value(value)
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Option
+        module Conditionals
+          # Conditionally includes attributes based on runtime data evaluation.
+          #
+          # ## Usage Examples
+          #
+          # Basic usage with keyword arguments splat:
+          #   array :tags, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #   integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # Named argument pattern:
+          #   array :tags, if: ->(post:) { post[:published_at].present? }
+          #   integer :views, if: ->(post:) { post[:published_at].present? }
+          #
+          # Complex conditions:
+          #   string :admin_note, if: (lambda do |**attributes|
+          #     attributes.dig(:user, :role) == "admin" && attributes.dig(:post, :flagged)
+          #   end)
+          #
+          # ## Use Cases
+          #
+          # 1. **Show fields only when published**:
+          #    ```ruby
+          #    response 200 do
+          #      object :post do
+          #        string :id
+          #        string :title
+          #        datetime :published_at, :optional
+          #        integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #      end
+          #    end
+          #    # If published_at is nil → rating is excluded from response
+          #    # If published_at exists → rating is included
+          #    ```
+          #
+          # 2. **Role-based field visibility**:
+          #    ```ruby
+          #    response 200 do
+          #      object :user do
+          #        string :name
+          #        string :email, if: ->(user:) { user[:role] == "admin" }
+          #      end
+          #    end
+          #    ```
+          #
+          # 3. **Nested attribute conditionals**:
+          #    ```ruby
+          #    object :post do
+          #      string :title
+          #      array :tags, if: ->(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 false → attribute is completely omitted
+          # - If condition is true → attribute is validated and transformed normally
+          # - All exceptions in lambda are caught and wrapped in Treaty::Exceptions::Validation
+          # - Does NOT support simple mode (if: true) or advanced mode (if: { is: ..., message: ... })
+          #
+          # ## 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 :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+          #
+          # # Alternative: named argument pattern
+          # integer :rating, if: ->(post:) { post[:published_at].present? }
+          # ```
+          class IfConditional < Treaty::Entity::Attribute::Option::Conditionals::Base
+            # Validates that if option is a callable (Proc/Lambda)
+            #
+            # @raise [Treaty::Exceptions::Validation] If if 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.if.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, 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
+              !!result
+            rescue StandardError => e
+              # Catch all exceptions from lambda execution
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.if.evaluation_error",
+                      attribute: @attribute_name,
+                      error: e.message
+                    )
+            end
+          end
+        end
+      end
+    end
+  end
+end