easy_talk 3.2.0 → 3.3.0

data/lib/easy_talk/builders/base_builder.rb

@@ -23,7 +23,7 @@ module EasyTalk
         params(
           property_name: Symbol,
           schema: T::Hash[Symbol, T.untyped],
-          options: T::Hash[Symbol, String],
+          options: T::Hash[Symbol, T.untyped],
           valid_options: T::Hash[Symbol, T.untyped]
         ).void
       end
@@ -59,6 +59,7 @@ module EasyTalk
         end
       end
 
+      sig { returns(T::Boolean) }
       def self.collection_type?
         false
       end

data/lib/easy_talk/builders/boolean_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -14,7 +15,7 @@ module EasyTalk
         default: { type: T::Boolean, key: :default }
       }.freeze
 
-      sig { params(name: Symbol, constraints: Hash).void }
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, constraints = {})
         super(name, { type: 'boolean' }, constraints, VALID_OPTIONS)
       end

data/lib/easy_talk/builders/collection_helpers.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   module Builders
     # Base builder class for array-type properties.
     module CollectionHelpers
+      extend T::Sig
+
+      sig { returns(T::Boolean) }
       def collection_type?
         true
       end

data/lib/easy_talk/builders/composition_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'collection_helpers'
 require_relative '../ref_helper'
@@ -16,7 +17,7 @@ module EasyTalk
         'OneOfBuilder' => 'oneOf'
       }.freeze
 
-      sig { params(name: Symbol, type: T.untyped, constraints: Hash).void }
+      sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
       # Initializes a new instance of the CompositionBuilder class.
       #
       # @param name [Symbol] The name of the composition.
@@ -32,7 +33,8 @@ module EasyTalk
 
       # Builds the composed JSON schema.
       #
-      # @return [void]
+      # @return [Hash] The composed JSON schema.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
       def build
         @context[@name.to_sym] = {
           type: 'object',
@@ -43,6 +45,7 @@ module EasyTalk
       # Returns the composer keyword based on the composer type.
       #
       # @return [String] The composer keyword.
+      sig { returns(T.nilable(String)) }
       def composer_keyword
         COMPOSER_TO_KEYWORD[@composer_type]
       end
@@ -50,6 +53,7 @@ module EasyTalk
       # Returns an array of schemas for the composed JSON schema.
       #
       # @return [Array<Hash>] The array of schemas.
+      sig { returns(T::Array[T.untyped]) }
       def schemas
         items.map do |type|
           if EasyTalk::RefHelper.should_use_ref?(type, @constraints)
@@ -66,6 +70,7 @@ module EasyTalk
       # Returns the items of the type.
       #
       # @return [T.untyped] The items of the type.
+      sig { returns(T.untyped) }
       def items
         @type.items
       end

data/lib/easy_talk/builders/integer_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -20,7 +21,7 @@ module EasyTalk
       }.freeze
 
       # Initializes a new instance of the IntegerBuilder class.
-      sig { params(name: Symbol, constraints: Hash).void }
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, constraints = {})
         super(name, { type: 'integer' }, constraints, VALID_OPTIONS)
       end

data/lib/easy_talk/builders/null_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -6,8 +7,10 @@ module EasyTalk
   module Builders
     # builder class for Null properties.
     class NullBuilder < BaseBuilder
+      extend T::Sig
+
       # Initializes a new instance of the NullBuilder class.
-      sig { params(name: Symbol, _constraints: Hash).void }
+      sig { params(name: Symbol, _constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, _constraints = {})
         super(name, { type: 'null' }, {}, {})
       end

data/lib/easy_talk/builders/number_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -6,6 +7,8 @@ module EasyTalk
   module Builders
     # Builder class for number properties.
     class NumberBuilder < BaseBuilder
+      extend T::Sig
+
       VALID_OPTIONS = {
         multiple_of: { type: T.any(Integer, Float), key: :multipleOf },
         minimum: { type: T.any(Integer, Float), key: :minimum },
@@ -18,7 +21,7 @@ module EasyTalk
       }.freeze
 
       # Initializes a new instance of the NumberBuilder class.
-      sig { params(name: Symbol, constraints: Hash).void }
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, constraints = {})
         super(name, { type: 'number' }, constraints, VALID_OPTIONS)
       end

