easy_talk 3.2.0 → 3.3.0

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'
@@ -220,6 +221,9 @@ module EasyTalk
         # Track which properties have had validations applied
         @validated_properties ||= Set.new
 
+        # Initialize mutex eagerly for thread-safe schema-level validation application
+        @schema_level_validation_lock = Mutex.new
+
         # Apply validations using the adapter system
         apply_schema_validations
 
@@ -273,6 +277,26 @@ module EasyTalk
           adapter.build_validations(self, prop_name, prop_def[:type], prop_def[:constraints])
           @validated_properties.add(prop_name)
         end
+
+        # 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
@@ -285,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

@@ -1,7 +1,11 @@
 # 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) &&

data/lib/easy_talk/naming_strategies.rb

@@ -1,12 +1,16 @@
 # 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

data/lib/easy_talk/property.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'json'
 require_relative 'builders/integer_builder'
@@ -9,6 +10,7 @@ require_relative 'builders/string_builder'
 require_relative 'builders/temporal_builder'
 require_relative 'builders/composition_builder'
 require_relative 'builders/typed_array_builder'
+require_relative 'builders/tuple_builder'
 require_relative 'builders/union_builder'
 
 # EasyTalk module provides a DSL for building JSON Schema definitions.
@@ -99,6 +101,7 @@ module EasyTalk
     # @example Nested schema with $ref
     #   property = Property.new(:shipping_address, Address, ref: true)
     #   property.build  # => {"$ref"=>"#/$defs/Address", ...constraints}
+    sig { returns(T::Hash[Symbol, T.untyped]) }
     def build
       if nilable_type?
         build_nilable_schema
@@ -128,6 +131,7 @@ module EasyTalk
     #
     # @see #build
     # @see https://ruby-doc.org/stdlib-2.7.2/libdoc/json/rdoc/JSON.html#as_json-method
+    sig { params(_args: T.untyped).returns(T.untyped) }
     def as_json(*_args)
       build.as_json
     end
@@ -142,6 +146,7 @@ module EasyTalk
     # @return [Array(Class, Boolean), nil] A tuple of [builder_class, is_collection] or nil if none matches
     # @api private
     # @see Builders::Registry.resolve
+    sig { returns(T.nilable(T::Array[T.untyped])) }
     def find_builder_for_type
       Builders::Registry.resolve(type)
     end
@@ -153,6 +158,7 @@ module EasyTalk
     #
     # @return [Boolean] true if the type is nilable, false otherwise
     # @api private
+    sig { returns(T::Boolean) }
     def nilable_type?
       return false unless type.respond_to?(:types)
       return false unless type.types.all? { |t| t.respond_to?(:raw_type) }
@@ -167,6 +173,7 @@ module EasyTalk
     # @example
     #   # For a T.nilable(String) type:
     #   {"type"=>["string", "null"]}
+    sig { returns(T::Hash[Symbol, T.untyped]) }
     def build_nilable_schema
       # Extract the non-nil type from the Union
       actual_type = T::Utils::Nilable.get_underlying_type(type)

data/lib/easy_talk/ref_helper.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'model_helper'
 
 module EasyTalk
   module RefHelper
+    extend T::Sig
+
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
     def self.should_use_ref?(type, constraints)
       ModelHelper.easytalk_model?(type) && should_use_ref_for_type?(type, constraints)
     end
 
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
     def self.should_use_ref_for_type?(type, constraints)
       return false unless ModelHelper.easytalk_model?(type)
 
@@ -19,6 +24,7 @@ module EasyTalk
       end
     end
 
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
     def self.build_ref_schema(type, constraints)
       # Remove ref and optional from constraints as they're not JSON Schema keywords
       { '$ref': type.ref_template }.merge(constraints.except(:ref, :optional))

data/lib/easy_talk/schema.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'json'
 require 'active_support'

data/lib/easy_talk/schema_definition.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'keywords'
 require_relative 'types/composer'
@@ -19,28 +20,39 @@ module EasyTalk
     attr_reader :name, :schema
     attr_accessor :klass # Add accessor for the model class
 
+    sig { params(name: String, schema: T::Hash[Symbol, T.untyped]).void }
     def initialize(name, schema = {})
-      @schema = schema
-      @schema[:additional_properties] = false unless schema.key?(:additional_properties)
+      @schema = schema.dup
+      @schema[:additional_properties] = EasyTalk.configuration.default_additional_properties unless @schema.key?(:additional_properties)
       @name = name
       @klass = nil # Initialize klass to nil
       @property_naming_strategy = EasyTalk.configuration.property_naming_strategy
     end
 
     EasyTalk::KEYWORDS.each do |keyword|
