treaty 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e12062cde9c855fa59706b03143fc63760837b8b7ea2eacec1c78694212ec2c1
-  data.tar.gz: 8fddef7c5bb06a1e592ff45873556eab88ef46fa2c578a7425a915803210db50
+  metadata.gz: 44bc6d4e290eabdc45efdc7d1e73003f2bb1077e4eee99ad2e9912852d87ecb4
+  data.tar.gz: 72d4767ab3b9e69ec5eec87429cfabd54e6e82783ac4ea321b99eeb04eb85c07
 SHA512:
-  metadata.gz: '0684be39d9831977a7afefaf06d9ad5dc683b619b598c68e7d6afd0f751d834caaaa998cadffc921aa2d024939fa40778cdaedb7a2264f6582d43bcdbfc06405'
-  data.tar.gz: 64b70b809d8729b9fd2b9b7cf2e5c30404c6e1e84c51cdaf85596a6b38538dd3cd3c85679b0f5d183d948ca81de15f85acf204ace86972cd47f35c8d884ed3a9
+  metadata.gz: c5d922b7116ebb82cf7d9c60d8bca8c9f45594744cc10e19319f0b3e22d631f8310a1695861f7979f8bf472b87b8bf5687248faae8ca93f90bec04e6fcfa7fd1
+  data.tar.gz: 2fbebe3ceaeeaf1bd743f36fbd40678bda0f9c8dbdbd284610f2de4a0101c6e8d865fa11f555b1fa195fd37e06eae519f82aa08fae8fb29694296ad65fa42be7

data/README.md

@@ -12,6 +12,9 @@
 
 </div>
 
+> [!WARNING]
+> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.5.0"`) until the 1.0 release.
+
 ## 📚 Documentation
 
 Explore comprehensive guides and documentation at [docs](./docs):
@@ -29,6 +32,8 @@ Treaty provides a complete solution for building versioned APIs in Ruby on Rails
 
 - **Type Safety** - Enforce strict type checking for request and response data
 - **API Versioning** - Manage multiple concurrent API versions effortlessly
+- **Unified Architecture** - Request blocks, response blocks, and Entity classes share the same validation system
+- **Entity Classes (DTOs)** - Define reusable data transfer objects for better code organization
 - **Built-in Validation** - Validate incoming requests and outgoing responses automatically
 - **Data Transformation** - Transform data seamlessly between different API versions
 - **Deprecation Management** - Mark versions as deprecated with flexible conditions

data/config/locales/en.yml

@@ -47,6 +47,7 @@ en:
       # Attribute builder DSL
       builder:
         not_implemented: "%{class} must implement #create_attribute"
+        create_attribute_not_implemented: "Subclass %{class} must implement #create_attribute method"
 
       # Attribute-level errors
       errors:
@@ -61,6 +62,7 @@ en:
       # Request factory DSL
       factory:
         unknown_method: "Unknown method '%{method}' in request definition. Use 'object :name do ... end' to define request structure"
+        invalid_entity_class: "Request expects a Treaty::Entity subclass, got %{type}: %{value}"
 
     # ============================================================================
     # Response: Response definition and structure
@@ -69,6 +71,7 @@ en:
       # Response factory DSL
       factory:
         unknown_method: "Unknown method '%{method}' in response definition. Use 'object :name do ... end' to define response structure"
+        invalid_entity_class: "Response expects a Treaty::Entity subclass, got %{type}: %{value}"
 
     # ============================================================================
     # Versioning: API version management and resolution

data/lib/treaty/attribute/base.rb

@@ -122,9 +122,11 @@ module Treaty
         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)
+              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
@@ -155,7 +157,10 @@ module Treaty
       def apply_defaults!
         # Must be implemented in subclasses
         raise Treaty::Exceptions::NotImplemented,
-              I18n.t("treaty.attributes.errors.apply_defaults_not_implemented", class: self.class)
+              I18n.t(
+                "treaty.attributes.errors.apply_defaults_not_implemented",
+                class: self.class
+              )
       end
 
       # Processes nested attributes block for object/array types
@@ -167,7 +172,10 @@ module Treaty
       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)
+              I18n.t(
+                "treaty.attributes.errors.process_nested_not_implemented",
+                class: self.class
+              )
       end
     end
   end

data/lib/treaty/attribute/dsl.rb