data/lib/easy_talk/builders/object_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 require_relative '../model_helper'
@@ -20,7 +21,12 @@ module EasyTalk
       # Required by BaseBuilder: recognized schema options for "object" types
       VALID_OPTIONS = {
         properties: { type: T::Hash[T.any(Symbol, String), T.untyped], key: :properties },
-        additional_properties: { type: T::Boolean, key: :additionalProperties },
+        additional_properties: { type: T.any(T::Boolean, Class, T::Hash[Symbol, T.untyped]), key: :additionalProperties },
+        pattern_properties: { type: T::Hash[String, T.untyped], key: :patternProperties },
+        min_properties: { type: Integer, key: :minProperties },
+        max_properties: { type: Integer, key: :maxProperties },
+        dependencies: { type: T::Hash[String, T.any(T::Array[String], T::Hash[String, T.untyped])], key: :dependencies },
+        dependent_required: { type: T::Hash[String, T::Array[String]], key: :dependentRequired },
         subschemas: { type: T::Array[T.untyped], key: :subschemas },
         required: { type: T::Array[T.any(Symbol, String)], key: :required },
         defs: { type: T.untyped, key: :$defs },
@@ -55,6 +61,14 @@ module EasyTalk
         )
       end
 
+      # Override build to add additionalProperties after BaseBuilder validation
+      sig { override.returns(T::Hash[Symbol, T.untyped]) }
+      def build
+        result = super
+        process_additional_properties(result)
+        result
+      end
+
       private
 
       ##
@@ -99,8 +113,9 @@ module EasyTalk
         # Populate the final "required" array from @required_properties
         merged[:required] = @required_properties.to_a if @required_properties.any?
 
-        # Add additionalProperties: false by default if not explicitly set
-        merged[:additional_properties] = false unless merged.key?(:additional_properties)
+        # Process additionalProperties separately (don't let BaseBuilder validate it)
+        # Extract the value, process it, and we'll add it back after BaseBuilder runs
+        @additional_properties_value = merged.delete(:additional_properties)
 
         # Prune empty or nil values so we don't produce stuff like "properties": {} unnecessarily
         merged.reject! { |_k, v| v.nil? || v == {} || v == [] }
@@ -108,6 +123,52 @@ module EasyTalk
         merged
       end
 
+      ##
+      # Process additionalProperties to handle schema objects.
+      # Converts type classes or constraint hashes into proper JSON Schema.
+      # Called from build() method with the final schema hash.
+      #
+      def process_additional_properties(schema_hash)
+        value = @additional_properties_value
+
+        # If not set, use config default
+        if value.nil?
+          schema_hash[:additionalProperties] = EasyTalk.configuration.default_additional_properties
+          return
+        end
+
+        # Boolean: pass through as-is
+        if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          schema_hash[:additionalProperties] = value
+          return
+        end
+
+        # Class type: build schema
+        if value.is_a?(Class)
+          schema_hash[:additionalProperties] = build_additional_properties_schema(value, {})
+          return
+        end
+
+        # Hash with type + constraints: build schema with constraints
+        return unless value.is_a?(Hash)
+
+        type = value[:type] || value['type']
+        constraints = value.except(:type, 'type')
+        schema_hash[:additionalProperties] = build_additional_properties_schema(type, constraints)
+      end
+
+      ##
+      # Builds a JSON Schema for additionalProperties from a type and constraints.
+      # Uses the Property builder to generate the schema.
+      #
+      def build_additional_properties_schema(type, constraints)
+        return {} unless type
+
+        # Use Property builder to generate schema for the type
+        property = EasyTalk::Property.new(:_additional, type, constraints)
+        property.as_json
+      end
+
       ##
       # Given the property definitions hash, produce a new hash of
       # { property_name => [Property or nested schema builder result] }.

data/lib/easy_talk/builders/registry.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   module Builders
@@ -22,9 +23,12 @@ module EasyTalk
     #
     class Registry
       class << self
+        extend T::Sig
+
         # Get the hash of registered type builders.
         #
         # @return [Hash{String => Hash}] The registered builders with metadata
+        sig { returns(T::Hash[String, T::Hash[Symbol, T.untyped]]) }
         def registry
           @registry ||= {}
         end
@@ -43,6 +47,7 @@ module EasyTalk
         #
         # @example Register a collection type
         #   Registry.register(CustomArray, CustomArrayBuilder, collection: true)
