easy_talk 3.1.0 → 3.2.0

data/lib/easy_talk/error_formatter/rfc7807.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors according to RFC 7807 (Problem Details for HTTP APIs).
+    #
+    # RFC 7807 defines a standard format for describing errors in HTTP APIs.
+    # This formatter produces a Problem Details object with validation errors
+    # in an extended "errors" array.
+    #
+    # @see https://tools.ietf.org/html/rfc7807
+    #
+    # @example Output
+    #   {
+    #     "type" => "https://example.com/validation-error",
+    #     "title" => "Validation Failed",
+    #     "status" => 422,
+    #     "detail" => "The request contains invalid parameters",
+    #     "errors" => [
+    #       { "pointer" => "/properties/name", "detail" => "can't be blank", "code" => "blank" }
+    #     ]
+    #   }
+    #
+    class Rfc7807 < Base
+      # Default values for RFC 7807 fields
+      DEFAULT_TITLE = 'Validation Failed'
+      DEFAULT_STATUS = 422
+      DEFAULT_DETAIL = 'The request contains invalid parameters'
+
+      # Format the errors as an RFC 7807 Problem Details object.
+      #
+      # @return [Hash] The Problem Details object
+      def format
+        {
+          'type' => error_type_uri,
+          'title' => options.fetch(:title, DEFAULT_TITLE),
+          'status' => options.fetch(:status, DEFAULT_STATUS),
+          'detail' => options.fetch(:detail, DEFAULT_DETAIL),
+          'errors' => build_errors_array
+        }
+      end
+
+      private
+
+      def error_type_uri
+        base_uri = options.fetch(:type_base_uri, EasyTalk.configuration.error_type_base_uri)
+        type_suffix = options.fetch(:type, 'validation-error')
+        return type_suffix if base_uri.nil? || base_uri == 'about:blank'
+
+        "#{base_uri.chomp('/')}/#{type_suffix}"
+      end
+
+      def build_errors_array
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      def build_error_object(entry)
+        error = {
+          'pointer' => PathConverter.to_json_pointer(entry[:attribute]),
+          'detail' => entry[:message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative 'error_formatter/error_code_mapper'
+require_relative 'error_formatter/path_converter'
+require_relative 'error_formatter/base'
+require_relative 'error_formatter/flat'
+require_relative 'error_formatter/json_pointer'
+require_relative 'error_formatter/rfc7807'
+require_relative 'error_formatter/jsonapi'
+
+module EasyTalk
+  # Module for formatting ActiveModel validation errors into standardized formats.
+  #
+  # Provides multiple output formats for API responses:
+  # - `:flat` - Simple flat array of field/message/code objects
+  # - `:json_pointer` - Array with JSON Pointer (RFC 6901) paths
+  # - `:rfc7807` - RFC 7807 Problem Details format
+  # - `:jsonapi` - JSON:API specification error format
+  #
+  # @example Using via model instance methods
+  #   user = User.new(name: '')
+  #   user.valid?
+  #
+  #   user.validation_errors                    # Uses default format from config
+  #   user.validation_errors_flat               # Flat format
+  #   user.validation_errors_json_pointer       # JSON Pointer format
+  #   user.validation_errors_rfc7807            # RFC 7807 format
+  #   user.validation_errors_jsonapi            # JSON:API format
+  #
+  # @example Using the format method directly
+  #   EasyTalk::ErrorFormatter.format(user.errors, format: :rfc7807, title: 'Custom Title')
+  #
+  module ErrorFormatter
+    # Map of format symbols to formatter classes
+    FORMATTERS = {
+      flat: Flat,
+      json_pointer: JsonPointer,
+      rfc7807: Rfc7807,
+      jsonapi: Jsonapi
+    }.freeze
+
+    class << self
+      # Format validation errors using the specified format.
+      #
+      # @param errors [ActiveModel::Errors] The errors object to format
+      # @param format [Symbol] The output format (:flat, :json_pointer, :rfc7807, :jsonapi)
+      # @param options [Hash] Format-specific options
+      # @return [Hash, Array] The formatted errors
+      # @raise [ArgumentError] If the format is not recognized
+      #
+      # @example
+      #   EasyTalk::ErrorFormatter.format(user.errors, format: :flat)
+      #   EasyTalk::ErrorFormatter.format(user.errors, format: :rfc7807, title: 'Validation Error')
+      def format(errors, format: nil, **options)
+        format ||= EasyTalk.configuration.default_error_format
+        formatter_class = FORMATTERS[format.to_sym]
+
+        raise ArgumentError, "Unknown error format: #{format}. Valid formats: #{FORMATTERS.keys.join(', ')}" unless formatter_class
+
+        formatter_class.new(errors, options).format
+      end
+    end
+
+    # Instance methods mixed into EasyTalk::Model classes.
+    #
+    # Provides convenient methods for formatting validation errors
+    # on model instances.
+    module InstanceMethods
+      # Format validation errors using the default or specified format.
+      #
+      # @param format [Symbol] The output format (optional, uses config default)
+      # @param options [Hash] Format-specific options
+      # @return [Hash, Array] The formatted errors
+      #
+      # @example
+      #   user.validation_errors
+      #   user.validation_errors(format: :rfc7807, title: 'User Error')
+      def validation_errors(format: nil, **)
+        ErrorFormatter.format(errors, format: format, **)
+      end
+
+      # Format validation errors as a flat array.
+      #
+      # @param options [Hash] Format options
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Array<Hash>] Array of error objects
+      #
+      # @example
+      #   user.validation_errors_flat
+      #   # => [{ "field" => "name", "message" => "can't be blank", "code" => "blank" }]
+      def validation_errors_flat(**)
+        ErrorFormatter.format(errors, format: :flat, **)
+      end
+
+      # Format validation errors with JSON Pointer paths.
+      #
+      # @param options [Hash] Format options
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Array<Hash>] Array of error objects with pointer paths
+      #
+      # @example
+      #   user.validation_errors_json_pointer
+      #   # => [{ "pointer" => "/properties/name", "message" => "can't be blank", "code" => "blank" }]
+      def validation_errors_json_pointer(**)
+        ErrorFormatter.format(errors, format: :json_pointer, **)
+      end
+
+      # Format validation errors as RFC 7807 Problem Details.
+      #
+      # @param options [Hash] Format options
+      # @option options [String] :title The problem title
+      # @option options [Integer] :status The HTTP status code
+      # @option options [String] :detail The problem detail message
+      # @option options [String] :type_base_uri Base URI for error type
+      # @option options [String] :type The error type suffix
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Hash] The Problem Details object
+      #
+      # @example
+      #   user.validation_errors_rfc7807
+      #   user.validation_errors_rfc7807(title: 'User Validation Failed', status: 400)
+      def validation_errors_rfc7807(**)
+        ErrorFormatter.format(errors, format: :rfc7807, **)
+      end
+
+      # Format validation errors according to JSON:API specification.
+      #
+      # @param options [Hash] Format options
+      # @option options [String] :status The HTTP status code (as string)
+      # @option options [String] :title The error title
+      # @option options [String] :source_prefix The source pointer prefix
+      # @option options [Boolean] :include_codes Whether to include error codes
+      # @return [Hash] The JSON:API error object
+      #
+      # @example
+      #   user.validation_errors_jsonapi
+      #   user.validation_errors_jsonapi(title: 'Validation Error', source_prefix: '/data')
+      def validation_errors_jsonapi(**)
+        ErrorFormatter.format(errors, format: :jsonapi, **)
+      end
+    end
+  end
+end

