treaty 0.18.0 → 0.20.0

data/lib/treaty/attribute/base.rb

@@ -1,182 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Attribute
-    # Base class for all attribute definitions in Treaty DSL.
-    #
-    # ## Purpose
-    #
-    # Represents a single attribute defined in request/response definitions.
-    # Handles:
-    # - Attribute metadata (name, type, nesting level)
-    # - Helper mode to simple mode conversion
-    # - Simple mode to advanced mode normalization
-    # - Nested attributes (for object and array types)
-    #
-    # ## Usage
-    #
-    # Attributes are created through DSL methods:
-    #   string :title, :required
-    #   integer :age, default: 18
-    #   object :author do
-    #     string :name
-    #   end
-    #
-    # ## Processing Flow
-    #
-    # 1. Extract helpers from arguments (`:required`, `:optional`)
-    # 2. Convert helpers to simple mode options
-    # 3. Merge with explicit options
-    # 4. Normalize all options to advanced mode
-    # 5. Apply defaults (required: true for request, false for response)
-    # 6. Process nested attributes if block given
-    #
-    # ## Nested Attributes
-    #
-    # Object and array types can have nested attributes:
-    # - `object` - nested attributes as direct children
-    # - `array` - nested attributes define array element structure
-    #
-    # Special attribute name `:_self` is used for simple arrays:
-    #   array :tags do
-    #     string :_self  # Array of strings
-    #   end
-    class Base
-      attr_reader :name,
-                  :type,
-                  :options,
-                  :nesting_level
-
-      # Creates a new attribute instance
-      #
-      # @param name [Symbol] The attribute name
-      # @param type [Symbol] The attribute type (:string, :integer, :object, :array, etc.)
-      # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
-      # @param nesting_level [Integer] Current nesting depth (default: 0)
-      # @param options [Hash] Attribute options (required, default, as, etc.)
-      # @param block [Proc] Block for defining nested attributes (for object/array types)
-      def initialize(name, type, *helpers, nesting_level: 0, **options, &block)
-        @name = name
-        @type = type
-        @nesting_level = nesting_level
-
-        validate_nesting_level!
-
-        # Separate helpers from non-helper symbols.
-        @helpers = extract_helpers(helpers)
-
-        # Merge helper options with explicit options.
-        merged_options = merge_options(@helpers, options)
-
-        # Normalize all options to advanced mode.
-        @options = OptionNormalizer.normalize(merged_options)
-
-        apply_defaults!
-
-        # Process nested attributes for object and array types.
-        process_nested_attributes(&block) if block_given?
-      end
-
-      # Returns collection of nested attributes for this attribute
-      #
-      # @return [Collection] Collection of nested attributes
-      def collection_of_attributes
-        @collection_of_attributes ||= Collection.new
-      end
-
-      # Checks if this attribute has nested attributes
-      #
-      # @return [Boolean] True if attribute is object/array with nested attributes
-      def nested?
-        object_or_array? && collection_of_attributes.exists?
-      end
-
-      # Checks if this attribute is an object or array type
-      #
-      # @return [Boolean] True if type is :object or :array
-      def object_or_array?
-        object? || array?
-      end
-
-      # Checks if this attribute is an object type
-      #
-      # @return [Boolean] True if type is :object
-      def object?
-        @type == :object
-      end
-
-      # Checks if this attribute is an array type
-      #
-      # @return [Boolean] True if type is :array
-      def array?
-        @type == :array
-      end
-
-      private
-
-      # Validates that nesting level doesn't exceed maximum allowed depth
-      #
-      # @raise [Treaty::Exceptions::NestedAttributes] If nesting exceeds limit
-      # @return [void]
-      def validate_nesting_level!
-        return unless @nesting_level > Treaty::Engine.config.treaty.attribute_nesting_level
-
-        raise Treaty::Exceptions::NestedAttributes,
-              I18n.t(
-                "treaty.attributes.errors.nesting_level_exceeded",
-                level: @nesting_level,
-                max_level: Treaty::Engine.config.treaty.attribute_nesting_level
-              )
-      end
-
-      # Extracts helper symbols from arguments
-      #
-      # @param helpers [Array] Mixed array that may contain helper symbols
-      # @return [Array<Symbol>] Filtered array of valid helper symbols
-      def extract_helpers(helpers)
-        helpers.select do |helper|
-          helper.is_a?(Symbol) && HelperMapper.helper?(helper)
-        end
-      end
-
-      # Merges helper-derived options with explicit options
-      #
-      # @param helpers [Array<Symbol>] Helper symbols to convert
-      # @param explicit_options [Hash] Explicitly provided options
-      # @return [Hash] Merged options hash
-      def merge_options(helpers, explicit_options)
-        helper_options = HelperMapper.map(helpers)
-        helper_options.merge(explicit_options)
-      end
-
-      # Applies default values for options based on context (request/response)
-      # Must be implemented in subclasses
-      #
-      # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
-      # @return [void]
-      def apply_defaults!
-        # Must be implemented in subclasses
-        raise Treaty::Exceptions::NotImplemented,
-              I18n.t(
-                "treaty.attributes.errors.apply_defaults_not_implemented",
-                class: self.class
-              )
-      end
-
-      # Processes nested attributes block for object/array types
-      # Must be implemented in subclasses
-      #
-      # @param block [Proc] Block containing nested attribute definitions
-      # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
-      # @return [void]
-      def process_nested_attributes
-        # Must be implemented in subclasses
-        raise Treaty::Exceptions::NotImplemented,
-              I18n.t(
-                "treaty.attributes.errors.process_nested_not_implemented",
-                class: self.class
-              )
-      end
-    end
-  end
-end