@@ -0,0 +1,90 @@
+# 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/attribute.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Entity
+      # Entity-specific attribute that defaults to required: true
+      class Attribute < Treaty::Attribute::Base
+        private
+
+        def apply_defaults!
+          # For entity: required by default (true).
+          # message: nil means use I18n default message from validators
+          @options[:required] ||= { is: true, message: nil }
+        end
+
+        def process_nested_attributes(&block)
+          return unless object_or_array?
+
+          builder = Builder.new(collection_of_attributes, @nesting_level + 1)
+          builder.instance_eval(&block)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# 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/option/base.rb

@@ -134,13 +134,29 @@ module Treaty
         # Gets custom error message from advanced mode schema
         # Returns nil if no custom message, which triggers I18n default message
         #
-        # @return [String, nil] Custom error message or nil for 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
+        #
+        # @param context [Hash] Named arguments to pass to lambda
+        # @return [String, nil] Resolved message string or nil
+        def resolve_custom_message(**context)
+          message = custom_message
+          return nil if message.nil?
+
+          if message.respond_to?(:call)
+            message.call(**context)
+          else
+            message
+          end
+        end
+
         # Checks if schema is in advanced mode
         #
         # @return [Boolean] True if schema is in advanced mode (hash with value key)

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

@@ -54,9 +54,11 @@ module Treaty
             return if target.is_a?(Symbol)
 
             raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.modifiers.as.invalid_type",
-                         attribute: @attribute_name,
-                         type: target.class)
+                  I18n.t(
+                    "treaty.attributes.modifiers.as.invalid_type",
+                    attribute: @attribute_name,
+                    type: target.class
+                  )
           end
 
           # Indicates that AsModifier transforms attribute names

data/lib/treaty/attribute/option/validators/inclusion_validator.rb

@@ -29,7 +29,10 @@ module Treaty
             return if allowed_values.is_a?(Array) && !allowed_values.empty?
 
             raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.inclusion.invalid_schema", attribute: @attribute_name)
+                  I18n.t(
+                    "treaty.attributes.validators.inclusion.invalid_schema",
+                    attribute: @attribute_name
+                  )
           end
 
           # Validates that value is included in allowed set
@@ -45,7 +48,13 @@ module Treaty
 
             return if allowed_values.include?(value)
 
-            message = custom_message || default_message(allowed_values, value)
+            attributes = {
+              attribute: @attribute_name,
+              value:,
+              allowed_values:
+            }
+
+            message = resolve_custom_message(**attributes) || default_message(**attributes)
 
             raise Treaty::Exceptions::Validation, message
           end
@@ -64,14 +73,17 @@ module Treaty
 
           # Generates default error message with allowed values using I18n
           #
-          # @param allowed_values [Array] Array of allowed values
+          # @param attribute [Symbol] The attribute name
           # @param value [Object] The actual value that failed validation
+          # @param allowed_values [Array] Array of allowed values
           # @return [String] Default error message
-          def default_message(allowed_values, value)
-            I18n.t("treaty.attributes.validators.inclusion.not_included",
-                   attribute: @attribute_name,
-                   allowed: allowed_values.join(", "),
-                   value:)
+          def default_message(attribute:, value:, allowed_values:)
+            I18n.t(
+              "treaty.attributes.validators.inclusion.not_included",
+              attribute:,
+              allowed: allowed_values.join(", "),
+              value:
+            )
           end
         end
       end

data/lib/treaty/attribute/option/validators/required_validator.rb

@@ -51,7 +51,10 @@ module Treaty
             return unless required?
             return if present?(value)
 
-            message = custom_message || default_message
+            message = resolve_custom_message(
+              attribute: @attribute_name,
+              value:
+            ) || default_message
 
             raise Treaty::Exceptions::Validation, message
           end
@@ -83,7 +86,10 @@ module Treaty
           #
           # @return [String] Default error message
           def default_message
-            I18n.t("treaty.attributes.validators.required.blank", attribute: @attribute_name)
+            I18n.t(
+              "treaty.attributes.validators.required.blank",
+              attribute: @attribute_name
+            )
           end
         end
       end

data/lib/treaty/attribute/option/validators/type_validator.rb

@@ -53,10 +53,12 @@ module Treaty
             return if ALLOWED_TYPES.include?(@attribute_type)
 
             raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.type.unknown_type",
-                         type: @attribute_type,
-                         attribute: @attribute_name,
-                         allowed: ALLOWED_TYPES.join(", "))
+                  I18n.t(
+                    "treaty.attributes.validators.type.unknown_type",
+                    type: @attribute_type,
+                    attribute: @attribute_name,
+                    allowed: ALLOWED_TYPES.join(", ")
+                  )
           end
 
           # Validates that the value matches the declared type
@@ -86,18 +88,52 @@ module Treaty
 
           private
 