data/lib/easy_talk/errors.rb

@@ -4,5 +4,7 @@ module EasyTalk
   class Error < StandardError; end
   class ConstraintError < Error; end
   class UnknownOptionError < Error; end
+  class UnknownTypeError < Error; end
+  class InvalidInstructionsError < Error; end
   class InvalidPropertyNameError < Error; end
 end

data/lib/easy_talk/errors_helper.rb

@@ -27,7 +27,7 @@ module EasyTalk
       if type_info.respond_to?(:type) && type_info.type.respond_to?(:raw_type)
         type_info.type.raw_type
       # special boolean handling
-      elsif type_info.try(:type).try(:name) == 'T::Boolean'
+      elsif TypeIntrospection.boolean_type?(type_info.try(:type))
         T::Boolean
       elsif type_info.respond_to?(:type_parameter)
         type_info.type_parameter
@@ -44,47 +44,77 @@ module EasyTalk
     end
 
     def self.validate_typed_array_values(property_name:, constraint_name:, type_info:, array_value:)
-      # Skip validation if it's not actually an array
-      return unless array_value.is_a?(Array)
+      # Raise error if value is not an array but type expects one
+      unless array_value.is_a?(Array)
+        inner_type = extract_inner_type(type_info)
+        expected_desc = TypeIntrospection.boolean_type?(inner_type) ? 'Boolean (true or false)' : inner_type.to_s
+        raise_constraint_error(
+          property_name: property_name,
+          constraint_name: constraint_name,
+          expected: expected_desc,
+          got: array_value
+        )
+      end
 
