easy_talk 3.1.0 → 3.3.0

data/lib/easy_talk/errors_helper.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   # Helper module for generating consistent error messages
   module ErrorHelper
+    extend T::Sig
+
     def self.raise_constraint_error(property_name:, constraint_name:, expected:, got:)
       message = "Error in property '#{property_name}': Constraint '#{constraint_name}' expects #{expected}, " \
                 "but received #{got.inspect} (#{got.class})."
@@ -27,7 +30,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 +47,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 +142,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/json_schema_equality.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  # Implements JSON Schema equality semantics for comparing values.
+  #
+  # Per JSON Schema specification:
+  # - Objects with same keys/values in different order are equal
+  # - Numbers that are mathematically equal are equal (1 == 1.0)
+  # - Type matters for non-numbers (true != 1, false != 0)
+  module JsonSchemaEquality
+    # Maximum nesting depth to prevent SystemStackError on deeply nested structures
+    MAX_DEPTH = 100
+
+    class << self
+      # Check if an array contains duplicate values using JSON Schema equality.
+      # Uses a Set for O(n) performance and early termination on first duplicate.
+      def duplicates?(array)
+        seen = Set.new
+        array.any? { |item| !seen.add?(normalize(item)) }
+      end
+
+      # Normalize a value for JSON Schema equality comparison
+      # @param value [Object] The value to normalize
+      # @param depth [Integer] Current recursion depth (for stack overflow protection)
+      # @raise [ArgumentError] if nesting depth exceeds MAX_DEPTH
+      def normalize(value, depth = 0)
+        raise ArgumentError, "Nesting depth exceeds maximum of #{MAX_DEPTH}" if depth > MAX_DEPTH
+
+        case value
+        when Hash
+          # Convert keys to strings before sorting to handle mixed key types (Symbol/String)
+          # and ensure consistent, order-independent comparison (JSON only has string keys)
+          value.map { |k, v| [k.to_s, normalize(v, depth + 1)] }.sort
+        when Array
+          value.map { |item| normalize(item, depth + 1) }
+        when Integer, Float
+          # Normalize numbers to a canonical form for mathematical equality
+          value.to_r
+        else
+          # Booleans, strings, nil - preserve as-is (type matters)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/keywords.rb

@@ -7,7 +7,6 @@ module EasyTalk
     description
     type
     title
-    property
     required
     items
     additional_items

data/lib/easy_talk/model.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'json'
 require 'active_support'
@@ -10,6 +11,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 +43,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
+
+      private
+
+      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?
 
-          next 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
 
-          defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
+      def apply_default_value(prop_name, prop_definition, provided_keys)
+        return if provided_keys.include?(prop_name)
 
-          # 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)
+        default_value = prop_definition.dig(:constraints, :default)
+        public_send("#{prop_name}=", default_value) unless default_value.nil?
+      end
 
-          # Instantiate the nested model and assign it back
-          nested_instance = defined_type.new(current_value)
-          public_send("#{prop_name}=", nested_instance)
+      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 +124,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 +170,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 +183,124 @@ 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
+      # @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?
 
-      # 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
+        @schema_definition = SchemaDefinition.new(name)
+        @schema_definition.klass = self # Pass the model class to the schema definition
+        @schema_definition.instance_eval(&)
 
-        # 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
+        # Store validation options for this model
+        @validation_options = normalize_validation_options(options)
 
-        return result if prefix.empty?
+        # Define accessors immediately based on schema_definition
+        defined_properties = (@schema_definition.schema[:properties] || {}).keys
+        attr_accessor(*defined_properties)
 
-        prefix.merge(result)
-      end
+        # Track which properties have had validations applied
+        @validated_properties ||= Set.new
 
-      # Resolves the schema URI from per-model setting or global config.
-      def resolve_schema_uri
-        model_version = @schema_definition&.schema&.dig(:schema_version)
+        # Initialize mutex eagerly for thread-safe schema-level validation application
+        @schema_level_validation_lock = Mutex.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
+        # Apply schema-level validations (min_properties, max_properties, dependent_required)
+        apply_schema_level_validations(adapter)
       end
 
+      # Apply schema-level validations for object-level constraints.
+      # Uses double-checked locking for thread safety.
+      # The mutex is initialized eagerly in define_schema.
+      #
+      # @param adapter [Class] The validation adapter class
+      # @return [void]
+      def apply_schema_level_validations(adapter)
+        return if @schema_level_validations_applied
+
+        @schema_level_validation_lock.synchronize do
+          return if @schema_level_validations_applied
+
+          adapter.build_schema_validations(self, @schema_definition.schema)
+          @schema_level_validations_applied = true
+        end
+      end
+
+      public
+
       # Returns the unvalidated schema definition for the model.
       #
       # @return [SchemaDefinition] The unvalidated schema definition for the model.
@@ -252,7 +309,9 @@ module EasyTalk
       end
 
       def additional_properties_allowed?
-        @schema_definition&.schema&.fetch(:additional_properties, false)
+        ap = @schema_definition&.schema&.fetch(:additional_properties, false)
+        # Allow if true, or if it's a schema object (Class or Hash with type)
+        ap == true || ap.is_a?(Class) || ap.is_a?(Hash)
       end
 
       # Returns the property names defined in the schema

data/lib/easy_talk/model_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: true
+
+module EasyTalk
+  module ModelHelper
+    extend T::Sig
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    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,24 @@
+# frozen_string_literal: true
+# typed: true
+
+module EasyTalk
+  module NamingStrategies
+    extend T::Sig
+
+    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 }
+
+    sig { params(strategy: T.any(Symbol, T.proc.params(arg0: T.untyped).returns(Symbol))).returns(T.proc.params(arg0: T.untyped).returns(Symbol)) }
+    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