+          # Common type validation logic
+          # Checks if value matches expected type and raises exception with appropriate message
+          #
+          # @param value [Object] The value to validate
+          # @param expected_type [Symbol] The expected type symbol
+          # @yield Block that returns true if value is valid
+          # @raise [Treaty::Exceptions::Validation] If type validation fails
+          # @return [void]
+          def validate_type!(value, expected_type)
+            return if yield(value)
+
+            actual_type = value.class
+
+            attributes = {
+              attribute: @attribute_name,
+              value:,
+              expected_type:,
+              actual_type:
+            }
+
+            message = resolve_custom_message(**attributes) || default_message(**attributes)
+
+            raise Treaty::Exceptions::Validation, message
+          end
+
+          # Generates default error message for type mismatch using I18n
+          #
+          # @param attribute [Symbol] The attribute name
+          # @param expected_type [Symbol] The expected type
+          # @param actual_type [Class] The actual class of the value
+          # @return [String] Default error message
+          def default_message(attribute:, expected_type:, actual_type:, **)
+            I18n.t(
+              "treaty.attributes.validators.type.mismatch.#{expected_type}",
+              attribute:,
+              actual: actual_type
+            )
+          end
+
           # Validates that value is an Integer
           #
           # @param value [Object] The value to validate
           # @raise [Treaty::Exceptions::Validation] If value is not an Integer
           # @return [void]
           def validate_integer!(value)
-            return if value.is_a?(Integer)
-
-            raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.type.mismatch.integer",
-                         attribute: @attribute_name,
-                         actual: value.class)
+            validate_type!(value, :integer) { |v| v.is_a?(Integer) }
           end
 
           # Validates that value is a String
@@ -106,12 +142,7 @@ module Treaty
           # @raise [Treaty::Exceptions::Validation] If value is not a String
           # @return [void]
           def validate_string!(value)
-            return if value.is_a?(String)
-
-            raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.type.mismatch.string",
-                         attribute: @attribute_name,
-                         actual: value.class)
+            validate_type!(value, :string) { |v| v.is_a?(String) }
           end
 
           # Validates that value is a Boolean (TrueClass or FalseClass)
@@ -120,12 +151,7 @@ module Treaty
           # @raise [Treaty::Exceptions::Validation] If value is not a Boolean
           # @return [void]
           def validate_boolean!(value)
-            return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
-
-            raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.type.mismatch.boolean",
-                         attribute: @attribute_name,
-                         actual: value.class)
+            validate_type!(value, :boolean) { |v| v.is_a?(TrueClass) || v.is_a?(FalseClass) }
           end
 
           # Validates that value is a Hash (object type)
@@ -134,12 +160,7 @@ module Treaty
           # @raise [Treaty::Exceptions::Validation] If value is not a Hash
           # @return [void]
           def validate_object!(value)
-            return if value.is_a?(Hash)
-
-            raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.type.mismatch.object",
-                         attribute: @attribute_name,
-                         actual: value.class)
+            validate_type!(value, :object) { |v| v.is_a?(Hash) }
           end
 
           # Validates that value is an Array
@@ -148,12 +169,7 @@ module Treaty
           # @raise [Treaty::Exceptions::Validation] If value is not an Array
           # @return [void]
           def validate_array!(value)
-            return if value.is_a?(Array)
-
-            raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.type.mismatch.array",
-                         attribute: @attribute_name,
-                         actual: value.class)
+            validate_type!(value, :array) { |v| v.is_a?(Array) }
           end
 
           # Validates that value is a DateTime, Time, or Date
@@ -163,12 +179,7 @@ module Treaty
           # @return [void]
           def validate_datetime!(value)
             # TODO: It is better to divide it into different methods for each class.
-            return if value.is_a?(DateTime) || value.is_a?(Time) || value.is_a?(Date)
-
-            raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.type.mismatch.datetime",
-                         attribute: @attribute_name,
-                         actual: value.class)
+            validate_type!(value, :datetime) { |v| v.is_a?(DateTime) || v.is_a?(Time) || v.is_a?(Date) }
           end
         end
       end

data/lib/treaty/attribute/option_orchestrator.rb

@@ -146,7 +146,7 @@ module Treaty
         @attribute.options.each do |option_name, option_schema|
           processor_class = Option::Registry.processor_for(option_name)
 
