easy_talk 3.1.0 → 3.3.0

data/lib/easy_talk/builders/object_builder.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
+require_relative '../model_helper'
 
 module EasyTalk
   module Builders
@@ -19,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 },
@@ -33,8 +40,8 @@ module EasyTalk
       def initialize(schema_definition)
         # Keep a reference to the original schema definition
         @schema_definition = schema_definition
-        # Duplicate the raw schema hash so we can mutate it safely
-        @original_schema = schema_definition.schema.dup
+        # Deep duplicate the raw schema hash so we can mutate it safely
+        @original_schema = deep_dup(schema_definition.schema)
 
         # We'll collect required property names in this Set
         @required_properties = Set.new
@@ -54,8 +61,34 @@ 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
 
+      ##
+      # Deep duplicates a hash, including nested hashes.
+      # This prevents mutations from leaking back to the original schema.
+      #
+      def deep_dup(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| deep_dup(v) }
+        when Array
+          obj.map { |v| deep_dup(v) }
+        when Class, Module
+          # Don't duplicate Class or Module objects - they represent types
+          obj
+        else
+          obj.duplicable? ? obj.dup : obj
+        end
+      end
+
       ##
       # Main aggregator: merges the top-level schema keys (like :properties, :subschemas)
       # into a single hash that we'll feed to BaseBuilder.
@@ -80,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 == [] }
@@ -89,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] }.
@@ -99,16 +179,18 @@ module EasyTalk
         # Cache with a key based on property name and its full configuration
         @properties_cache ||= {}
 
-        properties_hash.each_with_object({}) do |(prop_name, prop_options), result|
-          cache_key = [prop_name, prop_options].hash
+        properties_hash.each_with_object({}) do |(original_name, prop_options), result|
+          # Use :as constraint for property name without mutating original constraints
+          property_name = (prop_options[:constraints][:as] || original_name).to_sym
+          cache_key = [property_name, prop_options].hash
 
           # Use cache if the exact property and configuration have been processed before
           @properties_cache[cache_key] ||= begin
-            mark_required_unless_optional(prop_name, prop_options)
-            build_property(prop_name, prop_options)
+            mark_required_unless_optional(property_name, prop_options)
+            build_property(property_name, prop_options)
           end
 
-          result[prop_name] = @properties_cache[cache_key]
+          result[property_name] = @properties_cache[cache_key]
         end
       end
 
@@ -145,8 +227,8 @@ module EasyTalk
 
         # Memoize so we only build each property once
         @property_cache[prop_name] ||= begin
-          # Remove optional constraints from the property
-          constraints = prop_options[:constraints].except(:optional)
+          # Remove internal constraints that shouldn't be passed to Property
+          constraints = prop_options[:constraints].except(:optional, :as)
           prop_type = prop_options[:type]
 
           # Track models that will use $ref for later $defs generation
@@ -165,10 +247,11 @@ module EasyTalk
         # Check if this type should use $ref
         if should_collect_ref?(prop_type, constraints)
           @ref_models.add(prop_type)
+        elsif prop_type.is_a?(EasyTalk::Types::Composer)
+          collect_ref_models(prop_type.items, constraints)
         # Handle typed arrays with EasyTalk model items
-        elsif typed_array_with_model?(prop_type)
-          inner_type = prop_type.type.raw_type
-          @ref_models.add(inner_type) if should_collect_ref?(inner_type, constraints)
+        elsif typed_array?(prop_type)
+          extract_inner_types(prop_type).each { |inner_type| collect_ref_models(inner_type, constraints) }
         # Handle nilable types
         elsif nilable_with_model?(prop_type)
           actual_type = T::Utils::Nilable.get_underlying_type(prop_type)
@@ -180,7 +263,7 @@ module EasyTalk
       # Determines if a type should be collected for $ref based on config and constraints.
       #
       def should_collect_ref?(check_type, constraints)
-        return false unless easytalk_model?(check_type)
+        return false unless ModelHelper.easytalk_model?(check_type)
 
         # Per-property constraint takes precedence
         return constraints[:ref] if constraints.key?(:ref)
@@ -189,25 +272,18 @@ module EasyTalk
         EasyTalk.configuration.use_refs
       end
 
-      ##
-      # Checks if a type is an EasyTalk model.
-      #
-      def easytalk_model?(check_type)
-        check_type.is_a?(Class) &&
-          check_type.respond_to?(:schema) &&
-          check_type.respond_to?(:ref_template) &&
-          defined?(EasyTalk::Model) &&
-          check_type.include?(EasyTalk::Model)
+      def typed_array?(prop_type)
+        prop_type.is_a?(T::Types::TypedArray)
       end
 
-      ##
-      # Checks if type is a typed array containing an EasyTalk model.
-      #
-      def typed_array_with_model?(prop_type)
-        return false unless prop_type.is_a?(T::Types::TypedArray)
+      def extract_inner_types(prop_type)
+        return [] unless typed_array?(prop_type)
 
-        inner_type = prop_type.type.raw_type
-        easytalk_model?(inner_type)
+        if prop_type.type.is_a?(EasyTalk::Types::Composer)
+          prop_type.type.items
+        else
+          [prop_type.type.raw_type]
+        end
       end
 
       ##
@@ -219,7 +295,7 @@ module EasyTalk
         return false unless prop_type.types.any? { |t| t.raw_type == NilClass }
 
         actual_type = T::Utils::Nilable.get_underlying_type(prop_type)