-      # Extract the inner type from the array type definition
       inner_type = extract_inner_type(type_info)
-
-      # Check each element of the array
       array_value.each_with_index do |element, index|
-        if inner_type.is_a?(Array)
-          # For union types, check if the element matches any of the allowed types
-          unless inner_type.any? { |t| element.is_a?(t) }
-            expected = inner_type.join(' or ')
-            raise_array_constraint_error(
-              property_name: property_name,
-              constraint_name: constraint_name,
-              index: index,
-              expected: expected,
-              got: element
-            )
-          end
-        else
-          # For single types, just check against that type
-          next if [true, false].include?(element)
+        validate_array_element(
+          property_name: property_name,
+          constraint_name: constraint_name,
+          inner_type: inner_type,
+          element: element,
+          index: index
+        )
+      end
+    end
 
-          unless element.is_a?(inner_type)
-            raise_array_constraint_error(
-              property_name: property_name,
-              constraint_name: constraint_name,
-              index: index,
-              expected: inner_type,
-              got: element
-            )
-          end
-        end
+    def self.validate_array_element(property_name:, constraint_name:, inner_type:, element:, index:)
+      if inner_type.is_a?(Array)
+        validate_union_element(property_name, constraint_name, inner_type, element, index)
+      else
+        validate_single_type_element(property_name, constraint_name, inner_type, element, index)
+      end
+    end
+
+    def self.validate_union_element(property_name, constraint_name, inner_type, element, index)
+      return if inner_type.any? { |t| element.is_a?(t) }
+
+      raise_array_constraint_error(
+        property_name: property_name,
+        constraint_name: constraint_name,
+        index: index,
+        expected: inner_type.join(' or '),
+        got: element
+      )
+    end
+
+    def self.validate_single_type_element(property_name, constraint_name, inner_type, element, index)
+      # Skip if element is a boolean (booleans are valid in many contexts)
+      return if [true, false].include?(element)
+
+      if TypeIntrospection.boolean_type?(inner_type)
+        raise_array_constraint_error(
+          property_name: property_name,
+          constraint_name: constraint_name,
+          index: index,
+          expected: 'Boolean (true or false)',
+          got: element
+        )
+      elsif !element.is_a?(inner_type)
+        raise_array_constraint_error(
+          property_name: property_name,
+          constraint_name: constraint_name,
+          index: index,
+          expected: inner_type,
+          got: element
+        )
       end
     end
 
     def self.validate_constraint_value(property_name:, constraint_name:, value_type:, value:)
       return if value.nil?
 
-      if value_type.to_s.include?('Boolean')
+      if TypeIntrospection.boolean_type?(value_type)
         return if value.is_a?(Array) && value.all? { |v| [true, false].include?(v) }
 
         unless [true, false].include?(value)
@@ -109,8 +139,7 @@ module EasyTalk
           )
         end
       # Handle array types specifically