+        sig { params(type_key: T.any(T::Class[T.anything], String, Symbol), builder_class: T.untyped, collection: T::Boolean).void }
         def register(type_key, builder_class, collection: false)
           raise ArgumentError, 'Builder must respond to .new' unless builder_class.respond_to?(:new)
 
@@ -63,6 +68,7 @@ module EasyTalk
         # @example
         #   builder_class, is_collection = Registry.resolve(String)
         #   # => [StringBuilder, false]
+        sig { params(type: T.untyped).returns(T.nilable(T::Array[T.untyped])) }
         def resolve(type)
           entry = find_registration(type)
           return nil unless entry
@@ -74,6 +80,7 @@ module EasyTalk
         #
         # @param type_key [Class, String, Symbol] The type to check
         # @return [Boolean] true if the type is registered
+        sig { params(type_key: T.any(T::Class[T.anything], String, Symbol)).returns(T::Boolean) }
         def registered?(type_key)
           registry.key?(normalize_key(type_key))
         end
@@ -82,6 +89,7 @@ module EasyTalk
         #
         # @param type_key [Class, String, Symbol] The type to unregister
         # @return [Hash, nil] The removed registration or nil if not found
+        sig { params(type_key: T.any(T::Class[T.anything], String, Symbol)).returns(T.nilable(T::Hash[Symbol, T.untyped])) }
         def unregister(type_key)
           registry.delete(normalize_key(type_key))
         end
@@ -89,6 +97,7 @@ module EasyTalk
         # Get a list of all registered type keys.
         #
         # @return [Array<String>] The registered type keys
+        sig { returns(T::Array[String]) }
         def registered_types
           registry.keys
         end
@@ -96,6 +105,7 @@ module EasyTalk
         # Reset the registry to empty state and re-register built-in types.
         #
         # @return [void]
+        sig { void }
         def reset!
           @registry = nil
           register_built_in_types
@@ -105,6 +115,7 @@ module EasyTalk
         # This is called during gem initialization and after reset!
         #
         # @return [void]
+        sig { void }
         def register_built_in_types
           register(String, Builders::StringBuilder)
           register(Integer, Builders::IntegerBuilder)
@@ -116,9 +127,10 @@ module EasyTalk
           register(Date, Builders::TemporalBuilder::DateBuilder)
           register(DateTime, Builders::TemporalBuilder::DatetimeBuilder)
           register(Time, Builders::TemporalBuilder::TimeBuilder)
-          register('anyOf', Builders::CompositionBuilder::AnyOfBuilder, collection: true)
           register('allOf', Builders::CompositionBuilder::AllOfBuilder, collection: true)
+          register('anyOf', Builders::CompositionBuilder::AnyOfBuilder, collection: true)
           register('oneOf', Builders::CompositionBuilder::OneOfBuilder, collection: true)
+          register('EasyTalk::Types::Tuple', Builders::TupleBuilder, collection: true)
           register('T::Types::TypedArray', Builders::TypedArrayBuilder, collection: true)
           register('T::Types::Union', Builders::UnionBuilder, collection: true)
         end
@@ -129,6 +141,7 @@ module EasyTalk
         #
         # @param type_key [Class, String, Symbol] The type key to normalize
         # @return [String] The normalized key
+        sig { params(type_key: T.any(T::Class[T.anything], String, Symbol)).returns(String) }
         def normalize_key(type_key)
           case type_key
           when Class
@@ -146,6 +159,7 @@ module EasyTalk
         #
         # @param type [Object] The type to find
         # @return [Hash, nil] The registration entry or nil
+        sig { params(type: T.untyped).returns(T.nilable(T::Hash[Symbol, T.untyped])) }
         def find_registration(type)
           # Strategy 1: Check type.class.name (for Sorbet types like T::Types::TypedArray)
           class_name = type.class.name.to_s

data/lib/easy_talk/builders/string_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 require 'js_regex' # Compile the ruby regex to JS regex
@@ -20,11 +21,12 @@ module EasyTalk
         default: { type: String, key: :default }
       }.freeze
 
-      sig { params(name: Symbol, constraints: Hash).void }
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, constraints = {})
         super(name, { type: 'string' }, constraints, VALID_OPTIONS)
       end
 