-      define_method(keyword) do |*values|
-        @schema[keyword] = values.size > 1 ? values : values.first
+      if keyword == :additional_properties
+        # Special handling for additional_properties to support type + constraints syntax
+        define_method(keyword) do |*args|
+          value = parse_additional_properties_args(args)
+          @schema[keyword] = value
+        end
+      else
+        define_method(keyword) do |*values|
+          @schema[keyword] = values.size > 1 ? values : values.first
+        end
       end
     end
 
+    sig { params(subschemas: T.untyped).void }
     def compose(*subschemas)
       @schema[:subschemas] ||= []
       @schema[:subschemas] += subschemas
     end
 
-    def property(name, type, constraints = {}, &)
+    sig { params(name: T.any(Symbol, String), type: T.untyped, constraints: T::Hash[Symbol, T.untyped], block: T.nilable(T.proc.void)).void }
+    def property(name, type, constraints = {}, &block)
+      validate_property_name(name)
       constraints[:as] ||= @property_naming_strategy.call(name)
-      validate_property_name(constraints[:as])
       @schema[:properties] ||= {}
 
       if block_given?
@@ -51,6 +63,7 @@ module EasyTalk
       @schema[:properties][name] = { type:, constraints: }
     end
 
+    sig { params(name: T.any(Symbol, String)).void }
     def validate_property_name(name)
       return if name.to_s.match?(/^[A-Za-z_][A-Za-z0-9_]*$/)
 
@@ -59,11 +72,13 @@ module EasyTalk
       raise InvalidPropertyNameError, message
     end
 
+    sig { returns(T.nilable(T::Boolean)) }
     def optional?
       @schema[:optional]
     end
 
     # Helper method for nullable and optional properties
+    sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
     def nullable_optional_property(name, type, constraints = {})
       # Ensure type is nilable
       nilable_type = if type.respond_to?(:nilable?) && type.nilable?
@@ -79,8 +94,39 @@ module EasyTalk
       property(name, nilable_type, constraints)
     end
 
+    sig { params(strategy: T.any(Symbol, T.proc.params(arg0: T.untyped).returns(Symbol))).void }
     def property_naming_strategy(strategy)
       @property_naming_strategy = EasyTalk::NamingStrategies.derive_strategy(strategy)
     end
+
+    private
+
+    # Parses arguments for additional_properties to support multiple syntaxes:
+    # - additional_properties true/false (boolean)
+    # - additional_properties String (type class)
+    # - additional_properties Integer, minimum: 0, maximum: 100 (type + constraints)
+    sig { params(args: T::Array[T.untyped]).returns(T.untyped) }
+    def parse_additional_properties_args(args)
+      return args.first if args.empty?
+
+      # Single boolean argument
+      first_arg = args.first
+      return first_arg if args.size == 1 && (first_arg.is_a?(TrueClass) || first_arg.is_a?(FalseClass))
+
+      # Single type class (String, Integer, custom model, etc.)
+      return first_arg if args.size == 1 && first_arg.is_a?(Class)
+
+      # Type + constraints: additional_properties Integer, minimum: 0, maximum: 100
+      # args = [Integer, { minimum: 0, maximum: 100 }] or [Integer, minimum: 0, maximum: 100]
+      if args.size >= 1 && args.first.is_a?(Class)
+        type = args.first
+        # Merge all hash arguments as constraints
+        constraints = args[1..].select { |arg| arg.is_a?(Hash) }.reduce({}, :merge)
+        return { type:, **constraints }
+      end
+
+      # Fallback: return as-is
+      args.first
+    end
   end
 end

data/lib/easy_talk/schema_methods.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   # Shared methods for JSON Schema generation.
@@ -14,10 +15,16 @@ module EasyTalk
   #
   module SchemaMethods
     # Returns the reference template for the model.
+    # When prefer_external_refs is enabled and the model has a schema ID,
+    # returns the external $id URI. Otherwise, returns the local $defs reference.
     #
     # @return [String] The reference template for the model.
     def ref_template
-      "#/$defs/#{name}"
+      config = EasyTalk.configuration
+
+      # Use external ref when configured and $id available, otherwise fall back to local $defs
+      schema_id = resolve_schema_id if config.prefer_external_refs
+      schema_id || "#/$defs/#{name}"
     end
 
     # Returns the JSON schema for the model.
@@ -62,19 +69,43 @@ module EasyTalk
       end
     end
 