-          next unless processor_class
+          next if processor_class.nil?
 
           processors_hash[option_name] = processor_class.new(
             attribute_name: @attribute.name,
@@ -177,10 +177,12 @@ module Treaty
         return if unknown_options.empty?
 
         raise Treaty::Exceptions::Validation,
-              I18n.t("treaty.attributes.options.unknown",
-                     attribute: @attribute.name,
-                     unknown: unknown_options.join(", "),
-                     known: Option::Registry.all_options.join(", "))
+              I18n.t(
+                "treaty.attributes.options.unknown",
+                attribute: @attribute.name,
+                unknown: unknown_options.join(", "),
+                known: Option::Registry.all_options.join(", ")
+              )
       end
     end
   end

data/lib/treaty/attribute/validation/nested_array_validator.rb

@@ -115,10 +115,12 @@ module Treaty
           return if validated
 
           raise Treaty::Exceptions::Validation,
-                I18n.t("treaty.attributes.validators.nested.array.element_validation_error",
-                       attribute: @attribute.name,
-                       index:,
-                       errors: errors.join("; "))
+                I18n.t(
+                  "treaty.attributes.validators.nested.array.element_validation_error",
+                  attribute: @attribute.name,
+                  index:,
+                  errors: errors.join("; ")
+                )
         end
 
         # Validates array item for complex arrays (with regular attributes)
@@ -132,10 +134,12 @@ module Treaty
         def validate_regular_array_item!(array_item, index) # rubocop:disable Metrics/MethodLength
           unless array_item.is_a?(Hash)
             raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.nested.array.element_type_error",
-                         attribute: @attribute.name,
-                         index:,
-                         actual: array_item.class)
+                  I18n.t(
+                    "treaty.attributes.validators.nested.array.element_type_error",
+                    attribute: @attribute.name,
+                    index:,
+                    actual: array_item.class
+                  )
           end
 
           regular_validators.each do |nested_attribute, validator|
@@ -143,10 +147,12 @@ module Treaty
             validator.validate_value!(nested_value)
           rescue Treaty::Exceptions::Validation => e
             raise Treaty::Exceptions::Validation,
-                  I18n.t("treaty.attributes.validators.nested.array.attribute_error",
-                         attribute: @attribute.name,
-                         index:,
-                         message: e.message)
+                  I18n.t(
+                    "treaty.attributes.validators.nested.array.attribute_error",
+                    attribute: @attribute.name,
+                    index:,
+                    message: e.message
+                  )
           end
         end
 

data/lib/treaty/attribute/validation/nested_transformer.rb

@@ -171,10 +171,12 @@ module Treaty
               validator.validate_value!(item)
             rescue Treaty::Exceptions::Validation => e
               raise Treaty::Exceptions::Validation,
-                    I18n.t("treaty.attributes.validators.nested.array.element_validation_error",
-                           attribute: attribute.name,
-                           index:,
-                           errors: e.message)
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.element_validation_error",
+                      attribute: attribute.name,
+                      index:,
+                      errors: e.message
+                    )
             end
           end
 
@@ -187,10 +189,12 @@ module Treaty
           def transform_array_item(item, index) # rubocop:disable Metrics/MethodLength
             unless item.is_a?(Hash)
               raise Treaty::Exceptions::Validation,
-                    I18n.t("treaty.attributes.validators.nested.array.element_type_error",
-                           attribute: attribute.name,
-                           index:,
-                           actual: item.class)
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.element_type_error",
+                      attribute: attribute.name,
+                      index:,
+                      actual: item.class
+                    )
             end
 
             transformed = {}
@@ -230,10 +234,12 @@ module Treaty
                                   end
             rescue Treaty::Exceptions::Validation => e
               raise Treaty::Exceptions::Validation,
-                    I18n.t("treaty.attributes.validators.nested.array.attribute_error",
-                           attribute: attribute.name,
-                           index:,
-                           message: e.message)
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.attribute_error",
+                      attribute: attribute.name,
+                      index:,
+                      message: e.message
+                    )
             end
 
             target_name = validator.target_name

data/lib/treaty/base.rb

@@ -2,7 +2,7 @@
 
 module Treaty
   class Base
-    include Info::DSL
+    include Info::Rest::DSL
     include Context::DSL
     include Versions::DSL
   end

data/lib/treaty/controller/dsl.rb

@@ -25,7 +25,10 @@ module Treaty
           treaty_class_name.constantize
         rescue NameError
           raise Treaty::Exceptions::ClassName,
-                I18n.t("treaty.controller.treaty_class_not_found", class_name: treaty_class_name)
+                I18n.t(
+                  "treaty.controller.treaty_class_not_found",
+                  class_name: treaty_class_name
+                )
         end
 
         def treaty_class_name