data/lib/treaty/attribute/builder/base.rb

@@ -1,273 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Attribute
-    module Builder
-      # Base DSL builder for defining attributes in request/response definitions.
-      #
-      # ## Purpose
-      #
-      # Provides the DSL interface for defining attributes within objects.
-      # Handles method_missing magic to support type-based method calls.
-      #
-      # ## Responsibilities
-      #
-      # 1. **DSL Interface** - Provides clean syntax for attribute definitions
-      # 2. **Method Dispatch** - Routes type methods (string, integer, etc.) to attribute creation
-      # 3. **Helper Support** - Handles helper symbols in various positions
-      # 4. **Nesting Tracking** - Tracks nesting level for nested attributes
-      # 5. **Entity Reuse** - Supports use_entity for copying attributes from Entity classes
-      #
-      # ## DSL Usage
-      #
-      # The builder enables this clean DSL syntax:
-      #
-      # ```ruby
-      # request do
-      #   object :user do
-      #     string :name
-      #     integer :age, default: 18
-      #     object :profile do
-      #       string :bio
-      #     end
-      #   end
-      # end
-      # ```
-      #
-      # ## Entity Reuse
-      #
-      # You can use `use_entity` to copy attributes from an Entity class:
-      #
-      # ```ruby
-      # object :author do
-      #   use_entity(AuthorEntity)
-      # end
-      # ```
-      #
-      # Note: `use_entity` must be the only statement in the block.
-      #
-      # ## Method Dispatch
-      #
-      # ### Type-based Methods
-      # When you call `string :name`, it routes through `method_missing`:
-      # 1. `string` becomes the type
-      # 2. `:name` becomes the attribute name
-      # 3. Calls `attribute(:name, :string, ...)`
-      #
-      # ### Helper Position Handling
-      # Handles helpers in different positions:
-      #
-      # ```ruby
-      # string :required, :name    # Helper first, then name
-      # string :name, :required    # Name first, then helper
-      # ```
-      #
-      # Both resolve to the same attribute definition.
-      #
-      # ## Nesting
-      #
-      # Tracks nesting level for:
-      # - Validation (enforcing maximum nesting depth)
-      # - Error messages (showing context)
-      #
-      # Maximum nesting level is configured in Treaty::Engine.config.
-      #
-      # ## Subclass Requirements
-      #
-      # Subclasses must implement:
-      # - `create_attribute` - Creates the appropriate attribute type (Request/Response)
-      # - `deep_copy_attribute` - Deep copies an attribute with adjusted nesting level
-      #
-      # ## Architecture
-      #
-      # Used by:
-      # - Request::Builder - For request attribute definitions
-      # - Response::Builder - For response attribute definitions
-      # - Entity::Builder - For entity attribute definitions
-      class Base
-        attr_reader :nesting_level,
-                    :collection_of_attributes
-
-        # Creates a new builder instance
-        #
-        # @param collection_of_attributes [Collection] Collection to add attributes to
-        # @param nesting_level [Integer] Current nesting depth
-        def initialize(collection_of_attributes, nesting_level)
-          @collection_of_attributes = collection_of_attributes
-          @nesting_level = nesting_level
-          @use_entity_called = false
-          @attributes_defined = false
-        end
-
-        # Uses an Entity class to copy its attributes into this builder's collection.
-        # Must be the ONLY statement in the block - no other attributes allowed.
-        #
-        # @param entity_class [Class] Entity class (must be Treaty::Entity subclass)
-        # @raise [Treaty::Exceptions::Validation] if entity_class is invalid
-        # @raise [Treaty::Exceptions::Validation] if mixed with other attributes
-        # @return [void]
-        #
-        # @example Using an Entity in a nested object
-        #   object :author do
-        #     use_entity(AuthorEntity)
-        #   end
-        #
-        # @example Using an Entity in a nested array
-        #   array :items, :optional do
-        #     use_entity(ItemEntity)
-        #   end
-        def use_entity(entity_class)
-          validate_use_entity_preconditions!
-          validate_entity_class!(entity_class)
-
-          @use_entity_called = true
-
-          copy_attributes_from_entity(entity_class)
-        end
-
-        # 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)
-          validate_no_use_entity_called!
-
-          @attributes_defined = true
-
-          @collection_of_attributes << create_attribute(
-            name,
-            type,
-            *helpers,
-            nesting_level: @nesting_level,
-            **options,
-            &block
-          )
-        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, name, *helpers, **options, &block)
-          if name.is_a?(Symbol) && HelperMapper.helper?(name)
-            helpers.unshift(name)
-            name = helpers.shift
-          end
-
-          attribute(name, type, *helpers, **options, &block)
-        end
-
-        # Checks if method should be handled by method_missing
-        #
-        # @param name [Symbol] Method name
-        # @return [Boolean]
-        def respond_to_missing?(name, *)
-          super
-        end
-
-        private
-
-        # Creates an attribute instance (must be implemented in subclasses)
-        #
-        # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
-        # @return [Attribute::Base] Created attribute instance
-        def create_attribute(*)
-          raise Treaty::Exceptions::NotImplemented,
-                I18n.t("treaty.attributes.builder.not_implemented", class: self.class)
-        end
-
-        # Validates that use_entity can be called (no attributes defined before)
-        #
-        # @raise [Treaty::Exceptions::Validation] if attributes were defined before use_entity
-        def validate_use_entity_preconditions!
-          return unless @attributes_defined
-
-          raise Treaty::Exceptions::Validation,
-                I18n.t("treaty.attributes.builder.use_entity_after_attributes")
-        end
-
-        # Validates that no use_entity was called before defining attributes
-        #
-        # @raise [Treaty::Exceptions::Validation] if use_entity was already called
-        def validate_no_use_entity_called!
-          return unless @use_entity_called
-
-          raise Treaty::Exceptions::Validation,
-                I18n.t("treaty.attributes.builder.attributes_after_use_entity")
-        end
-
-        # Validates that entity_class is a valid Treaty::Entity subclass
-        #
-        # @param entity_class [Class] Entity class to validate
-        # @raise [Treaty::Exceptions::Validation] if entity_class is not valid
-        def validate_entity_class!(entity_class)
-          return if entity_class.is_a?(Class) && entity_class < Treaty::Entity
-
-          raise Treaty::Exceptions::Validation,
-                I18n.t(
-                  "treaty.attributes.builder.invalid_entity_class",
-                  type: entity_class.class,
-                  value: entity_class
-                )
-        end
-
-        # Copies all attributes from entity_class to this builder's collection
-        # with adjusted nesting levels.
-        #
-        # @param entity_class [Class] Source entity class
-        def copy_attributes_from_entity(entity_class)
-          entity_class.collection_of_attributes.each do |source_attribute|
-            copied_attribute = deep_copy_attribute(source_attribute, @nesting_level)
-            @collection_of_attributes << copied_attribute
-          end
-        end
-
-        # Deep copies an attribute with adjusted nesting level.
-        # Must be implemented by subclasses to use proper attribute types.
-        #
-        # @param source_attribute [Attribute::Base] Attribute to copy
-        # @param new_nesting_level [Integer] New nesting level for copied attribute
-        # @return [Attribute::Base] Copied attribute with correct type
-        def deep_copy_attribute(_source_attribute, _new_nesting_level)
-          raise Treaty::Exceptions::NotImplemented,
-                I18n.t(
-                  "treaty.attributes.builder.deep_copy_not_implemented",
-                  class: self.class
-                )
-        end
-
-        # Deep copies options hash, preserving Proc references
-        # and recursively handling nested Hash/Array structures.
-        #
-        # @param options [Hash] Options to copy
-        # @return [Hash] Copied options
-        def deep_copy_options(options)
-          options.transform_values { |value| deep_copy_value(value) }
-        end
-
-        # Deep copies a single value, handling nested structures.
-        # Immutable types (Proc, Symbol, Numeric, nil, true, false) are returned as-is.
-        # Hash and Array are recursively copied. Strings are duplicated if not frozen.
-        #
-        # @param value [Object] Value to copy
-        # @return [Object] Copied value
-        def deep_copy_value(value)
-          case value
-          when Hash  then value.transform_values { |v| deep_copy_value(v) }
-          when Array then value.map { |v| deep_copy_value(v) }
-          when String then value.frozen? ? value : value.dup
-          else value
-          end
-        end
-      end
-    end
-  end
-end

