treaty 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e12062cde9c855fa59706b03143fc63760837b8b7ea2eacec1c78694212ec2c1
-  data.tar.gz: 8fddef7c5bb06a1e592ff45873556eab88ef46fa2c578a7425a915803210db50
+  metadata.gz: 8fd8fd4a097f7ff97cdb53e0d7825d79da5562d0bb6347e8e40794c158f8cb41
+  data.tar.gz: b0e119a2ba1018b4eeeb49c753b2949fb4c320ca89be29d633e7e6367cbd7360
 SHA512:
-  metadata.gz: '0684be39d9831977a7afefaf06d9ad5dc683b619b598c68e7d6afd0f751d834caaaa998cadffc921aa2d024939fa40778cdaedb7a2264f6582d43bcdbfc06405'
-  data.tar.gz: 64b70b809d8729b9fd2b9b7cf2e5c30404c6e1e84c51cdaf85596a6b38538dd3cd3c85679b0f5d183d948ca81de15f85acf204ace86972cd47f35c8d884ed3a9
+  metadata.gz: 10514553e41066a04e066e6561744f69ca779bc4a87594bab7dce48b7e6217a5d5a6f2b7e28f1770876a9d3ff82d2f715cf4d167ef683dc36723b65a1549dc62
+  data.tar.gz: e262a6a4b2dbe068c53ced57ddcd7d9687a8e0be7d13f90ab8c2b9176015a3099829af702f59d22d28588a8c929e7178746d79356c35d4d0e899cc46991ce439

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

@@ -23,6 +23,11 @@ en:
           invalid_schema: "Option 'inclusion' for attribute '%{attribute}' must have a non-empty array of allowed values"
           not_included: "Attribute '%{attribute}' must be one of: %{allowed}. Got: '%{value}'"
 
+        format:
+          type_mismatch: "Option 'format' for attribute '%{attribute}' can only be used with String type. Current type: %{type}"
+          unknown_format: "Unknown format '%{format_name}' for attribute '%{attribute}'. Allowed formats: %{allowed}"
+          mismatch: "Attribute '%{attribute}' has invalid %{format_name} format: '%{value}'"
+
         # Nested structures validation
         nested:
           # Orchestrator errors
@@ -47,6 +52,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 +67,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 +76,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/registry_initializer.rb

@@ -21,6 +21,7 @@ module Treaty
       # - `:required` → RequiredValidator - Validates required/optional attributes
       # - `:type` → TypeValidator - Validates value types
       # - `:inclusion` → InclusionValidator - Validates value is in allowed set
+      # - `:format` → FormatValidator - Validates string values match specific formats
       #
       # ## Built-in Modifiers
       #
@@ -71,6 +72,7 @@ module Treaty
             Registry.register(:required, Validators::RequiredValidator, category: :validator)
             Registry.register(:type, Validators::TypeValidator, category: :validator)
             Registry.register(:inclusion, Validators::InclusionValidator, category: :validator)