-      elsif value_type.class.name.include?('TypedArray') ||
-            (value_type.respond_to?(:to_s) && value_type.to_s.include?('T::Array'))
+      elsif TypeIntrospection.typed_array?(value_type)
         # This is an array type, validate it
         validate_typed_array_values(
           property_name: property_name,

data/lib/easy_talk/model.rb

@@ -10,6 +10,7 @@ require 'active_model'
 require_relative 'builders/object_builder'
 require_relative 'schema_definition'
 require_relative 'validation_builder'
+require_relative 'error_formatter'
 
 module EasyTalk
   # The `Model` module is a mixin that provides functionality for defining and accessing the schema of a model.
@@ -41,39 +42,70 @@ module EasyTalk
       base.include ActiveModel::Validations
       base.extend ActiveModel::Callbacks
       base.include(InstanceMethods)
+      base.include(ErrorFormatter::InstanceMethods)
     end
 
     # Instance methods mixed into models that include EasyTalk::Model
     module InstanceMethods
       def initialize(attributes = {})
         @additional_properties = {}
+        provided_keys = attributes.keys.to_set(&:to_sym)
+
         super # Perform initial mass assignment
 
-        # After initial assignment, instantiate nested EasyTalk::Model objects
         schema_def = self.class.schema_definition
-
-        # Only proceed if we have a valid schema definition
         return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
 
         (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
-          # Get the defined type and the currently assigned value
-          defined_type = prop_definition[:type]
-          current_value = public_send(prop_name)
-          nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
+          process_property_initialization(prop_name, prop_definition, provided_keys)
+        end
+      end
 
-          next if nilable_type && current_value.nil?
+      private
 
-          defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
+      def process_property_initialization(prop_name, prop_definition, provided_keys)
+        defined_type = prop_definition[:type]
+        nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
+
+        apply_default_value(prop_name, prop_definition, provided_keys)
+
+        current_value = public_send(prop_name)
+        return if nilable_type && current_value.nil?
+
+        defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
+        instantiate_nested_models(prop_name, defined_type, current_value)
+      end
 
-          # Check if the type is another EasyTalk::Model and the value is a Hash
-          next unless defined_type.is_a?(Class) && defined_type.include?(EasyTalk::Model) && current_value.is_a?(Hash)
+      def apply_default_value(prop_name, prop_definition, provided_keys)
+        return if provided_keys.include?(prop_name)
 
-          # Instantiate the nested model and assign it back
-          nested_instance = defined_type.new(current_value)
-          public_send("#{prop_name}=", nested_instance)
+        default_value = prop_definition.dig(:constraints, :default)
+        public_send("#{prop_name}=", default_value) unless default_value.nil?
+      end
+
+      def instantiate_nested_models(prop_name, defined_type, current_value)
+        # Single nested model: convert Hash to model instance
+        if defined_type.is_a?(Class) && defined_type.include?(EasyTalk::Model) && current_value.is_a?(Hash)
+          public_send("#{prop_name}=", defined_type.new(current_value))
+          return
         end
+
+        # Array of nested models: convert Hash items to model instances
+        instantiate_array_items(prop_name, defined_type, current_value)
+      end
+
+      def instantiate_array_items(prop_name, defined_type, current_value)
+        return unless defined_type.is_a?(T::Types::TypedArray) && current_value.is_a?(Array)
+
+        item_type = defined_type.type.respond_to?(:raw_type) ? defined_type.type.raw_type : nil
+        return unless item_type.is_a?(Class) && item_type.include?(EasyTalk::Model)
+
+        instantiated = current_value.map { |item| item.is_a?(Hash) ? item_type.new(item) : item }
+        public_send("#{prop_name}=", instantiated)
       end
 
+      public
+
       def method_missing(method_name, *args)
         method_string = method_name.to_s
         if method_string.end_with?('=')
@@ -91,9 +123,10 @@ module EasyTalk
       end
 
       def respond_to_missing?(method_name, include_private = false)
+        return super unless self.class.additional_properties_allowed?
+
         method_string = method_name.to_s
-        method_string.end_with?('=') ? method_string.chomp('=') : method_string
-        self.class.additional_properties_allowed? || super
+        method_string.end_with?('=') || @additional_properties.key?(method_string) || super
       end
 
       # Add to_hash method to convert defined properties to hash
@@ -136,6 +169,8 @@ module EasyTalk
 
     # Module containing class-level methods for defining and accessing the schema of a model.
     module ClassMethods
+      include SchemaMethods
+
       # Returns the schema for the model.
       #
       # @return [Schema] The schema for the model.
@@ -147,103 +182,101 @@ module EasyTalk
                     end
       end
 
-      # Returns the reference template for the model.
+      # Define the schema for the model using the provided block.
       #
-      # @return [String] The reference template for the model.
-      def ref_template
-        "#/$defs/#{name}"
-      end
-
-      # Returns the JSON schema for the model.
-      # This is the final output that includes the $schema keyword if configured.
+      # @param options [Hash] Options for schema definition
+      # @option options [Boolean, Symbol, Class] :validations Controls validation behavior:
+      #   - true: Enable validations using the configured adapter (default behavior)
+      #   - false: Disable validations for this model
+      #   - :none: Use the NoneAdapter (no validations)
+      #   - :active_model: Use the ActiveModelAdapter
+      #   - CustomAdapter: Use a custom adapter class
+      # @yield The block to define the schema.
+      # @raise [ArgumentError] If the class does not have a name.
       #
-      # @return [Hash] The JSON schema for the model.
-      def json_schema
-        @json_schema ||= build_json_schema
-      end
-
-      private
-
-      # Builds the final JSON schema with optional $schema and $id keywords.
-      def build_json_schema
-        result = schema.as_json
-        schema_uri = resolve_schema_uri
-        id_uri = resolve_schema_id
+      # @example Disable validations for a model
+      #   define_schema(validations: false) do
+      #     property :name, String
+      #   end
+      #
+      # @example Use a custom adapter
+      #   define_schema(validations: MyCustomAdapter) do
+      #     property :name, String
+      #   end
+      def define_schema(options = {}, &)
+        raise ArgumentError, 'The class must have a name' unless name.present?
 
-        # Build prefix hash with $schema and $id (in that order per JSON Schema convention)
-        prefix = {}
-        prefix['$schema'] = schema_uri if schema_uri
-        prefix['$id'] = id_uri if id_uri
+        @schema_definition = SchemaDefinition.new(name)
+        @schema_definition.klass = self # Pass the model class to the schema definition
+        @schema_definition.instance_eval(&)
 
-        return result if prefix.empty?
+        # Store validation options for this model
+        @validation_options = normalize_validation_options(options)
 
-        prefix.merge(result)
-      end
+        # Define accessors immediately based on schema_definition
+        defined_properties = (@schema_definition.schema[:properties] || {}).keys
+        attr_accessor(*defined_properties)
 
-      # Resolves the schema URI from per-model setting or global config.
-      def resolve_schema_uri
-        model_version = @schema_definition&.schema&.dig(:schema_version)
+        # Track which properties have had validations applied
+        @validated_properties ||= Set.new
 
-        if model_version
-          # Per-model override - :none means explicitly no $schema
-          return nil if model_version == :none
+        # Apply validations using the adapter system
+        apply_schema_validations
 
-          Configuration::SCHEMA_VERSIONS[model_version] || model_version.to_s
-        else
-          # Fall back to global configuration
-          EasyTalk.configuration.schema_uri
-        end
+        @schema_definition
       end
 
-      # Resolves the schema ID from per-model setting or global config.
-      def resolve_schema_id
-        model_id = @schema_definition&.schema&.dig(:schema_id)
-
-        if model_id
-          # Per-model override - :none means explicitly no $id
-          return nil if model_id == :none
+      private
 
-          model_id.to_s
+      # Normalize validation options from various input formats.
+      #
+      # @param options [Hash] The options hash from define_schema
+      # @return [Hash] Normalized options with :enabled and :adapter keys
+      def normalize_validation_options(options)
+        validations = options.fetch(:validations, nil)
+
+        case validations
+        when nil
+          # Use global configuration
+          { enabled: EasyTalk.configuration.auto_validations,
+            adapter: EasyTalk.configuration.validation_adapter }
+        when false
+          # Explicitly disabled
+          { enabled: false, adapter: :none }
+        when true
+          # Explicitly enabled with configured adapter
+          { enabled: true, adapter: EasyTalk.configuration.validation_adapter }
+        when Symbol, Class
+          # Specific adapter specified
+          { enabled: true, adapter: validations }
         else
-          # Fall back to global configuration
-          EasyTalk.configuration.schema_id
+          raise ArgumentError, "Invalid validations option: #{validations.inspect}. " \
+                               "Expected true, false, Symbol, or Class."
         end
       end
 
-      public
-
-      # Define the schema for the model using the provided block.
+      # Apply validations to all schema properties using the configured adapter.
       #
-      # @yield The block to define the schema.
-      # @raise [ArgumentError] If the class does not have a name.
-      def define_schema(&)
-        raise ArgumentError, 'The class must have a name' unless name.present?
+      # @return [void]
+      def apply_schema_validations
+        return unless @validation_options[:enabled]
 
-        @schema_definition = SchemaDefinition.new(name)
-        @schema_definition.klass = self # Pass the model class to the schema definition
-        @schema_definition.instance_eval(&)
+        adapter = ValidationAdapters::Registry.resolve(@validation_options[:adapter])
 
-        # Define accessors immediately based on schema_definition
-        defined_properties = (@schema_definition.schema[:properties] || {}).keys
-        attr_accessor(*defined_properties)
+        (@schema_definition.schema[:properties] || {}).each do |prop_name, prop_def|
+          # Skip if already validated
+          next if @validated_properties.include?(prop_name)
 
-        # Track which properties have had validations applied
-        @validated_properties ||= Set.new
+          # Skip if property has validate: false
+          next if prop_def[:constraints][:validate] == false
 
-        # Apply auto-validations immediately after definition
-        if EasyTalk.configuration.auto_validations
-          (@schema_definition.schema[:properties] || {}).each do |prop_name, prop_def|
-            # Only apply validations if they haven't been applied yet
-            unless @validated_properties.include?(prop_name)
-              ValidationBuilder.build_validations(self, prop_name, prop_def[:type], prop_def[:constraints])
-              @validated_properties.add(prop_name)
-            end
-          end
+          adapter.build_validations(self, prop_name, prop_def[:type], prop_def[:constraints])
+          @validated_properties.add(prop_name)
         end
-
-        @schema_definition
       end
 
+      public
+
       # Returns the unvalidated schema definition for the model.
       #
       # @return [SchemaDefinition] The unvalidated schema definition for the model.

data/lib/easy_talk/model_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ModelHelper
+    def self.easytalk_model?(type)
+      type.is_a?(Class) &&
+        type.respond_to?(:schema) &&
+        type.respond_to?(:ref_template) &&
+        defined?(EasyTalk::Model) &&
+        type.include?(EasyTalk::Model)
+    end
+  end
+end

data/lib/easy_talk/naming_strategies.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module NamingStrategies
+    IDENTITY = lambda(&:to_sym)
+    SNAKE_CASE = ->(property_name) { property_name.to_s.underscore.to_sym }
+    CAMEL_CASE = ->(property_name) { property_name.to_s.tr('-', '_').camelize(:lower).to_sym }
+    PASCAL_CASE = ->(property_name) { property_name.to_s.tr('-', '_').camelize.to_sym }
+
+    def self.derive_strategy(strategy)
+      if strategy.is_a?(Symbol)
+        "EasyTalk::NamingStrategies::#{strategy.to_s.upcase}".constantize
+      elsif strategy.is_a?(Proc)
+        strategy
+      else
+        raise ArgumentError, 'Invalid property naming strategy. Must be a Symbol or a Proc.'
+      end
+    end
+  end
+end