+      sig { returns(T::Hash[Symbol, T.untyped]) }
       def build
         super.tap do |schema|
           pattern = schema[:pattern]

data/lib/easy_talk/builders/temporal_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'string_builder'
 
@@ -6,11 +7,14 @@ module EasyTalk
   module Builders
     # Builder class for temporal properties (date, datetime, time).
     class TemporalBuilder < StringBuilder
+      extend T::Sig
+
       # Initializes a new instance of the TemporalBuilder class.
       #
       # @param property_name [Symbol] The name of the property.
       # @param options [Hash] The options for the builder.
       # @param format [String] The format of the temporal property (date, date-time, time).
+      sig { params(property_name: Symbol, options: T::Hash[Symbol, T.untyped], format: T.nilable(String)).void }
       def initialize(property_name, options = {}, format = nil)
         super(property_name, options)
         @format = format
@@ -26,6 +30,7 @@ module EasyTalk
 
       # Builder class for date properties.
       class DateBuilder < TemporalBuilder
+        sig { params(property_name: Symbol, options: T::Hash[Symbol, T.untyped]).void }
         def initialize(property_name, options = {})
           super(property_name, options, 'date')
         end
@@ -33,6 +38,7 @@ module EasyTalk
 
       # Builder class for datetime properties.
       class DatetimeBuilder < TemporalBuilder
+        sig { params(property_name: Symbol, options: T::Hash[Symbol, T.untyped]).void }
         def initialize(property_name, options = {})
           super(property_name, options, 'date-time')
         end
@@ -40,6 +46,7 @@ module EasyTalk
 
       # Builder class for time properties.
       class TimeBuilder < TemporalBuilder
+        sig { params(property_name: Symbol, options: T::Hash[Symbol, T.untyped]).void }
         def initialize(property_name, options = {})
           super(property_name, options, 'time')
         end

data/lib/easy_talk/builders/tuple_builder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+# typed: true
+
+module EasyTalk
+  module Builders
+    # Builder class for tuple array properties (T::Tuple[Type1, Type2, ...]).
+    #
+    # Tuples are arrays with positional type validation where each index
+    # has a specific expected type.
+    #
+    # @example Basic tuple
+    #   property :coordinates, T::Tuple[Float, Float]
+    #
+    # @example Tuple with additional items constraint
+    #   property :record, T::Tuple[String, Integer], additional_items: false
+    #
+    class TupleBuilder < BaseBuilder
+      extend T::Sig
+
+      # NOTE: additional_items is handled separately in build() since it can be a type
+      VALID_OPTIONS = {
+        min_items: { type: Integer, key: :minItems },
+        max_items: { type: Integer, key: :maxItems },
+        unique_items: { type: T::Boolean, key: :uniqueItems }
+      }.freeze
+
+      attr_reader :type
+
+      sig { params(name: Symbol, type: Types::Tuple, constraints: T::Hash[Symbol, T.untyped]).void }
+      def initialize(name, type, constraints = {})
+        @name = name
+        @type = type
+        # Work on a copy to avoid mutating the original constraints hash
+        local_constraints = constraints.dup
+        # Extract additional_items before passing to super (it's handled separately in build)
+        @additional_items_constraint = local_constraints.delete(:additional_items)
+        super(name, { type: 'array' }, local_constraints, VALID_OPTIONS)
+      end
+
+      sig { returns(T::Boolean) }
+      def self.collection_type?
+        true
+      end
+
+      # Builds the tuple schema with positional items.
+      #
+      # @return [Hash] The built schema.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def build
+        schema = super
+
+        # Build items array from tuple types
+        schema[:items] = build_items
+
+        # Handle additional_items constraint
+        schema[:additionalItems] = build_additional_items_schema(@additional_items_constraint) unless @additional_items_constraint.nil?
+
+        schema
+      end
+
+      private
+
+      # Builds the items array from tuple types.
+      #
+      # @return [Array<Hash>] Array of schemas for each position
+      sig { returns(T::Array[T::Hash[Symbol, T.untyped]]) }
+      def build_items
+        type.types.map.with_index do |item_type, index|
+          Property.new(:"#{@name}_item_#{index}", item_type, {}).build
+        end
+      end
+
+      # Builds the additionalItems schema value.
+      #
+      # @param value [Boolean, Class] The additional_items constraint
+      # @return [Boolean, Hash] The schema value for additionalItems
+      sig { params(value: T.untyped).returns(T.any(T::Boolean, T::Hash[Symbol, T.untyped])) }
+      def build_additional_items_schema(value)
+        case value
+        when true, false
+          value
+        else
+          # It's a type - build a schema for it
+          Property.new(:"#{@name}_additional", value, {}).build
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/typed_array_builder.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'collection_helpers'
 
 module EasyTalk
   module Builders
