treaty 0.17.0 → 0.19.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,143 +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
-      #
-      # ## 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
-      # ```
-      #
-      # ## 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)
-      #
-      # ## Architecture
-      #
-      # Used by:
-      # - Request::Builder - For request attribute definitions
-      # - Response::Builder - For response 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
-        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)
-          @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(*)
-          # Must be implemented in subclasses
-          raise Treaty::Exceptions::NotImplemented,
-                I18n.t("treaty.attributes.builder.not_implemented", class: self.class)
-        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,23 +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
-      end
-    end
-  end
-end

data/lib/treaty/attribute/helper_mapper.rb

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