-    # Resolves the schema ID from per-model setting or global config.
+    # Resolves the schema ID from per-model setting, auto-generation, or global config.
+    # Precedence order:
+    #   1. Per-model explicit schema_id (highest priority)
+    #   2. Auto-generated from base_schema_uri (middle priority)
+    #   3. Global schema_id (lowest priority)
     #
     # @return [String, nil] The schema ID.
     def resolve_schema_id
       model_id = @schema_definition&.schema&.dig(:schema_id)
 
+      # Per-model explicit ID takes precedence
       if model_id
         return nil if model_id == :none
 
-        model_id.to_s
-      else
-        EasyTalk.configuration.schema_id
+        return model_id.to_s
       end
+
+      # Auto-generate from base_schema_uri if enabled
+      config = EasyTalk.configuration
+      return generate_schema_id(config.base_schema_uri, name) if config.auto_generate_ids && config.base_schema_uri && name
+
+      # Fall back to global schema_id
+      config.schema_id
+    end
+
+    # Generates a schema ID from the base URI and model name.
+    # Normalizes the base URI and converts the model name to underscore case.
+    #
+    # @param base_uri [String] The base URI for schema IDs.
+    # @param model_name [String] The model class name.
+    # @return [String] The generated schema ID.
+    def generate_schema_id(base_uri, model_name)
+      # Normalize base URI (remove trailing slash)
+      base = base_uri.to_s.chomp('/')
+      # Convert model name to lowercase with underscores for URI segment
+      segment = model_name.to_s.underscore
+      "#{base}/#{segment}"
     end
   end
 end

data/lib/easy_talk/sorbet_extension.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 # This module provides additional functionality for working with Sorbet types.
 module SorbetExtension

data/lib/easy_talk/type_introspection.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'bigdecimal'
 
@@ -31,6 +32,8 @@ module EasyTalk
     }.freeze
 
     class << self
+      extend T::Sig
+
       # Check if type represents a boolean (T::Boolean or TrueClass/FalseClass).
       #
       # @param type [Object] The type to check
@@ -41,6 +44,7 @@ module EasyTalk
       #   boolean_type?(TrueClass)   # => true
       #   boolean_type?(FalseClass)  # => true
       #   boolean_type?(String)      # => false
+      sig { params(type: T.untyped).returns(T::Boolean) }
       def boolean_type?(type)
         return false if type.nil?
         return true if [TrueClass, FalseClass].include?(type)
@@ -58,6 +62,23 @@ module EasyTalk
         false
       end
 
+      # Check if a resolved type class represents a boolean union ([TrueClass, FalseClass]).
+      #
+      # This is useful when checking resolved type classes rather than raw Sorbet types.
+      # The internal representation of T::Boolean resolves to [TrueClass, FalseClass].
+      #
+      # @param type_class [Object] The resolved type class to check
+      # @return [Boolean] true if the type class is a boolean union array
+      #
+      # @example
+      #   boolean_union_type?([TrueClass, FalseClass]) # => true
+      #   boolean_union_type?(TrueClass)               # => false
+      #   boolean_union_type?(String)                  # => false
+      sig { params(type_class: T.untyped).returns(T::Boolean) }
+      def boolean_union_type?(type_class)
+        type_class.is_a?(Array) && type_class.sort_by(&:name) == [FalseClass, TrueClass].sort_by(&:name)
+      end
+
       # Check if type is a typed array (T::Array[...]).
       #
       # @param type [Object] The type to check
@@ -66,12 +87,30 @@ module EasyTalk
       # @example
       #   typed_array?(T::Array[String]) # => true
       #   typed_array?(Array)            # => false
+      sig { params(type: T.untyped).returns(T::Boolean) }
       def typed_array?(type)
         return false if type.nil?
 
         type.is_a?(T::Types::TypedArray)
       end
 
+      # Check if type is any array type (plain Array, T::Array[...], or T::Tuple[...]).
+      #
+      # @param type [Object] The type to check
+      # @return [Boolean] true if the type is an array type
+      #
+      # @example
+      #   array_type?(Array)                      # => true
+      #   array_type?(T::Array[String])           # => true
+      #   array_type?(T::Tuple[String, Integer])  # => true
+      #   array_type?(String)                     # => false
+      sig { params(type: T.untyped).returns(T::Boolean) }
+      def array_type?(type)
+        return false if type.nil?
+
+        type == Array || type.is_a?(T::Types::TypedArray) || type.is_a?(EasyTalk::Types::Tuple)
+      end
+
       # Check if type is nilable (T.nilable(...)).
       #
       # @param type [Object] The type to check
