treaty 0.7.0 → 0.8.0

data/lib/treaty/entity.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Treaty
+  # Base class for defining DTO (Data Transfer Object) entities in Treaty.
+  #
+  # ## Purpose
+  #
+  # Treaty::Entity provides a base class for creating reusable DTO classes
+  # that can be used in both request and response definitions. This allows
+  # for better code organization and reusability of common data structures.
+  #
+  # ## Usage
+  #
+  # Create a DTO class by inheriting from Treaty::Entity:
+  #
+  # ```ruby
+  # class PostEntity < Treaty::Entity
+  #   string :id
+  #   string :title
+  #   string :content
+  #   datetime :created_at
+  # end
+  # ```
+  #
+  # Then use it in your treaty definitions:
+  #
+  # ```ruby
+  # class CreateTreaty < ApplicationTreaty
+  #   version 1 do
+  #     request PostEntity
+  #     response 201, PostEntity
+  #   end
+  # end
+  # ```
+  #
+  # ## Attribute Defaults
+  #
+  # Unlike request/response blocks, Entity attributes are required by default:
+  # - All attributes have `required: true` unless explicitly marked as `:optional`
+  # - Use `:optional` helper to make attributes optional:
+  #   ```ruby
+  #   string :title           # required by default
+  #   string :summary, :optional  # optional
+  #   ```
+  #
+  # ## Features
+  #
+  # - **Type Safety** - Enforce strict type checking for all attributes
+  # - **Nested Structures** - Support for nested objects and arrays
+  # - **Validation** - Built-in validation for all attribute types
+  # - **Reusability** - Define once, use in multiple treaties
+  # - **Options** - Full support for attribute options (required, default, as, etc.)
+  #
+  # ## Supported Types
+  #
+  # - `string` - String values
+  # - `integer` - Integer values
+  # - `boolean` - Boolean values (true/false)
+  # - `datetime` - DateTime values
+  # - `array` - Array values (with nested type definition)
+  # - `object` - Object values (with nested attributes)
+  class Entity
+    include Info::Entity::DSL
+    include Attribute::DSL
+
+    class << self
+      private
+
+      # Creates an Attribute::Entity::Attribute for this Entity class
+      #
+      # @return [Attribute::Entity::Attribute] Created attribute instance
+      def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+        Attribute::Entity::Attribute.new(
+          name,
+          type,
+          *helpers,
+          nesting_level:,
+          **options,
+          &block
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Entity
+      class Builder
+        attr_reader :attributes
+
+        def self.build(...)
+          new.build(...)
+        end
+
+        def build(collection_of_attributes:)
+          build_all(
+            attributes: collection_of_attributes
+          )
+
+          self
+        end
+
+        private
+
+        def build_all(attributes:)
+          @attributes = build_versions_with(attributes)
+        end
+
+        ##########################################################################
+
+        def build_versions_with(collection, current_level = 0)
+          collection.to_h do |attribute|
+            [
+              attribute.name,
+              {
+                type: attribute.type,
+                options: attribute.options,
+                attributes: build_nested_attributes(attribute, current_level)
+              }
+            ]
+          end
+        end
+
+        def build_nested_attributes(attribute, current_level)
+          return {} unless attribute.nested?
+
+          build_versions_with(attribute.collection_of_attributes, current_level + 1)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Entity
+      module DSL
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def info
+            builder = Builder.build(
+              collection_of_attributes:
+            )
+
+            Result.new(builder)
+          end
+
+          # API: Treaty Web
+          def treaty?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/info/entity/result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Entity
+      class Result
+        attr_reader :attributes
+
+        def initialize(builder)
+          @attributes = builder.attributes
+        end
+      end
+    end
+  end
+end

data/lib/treaty/info/rest/builder.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Rest
+      class Builder
+        attr_reader :versions
+
+        def self.build(...)
+          new.build(...)
+        end
+
+        def build(collection_of_versions:)
+          build_all(
+            versions: collection_of_versions
+          )
+
+          self
+        end
+
+        private
+
+        def build_all(versions:)
+          build_versions_with(
+            collection: versions
+          )
+        end
+
+        ##########################################################################
+
+        def build_versions_with(collection:) # rubocop:disable Metrics/MethodLength
+          @versions = collection.map do |version|
+            gem_version = version.version.version
+            {
+              version: gem_version.version,
+              segments: gem_version.segments,
+              default: version.default_result,
+              summary: version.summary_text,
+              strategy: version.strategy_instance.code,
+              deprecated: version.deprecated_result,
+              executor: build_executor_with(version),
+              request: build_request_with(version),
+              response: build_response_with(version)
+            }
+          end
+        end
+
+        ##########################################################################
+
+        def build_executor_with(version)
+          {
+            executor: version.executor.executor,
+            method: version.executor.method
+          }
+        end
+
+        ##########################################################################
+
+        def build_request_with(version)
+          build_attributes_structure(version.request_factory)
+        end
+
+        def build_response_with(version)
+          response_factory = version.response_factory
+          {
+            status: response_factory.status
+          }.merge(build_attributes_structure(response_factory))
+        end
+
+        ##########################################################################
+
+        def build_attributes_structure(factory)
+          {
+            attributes: build_attributes_hash(factory.collection_of_attributes)
+          }
+        end
+
+        def build_attributes_hash(collection, current_level = 0)
+          # validate_nesting_level!(current_level)
+
+          collection.to_h do |attribute|
+            [
+              attribute.name,
+              {
+                type: attribute.type,
+                options: attribute.options,
+                attributes: build_nested_attributes(attribute, current_level)
+              }
+            ]
+          end
+        end
+
+        def build_nested_attributes(attribute, current_level)
+          return {} unless attribute.nested?
+
+          build_attributes_hash(attribute.collection_of_attributes, current_level + 1)
+        end
+
+        # def validate_nesting_level!(level)
+        #   return unless level > Treaty::Engine.config.treaty.attribute_nesting_level
+        #
+        #   raise Treaty::Exceptions::NestedAttributes,
+        #         I18n.t("treaty.attributes.errors.nesting_level_exceeded",
+        #                level:,
+        #                max_level: Treaty::Engine.config.treaty.attribute_nesting_level)
+        # end
+      end
+    end
+  end
+end

data/lib/treaty/info/rest/dsl.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Rest
+      module DSL
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def info
+            builder = Builder.build(
+              collection_of_versions:
+            )
+
+            Result.new(builder)
+          end
+
+          # API: Treaty Web
+          def treaty?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/info/rest/result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Info
+    module Rest
+      class Result
+        attr_reader :versions
+
+        def initialize(builder)
+          @versions = builder.versions
+        end
+      end
+    end
+  end
+end

data/lib/treaty/request/attribute/attribute.rb

@@ -3,6 +3,7 @@
 module Treaty
   module Request
     module Attribute
+      # Request-specific attribute that defaults to required: true
       class Attribute < Treaty::Attribute::Base
         private
 

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

@@ -3,6 +3,7 @@
 module Treaty
   module Request
     module Attribute
+      # Request-specific attribute builder
       class Builder < Treaty::Attribute::Builder::Base
         private
 

data/lib/treaty/request/entity.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Request
+    # Entity class for request definitions.
+    # Attributes are required by default.
+    #
+    # This class is used internally when defining request blocks.
+    # When you write a request block, Treaty creates an anonymous
+    # class based on Request::Entity.
+    class Entity
+      include Treaty::Attribute::DSL
+
+      class << self
+        private
+
+        # Creates a Request::Attribute::Attribute for this Request::Entity class
+        #
+        # @return [Request::Attribute::Attribute] Created attribute instance
+        def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+          Attribute::Attribute.new(
+            name,
+            type,
+            *helpers,
+            nesting_level:,
+            **options,
+            &block
+          )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/request/factory.rb

@@ -2,33 +2,80 @@
 
 module Treaty
   module Request
+    # Factory for creating request definitions.
+    #
+    # Supports two modes:
+    # 1. Block mode: Creates an anonymous Request::Entity class with the block
+    # 2. Entity mode: Uses a provided Entity class directly
+    #
+    # ## Block Mode
+    #
+    # ```ruby
+    # request do
+    #   object :post do
+    #     string :title
+    #   end
+    # end
+    # ```
+    #
+    # ## Entity Mode
+    #
+    # ```ruby
+    # request PostRequestEntity
+    # ```
     class Factory
-      def attribute(name, type, *helpers, **options, &block)
-        collection_of_attributes << Attribute::Attribute.new(
-          name,
-          type,
-          *helpers,
-          nesting_level: 0,
-          **options,
-          &block
-        )
+      # Uses a provided Entity class
+      #
+      # @param entity_class [Class] Entity class to use
+      # @return [void]
+      # @raise [Treaty::Exceptions::Validation] if entity_class is not a valid Treaty::Entity subclass
+      def use_entity(entity_class)
+        validate_entity_class!(entity_class)
+        @entity_class = entity_class
       end
 
+      # Returns collection of attributes from the entity class
+      #
+      # @return [Collection] Collection of attributes
       def collection_of_attributes
-        @collection_of_attributes ||= Treaty::Attribute::Collection.new
-      end
+        return Treaty::Attribute::Collection.new if @entity_class.nil?
 
-      ##########################################################################
+        @entity_class.collection_of_attributes
+      end
 
+      # Handles DSL methods for defining attributes
+      #
+      # This allows the factory to be used with method_missing
+      # for backwards compatibility with direct method calls.
+      # Creates an anonymous Request::Entity class on first use.
       def method_missing(type, *helpers, **options, &block)
-        name = helpers.shift
+        # If no entity class yet, create one
+        @entity_class ||= Class.new(Entity)
 
-        attribute(name, type, *helpers, **options, &block)
+        # Call the method on the entity class
+        @entity_class.public_send(type, *helpers, **options, &block)
       end
 
       def respond_to_missing?(name, *)
         super
       end
+
+      private
+
+      # Validates that the provided 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 a valid Treaty::Entity subclass
+      def validate_entity_class!(entity_class)
+        return if entity_class.is_a?(Class) && entity_class < Treaty::Entity
+
+        raise Treaty::Exceptions::Validation,
+              I18n.t(
+                "treaty.request.factory.invalid_entity_class",
+                type: entity_class.class,
+                value: entity_class
+              )
+      end
     end
   end
 end

data/lib/treaty/request/validator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Request
+    # Validator for request data
+    class Validator
+      class << self
+        # Validates request parameters against the request definition
+        #
+        # @param params [Hash] Request parameters to validate
+        # @param version_factory [Versions::Factory] Version factory with request definition
+        # @return [Hash] Validated and transformed parameters
+        def validate!(params:, version_factory:)
+          new(params:, version_factory:).validate!
+        end
+      end
+
+      def initialize(params:, version_factory:)
+        @params = params
+        @version_factory = version_factory
+      end
+
+      def validate!
+        validate_request_attributes!
+      end
+
+      private
+
+      def request_data
+        @request_data ||= begin
+          @params.to_unsafe_h
+        rescue NoMethodError
+          @params
+        end
+      end
+
+      def validate_request_attributes! # rubocop:disable Metrics/MethodLength
+        return request_data unless adapter_strategy?
+        return request_data unless request_attributes_exist?
+
+        # For adapter strategy with attributes defined:
+        orchestrator_class = Class.new(Treaty::Attribute::Validation::Orchestrator::Base) do
+          define_method(:collection_of_attributes) do
+            @version_factory.request_factory.collection_of_attributes
+          end
+        end
+
+        orchestrator_class.validate!(
+          version_factory: @version_factory,
+          data: request_data
+        )
+      end
+
+      def adapter_strategy?
+        !@version_factory.strategy_instance.direct?
+      end
+
+      def request_attributes_exist?
+        return false if @version_factory.request_factory&.collection_of_attributes&.empty?
+
+        @version_factory.request_factory.collection_of_attributes.exists?
+      end
+    end
+  end
+end

data/lib/treaty/response/attribute/attribute.rb

@@ -3,6 +3,7 @@
 module Treaty
   module Response
     module Attribute
+      # Response-specific attribute that defaults to required: false
       class Attribute < Treaty::Attribute::Base
         private
 

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

@@ -3,6 +3,7 @@
 module Treaty
   module Response
     module Attribute
+      # Response-specific attribute builder
       class Builder < Treaty::Attribute::Builder::Base
         private
 

data/lib/treaty/response/entity.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Response
+    # Entity class for response definitions.
+    # Attributes are optional by default.
+    #
+    # This class is used internally when defining response blocks.
+    # When you write a response block, Treaty creates an anonymous
+    # class based on Response::Entity.
+    class Entity
+      include Treaty::Attribute::DSL
+
+      class << self
+        private
+
+        # Creates a Response::Attribute::Attribute for this Response::Entity class
+        #
+        # @return [Response::Attribute::Attribute] Created attribute instance
+        def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+          Attribute::Attribute.new(
+            name,
+            type,
+            *helpers,
+            nesting_level:,
+            **options,
+            &block
+          )
+        end
+      end
+    end
+  end
+end