-        easytalk_model?(actual_type)
+        ModelHelper.easytalk_model?(actual_type)
       end
 
       ##

data/lib/easy_talk/builders/registry.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+# typed: true
+
+module EasyTalk
+  module Builders
+    # Registry for type-to-builder mappings.
+    #
+    # The registry allows custom types to be registered with their corresponding
+    # schema builder classes at runtime, without modifying the gem's source code.
+    #
+    # Custom registrations take priority over built-in types, allowing users to
+    # override default behavior when needed.
+    #
+    # @example Registering a custom type
+    #   EasyTalk::Builders::Registry.register(Money, MoneySchemaBuilder)
+    #
+    # @example Registering a collection type
+    #   EasyTalk::Builders::Registry.register(CustomArray, CustomArrayBuilder, collection: true)
+    #
+    # @example Resolving a builder for a type
+    #   builder_class, is_collection = EasyTalk::Builders::Registry.resolve(Money)
+    #   builder_class.new(name, constraints).build
+    #
+    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
+
+        # Register a type with its corresponding builder class.
+        #
+        # @param type_key [Class, String, Symbol] The type identifier
+        # @param builder_class [Class] The builder class (must respond to .new)
+        # @param collection [Boolean] Whether this is a collection type builder
+        #   Collection builders receive (name, type, constraints) instead of (name, constraints)
+        # @raise [ArgumentError] if the builder does not respond to .new
+        # @return [void]
+        #
+        # @example Register a simple type
+        #   Registry.register(Money, MoneySchemaBuilder)
+        #
+        # @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)
+
+          key = normalize_key(type_key)
+          registry[key] = { builder: builder_class, collection: collection }
+        end
+
+        # Resolve a builder for the given type.
+        #
+        # Resolution order:
+        # 1. Check type.class.name (e.g., "T::Types::TypedArray")
+        # 2. Check type.name if type responds to :name (e.g., "String")
+        # 3. Check type itself if it's a Class (e.g., String class)
+        #
+        # @param type [Object] The type to find a builder for
+        # @return [Array(Class, Boolean), nil] A tuple of [builder_class, is_collection] or nil if not found
+        #
+        # @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
+
+          [entry[:builder], entry[:collection]]
+        end
+
+        # Check if a type is registered.
+        #
+        # @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
+
+        # Unregister a type.
+        #
+        # @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
+
+        # 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
+
+        # Reset the registry to empty state and re-register built-in types.
+        #
+        # @return [void]
+        sig { void }
+        def reset!
+          @registry = nil
+          register_built_in_types
+        end
+
+        # Register all built-in type builders.
+        # 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)
+          register(Float, Builders::NumberBuilder)
+          register(BigDecimal, Builders::NumberBuilder)
+          register('T::Boolean', Builders::BooleanBuilder)
+          register(TrueClass, Builders::BooleanBuilder)
+          register(NilClass, Builders::NullBuilder)
+          register(Date, Builders::TemporalBuilder::DateBuilder)
+          register(DateTime, Builders::TemporalBuilder::DatetimeBuilder)
+          register(Time, Builders::TemporalBuilder::TimeBuilder)
+          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
+
+        private
+
+        # Normalize a type key to a canonical string form.
+        #
+        # @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
+            type_key.name.to_s
+          when Symbol
+            type_key.to_s
+          else
+            type_key.to_s
+          end
+        end
+
+        # Find a registration for the given type.
+        #
+        # Tries multiple resolution strategies in order.
+        #
+        # @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
+          return registry[class_name] if registry.key?(class_name)
+
+          # Strategy 2: Check type.name (for types that respond to :name, like "String")
+          if type.respond_to?(:name)
+            type_name = type.name.to_s
+            return registry[type_name] if registry.key?(type_name)
+          end
+
+          # Strategy 3: Check the type itself if it's a Class
+          return registry[type.name.to_s] if type.is_a?(Class) && registry.key?(type.name.to_s)
+
+          nil
+        end
+      end
+    end
+  end
+end

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,16 +21,23 @@ 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
+        @valid_options = deep_dup_options(VALID_OPTIONS)
         update_option_types
-        super(name, { type: 'array' }, constraints, VALID_OPTIONS)
+        super(name, { type: 'array' }, constraints, @valid_options)
       end
 
       private
 
+      # Creates a copy of options with duped nested hashes to avoid mutating the constant.
+      sig { params(options: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      def deep_dup_options(options)
+        options.transform_values(&:dup)
+      end
+
       # Modifies the schema to include the `items` property.
       #
       # @return [Hash] The built schema.
@@ -42,17 +50,22 @@ module EasyTalk
         end
       end
 
+      sig { returns(T.untyped) }
       def inner_type
         return unless type.is_a?(T::Types::TypedArray)
 
-        type.type.raw_type
+        if type.type.is_a?(EasyTalk::Types::Composer)
+          type.type
+        else
+          type.type.raw_type
+        end
       end
 
       sig { void }
       # Updates the option types for the array builder.
       def update_option_types
-        VALID_OPTIONS[:enum][:type] = T::Array[inner_type]
-        VALID_OPTIONS[:const][:type] = T::Array[inner_type]
+        @valid_options[:enum][:type] = T::Array[inner_type]
+        @valid_options[:const][:type] = T::Array[inner_type]
       end
     end
   end

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