-    # Builder class for array properties.
+    # Builder class for homogeneous array properties (T::Array[Type]).
     class TypedArrayBuilder < BaseBuilder
       extend CollectionHelpers
       extend T::Sig
@@ -20,7 +21,7 @@ module EasyTalk
 
       attr_reader :type
 
-      sig { params(name: Symbol, type: T.untyped, constraints: Hash).void }
+      sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, type, constraints = {})
         @name = name
         @type = type
@@ -49,6 +50,7 @@ module EasyTalk
         end
       end
 
+      sig { returns(T.untyped) }
       def inner_type
         return unless type.is_a?(T::Types::TypedArray)
 

data/lib/easy_talk/builders/union_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'collection_helpers'
 
@@ -9,7 +10,7 @@ module EasyTalk
       extend CollectionHelpers
       extend T::Sig
 
-      sig { params(name: Symbol, type: T.untyped, constraints: T.untyped).void }
+      sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, type, constraints)
         @name = name
         @type = type
@@ -17,18 +18,21 @@ module EasyTalk
         @context = {}
       end
 
+      sig { returns(T::Hash[Symbol, T.untyped]) }
       def build
         @context[@name] = {
           'anyOf' => schemas
         }
       end
 
+      sig { returns(T::Array[T.untyped]) }
       def schemas
         types.map do |type|
           Property.new(@name, type, @constraints).build
         end
       end
 
+      sig { returns(T.untyped) }
       def types
         @type.types
       end

data/lib/easy_talk/configuration.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'naming_strategies'
 
 module EasyTalk
   class Configuration
+    extend T::Sig
+
     # JSON Schema draft version URIs
     SCHEMA_VERSIONS = {
       draft202012: 'https://json-schema.org/draft/2020-12/schema',
@@ -14,9 +17,11 @@ module EasyTalk
     }.freeze
 
     attr_accessor :default_additional_properties, :nilable_is_optional, :auto_validations, :schema_version, :schema_id,
-                  :use_refs, :validation_adapter, :default_error_format, :error_type_base_uri, :include_error_codes
+                  :use_refs, :validation_adapter, :default_error_format, :error_type_base_uri, :include_error_codes,
+                  :base_schema_uri, :auto_generate_ids, :prefer_external_refs
     attr_reader :property_naming_strategy
 
+    sig { void }
     def initialize
       @default_additional_properties = false
       @nilable_is_optional = false
@@ -28,16 +33,21 @@ module EasyTalk
       @default_error_format = :flat
       @error_type_base_uri = 'about:blank'
       @include_error_codes = true
+      @base_schema_uri = nil
+      @auto_generate_ids = false
+      @prefer_external_refs = false
       self.property_naming_strategy = :identity
     end
 
     # Returns the URI for the configured schema version, or nil if :none
+    sig { returns(T.nilable(String)) }
     def schema_uri
       return nil if @schema_version == :none
 
       SCHEMA_VERSIONS[@schema_version] || @schema_version.to_s
     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
@@ -56,17 +66,22 @@ module EasyTalk
     #   EasyTalk.configure do |config|
     #     config.register_type Money, MoneySchemaBuilder
     #   end
+    sig { params(type_key: T.any(T::Class[T.anything], String, Symbol), builder_class: T.untyped, collection: T::Boolean).void }
     def register_type(type_key, builder_class, collection: false)
       EasyTalk::Builders::Registry.register(type_key, builder_class, collection: collection)
     end
   end
 
   class << self
+    extend T::Sig
+
+    sig { returns(Configuration) }
     def configuration
       @configuration ||= Configuration.new
     end
 
-    def configure
+    sig { params(block: T.proc.params(config: Configuration).void).void }
+    def configure(&block)
       yield(configuration)
     end
   end

data/lib/easy_talk/errors.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   class Error < StandardError; end

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})."