easy_talk 3.1.0 → 3.2.0

data/lib/easy_talk/builders/registry.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: 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
+        # Get the hash of registered type builders.
+        #
+        # @return [Hash{String => Hash}] The registered builders with metadata
+        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)
+        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]
+        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
+        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
+        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
+        def registered_types
+          registry.keys
+        end
+
+        # Reset the registry to empty state and re-register built-in types.
+        #
+        # @return [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]
+        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('anyOf', Builders::CompositionBuilder::AnyOfBuilder, collection: true)
+          register('allOf', Builders::CompositionBuilder::AllOfBuilder, collection: true)
+          register('oneOf', Builders::CompositionBuilder::OneOfBuilder, 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
+        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
+        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/typed_array_builder.rb

@@ -24,12 +24,19 @@ module EasyTalk
       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.
@@ -45,14 +52,18 @@ module EasyTalk
       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/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'naming_strategies'
+
 module EasyTalk
   class Configuration
     # JSON Schema draft version URIs
@@ -12,15 +14,21 @@ module EasyTalk
     }.freeze
 
     attr_accessor :default_additional_properties, :nilable_is_optional, :auto_validations, :schema_version, :schema_id,
-                  :use_refs
+                  :use_refs, :validation_adapter, :default_error_format, :error_type_base_uri, :include_error_codes
+    attr_reader :property_naming_strategy
 
     def initialize
       @default_additional_properties = false
       @nilable_is_optional = false
       @auto_validations = true
+      @validation_adapter = :active_model
       @schema_version = :none
       @schema_id = nil
       @use_refs = false
+      @default_error_format = :flat
+      @error_type_base_uri = 'about:blank'
+      @include_error_codes = true
+      self.property_naming_strategy = :identity
     end
 
     # Returns the URI for the configured schema version, or nil if :none
@@ -29,6 +37,28 @@ module EasyTalk
 
       SCHEMA_VERSIONS[@schema_version] || @schema_version.to_s
     end
+
+    def property_naming_strategy=(strategy)
+      @property_naming_strategy = EasyTalk::NamingStrategies.derive_strategy(strategy)
+    end
+
+    # Register a custom type with its corresponding schema builder.
+    #
+    # This convenience method delegates to Builders::Registry.register
+    # and allows type registration within a configuration block.
+    #
+    # @param type_key [Class, String, Symbol] The type to register
+    # @param builder_class [Class] The builder class that generates JSON Schema
+    # @param collection [Boolean] Whether this is a collection type builder
+    # @return [void]
+    #
+    # @example
+    #   EasyTalk.configure do |config|
+    #     config.register_type Money, MoneySchemaBuilder
+    #   end
+    def register_type(type_key, builder_class, collection: false)
+      EasyTalk::Builders::Registry.register(type_key, builder_class, collection: collection)
+    end
   end
 
   class << self