+            Registry.register(:format, Validators::FormatValidator, category: :validator)
           end
 
           # Registers all built-in modifiers

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

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Validators
+        # Validates that string attribute value matches a specific format.
+        #
+        # ## Supported Formats
+        #
+        # - `:uuid` - Universally unique identifier
+        # - `:email` - Email address (RFC 2822 compliant)
+        # - `:password` - Password (8-16 chars, must contain digit, lowercase, and uppercase)
+        # - `:duration` - ActiveSupport::Duration compatible string (e.g., "1 day", "2 hours")
+        # - `:date` - ISO 8601 date string (e.g., "2025-01-15")
+        # - `:datetime` - ISO 8601 datetime string (e.g., "2025-01-15T10:30:00Z")
+        # - `:time` - Time string (e.g., "10:30:00", "10:30 AM")
+        # - `:boolean` - Boolean string ("true", "false", "0", "1")
+        #
+        # ## Usage Examples
+        #
+        # Simple mode:
+        #   string :email, format: :email
+        #   string :started_on, format: :date
+        #
+        # Advanced mode:
+        #   string :email, format: { is: :email }
+        #   string :started_on, format: { is: :date, message: "Invalid date format" }
+        #   string :started_on, format: { is: :date, message: ->(attribute:, value:, **) { "#{attribute} has invalid date: #{value}" } } # rubocop:disable Layout/LineLength
+        #
+        # ## Validation Rules
+        #
+        # - Only works with `:string` type attributes
+        # - Raises Treaty::Exceptions::Validation if used with non-string types
+        # - Skips validation for nil values (handled by RequiredValidator)
+        # - Each format has a pattern and/or validator for flexible validation
+        #
+        # ## Extensibility
+        #
+        # To add new formats, extend DEFAULT_FORMATS hash with format definition:
+        #   DEFAULT_FORMATS[:custom_format] = {
+        #     pattern: /regex/,
+        #     validator: ->(value) { custom_validation_logic }
+        #   }
+        class FormatValidator < Treaty::Attribute::Option::Base # rubocop:disable Metrics/ClassLength
+          # UUID format regex (8-4-4-4-12 hexadecimal pattern)
+          UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+          # Password format regex (8-16 chars, at least one digit, lowercase, and uppercase)
+          PASSWORD_PATTERN = /\A(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{8,16}\z/
+
+          # Boolean string format regex (accepts "true", "false", "0", "1" case-insensitive)
+          BOOLEAN_PATTERN = /\A(true|false|0|1)\z/i
+
+          # Default format definitions with patterns and validators
+          # Each format can have:
+          # - pattern: Regex for pattern matching
+          # - validator: Lambda for custom validation logic
+          DEFAULT_FORMATS = {
+            uuid: {
+              pattern: UUID_PATTERN,
+              validator: nil
+            },
+            email: {
+              pattern: URI::MailTo::EMAIL_REGEXP,
+              validator: nil
+            },
+            password: {
+              pattern: PASSWORD_PATTERN,
+              validator: nil
+            },
+            duration: {
+              pattern: nil,
+              validator: lambda do |value|
+                ActiveSupport::Duration.parse(value)
+                true
+              rescue StandardError
+                false
+              end
+            },
+            date: {
+              pattern: nil,
+              validator: lambda do |value|
+                Date.parse(value)
+                true
+              rescue ArgumentError, TypeError
+                false
+              end
+            },
+            datetime: {
+              pattern: nil,
+              validator: lambda do |value|
+                DateTime.parse(value)
+                true
+              rescue ArgumentError, TypeError
+                false
+              end
+            },
+            time: {
+              pattern: nil,
+              validator: lambda do |value|
+                Time.parse(value)
+                true
+              rescue ArgumentError, TypeError
+                false
+              end
+            },
+            boolean: {
+              pattern: BOOLEAN_PATTERN,
+              validator: nil
+            }
+          }.freeze
+
+          # Validates that format is only used with string type attributes
+          # and that the format name is valid
+          #
+          # @raise [Treaty::Exceptions::Validation] If format is used with non-string type
+          # @raise [Treaty::Exceptions::Validation] If format name is unknown
+          # @return [void]
+          def validate_schema! # rubocop:disable Metrics/MethodLength
+            # Format option only works with string types
+            unless @attribute_type == :string
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.validators.format.type_mismatch",
+                      attribute: @attribute_name,
+                      type: @attribute_type
+                    )
+            end
+
+            format_name = option_value
+
+            # Validate that format name exists
+            return if formats.key?(format_name)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.validators.format.unknown_format",
+                    attribute: @attribute_name,
+                    format_name:,
+                    allowed: formats.keys.join(", ")
+                  )
+          end
+
+          # Validates that the value matches the specified format
+          # Skips validation for nil values (handled by RequiredValidator)
+          #
+          # @param value [String] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value doesn't match format
+          # @return [void]
+          def validate_value!(value) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            return if value.nil? # Format validation doesn't check for nil, required does.
+
+            format_name = option_value
+            format_definition = formats[format_name]
+
+            # Allow blank values (empty strings should be caught by required validator)
+            return if value.to_s.strip.empty?
+
+            # Apply pattern matching if defined
+            if format_definition.fetch(:pattern)
+              return if value.match?(format_definition.fetch(:pattern))
+
+              # Pattern failed, and no validator - raise error
+              unless format_definition.fetch(:validator)
+                attributes = {
+                  attribute: @attribute_name,
+                  value:,
+                  format_name:
+                }
+
+                message = resolve_custom_message(**attributes) || default_message(**attributes)
+
+                raise Treaty::Exceptions::Validation, message
+              end
+            end
+
+            # Apply validator if defined
+            return unless format_definition.fetch(:validator)
+            return if format_definition.fetch(:validator).call(value)
+
+            attributes = {
+              attribute: @attribute_name,
+              value:,
+              format_name:
+            }
+
+            message = resolve_custom_message(**attributes) || default_message(**attributes)
+
+            raise Treaty::Exceptions::Validation, message
+          end
+
+          private
+
+          # Returns the available formats (allows for extension)
+          #
+          # @return [Hash] Hash of available formats with their definitions
+          def formats
+            DEFAULT_FORMATS
+          end
+
+          # Generates default error message for format validation failure using I18n
+          #
+          # @param attribute [Symbol] The attribute name
+          # @param value [Object] The actual value that failed validation
+          # @param format_name [Symbol] The format name
+          # @return [String] Default error message
+          def default_message(attribute:, value:, format_name:)
+            I18n.t(
+              "treaty.attributes.validators.format.mismatch",
+              attribute:,
+              value:,
+              format_name:
+            )
+          end
+        end
+      end
+    end
+  end
+end

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