@@ -80,6 +119,7 @@ module EasyTalk
       # @example
       #   nilable_type?(T.nilable(String)) # => true
       #   nilable_type?(String)            # => false
+      sig { params(type: T.untyped).returns(T::Boolean) }
       def nilable_type?(type)
         return false if type.nil?
 
@@ -90,6 +130,7 @@ module EasyTalk
       #
       # @param type [Object] The type to check
       # @return [Boolean] true if the type is a primitive
+      sig { params(type: T.untyped).returns(T::Boolean) }
       def primitive_type?(type)
         return false if type.nil?
 
@@ -111,6 +152,7 @@ module EasyTalk
       #   json_schema_type(Float)      # => 'number'
       #   json_schema_type(BigDecimal) # => 'number'
       #   json_schema_type(String)     # => 'string'
+      sig { params(type: T.untyped).returns(String) }
       def json_schema_type(type)
         return 'object' if type.nil?
         return 'boolean' if boolean_type?(type)
@@ -133,11 +175,12 @@ module EasyTalk
       #   get_type_class(String)           # => String
       #   get_type_class(T::Boolean)       # => [TrueClass, FalseClass]
       #   get_type_class(T::Array[String]) # => Array
+      sig { params(type: T.untyped).returns(T.untyped) }
       def get_type_class(type)
         return nil if type.nil?
         return type if type.is_a?(Class)
         return type.raw_type if type.respond_to?(:raw_type)
-        return Array if typed_array?(type)
+        return Array if type.is_a?(T::Types::TypedArray) || type.is_a?(EasyTalk::Types::Tuple)
         return [TrueClass, FalseClass] if boolean_type?(type)
 
         if nilable_type?(type)
@@ -155,6 +198,7 @@ module EasyTalk
       #
       # @example
       #   extract_inner_type(T.nilable(String)) # => String
+      sig { params(type: T.untyped).returns(T.untyped) }
       def extract_inner_type(type)
         return type if type.nil?
 

data/lib/easy_talk/types/tuple.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module Types
+    # Represents a tuple type for arrays with positional type validation.
+    #
+    # A tuple is an array where each position has a specific type. This class
+    # stores the types for each position.
+    #
+    # @example Basic tuple
+    #   T::Tuple[String, Integer]  # First item must be String, second must be Integer
+    #
+    # @example With additional_items constraint
+    #   property :flags, T::Tuple[T::Boolean, T::Boolean], additional_items: false
+    #
+    class Tuple
+      extend T::Sig
+
+      # @return [Array<Object>] The types for each position in the tuple
+      sig { returns(T::Array[T.untyped]) }
+      attr_reader :types
+
+      # Creates a new Tuple instance with the given positional types.
+      #
+      # @param types [Array] The types for each position in the tuple
+      # @raise [ArgumentError] if types is empty or contains nil values
+      sig { params(types: T.untyped).void }
+      def initialize(*types)
+        raise ArgumentError, 'Tuple requires at least one type' if types.empty?
+        raise ArgumentError, 'Tuple types cannot be nil' if types.any?(&:nil?)
+
+        @types = types.freeze
+      end
+
+      # Returns a string representation of the tuple type.
+      #
+      # @return [String] A human-readable representation
+      sig { returns(String) }
+      def to_s
+        type_names = @types.map { |t| (t.respond_to?(:name) && t.name) || t.to_s }
+        "T::Tuple[#{type_names.join(', ')}]"
+      end
+
+      # Returns the name of this type (used by Property for error messages).
+      #
+      # @return [String] The type name
+      sig { returns(String) }
+      def name
+        to_s
+      end
+    end
+  end
+end
+
+# Add T::Tuple module for bracket syntax
+module T
+  # Provides tuple type syntax: T::Tuple[Type1, Type2, ...]
+  #
+  # Creates a tuple type that validates array elements by position.
+  #
+  # @example Basic usage
+  #   property :coordinates, T::Tuple[Float, Float]
+  #   property :record, T::Tuple[String, Integer, T::Boolean]
+  #
+  # @example With additional_items constraint
+  #   property :flags, T::Tuple[T::Boolean, T::Boolean], additional_items: false
+  #
+  module Tuple
+    # Creates a new Tuple type with the given positional types.
+    #
+    # @param types [Array] The types for each position
+    # @return [EasyTalk::Types::Tuple] A new Tuple instance
+    def self.[](*types)
+      EasyTalk::Types::Tuple.new(*types)
+    end
+  end
+end