data/lib/easy_talk/error_formatter/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Abstract base class for error formatters.
+    #
+    # Provides common functionality for transforming ActiveModel::Errors
+    # into standardized formats. Subclasses implement the `format` method
+    # to produce specific output formats.
+    #
+    # @abstract Subclass and implement {#format} to create a formatter.
+    #
+    # @example Creating a custom formatter
+    #   class CustomFormatter < EasyTalk::ErrorFormatter::Base
+    #     def format
+    #       error_entries.map do |entry|
+    #         { custom_field: entry[:attribute], custom_message: entry[:message] }
+    #       end
+    #     end
+    #   end
+    #
+    class Base
+      attr_reader :errors, :options
+
+      # Initialize a new formatter.
+      #
+      # @param errors [ActiveModel::Errors] The errors object to format
+      # @param options [Hash] Formatting options
+      # @option options [Boolean] :include_codes Whether to include error codes
+      def initialize(errors, options = {})
+        @errors = errors
+        @options = options
+      end
+
+      # Format the errors into the target format.
+      #
+      # @abstract
+      # @return [Hash, Array] The formatted errors
+      # @raise [NotImplementedError] if the subclass does not implement this method
+      def format
+        raise NotImplementedError, "#{self.class} must implement #format"
+      end
+
+      protected
+
+      # Check if error codes should be included in the output.
+      #
+      # @return [Boolean]
+      def include_codes?
+        @options.fetch(:include_codes, EasyTalk.configuration.include_error_codes)
+      end
+
+      # Build a normalized list of error entries from ActiveModel::Errors.
+      #
+      # Each entry contains:
+      # - :attribute - The attribute name (may include dots for nested)
+      # - :message - The error message
+      # - :full_message - The full error message with attribute name
+      # - :type - The error type from errors.details (e.g., :blank, :too_short)
+      # - :detail_options - Additional options from the error detail
+      #
+      # @return [Array<Hash>] The normalized error entries
+      def error_entries
+        @error_entries ||= build_error_entries
+      end
+
+      private
+
+      def build_error_entries
+        # Group details by attribute for matching
+        details_by_attr = {}
+        errors.details.each do |attr, detail_list|
+          details_by_attr[attr] = detail_list.dup
+        end
+
+        errors.map do |error|
+          attr = error.attribute
+          detail = find_and_consume_detail(details_by_attr, attr)
+
+          {
+            attribute: attr,
+            message: error.message,
+            full_message: error.full_message,
+            type: detail[:error],
+            detail_options: detail.except(:error)
+          }
+        end
+      end
+
+      # Find and consume a detail entry for an attribute.
+      # This handles the case where an attribute has multiple errors.
+      def find_and_consume_detail(details_by_attr, attribute)
+        detail_list = details_by_attr[attribute]
+        return {} if detail_list.nil? || detail_list.empty?
+
+        detail_list.shift || {}
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/error_code_mapper.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Maps ActiveModel validation error types to semantic error codes.
+    #
+    # ActiveModel's `errors.details` provides the validation type (e.g., :blank, :too_short).
+    # This class maps those types to standardized semantic codes for API responses.
+    #
+    # @example
+    #   ErrorCodeMapper.map(:blank)        # => "blank"
+    #   ErrorCodeMapper.map(:too_short)    # => "too_short"
+    #   ErrorCodeMapper.map(:invalid)      # => "invalid_format"
+    #
+    class ErrorCodeMapper
+      # Mapping of ActiveModel error types to semantic codes
+      VALIDATION_TO_CODE = {
+        # Presence validations
+        blank: 'blank',
+        present: 'present',
+        empty: 'empty',
+
+        # Format validations
+        invalid: 'invalid_format',
+
+        # Length validations
+        too_short: 'too_short',
+        too_long: 'too_long',
+        wrong_length: 'wrong_length',
+
+        # Numericality validations
+        not_a_number: 'not_a_number',
+        not_an_integer: 'not_an_integer',
+        greater_than: 'too_small',
+        greater_than_or_equal_to: 'too_small',
+        less_than: 'too_large',
+        less_than_or_equal_to: 'too_large',
+        equal_to: 'not_equal',
+        other_than: 'equal',
+        odd: 'not_odd',
+        even: 'not_even',
+
+        # Inclusion/exclusion validations
+        inclusion: 'not_included',
+        exclusion: 'excluded',
+
+        # Other validations
+        taken: 'taken',
+        confirmation: 'confirmation',
+        accepted: 'not_accepted'
+      }.freeze
+
+      class << self
+        # Map an ActiveModel error type to a semantic code.
+        #
+        # @param error_type [Symbol, String] The ActiveModel error type
+        # @return [String] The semantic error code
+        def map(error_type)
+          VALIDATION_TO_CODE[error_type.to_sym] || error_type.to_s
+        end
+
+        # Extract the error code from an ActiveModel error detail hash.
+        #
+        # @param detail [Hash] The error detail from errors.details
+        # @return [String] The semantic error code
+        #
+        # @example
+        #   ErrorCodeMapper.code_from_detail({ error: :blank })
+        #   # => "blank"
+        #
+        #   ErrorCodeMapper.code_from_detail({ error: :too_short, count: 2 })
+        #   # => "too_short"
+        def code_from_detail(detail)
+          error_key = detail[:error]
+          return 'unknown' unless error_key
+
+          map(error_key)
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/flat.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors as a simple flat array.
+    #
+    # This is the simplest format, providing an array of error objects
+    # with field name, message, and optional error code.
+    #
+    # @example Output
+    #   [
+    #     { "field" => "name", "message" => "can't be blank", "code" => "blank" },
+    #     { "field" => "email.address", "message" => "is invalid", "code" => "invalid_format" }
+    #   ]
+    #
+    class Flat < Base
+      # Format the errors as a flat array.
+      #
+      # @return [Array<Hash>] Array of error objects
+      def format
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      private
+
+      def build_error_object(entry)
+        error = {
+          'field' => PathConverter.to_flat(entry[:attribute]),
+          'message' => entry[:message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/json_pointer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors using JSON Pointer (RFC 6901) paths.
+    #
+    # Converts attribute paths to JSON Pointer format pointing to the
+    # property location in the JSON Schema.
+    #
+    # @example Output
+    #   [
+    #     { "pointer" => "/properties/name", "message" => "can't be blank", "code" => "blank" },
+    #     { "pointer" => "/properties/email/properties/address", "message" => "is invalid", "code" => "invalid_format" }
+    #   ]
+    #
+    class JsonPointer < Base
+      # Format the errors as an array with JSON Pointer paths.
+      #
+      # @return [Array<Hash>] Array of error objects with pointer paths
+      def format
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      private
+
+      def build_error_object(entry)
+        error = {
+          'pointer' => PathConverter.to_json_pointer(entry[:attribute]),
+          'message' => entry[:message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/jsonapi.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Formats validation errors according to the JSON:API specification.
+    #
+    # JSON:API defines a standard error format with specific fields for
+    # status, source, title, detail, and optional code.
+    #
+    # @see https://jsonapi.org/format/#error-objects
+    #
+    # @example Output
+    #   {
+    #     "errors" => [
+    #       {
+    #         "status" => "422",
+    #         "code" => "blank",
+    #         "source" => { "pointer" => "/data/attributes/name" },
+    #         "title" => "Invalid Attribute",
+    #         "detail" => "Name can't be blank"
+    #       }
+    #     ]
+    #   }
+    #
+    class Jsonapi < Base
+      # Default values for JSON:API error fields
+      DEFAULT_STATUS = '422'
+      DEFAULT_TITLE = 'Invalid Attribute'
+
+      # Format the errors as a JSON:API error response.
+      #
+      # @return [Hash] The JSON:API error object with "errors" array
+      def format
+        {
+          'errors' => build_errors_array
+        }
+      end
+
+      private
+
+      def build_errors_array
+        error_entries.map do |entry|
+          build_error_object(entry)
+        end
+      end
+
+      def build_error_object(entry)
+        error = {
+          'status' => options.fetch(:status, DEFAULT_STATUS).to_s,
+          'source' => {
+            'pointer' => PathConverter.to_jsonapi_pointer(
+              entry[:attribute],
+              prefix: options.fetch(:source_prefix, '/data/attributes')
+            )
+          },
+          'title' => options.fetch(:title, DEFAULT_TITLE),
+          'detail' => entry[:full_message]
+        }
+        error['code'] = ErrorCodeMapper.map(entry[:type]) if include_codes? && entry[:type]
+        error
+      end
+    end
+  end
+end

data/lib/easy_talk/error_formatter/path_converter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorFormatter
+    # Converts attribute paths between different formats.
+    #
+    # EasyTalk uses dot notation for nested model errors (e.g., "email.address").
+    # This class converts those paths to different standard formats:
+    # - JSON Pointer (RFC 6901): /properties/email/properties/address
+    # - JSON:API: /data/attributes/email/address
+    # - Flat: email.address (unchanged)
+    #
+    # @example
+    #   PathConverter.to_json_pointer("email.address")
+    #   # => "/properties/email/properties/address"
+    #
+    #   PathConverter.to_jsonapi_pointer("email.address")
+    #   # => "/data/attributes/email/address"
+    #
+    class PathConverter
+      class << self
+        # Convert an attribute path to JSON Schema pointer format.
+        #
+        # @param attribute [Symbol, String] The attribute path (e.g., "email.address")
+        # @return [String] The JSON Pointer path (e.g., "/properties/email/properties/address")
+        def to_json_pointer(attribute)
+          parts = attribute.to_s.split('.')
+          return "/properties/#{parts.first}" if parts.length == 1
+
+          parts.map { |part| "/properties/#{part}" }.join
+        end
+
+        # Convert an attribute path to JSON:API pointer format.
+        #
+        # @param attribute [Symbol, String] The attribute path
+        # @param prefix [String] The path prefix (default: "/data/attributes")
+        # @return [String] The JSON:API pointer path
+        def to_jsonapi_pointer(attribute, prefix: '/data/attributes')
+          parts = attribute.to_s.split('.')
+          "#{prefix}/#{parts.join('/')}"
+        end
+
+        # Return the attribute path as-is (flat format).
+        #
+        # @param attribute [Symbol, String] The attribute path
+        # @return [String] The attribute as a string
+        def to_flat(attribute)
+          attribute.to_s
+        end
+      end
+    end
+  end
+end