data/lib/treaty/attribute/collection.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require "forwardable"
-
-module Treaty
-  module Attribute
-    # Collection wrapper for sets of attributes.
-    #
-    # ## Purpose
-    #
-    # Provides a unified interface for working with collections of attributes.
-    # Uses Ruby Set internally for uniqueness but exposes Array-like interface.
-    #
-    # ## Usage
-    #
-    # Used internally by:
-    # - Request/Response factories (to store attributes)
-    # - Attribute::Base (to store nested attributes)
-    #
-    # ## Methods
-    #
-    # Delegates common collection methods to internal Set:
-    # - `<<` - Add attribute
-    # - `each`, `map`, `select`, `reject` - Iteration
-    # - `find`, `first` - Access
-    # - `size`, `empty?` - Size checks
-    # - `to_h` - Convert to hash
-    #
-    # Custom methods:
-    # - `exists?` - Returns true if collection is not empty
-    #
-    # ## Example
-    #
-    #   collection = Collection.new
-    #   collection << Attribute::Base.new(:name, :string)
-    #   collection << Attribute::Base.new(:age, :integer)
-    #   collection.size  # => 2
-    #   collection.exists?  # => true
-    class Collection
-      extend Forwardable
-
-      def_delegators :@collection,
-                     :<<,
-                     :to_h, :map,
-                     :each_with_object, :each,
-                     :select, :reject, :size,
-                     :find, :first,
-                     :empty?
-
-      # Creates a new collection instance
-      #
-      # @param collection [Set] Initial collection (default: empty Set)
-      def initialize(collection = Set.new)
-        @collection = collection
-      end
-
-      # Checks if collection has any elements
-      #
-      # @return [Boolean] True if collection is not empty
-      def exists?
-        !empty?
-      end
-    end
-  end
-end

data/lib/treaty/attribute/dsl.rb

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

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

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Treaty
-  module Attribute
-    module Entity
-      # Entity-specific attribute builder
-      class Builder < Treaty::Attribute::Builder::Base
-        private
-
-        def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
-          Attribute.new(
-            name,
-            type,
-            *helpers,
-            nesting_level:,
-            **options,
-            &block
-          )
-        end
-
-        # Deep copies an attribute with adjusted nesting level for Entity context.
-        #
-        # @param source_attribute [Treaty::Attribute::Base] Attribute to copy
-        # @param new_nesting_level [Integer] New nesting level
-        # @return [Entity::Attribute] Copied attribute
-        def deep_copy_attribute(source_attribute, new_nesting_level) # rubocop:disable Metrics/MethodLength
-          copied = Attribute.new(
-            source_attribute.name,
-            source_attribute.type,
-            nesting_level: new_nesting_level,
-            **deep_copy_options(source_attribute.options)
-          )
-
-          return copied unless source_attribute.nested?
-
-          source_attribute.collection_of_attributes.each do |nested_source|
-            nested_copied = deep_copy_attribute(nested_source, new_nesting_level + 1)
-            copied.collection_of_attributes << nested_copied
-          end
-
-          copied
-        end
-      end
-    end
-  end
-end